Emitente

Emitentes são os responsáveis por emitir a nota fiscal, ele está vínculado diretamente no documento. É importante o preenchimento correto dos dados, afim de evitar problemas futuros.

Estrutura do modelo

O modelo de emitentes segue o seguinte padrão:

Parâmetro Descrição Padrão Obrigatório Tipo de Dado Tamanho Máximo
email E-mail que irá constar na nota fiscal de serviço após emissão   Sim Caracteres 255
social_reason Razão social do emitente. Deve ser único dentro da conta   Sim Caracteres 255
cnpj CNPJ do emitente. Deve ser único dentro da conta   Sim Caracteres 18
fancy_name Nome fantasia do emitente   Sim Caracteres 60
state_inscription Inscrição estadual do emitente   Nao Caracteres 255
city_inscription Inscrição municipal do emitente   Sim Caracteres 255
state Sigla do Estado onde se localiza o emitente   Sim Caracteres 2
city* Cidade do emitente   Sim Caracteres 255
neighborhood Bairro ou distrito do emitente   Sim Caracteres 60
street_type Tipo do logradouro RUA Sim Caracteres 125
street Logradouro do emitente   Sim Caracteres 125
number Número do endereço   Sim Caracteres 10
zip_code CEP do Logradouro   Sim Caracteres 9
complement Complemento do endereço   Não Caracteres 60
phone Telefone do emitente, com o código ddd   Sim Caracteres 11
certificate Arquivo com extensão .pfx codificado em base64   Sim Caracteres  
password Senha do certificado digital   Sim Caracteres 255
environment* Ambiente da prefeitura no qual a NFSe será emitida sandbox Não Caracteres 11
filename Nome do certificado   Não Caracteres 100
latest_serie Permite você cadastrar a série que você já utiliza na emissão de NFSe de outro sistema   Não Caracteres 5
latest_number Permite você cadastrar o número do RPS que você já utiliza na emissão de NFSe de outro sistema   Não Numérico 10
code_tax_regime Código de Regime Tributário Ver valores permitidos   Não Numérico 1
national_simple_optant Optante pelo simples nacional. Sim (true) ou Não (false) false Não Booleano  
cultural_promoter Incentivador cultural. Sim (true) ou Não (false) false Não Booleano  

*Só pode ser alterado quando usando o emites em produção.

*city: Somente emitentes das cidades do Rio de Janeiro e São Paulo estão podendo emitir nota.

Os campos latest_serie e latest_number não são alterados no PATCH e PUT.

Criação

Para criar um novo emitente, siga o exemplo abaixo:

POST /api/v1/emitters

Corpo de exemplo da requisição:

{
    "email": "email@example.com",
    "social_reason": "Foo Bar",
    "cnpj": "47183855000169",
    "fancy_name": "Foo",
    "city_inscription": "3304557",
    "state": "RJ",
    "city": "Rio de Janeiro",
    "neighborhood": "Centro",
    "street": "Rua do Carmo",
    "number": 43,
    "zip_code": 20011020,
    "phone": "5432215566",
    "certificate": "base64",
    "password": "password"
}

Cabeçalho de exemplo da resposta:

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

Corpo de exemplo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/emitters/edit/1"
        "method": "GET"
        "rel": "html"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1/series"
        "method": "GET"
        "rel": "series"
    }],
    "is_active": false,
    "id": 1,
    "account_id": 1,
    "email": "email@example.com",
    "cnpj": "40059584000195",
    "social_reason": "Foo Bar",
    "fancy_name": "Foo",
    "state_inscription": "12615413563",
    "city_inscription": "12345",
    "state": "RJ",
    "city": "Rio de Janeiro",
    "city_code": 3304557,
    "neighborhood": "São Pelegrino",
    "street": "Rua Feijó Junior",
    "number": "535",
    "complement": "Sala 102",
    "zip_code": "5495034160",
    "phone": "32215566",
    "certificate_filename": "certificate.pfx",
    "environment": "sandbox"
}

Listagem

Lista todos os emitentes cadastrados na conta autenticada:

GET /api/v1/emitters

Cabeçalho de exemplo 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 de exemplo da resposta:

{
    "count": 2,
    "next": null,
    "previous": null,
    "collection": [{
        "_links": [{
            "href": "https://app.emites.com.br/api/v1/emitters/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/1",
            "method": "PUT",
            "rel": "update"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/1",
            "method": "PATCH",
            "rel": "partial_update"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/1",
            "method": "DELETE",
            "rel": "destroy"
        }, {
            "href": "https://app.emites.com.br/emitters/edit/1"
            "method": "GET"
            "rel": "html"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/1/series"
            "method": "GET"
            "rel": "series"
        }],
        "is_active": false,
        "id": 1,
        "account_id": 1,
        "email": "email@example.com",
        "cnpj": "40059584000195",
        "social_reason": "Foo Bar",
        "fancy_name": "Foo",
        "state_inscription": "12615413563",
        "city_inscription": "12345",
        "state": "RJ",
        "city": "Rio de Janeiro",
        "city_code": 3304557,
        "neighborhood": "São Pelegrino",
        "street": "Rua Feijó Junior",
        "number": "535",
        "complement": "Sala 102",
        "zip_code": "95034160",
        "phone": "5432215566",
        "certificate_filename": "certificate.pfx",
        "environment": "sandbox"
    }, {
        "_links": [{
            "href": "https://app.emites.com.br/api/v1/emitters/2",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/2",
            "method": "PUT",
            "rel": "update"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/2",
            "method": "PATCH",
            "rel": "partial_update"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/2",
            "method": "DELETE",
            "rel": "destroy"
        }, {
            "href": "https://app.emites.com.br/emitters/edit/2"
            "method": "GET"
            "rel": "html"
        }, {
            "href": "https://app.emites.com.br/api/v1/emitters/1/series"
            "method": "GET"
            "rel": "series"
        }],
        "is_active": false,
        "id": 2,
        "account_id": 1,
        "email": "email@example.com",
        "cnpj": "81249912000101",
        "social_reason": "Foo Bar Foo",
        "fancy_name": "Foo",
        "state_inscription": "12615413563",
        "city_inscription": "12345",
        "state": "RJ",
        "city": "Rio de Janeiro",
        "city_code": 3304557,
        "neighborhood": "São Pelegrino",
        "street": "Rua Feijó Junior",
        "number": "535",
        "complement": "Sala 102",
        "zip_code": "95034160",
        "phone": "5432215566",
        "certificate": "certificate.pfx",
        "environment": "sandbox"
    }]
}

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/emitters/?page=3",
    "previous": "https://app.emites.com.br/api/v1/emitters/?page=1",
    "collection": [
        ...
    ],
}

Filtros

Para filtrar uma listagem de Emitentes:

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

Você pode agrupar filtros, como no exemplo abaixo:

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

Todos os parâmetros devem ser URL Enconded

Detalhes

Para consultar os detalhes de um emitente, siga o exemplo abaixo:

GET /api/v1/emitters/1

Cabeçalho de exemplo 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 de exemplo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/emitters/edit/1"
        "method": "GET"
        "rel": "html"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1/series"
        "method": "GET"
        "rel": "series"
    }],
    "is_active": false,
    "id": 1,
    "account_id": 1,
    "email": "email@example.com",
    "cnpj": "40059584000195",
    "social_reason": "Foo Bar",
    "fancy_name": "Foo",
    "state_inscription": "12615413563",
    "city_inscription": "12345",
    "state": "RJ",
    "city": "Rio de Janeiro",
    "city_code": 3304557,
    "neighborhood": "São Pelegrino",
    "street": "Rua Feijó Junior",
    "number": "535",
    "complement": "Sala 102",
    "zip_code": "95034160",
    "ddd": 54,
    "phone": "32215566",
    "certificate_filename": "certificate.pfx",
    "environment": "sandbox"
}

Atualização completa

Na atualização completa não é possível alterar o CNPJ do emitente.

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

PUT /api/v1/emitters/1

Corpo de exemplo da requisição:

{
    "social_reason": "Nova Razão Social",
    "fancy_name": "Foo",
    "cnpj": "40059584000195",
    "state_inscription": "12615413563",
    "city_inscription": "12345",
    "state": "RJ",
    "city": "Rio de Janeiro",
    "city_code": 3304557,
    "neighborhood": "São Pelegrino",
    "street": "Rua Feijó Junior",
    "number": 535,
    "zip_code": 95034160,
    "complement": "Sala 102",
    "ddd": 54,
    "phone": "32215566",
    "email": "email@example.com",
    "certificate": "base64",
    "environment": "sandbox"
}

Cabeçalho de exemplo 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 de exemplo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/emitters/edit/1"
        "method": "GET"
        "rel": "html"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1/series"
        "method": "GET"
        "rel": "series"
    }],
    "is_active": false,
    "id": 1,
    "account_id": 1,
    "email": "email@example.com",
    "cnpj": "40059584000195",
    "social_reason": "Nova Razão Social",
    "fancy_name": "Foo",
    "state_inscription": "12615413563",
    "city_inscription": "12345",
    "state": "RJ",
    "city": "Rio de Janeiro",
    "city_code": 3304557,
    "neighborhood": "São Pelegrino",
    "street": "Rua Feijó Junior",
    "number": "535",
    "complement": "Sala 102",
    "zip_code": "95034160",
    "ddd": 54,
    "phone": "32215566",
    "certificate_filename": "certificate.pfx",
    "environment": "sandbox"
}

Atualização parcial

Na atualização parcial não é possível alterar o CNPJ do emitente.

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

PATCH /api/v1/emitters/1

Corpo de exemplo da requisição:

{
    "social_reason": "Outra Razão Social",
    "fancy_name": "Nova"
}

Cabeçalho de exemplo 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 de exemplo da resposta:

{
    "_links": [{
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/emitters/edit/1"
        "method": "GET"
        "rel": "html"
    }, {
        "href": "https://app.emites.com.br/api/v1/emitters/1/series"
        "method": "GET"
        "rel": "series"
    }],
    "is_active": false,
    "id": 1,
    "account_id": 1,
    "email": "email@example.com",
    "cnpj": "40059584000195",
    "social_reason": "Outra Razão Social",
    "fancy_name": "Nova",
    "state_inscription": "12615413563",
    "city_inscription": "12345",
    "state": "RJ",
    "city": "Rio de Janeiro",
    "city_code": 3304557,
    "neighborhood": "São Pelegrino",
    "street": "Rua Feijó Junior",
    "number": "535",
    "complement": "Sala 102",
    "zip_code": "95034160",
    "ddd": 54,
    "phone": "32215566",
    "certificate_filename": "certificate.pfx",
    "environment": "sandbox"
}

Remoção

Para remover/deletar um emitente, faça como o exemplo abaixo:

DELETE /api/v1/emitters/1

Cabeçalho de exemplo 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.

Últimas séries e números

Busca todas as séries com o último número utilizado na emissão de uma NFSe de todos os emitentes da conta.

Siga o exemplo abaixo:

GET /api/v1/emitters/series

Cabeçalho de exemplo da resposta:

Status Code: 200
Date: Wed, 9 Dec 2014 12:00:28 GMT
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

Corpo de exemplo da resposta:

[{
    "emitter_id": 1,
    "serie_number": {
        "serie": "0001",
        "latest_number": 1
    },
    "latest_nfse": {
        "id": 1,
        "_links": [
            {
                "href": "https://app.emites.com.br/api/v1/nfse/1",
                "method": "GET",
                "rel": "self"
            }
        ]
    }
}, {
    "emitter_id": 2,
    "serie_number": {
        "serie": "1",
        "latest_number": 2
    },
    "latest_nfse": {
        "id": 2,
        "_links": [
            {
                "href": "https://app.emites.com.br/api/v1/nfse/2",
                "method": "GET",
                "rel": "self"
            }
        ]
    }
}]

Busca todas as séries e o último número utilizado na emissão de uma NFSe a partir de um emitente.

Siga o exemplo abaixo:

GET /api/v1/emitters/1/series

Cabeçalho de exemplo da resposta:

Status Code: 200
Date: Wed, 9 Dec 2014 12:00:28 GMT
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

Corpo de exemplo da resposta:

[{
    "serie_number": {
        "serie": "0001",
        "latest_number": 1
    },
    "latest_nfse": {
        "id": 1,
        "_links": [
            {
                "href": "https://app.emites.com.br/api/v1/nfse/1",
                "method": "GET",
                "rel": "self"
            }
        ]
    }
}, {
    "serie_number": {
        "serie": "0002",
        "latest_number": 2
    },
    "latest_nfse": {
        "id": 2,
        "_links": [
            {
                "href": "https://app.emites.com.br/api/v1/nfse/2",
                "method": "GET",
                "rel": "self"
            }
        ]
    }
}]

Busca o último número utilizado na emissão de uma NFSe a partir de um emitente e série.

Siga o exemplo abaixo:

GET /api/v1/emitters/1/series/0001

Cabeçalho de exemplo da resposta:

Status Code: 200
Date: Wed, 9 Dec 2014 12:00:28 GMT
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

Corpo de exemplo da resposta:

{
    "serie_number": {
        "serie": "0001",
        "latest_number": 1
    },
    "latest_nfse": {
        "id": 1,
        "_links": [
            {
                "href": "https://app.emites.com.br/api/v1/nfse/1",
                "method": "GET",
                "rel": "self"
            }
        ]
    }
}