Referência
Todas as rotas da API, geradas do contrato OpenAPI. Importe o arquivo no Postman, no Insomnia ou no gerador de cliente da sua linguagem.
saude
GET/saude sem chave
200
GET/v1/openapi.yaml sem chave
200
conta
GET/v1/conta
200 401 403 429
emissoras
GET/v1/emissoras
200 401 403 429
POST/v1/emissoras
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
ambiente_padrao | Ambiente | |
cnpj | string | Obrigatório na criação; não muda depois. |
crt | integer | |
email_automatico | boolean | Manda o PDF e o XML por e-mail assim que a nota é autorizada, ao dest.email da NF-e e da NFC-e ou ao toma.email da NFS-e (vários separados por ponto e vírgula, até 5). Só quando o motor tem servidor de e-mail configurado. |
endereco | Endereco | |
inscricao_estadual | string | Só números ou ISENTO. |
inscricao_municipal | string | |
municipio_ibge | string | |
nome_fantasia | string | |
prazo_cancelamento_nfce_min | integer | Prazo do estado para cancelar a NFC-e, em minutos (trinta na maioria). Informado, o motor recusa o cancelamento fora do prazo antes de gastar um evento. Nulo, quem decide é a SEFAZ. |
razao_social | string | |
uf | string |
201 400 401 403 409 422 429
GET/v1/emissoras/{id}
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
PATCH/v1/emissoras/{id}
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
ambiente_padrao | Ambiente | |
cnpj | string | Obrigatório na criação; não muda depois. |
crt | integer | |
email_automatico | boolean | Manda o PDF e o XML por e-mail assim que a nota é autorizada, ao dest.email da NF-e e da NFC-e ou ao toma.email da NFS-e (vários separados por ponto e vírgula, até 5). Só quando o motor tem servidor de e-mail configurado. |
endereco | Endereco | |
inscricao_estadual | string | Só números ou ISENTO. |
inscricao_municipal | string | |
municipio_ibge | string | |
nome_fantasia | string | |
prazo_cancelamento_nfce_min | integer | Prazo do estado para cancelar a NFC-e, em minutos (trinta na maioria). Informado, o motor recusa o cancelamento fora do prazo antes de gastar um evento. Nulo, quem decide é a SEFAZ. |
razao_social | string | |
uf | string |
200 400 401 403 404 422 429
GET/v1/emissoras/{id}/certificado
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
PUT/v1/emissoras/{id}/certificado
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (multipart/form-data) | Tipo | Descrição |
|---|---|---|
arquivo * | string (binary) | |
senha * | string (password) |
200 400 401 403 404 413 415 422 429
GET/v1/emissoras/{id}/csc
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) | |
ambiente | query | simulado | homologacao | producao |
200 401 403 404 422 429
PUT/v1/emissoras/{id}/csc
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
ambiente * | simulado | homologacao | producao | |
csc * | string (password) | |
identificador * | integer | |
url_chave * | string | Endereço de consulta pela chave, exatamente como a SEFAZ do estado publica. Vários estados o publicam sem prefixo (www.sefaz.rs.gov.br/nfce/consulta). O esquema da NFC-e exige, e a SEFAZ confere (rejeição 878). |
url_qrcode * | string (uri) | Endereço do QR Code publicado pela SEFAZ do estado, em http ou https e sem parâmetro. Não é sempre https. |
200 400 401 403 404 413 415 422 429
GET/v1/emissoras/{id}/lacunas
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) | |
modelo | query | 55 | 65 | |
serie | query | integer | |
ambiente * | query | Ambiente |
200 401 403 404 422 429
GET/v1/emissoras/{id}/logo
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
PUT/v1/emissoras/{id}/logo
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (multipart/form-data) | Tipo | Descrição |
|---|---|---|
arquivo * | string (binary) |
200 400 401 403 404 413 415 422 429
DELETE/v1/emissoras/{id}/logo
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
204 401 403 404 429
GET/v1/emissoras/{id}/series
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
PUT/v1/emissoras/{id}/series
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
series * | lista de SerieEntrada |
200 400 401 403 404 422 429
documentos
GET/v1/documentos/{id}
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
POST/v1/documentos/{id}/cancelamento
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
justificativa * | string | |
motivo | 1 | 2 | 9 | Código do motivo, exigido pela NFS-e (1 erro na emissão, 2 serviço não prestado, 9 outros). Ignorado na NF-e. |
202 400 401 403 404 409 422 429
POST/v1/documentos/{id}/carta-correcao
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
correcao * | string |
202 400 401 403 404 409 422 429
GET/v1/documentos/{id}/email
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
POST/v1/documentos/{id}/email
Envia o PDF e o XML da nota por e-mail
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
destinatarios * | lista de string (email) |
202 400 401 403 404 409 422 429 503
GET/v1/documentos/{id}/eventos
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
GET/v1/documentos/{id}/pdf
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 409 429
GET/v1/documentos/{id}/xml
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 409 429
POST/v1/inutilizacoes
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
ambiente | Ambiente | |
emissora_id * | string (uuid) | |
justificativa * | string | |
modelo * | 55 | 65 | |
numero_final * | integer (int64) | |
numero_inicial * | integer (int64) | |
serie * | integer |
202 400 401 403 404 409 422 429
GET/v1/inutilizacoes/{id}
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
200 401 403 404 429
POST/v1/nfce
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
Idempotency-Key | header | string |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
ambiente | Ambiente | |
contingencia | Só na NFC-e. Emite o cupom em contingência offline: a chave sai com tipo de emissão 9, o XML leva dhCont e xJust, e o QR Code é montado depois da assinatura, porque leva o digest dela. Sem este campo, o motor entra em contingência sozinho quando a mensagem de autorização não chega à SEFAZ (conexão recusada, por exemplo): o documento passa a "contingencia", a chave muda para a de tipo de emissão 9, e o XML e o PDF ficam disponíveis antes do protocolo. | |
dest | object | |
det * | lista de object | |
emissora_id * | string (uuid) | |
id_externo | string | |
ide * | object | |
infAdic | object | |
numero | integer | Número informado pelo cliente que já numera as notas. Sem ele, o motor usa o próximo da série. Número com nota volta 409 NUMERO_EM_USO; número inutilizado, 409 NUMERO_INUTILIZADO. A série passa a continuar depois do maior número usado. |
pag * | object | |
serie | integer | |
simulacao | object | Só no ambiente simulado. Escolhe o desfecho. |
substitui | string (uuid) | Só na NFC-e. Identificador do cupom que foi enviado e ficou sem resposta da SEFAZ. Este cupom sai em contingência offline, com o número informado, e acoberta a venda. O motor passa a consultar o primeiro em vez de enviá-lo: se a SEFAZ o autorizou, cancela por substituição (evento 110112) quando este também estiver autorizado; se ele não consta, encerra como rejeitado com código 217, e o número fica para inutilizar. O valor total e o destinatário têm de ser os mesmos do primeiro, ou a SEFAZ recusa o cancelamento. Responde 409 `PRIMEIRO_JA_DECIDIDO` quando o primeiro já tem desfecho: use o primeiro. |
total * | object | |
transp | object |
200 202 400 401 403 404 409 413 415 422 429
POST/v1/nfe
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
Idempotency-Key | header | string |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
ambiente | Ambiente | |
contingencia | Só na NFC-e. Emite o cupom em contingência offline: a chave sai com tipo de emissão 9, o XML leva dhCont e xJust, e o QR Code é montado depois da assinatura, porque leva o digest dela. Sem este campo, o motor entra em contingência sozinho quando a mensagem de autorização não chega à SEFAZ (conexão recusada, por exemplo): o documento passa a "contingencia", a chave muda para a de tipo de emissão 9, e o XML e o PDF ficam disponíveis antes do protocolo. | |
dest | object | |
det * | lista de object | |
emissora_id * | string (uuid) | |
id_externo | string | |
ide * | object | |
infAdic | object | |
numero | integer | Número informado pelo cliente que já numera as notas. Sem ele, o motor usa o próximo da série. Número com nota volta 409 NUMERO_EM_USO; número inutilizado, 409 NUMERO_INUTILIZADO. A série passa a continuar depois do maior número usado. |
pag * | object | |
serie | integer | |
simulacao | object | Só no ambiente simulado. Escolhe o desfecho. |
substitui | string (uuid) | Só na NFC-e. Identificador do cupom que foi enviado e ficou sem resposta da SEFAZ. Este cupom sai em contingência offline, com o número informado, e acoberta a venda. O motor passa a consultar o primeiro em vez de enviá-lo: se a SEFAZ o autorizou, cancela por substituição (evento 110112) quando este também estiver autorizado; se ele não consta, encerra como rejeitado com código 217, e o número fica para inutilizar. O valor total e o destinatário têm de ser os mesmos do primeiro, ou a SEFAZ recusa o cancelamento. Responde 409 `PRIMEIRO_JA_DECIDIDO` quando o primeiro já tem desfecho: use o primeiro. |
total * | object | |
transp | object |
200 202 400 401 403 404 409 413 415 422 429
POST/v1/nfse
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
Idempotency-Key | header | string |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
IBSCBS | object | |
ambiente | Ambiente | |
dCompet | string | Competência (AAAA-MM-DD); padrão é a data de emissão. |
emissora_id * | string (uuid) | |
id_externo | string | |
interm | object | |
numero | integer | Número informado pelo cliente que já numera as notas. Sem ele, o motor usa o próximo da série. Número com nota volta 409 NUMERO_EM_USO; número inutilizado, 409 NUMERO_INUTILIZADO. A série passa a continuar depois do maior número usado. |
serie | integer | |
serv * | object | |
simulacao | object | Só no ambiente simulado. Escolhe o desfecho: rejeitar devolve a NFS-e rejeitada com um motivo no formato do Sistema Nacional (E0312). A NFS-e não tem denegação. |
subst | object | Motivo da substituição (cMotivo 01 a 05 ou 99, e xMotivo). Só com substitui. |
substitui | string (uuid) | Id, no motor, da NFS-e autorizada que esta substitui. Vai junto com subst (cMotivo e xMotivo); a chave da original (chSubstda) o motor preenche. Autorizada a substituta, a original fica cancelada e o webhook documento.cancelado sai para ela. Só NFS-e autorizada, da mesma emissora e do mesmo ambiente (SUBSTITUIDA_NAO_AUTORIZADA, SUBSTITUIDA_INVALIDA); uma substituta por vez (JA_SUBSTITUIDA). |
toma | object | |
tpEmit | 1 | 2 | |
valores * | object |
200 202 400 401 403 404 409 413 415 422 429
webhooks
GET/v1/webhooks
200 401 403 429
POST/v1/webhooks
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
eventos * | lista de TipoDeEvento | |
url * | string (uri) |
201 400 401 403 422 429
DELETE/v1/webhooks/{id}
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
204 401 403 404 429
destinatario
Notas emitidas contra o CNPJ da emissora (distribuição de DF-e e manifestação).
GET/v1/emissoras/{id}/distribuicao
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) | |
ambiente * | query | Ambiente | |
ultimo_nsu | query | string | Último NSU que quem integra já leu (até 15 dígitos). Vazio pede desde o começo. |
200 401 403 404 422 429 502
GET/v1/emissoras/{id}/distribuicao-nfse
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) | |
ambiente * | query | Ambiente | |
ultimo_nsu | query | string | Último NSU que quem integra já leu. Vazio pede desde o começo. |
200 401 403 404 422 429 502
POST/v1/emissoras/{id}/manifestacoes
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
id * | path | string (uuid) |
| Corpo (application/json) | Tipo | Descrição |
|---|---|---|
ambiente * | Ambiente | |
chave * | string | |
justificativa | string | Obrigatória em nao_realizada, ignorada nas outras. |
tipo * | ciencia | confirmacao | desconhecimento | nao_realizada |
200 400 401 403 404 422 429 502
cadastro
Situação cadastral de contribuintes na SEFAZ.
GET/v1/cadastro/{cnpj}
Situação cadastral do CNPJ na SEFAZ do estado
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
cnpj * | path | string | |
uf * | query | string | Estado cuja SEFAZ responde. O cadastro é por estado. |
ambiente | query | homologacao | producao | Padrão producao, onde está o cadastro de verdade. |
200 401 403 422 429 502 503
GET/v1/cnpj/{cnpj}
Dados do CNPJ na Receita Federal
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
cnpj * | path | string |
200 401 403 404 422 429 502
documentacao
Guias, referência e catálogo de erros, em HTML, sem chave.
GET/ sem chave
302
GET/docs sem chave
200
GET/docs/exemplos/{arquivo} sem chave
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
arquivo * | path | string |
200 404
GET/docs/{pagina} sem chave
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
pagina * | path | primeira-nota | cancelamento | webhooks | erros | referencia |
200
portal
Portal do cliente, em HTML, com sessão própria (e-mail e senha): chaves de teste, emissoras, certificado, séries, webhooks e uso do mês. Não faz parte da API; aqui fica só a porta de entrada.
GET/portal sem chave
200 303
GET/portal/entrar sem chave
200 303
nfse
GET/v1/municipios/{ibge}/convenio
O município aderiu ao padrão nacional da NFS-e?
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
ibge * | path | string | Código do município no IBGE, com 7 dígitos. |
ambiente | query | homologacao | producao | Qual Sistema Nacional perguntar. A adesão difere entre os dois: um município pode estar conveniado na produção e não na produção restrita. Pergunte pelo ambiente onde a nota vai sair. Sem o parâmetro, segue o ambiente da chave de API. |
200 401 403 422 429 502 503
GET/v1/municipios/{ibge}/servicos/{codigo}/aliquota
O município administra este código de serviço?
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
ibge * | path | string | Código do município de incidência do ISSQN no IBGE, 7 dígitos. |
codigo * | path | string | Código de tributação nacional (cTribNac), 6 dígitos: item, subitem e desdobro nacional. Ex.: 171201 para o subitem 17.12. |
competencia | query | string (date) | Data da competência, AAAA-MM-DD. Em branco, o motor usa hoje no fuso de Brasília. A lista de códigos muda por competência, então a resposta vale para a data perguntada. |
ambiente | query | homologacao | producao | Qual Sistema Nacional perguntar. Sem o parâmetro, segue o ambiente da chave de API. |
200 401 403 422 429 502 503
* obrigatório.