Motor de Emissão

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)TipoDescrição
ambiente_padraoAmbiente
cnpjstringObrigatório na criação; não muda depois.
crtinteger
email_automaticobooleanManda 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.
enderecoEndereco
inscricao_estadualstringSó números ou ISENTO.
inscricao_municipalstring
municipio_ibgestring
nome_fantasiastring
prazo_cancelamento_nfce_minintegerPrazo 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_socialstring
ufstring

201 400 401 403 409 422 429

GET/v1/emissoras/{id}

ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 429

PATCH/v1/emissoras/{id}

Altera só os campos enviados. O CNPJ não muda.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (application/json)TipoDescrição
ambiente_padraoAmbiente
cnpjstringObrigatório na criação; não muda depois.
crtinteger
email_automaticobooleanManda 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.
enderecoEndereco
inscricao_estadualstringSó números ou ISENTO.
inscricao_municipalstring
municipio_ibgestring
nome_fantasiastring
prazo_cancelamento_nfce_minintegerPrazo 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_socialstring
ufstring

200 400 401 403 404 422 429

GET/v1/emissoras/{id}/certificado

ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 429

PUT/v1/emissoras/{id}/certificado

Envia o certificado A1. A senha só é usada para abrir o arquivo; a chave e a cadeia ficam cifradas e nunca voltam pela API.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (multipart/form-data)TipoDescrição
arquivo *string (binary)
senha *string (password)

200 400 401 403 404 413 415 422 429

GET/v1/emissoras/{id}/csc

ParâmetroEmTipoDescrição
id *pathstring (uuid)
ambientequerysimulado | homologacao | producao

200 401 403 404 422 429

PUT/v1/emissoras/{id}/csc

Guarda o CSC da NFC-e da emissora, por ambiente. O CSC e o identificador saem do credenciamento na SEFAZ do estado; as URLs do QR Code e da consulta pela chave saem do manual da mesma SEFAZ, porque mudam por UF e por ambiente. O segredo fica cifrado e nunca volta.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (application/json)TipoDescrição
ambiente *simulado | homologacao | producao
csc *string (password)
identificador *integer
url_chave *stringEndereç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

Números abaixo do próximo que não têm nota concluída nem inutilização (até 500).
ParâmetroEmTipoDescrição
id *pathstring (uuid)
modeloquery55 | 65
seriequeryinteger
ambiente *queryAmbiente

200 401 403 404 422 429

GET/v1/emissoras/{id}/series

ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 429

PUT/v1/emissoras/{id}/series

Define o próximo número de cada série. Número já emitido não volta.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (application/json)TipoDescrição
series *lista de SerieEntrada

200 400 401 403 404 422 429

documentos

GET/v1/documentos/{id}

ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 429

POST/v1/documentos/{id}/cancelamento

Pede o cancelamento da nota autorizada. Devolve 202 com o evento em processando; o desfecho chega pelos webhooks documento.cancelado e evento.registrado (ou evento.rejeitado). A autorizadora recusa cancelamento fora do prazo da UF.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (application/json)TipoDescrição
justificativa *string
motivo1 | 2 | 9Có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

Registra uma carta de correção (até 20 por nota; vale a última).
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (application/json)TipoDescrição
correcao *string

202 400 401 403 404 409 422 429

GET/v1/documentos/{id}/email

ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 429

POST/v1/documentos/{id}/email

Envia o PDF e o XML da nota por e-mail

Nota autorizada ou cancelada, com XML (a NFS-e simulada não tem). O envio vai pela fila e é repetido se o servidor de e-mail falhar; a situação aparece no GET desta rota. Sem servidor de e-mail configurado no motor, responde 503 EMAIL_INDISPONIVEL.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (application/json)TipoDescrição
destinatarios *lista de string (email)

202 400 401 403 404 409 422 429 503

GET/v1/documentos/{id}/eventos

ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 429

GET/v1/documentos/{id}/pdf

Documento auxiliar da nota autorizada, em PDF, com o código de barras da chave (DANFE na NF-e, DANFSe na NFS-e).
ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 409 429

GET/v1/documentos/{id}/xml

XML autorizado (nfeProc, com o protocolo), guardado por cinco anos.
ParâmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 409 429

POST/v1/inutilizacoes

Inutiliza uma faixa sem nota autorizada (números sem nota ou com nota rejeitada). O próximo número da série passa para depois da faixa.
Corpo (application/json)TipoDescrição
ambienteAmbiente
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âmetroEmTipoDescrição
id *pathstring (uuid)

200 401 403 404 429

POST/v1/nfce

Recebe o cupom (modelo 65) e devolve 202 com o documento em `processando`. O corpo é o mesmo da NF-e. A emissora precisa de CSC no ambiente, porque o QR Code do cupom é assinado com ele. A transmissão à SEFAZ ainda não está ligada: por ora só o ambiente simulado.
ParâmetroEmTipoDescrição
Idempotency-Keyheaderstring
Corpo (application/json)TipoDescrição
ambienteAmbiente
contingenciaSó 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.
destobject
det *lista de object
emissora_id *string (uuid)
id_externostring
ide *object
infAdicobject
numerointegerNú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
serieinteger
simulacaoobjectSó no ambiente simulado. Escolhe o desfecho.
substituistring (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
transpobject

200 202 400 401 403 404 409 413 415 422 429

POST/v1/nfe

Recebe a NF-e e devolve 202 com o documento em `processando`. O desfecho chega por webhook e por GET /v1/documentos/{id}. Com a mesma `Idempotency-Key` e o mesmo corpo, devolve 200 com o documento já criado.
ParâmetroEmTipoDescrição
Idempotency-Keyheaderstring
Corpo (application/json)TipoDescrição
ambienteAmbiente
contingenciaSó 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.
destobject
det *lista de object
emissora_id *string (uuid)
id_externostring
ide *object
infAdicobject
numerointegerNú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
serieinteger
simulacaoobjectSó no ambiente simulado. Escolhe o desfecho.
substituistring (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
transpobject

200 202 400 401 403 404 409 413 415 422 429

POST/v1/nfse

Recebe a DPS (Declaração de Prestação de Serviços) no leiaute nacional da NFS-e e devolve 202 com o documento em `processando`. O motor preenche tpAmb, dhEmi, verAplic, serie, nDPS, cLocEmi, o grupo prest (inclusive regTrib pelo CRT) e o Id. A chave de acesso da NFS-e vem do Sistema Nacional depois de gerada. O ambiente `homologacao` usa a produção restrita do Sistema Nacional.
ParâmetroEmTipoDescrição
Idempotency-Keyheaderstring
Corpo (application/json)TipoDescrição
IBSCBSobject
ambienteAmbiente
dCompetstringCompetência (AAAA-MM-DD); padrão é a data de emissão.
emissora_id *string (uuid)
id_externostring
intermobject
numerointegerNú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.
serieinteger
serv *object
simulacaoobjectSó 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.
substobjectMotivo da substituição (cMotivo 01 a 05 ou 99, e xMotivo). Só com substitui.
substituistring (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).
tomaobject
tpEmit1 | 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

O segredo de assinatura aparece só nesta resposta.
Corpo (application/json)TipoDescrição
eventos *lista de TipoDeEvento
url *string (uri)

201 400 401 403 422 429

DELETE/v1/webhooks/{id}

ParâmetroEmTipoDescrição
id *pathstring (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

Documentos emitidos contra o CNPJ da emissora, pela distribuição de DF-e do Ambiente Nacional (NT 2014.002). O motor não guarda o NSU nem os documentos: quem integra guarda o cursor e repete enquanto ultimo_nsu for menor que max_nsu. Quando a distribuição chega ao fim, ou a SEFAZ acusa consumo indevido (656), a resposta traz consultar_depois_de e o motor recusa nova consulta da emissora até lá com 429, porque antes disso a SEFAZ bloqueia o CNPJ por uma hora.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
ambiente *queryAmbiente
ultimo_nsuquerystringÚ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

NFS-e e eventos em que o CNPJ da emissora aparece (emitente, tomador ou intermediário), pela distribuição do Ambiente de Dados Nacional (ADN), com o certificado da emissora. O motor não guarda o NSU nem os documentos: quem integra guarda o cursor (ultimo_nsu) e repete enquanto vierem documentos. Um documento pode vir de novo; guarde pela chave. Quando o ADN responde numa forma que o motor ainda não sabe ler, o corpo dele volta em resposta.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
ambiente *queryAmbiente
ultimo_nsuquerystringÚ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

Manifestação do destinatário no Ambiente Nacional (cOrgao 91). Síncrona e sem registro no motor: a nota é de terceiro. A ciência libera o XML completo na distribuição. Repetir é seguro: a duplicidade (573) volta como registrada, sem protocolo.
ParâmetroEmTipoDescrição
id *pathstring (uuid)
Corpo (application/json)TipoDescrição
ambiente *Ambiente
chave *string
justificativastringObrigató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

Consulta cadastro (CadConsultaCadastro4) na SEFAZ do estado, com o certificado de consulta do motor: inscrições estaduais, se estão habilitadas, razão social, regime e endereço. Serve para conferir emissora e destinatário antes da nota. Não exige emissora. A resposta fica guardada por 6 horas (1 hora quando não há inscrição). Amazonas e Maranhão não oferecem o serviço (CADASTRO_NAO_ATENDIDO). Várias SEFAZ só atendem a consulta de quem emite NF-e no estado; a recusa delas volta 503 CADASTRO_RECUSADO_PELA_SEFAZ.
ParâmetroEmTipoDescrição
cnpj *pathstring
uf *querystringEstado cuja SEFAZ responde. O cadastro é por estado.
ambientequeryhomologacao | producaoPadrã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

Razão social, nome fantasia, situação, atividades, opção pelo Simples e pelo MEI e endereço do CNPJ, com o município em código IBGE: o que preenche a emissora e o tomador sem digitar. Vem dos dados abertos do CNPJ, pela BrasilAPI, atualizados uma vez por mês; a inscrição estadual e a situação no estado são a consulta cadastro (/v1/cadastro/{cnpj}). crt_sugerido é 4 para MEI, 1 para o Simples e 3 para o resto (o 2, excesso de sublimite, a Receita não informa). O quadro de sócios não é devolvido. A resposta fica guardada por 24 horas (1 hora quando o CNPJ não consta).
ParâmetroEmTipoDescrição
cnpj *pathstring

200 401 403 404 422 429 502

documentacao

Guias, referência e catálogo de erros, em HTML, sem chave.

GET/ sem chave

Leva à documentação.

302

GET/docs sem chave

Começo da documentação pública.

200

GET/docs/exemplos/{arquivo} sem chave

Os corpos de exemplo dos guias, prontos para `curl -d @arquivo`. Onde aparece {{emissora_id}}, troque pelo id da emissora.
ParâmetroEmTipoDescrição
arquivo *pathstring

200 404

GET/docs/{pagina} sem chave

Guias, catálogo de erros e esta referência.
ParâmetroEmTipoDescrição
pagina *pathprimeira-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

Visão geral da conta; sem sessão, leva à entrada.

200 303

GET/portal/entrar sem chave

Entrada do portal, com e-mail e senha.

200 303

nfse

GET/v1/municipios/{ibge}/convenio

O município aderiu ao padrão nacional da NFS-e?

Pergunta ao Sistema Nacional se o município tem convênio ativo. Não exige emissora: é a pergunta que vem antes do cadastro, porque é ela que decide se vale a pena cadastrar. O motor usa o certificado dele para perguntar, e nenhum certificado de cliente é tocado. A resposta fica guardada por algumas horas.
ParâmetroEmTipoDescrição
ibge *pathstringCódigo do município no IBGE, com 7 dígitos.
ambientequeryhomologacao | producaoQual 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?

Pergunta ao Sistema Nacional se o município de incidência administra um código de tributação nacional na competência, e com que alíquota. É a pergunta que evita a rejeição E0312, que só aparece no envio da nota e não diz qual código serve no lugar. Não exige emissora: o motor usa o certificado dele para perguntar. A resposta fica guardada por algumas horas.
ParâmetroEmTipoDescrição
ibge *pathstringCódigo do município de incidência do ISSQN no IBGE, 7 dígitos.
codigo *pathstringCódigo de tributação nacional (cTribNac), 6 dígitos: item, subitem e desdobro nacional. Ex.: 171201 para o subitem 17.12.
competenciaquerystring (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.
ambientequeryhomologacao | producaoQual Sistema Nacional perguntar. Sem o parâmetro, segue o ambiente da chave de API.

200 401 403 422 429 502 503

* obrigatório.