Conceitos#

Conta, chave de API e empresas#

Uma chave só enxerga as empresas da própria conta. Se o seu ERP atende várias lojas (ou vários CNPJs), cadastre cada CNPJ como uma empresa e diga qual emite em cada chamada com cnpj_emitente. Quem tem uma única empresa pode omitir o campo.

Ambiente: homologação e produção#

Cada empresa está em um de dois ambientes:

• Homologação: a SEFAZ de teste. As notas não têm valor fiscal, têm numeração própria e levam o texto obrigatório de homologação. É onde toda empresa nasce.
• Produção: notas reais, com valor jurídico. A troca é por PUT /empresas/{cnpj}/ambiente e só libera com certificado válido, inscrição estadual e as tabelas fiscais da plataforma validadas (detalhes).

As notas ficam presas ao ambiente em que foram emitidas. Ao passar para produção você pode reaproveitar as mesmas ref: na produção elas começam do zero. As consultas olham sempre o ambiente atual da empresa.

A ref: identificador da nota e proteção contra duplicidade#

Toda emissão leva uma ref na URL (POST /nfe?ref=PEDIDO-1001). É um texto seu, de 1 a 60 caracteres (letras, números, ponto, hífen e sublinhado), único por empresa e ambiente. Use o identificador da venda no seu sistema.

A ref faz três coisas:

1. Idempotência. Se a rede cair e você repetir o POST com a mesma ref e o mesmo conteúdo, recebe o estado da nota que já existe, sem emitir outra. É seguro repetir à vontade.
2. Consulta. Você acompanha e opera a nota por ela: GET /nfe/{ref}, DELETE /nfe/{ref}...
3. Correção. Uma nota rejeitada pela SEFAZ aceita o reenvio corrigido na mesma ref, com o mesmo número fiscal.

Detalhes das regras de reenvio em Emitir NF-e.

Estados da nota#

O campo status da nota é um destes:

                 ┌─────────────── erro_autorizacao ◄──────┐
                 │               erro_validacao           │ (reenvio corrigido, mesma ref)
 POST /nfe ─► processando_autorizacao ─► autorizado ─► cancelado
                 │                                   (DELETE /nfe/{ref})
                 └─────────────► denegado

O que é síncrono e o que não é#

A API valida na hora tudo o que dá para validar sem a SEFAZ e responde 422 antes de gastar um número da série: formato, campos que faltam, tributos que o motor não consegue calcular, totais que não fecham, certificado vencido, produção bloqueada. Quando o POST /nfe responde 202, a nota foi aceita e já tem número reservado.

Daí em diante tudo o que depende da SEFAZ é assíncrono: emitir, cancelar, corrigir e inutilizar respondem 202 e o resultado chega depois. Você escolhe como saber dele:

• Webhook (recomendado): a plataforma chama o seu endereço a cada mudança de estado. Veja Webhooks.
• Consulta (polling): GET /nfe/{ref} até o status ficar final. Comece a cada 2 segundos e aumente o intervalo.
• Os dois juntos: webhook para reagir rápido e uma consulta periódica das notas pendentes como rede de segurança. É o que recomendamos em produção.

O que a plataforma calcula por você#

Você informa a venda (destinatário, itens, valores, pagamento). A plataforma:

• calcula ICMS, DIFAL, FCP, PIS, COFINS, IPI e IBS/CBS conforme o regime da empresa e a operação, e define o CFOP;
• monta o XML no leiaute oficial, assina com o certificado da empresa e valida contra o XSD;
• reserva o número da NF-e em sequência, sem buracos nem duplicidade, mesmo com várias lojas emitindo ao mesmo tempo;
• envia, trata as respostas da SEFAZ (inclusive timeouts: antes de reenviar ela consulta a chave, para nunca emitir uma nota duplicada) e gera o DANFE.

Se o seu ERP já calcula os tributos, você pode informá-los por item (CFOP, situação tributária, alíquotas) e a plataforma passa a usar o que você mandou: é o modo híbrido. Os valores de imposto (base de cálculo, valor do ICMS...) são sempre calculados pela API.

Responsabilidade fiscal: os parâmetros que você informa valem mais que as regras da plataforma, e a responsabilidade por eles é sua. Cenários que o motor ainda não cobre (por exemplo ICMS-ST como substituto) são recusados com 422 validacao_fiscal, em vez de a plataforma "chutar".

Vem do Focus NFe?#

A API segue o mesmo estilo (chave por HTTP Basic ou Bearer, ref na query, items[], nomes como nome_destinatario e codigo_ncm, cnpj_emitente, DELETE /nfe/{ref} com justificativa, POST /nfe/inutilizacao), então boa parte de um cliente já escrito para ele pode ser reaproveitada. Mas não é um clone: confira estas diferenças antes.