API do Motor de Emissão
Emita NF-e, NFC-e e NFS-e nacional por uma API HTTP com JSON. O motor monta o XML, assina, transmite para a SEFAZ ou para o Sistema Nacional, guarda o documento e avisa o seu sistema por webhook.
Quer ver funcionando? Siga Primeira nota: em uns dez minutos você emite uma NF-e no ambiente simulado, sem certificado digital e sem falar com a SEFAZ.
O que o motor faz e o que fica com você
O motor transmite o que você envia, com os tributos já calculados pelo seu sistema. Ele confere o leiaute e o esquema oficial antes de transmitir, numera, assina, trata contingência, guarda o XML autorizado e gera a DANFE. A regra fiscal (CFOP, CST, alíquotas) é de quem emite.
Ambientes
| Ambiente | O que acontece | Precisa de |
|---|---|---|
simulado | O motor faz tudo, menos falar com a SEFAZ: monta, valida, assina e devolve um protocolo simulado. Os webhooks saem normalmente. É o sandbox. | Chave de teste. Sem certificado, o motor assina com um certificado de teste próprio. |
homologacao | Transmite para o ambiente de homologação da SEFAZ (na NFS-e, a produção restrita do Sistema Nacional). Sem valor fiscal. | Chave de teste e o certificado A1 da empresa. |
producao | Nota de verdade, com valor fiscal. | Chave de produção, certificado A1 e a liberação da emissora pelo operador. |
O ambiente vem do campo ambiente do pedido; sem ele, vale o ambiente_padrao da emissora, que começa em simulado.
Autenticação
Toda chamada leva a chave da conta no cabeçalho:
Authorization: Bearer mtr_teste_...
A chave de teste (mtr_teste_) opera no simulado e em homologação; a de produção (mtr_prod_) opera em todos. A chave de teste você cria no portal, onde também cadastra emissoras, certificado, séries e webhooks; a de produção é entregue pelo operador do motor quando a conta é liberada. Guarde a chave como um segredo: ela não aparece de novo depois de criada.
Convenções
- Corpo e resposta em JSON (UTF-8). Os grupos da nota usam os nomes do leiaute oficial (
ide,dest,det,prod,imposto...), com valores como texto, do jeito que vão no XML. - A emissão é assíncrona: a resposta é
202com o documento emprocessando. O desfecho chega por webhook ou pela consulta do documento. - Mande
Idempotency-Keynas emissões: repetir o mesmo pedido com a mesma chave devolve o documento já criado, sem nota em dobro. - Erros saem em
application/problem+jsoncom umcodigoestável, a mensagem em português emtitlee, quando há, ocampo, aacaosugerida e a listaerros(um item por campo). Veja o catálogo de erros. - Toda resposta traz
X-Request-Id. Informe esse valor ao suporte quando algo der errado. - Há limite de requisições por minuto por conta; passou, a resposta é
429comRetry-After.
Guias
- Primeira nota: chave, emissora, NF-e e NFS-e no simulado, XML e DANFE.
- Cancelamento e eventos: cancelar, carta de correção e inutilização.
- Webhooks: receber o desfecho e conferir a assinatura.
- Erros: cada código, quando aparece e o que fazer.
- Referência: todas as rotas, gerada do contrato OpenAPI.