Teste de API¶

Em uma frase. Cole o JSON de uma NF-e sem impostos e veja o processo inteiro da emissão calculada: natureza de cada item, conversa com o motor de cálculo, impostos, totais, XML e DANFE.

Quem usa: equipe de integração do ERP, consultoria fiscal, suporte · Frequência: na implantação da integração e ao investigar uma nota que saiu com imposto diferente do esperado · Pré-requisitos: emitente cadastrado com certificado, naturezas de operação cadastradas e perfil owner, admin ou operator no motor de cálculo

Para que serve¶

A emissão calculada (POST /api/v1/nfe/emissao-calculada) recebe a NF-e no mesmo formato da integração, mas sem impostos: o motor de cálculo tributa cada item. Esta tela faz a mesma chamada que o ERP faria e mostra, etapa por etapa, o que aconteceu — inclusive onde parou quando algo é recusado.

Nas ações Calcular e Gerar XML nada é gravado nem enviado à SEFAZ.

Como chegar¶

No Hub, abra o app Invent Docs Flow NF-e.
Selecione o tile Teste de API.

A tela¶

À esquerda fica o editor do request; à direita, a prévia. Arraste a barra entre os dois para ajustar as larguras (a tela lembra a sua escolha). Em telas estreitas os dois ficam um embaixo do outro.

Editor¶

A tela abre vazia. Importe um XML de NF-e (ou cole o JSON do request) para começar.

Importar XML: escolha o arquivo e o tipo de preço. A tela mostra uma linha por item com o CFOP do XML, a natureza encontrada pelo CFOP e o preço que vai no request. Quando o CFOP tem mais de uma natureza, ou nenhuma, a linha fica em destaque: escolha a natureza antes de executar.

O request vem com numero: 0, e não com o número da nota original. No Autorizar, o número sai da série ativa do emitente (Configuração → Séries). Se a série do request não for a ativa, ou se não houver série ativa, a API recusa e diz o que ajustar.

Botão	O que faz
Importar XML	Escolhe um XML de NF-e (de saída ou de entrada própria) e monta o request a partir dele, sem os impostos
Preço	Bruto (vUnCom do XML) ou Líquido (`preco_contem_impostos: true` e o preço sem ICMS, PIS e COFINS). Trocar refaz o request do XML importado
Formatar	Reindenta o JSON (e acusa erro de sintaxe)
Copiar cURL	Copia a chamada pronta para o terminal, sem o token
Ação	Calcular, Gerar XML ou Autorizar (homologação)
Executar	Chama a API e preenche a prévia

Autorizar só funciona com tipo_ambiente: 2 (homologação) e pede confirmação. Autorização em produção é feita pela API, não pela tela.

Abas da prévia¶

Aba	Conteúdo
Resumo	Emitente, destinatário, natOp, ambiente, totais (vProd, ICMS, IPI, PIS, COFINS, IBS, CBS, vNF e vNFTot), avisos e alertas
Fluxo	Linha do tempo das etapas: contrato, emitente, natureza, motor, preço e vProd, totais, validação, XML e autorização — com status e duração. A etapa que falhou fica marcada
Itens e impostos	Cada item com natureza → CFOP, quantidade, preço e vProd; por tributo, CST, base, alíquota, valor e a origem (regra do motor, `tipi:<NCM>` ou `regime:real`)
De-para	Para cada tag da NF-e: o valor do request, o do motor e o da nota
Motor	Por item, o payload enviado ao motor e a resposta dele, com a latência
XML	O XML gerado (sem assinatura em Gerar XML; o nfeProc em Autorizar), indentado para leitura. Copiar e baixar levam o XML como veio da API, sem a indentação
DANFE	Prévia do PDF, sem valor fiscal, desenhada na própria tela; Baixar PDF salva o arquivo
Resposta	O JSON da API como chegou
Comparar com XML	Cole ou carregue um XML esperado (por exemplo, a NF-e autorizada) e veja a comparação tag a tag

Comparar com XML¶

Execute Gerar XML.
Na aba Comparar com XML, o XML importado no editor já vem carregado; se quiser, cole outro ou carregue um arquivo.
Clique em Comparar.

O contador mostra quantas tags estão iguais, dentro da tolerância (padrão R$ 0,01) e diferentes. Ficam de fora chave, cNF, nNF, dhEmi, assinatura e protocolo, que mudam por natureza. A comparação roda no navegador: o XML colado não é enviado ao servidor.

Histórico¶

Toda execução feita pela tela é guardada no seu histórico (outros usuários não o veem): data, ação, status, emitente → destinatário e valor. Clique para reabrir o request e o resultado. Dá para renomear, fixar e excluir. Ficam os 50 testes mais recentes, além dos fixados.

Preço bruto ou líquido¶

Sem preco_contem_impostos (ou false): valor_unitario_comercial é o vUnCom da nota.
Com true: é o preço líquido, sem ICMS, PIS e COFINS; o motor embute os tributos e o vProd sai das bases calculadas. Arredondamentos diferentes do ERP podem deixar uma base R$ 0,01 longe do XML do ERP — a aba Fluxo avisa (GROSSUP_DIVERGENTE).

Regras de negócio¶

A natureza de operação é por item (transacao_negocio, por exemplo T117); o natOp da nota é o nome da natureza do primeiro item, salvo quando o request informa natureza_operacao.
O motor é chamado um documento por item, para cada item casar com a própria regra.
O cálculo usa a rota de produção do motor e segue a configuração do tenant.
Os totais saem sempre dos itens; o vNFTot é o vNF somado de IBS, CBS e IS.
Sem pagamentos, a nota leva um pagamento "99 — Outros" no valor do vNF.
Autorizar exige referencia_externa: repetir o pedido devolve a nota já emitida.

O que esta tela não faz¶

Não autoriza em produção: na tela, só homologação. Em produção, use a API.
Não grava nada nas ações Calcular e Gerar XML, nem consome numeração da série.
Não envia o XML colado em Comparar com XML ao servidor.
Não aceita impostos no request: quem tributa é o motor de cálculo.

Erros comuns¶

Código	O que significa
`NATUREZA_NAO_ENCONTRADA`	A `transacao_negocio` do item não existe no cadastro de naturezas
`EMITENTE_NAO_CADASTRADO`	O CNPJ do emitente não é empresa do tenant
`SEM_REGRA_FISCAL`	O motor não encontrou regra para o item (confira natureza, NCM, origem e UFs)
`IMPOSTO_INFORMADO`	O request trouxe impostos — na emissão calculada só `icms_origem` e o II da importação são lidos
`PAGAMENTO_SEM_VALOR`	Há mais de um pagamento e algum está sem valor — só um pagamento único pode ir sem valor
`XML_ILEGIVEL`	O arquivo importado não é uma NF-e que o app consegue ler
`MOTOR_TIMEOUT`	O motor não calculou todos os itens no prazo — tente de novo
`MOTOR_SEM_PERMISSAO`	Seu perfil precisa ser owner, admin ou operator no motor de cálculo
`MOTOR_INDISPONIVEL`	O motor de cálculo não respondeu

A lista completa, com a causa e como resolver cada código, está no documento técnico da Emissão calculada.