Tomador

O Emites permite que você cadastre Tomadores de serviço na sua conta. Essa funcionalidade é util quando há um grande volume de documentos com o mesmo tomador. Se você preferir, pode também enviar o tomador normalmente junto com o restante da nota.

Estrutura do modelo de Tomador

O modelo de Tomador é divido em 3 modelos: Tomador, Endereço e Contato. Os padrões estão abaixo:

Tomador:

Parâmetro Descrição Padrão Obrigatório Tipo de Dado Tamanho Máximo
cpf CPF do tomador   Sim*    
cnpj CNPJ do tomador   Sim**    
city_inscription Inscrição municipal do tomador   Não Caracteres 25
social_reason Razão Social do Tomador   Sim Caracteres 120
fancy_name Nome Fantasia do Tomador   Não Caracteres 100
state_inscription Inscrição Estadual do Tomador   Não Caracteres 20
substitute_state_inscription Inscrição Estadual Substituída   Não Caracteres 15
special_situation Situação Especial do Tomador Ver valores permitidos 0 Não Numérico 1
foreign_taker Tomador Estrangeiro false Não Booleano  
allow_incomplete Flag para permitir o cadastro incompleto do tomador. No cadastro incompleto, somente a razão social do tomador é obrigatória. false Não Booleano  
is_complete Caso os dados do tomador não estejam completos o usuário poderá completar o cadastro posteriormente. O tomador ficara indisponível para uso. true Não Booleano  

*cpf: Não obrigatório caso seja passado o cnpj.

**cnpj: Não obrigatório caso seja passado o cpf.

Endereço do tomador:

Parâmetro Descrição Padrão Obrigatório Tipo de Dado Tamanho Máximo
street Logradouro   Não Caracteres 200
number Número   Não Caracteres 10
complement Complemento do endereço   Não Caracteres 100
neighborhood Bairro   Não Caracteres 60
city_code Código da Cidade conforme tabela do IBGE. Consultar código   Não Numérico 7
state Estado (Sigla)   Não Caracteres 2
zip_code CEP   Não Numérico 8
street_type Tipo do logradouro. Ver valores permitidos   Não Caracteres 10
neighborhood_type Tipo do bairro. Ver valores permitidos   Não Caracteres 10
city Cidade   Não Caracteres 60
reference_point Ponto de referência   Não Caracteres 100
country País Brasil Não Caracteres 100
country_code Código do País conforme tabela do IBGE. Consultar código 01058 Não Numérico 4
country_abbreviation Abreviação do nome do País BR Não Caracteres 2

Contato do tomador:

Parâmetro Descrição Obrigatório Tipo de Dado Tamanho Máximo
phone Telefone do tomador, com o código ddd Não Caracteres 15
email Email do tomador Não Caracteres 100

Cada Tomador só poderá ter um endereço e um contato associado.

Criação

Para criar um novo Tomador, siga o exemplo abaixo:

POST /api/v1/takers

Corpo de exemplo da requisição:

{
    "cpf": "44423739577",
    "social_reason": "Razão Social do Tomador"
}

É obrigatório o envio do “address” e do “contact” do tomador na mesma requisição.

Cabeçalho da resposta:

Status Code: 201
Location: https://sandbox.emites.com.br/api/v1/takers/1
Date: Wed, 20 Nov 2013 19:53:28 GMT
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "mehod": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/takers/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "address": null,
    "contact": null,
    "id": 1,
    "account_id": 1,
    "cpf": "44423739577",
    "cnpj": null,
    "city_inscription": null,
    "social_reason": "Razão Social do Tomador",
    "fancy_name": null,
    "state_inscription": null,
    "substitute_state_inscription": null,
    "special_situation": 0,
    "foreign_taker": false,
    "is_complete": true
}

Cadastro incompleto

Você cadastrar um tomador parcialmente. Isso é útil quando o seus sistema não possui todos os dados necessários para o cadastro completo. Dessa maneira será necessário continuar o cadastro manualmente. Para o cadastro parcial, passe a chave allow_incomplete como ´true´:

{
    "social_reason": "Razão Social do Tomador",
    "allow_incomplete": true
}

Listagem

Para listar todos os Tomadores cadastrados na conta:

GET /api/v1/takers

Cabeçalho da resposta:

Status Code: 200
Date: Wed, 20 Nov 2013 19:53:28 GMT
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da Resposta:

{
    "count": 1,
    "next": null,
    "previous": null,
    "collection": [{
        "_links": [{
            "href": "https://app.emites.com.br/api/v1/takers/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/takers/1",
            "method": "PUT",
            "rel": "update"
        }, {
            "href": "https://app.emites.com.br/api/v1/takers/1",
            "method": "PATCH",
            "rel": "partial_update"
        }, {
            "href": "https://app.emites.com.br/api/v1/takers/1",
            "mehod": "DELETE",
            "rel": "destroy"
        }], {
            "href": "https://app.emites.com.br/takers/edit/1"
            "method": "GET"
            "rel": "html"
        },
        "address": null,
        "contact": null,
        "id": 1,
        "account_id": 1,
        "cpf": "44423739577",
        "cnpj": null,
        "city_inscription": null,
        "social_reason": "Razão Social do Tomador",
        "fancy_name": null,
        "state_inscription": null,
        "substitute_state_inscription": null,
        "special_situation": 0,
        "foreign_taker": false,
        "is_complete": true
    }]
}

A API do Emites é paginada a cada 10 objetos, caso o retorno tenha mais de uma página, os campos next e previous virão preenchidos como o exemplo abaixo:

{
    "count": 30,
    "next": "https://app.emites.com.br/api/v1/takers?page=3",
    "previous": "https://app.emites.com.br/api/v1/takers?page=1",
    "collection": [
        ...
    ],
}

Filtros

Para filtrar uma listagem de Tomadores:

GET /api/v1/takers?cnpj=81249912000101
Parâmetro Exemplo
cnpj /api/v1/takers?cnpj=81249912000101
cpf /api/v1/takers?cpf=02091505080
social_reason /api/v1/takers?social_reason=Foo+bar+Foo

Você pode agrupar filtros, como no exemplo abaixo:

GET /api/v1/takers?cnpj=81249912000101&social_reason=Foo+bar+Foo

Todos os parâmetros devem ser URL Enconded

Detalhes

Para consultar os detalhes de um Tomador:

GET /api/v1/takers/1

Cabeçalho da resposta:

Status Code: 200
Date: Wed, 20 Nov 2013 19:53:28 GMT
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "mehod": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/takers/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "address": null,
    "contact": null,
    "id": 1,
    "account_id": 1,
    "cpf": "44423739577",
    "cnpj": null,
    "city_inscription": null,
    "social_reason": "Razão Social do Tomador",
    "fancy_name": null,
    "state_inscription": null,
    "substitute_state_inscription": null,
    "special_situation": 0,
    "foreign_taker": false,
    "is_complete": true
}

Atualização completa

Para a atualização completa do tomador todos os dados são obrigatórios, com exceção do id do tomador e o id da conta do tomador. Confira o exemplo de atualização completa:

PUT /api/v1/takers/1

Corpo de exemplo da requisição:

{
    "cpf": "44423739577",
    "social_reason": "Nova Razão Social do Tomador",
}

Cabeçalho da resposta:

Status Code: 200
Date: Wed, 20 Nov 2013 19:53:28 GMT
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "mehod": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/takers/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "address": null,
    "contact": null,
    "id": 1,
    "account_id": 1,
    "cpf": "44423739577",
    "cnpj": null,
    "city_inscription": "92708711",
    "social_reason": "Nova Razão Social do Tomador",
    "fancy_name": null,
    "state_inscription": null,
    "substitute_state_inscription": null,
    "special_situation": 0,
    "foreign_taker": false,
    "is_complete": true
    }
}

Atualização parcial

É semelhente a atualização completa, mas na atualização parcial, você pode passar apenas um item. Confira o exemplo abaixo:

PATCH /api/v1/takers/1

Corpo de exemplo da requisição:

{
    "social_reason": "Alguma Razão Social"
}

Cabeçalho da resposta:

Status Code: 200
Date: Wed, 20 Nov 2013 19:53:28 GMT
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/takers/1",
        "mehod": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/takers/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "address": null,
    "contact": null,
    "id": 1,
    "account_id": 1,
    "cpf": "44423739577",
    "cnpj": null,
    "city_inscription": null,
    "social_reason": "Alguma Razão Social",
    "fancy_name": null,
    "state_inscription": null,
    "substitute_state_inscription": null,
    "special_situation": 0,
    "foreign_taker": false,
    "is_complete": true
    }
}

Remoção

Para remover um Tomador, faça como o exemplo abaixo:

DELETE /api/v1/takers/1

Cabeçalho da resposta:

Status Code: 204
Date: Wed, 20 Nov 2013 19:53:28 GMT
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Na remoção não é retornado nenhum dado no corpo da resposta.