Fiscal: notas fiscais eletrônicas

No Brasil, toda venda precisa de um documento fiscal eletrônico autorizado pela SEFAZ (a secretaria da fazenda do estado). A NF-e (modelo 55) é a nota entre empresas e para entrega. A NFC-e (modelo 65) é a nota de consumidor, usada no balcão. A plataforma não fala com a SEFAZ diretamente: ela entrega os dados da nota a um provedor de emissão (Focus NFe), que valida, assina e transmite.

Estas são as rotas do administrador da loja para configurar e operar esse fluxo. Tudo gira em torno de uma fila de emissão: cada pedido que precisa de nota entra na fila, um processo em segundo plano emite, e as falhas ficam visíveis para você corrigir e reenviar.

Como funciona

O ciclo de um item da fila

Falhas de comunicação (timeout, erro 5xx) ficam em pending e são tentadas de novo com espera crescente: 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h e 24 h. A oitava falha leva a abandoned. Só failed e abandoned podem ser reenviados à mão.

Fluxo típico de implantação

1. Cadastre o estabelecimento
   POST /establishments com CNPJ, inscrição estadual, UF, endereço e série.
2. Provisione no provedor
   POST /establishments/{id}/provision cria a empresa no provedor. O certificado digital é enviado ao provedor, não à plataforma.
3. Configure perfis e CFOP
   Crie perfis fiscais, atribua-os a produtos, categorias ou prefixos de NCM e ajuste a matriz de CFOP.
4. Limpe o catálogo
   GET /catalog-issues lista produtos sem NCM ou com NCM inválido.
5. Escolha o gatilho
   PUT /settings com on_paid, on_completed ou on_shipped.
6. Acompanhe a fila
   GET /queue?status=failed, corrija a causa e use retry, reemit ou bulk-retry.

Conceitos importantes

Estabelecimento emissor

É o CNPJ que assina a nota: matriz, filial ou loja. O primeiro cadastrado vira o padrão. Na hora de emitir, a plataforma escolhe o emissor nesta ordem: o estabelecimento informado na fila, o estabelecimento ligado ao depósito de onde sai a mercadoria (warehouse_id) e, por fim, o padrão. Cada CNPJ e cada depósito só podem ter um estabelecimento.

Perfil fiscal

Um perfil reúne os códigos de imposto de um tipo de produto: csosn (regime Simples Nacional), icms_cst (regime normal), pis_cst, cofins_cst, origem da mercadoria e, se houver substituição tributária, a margem st_mva_bps. Para cada item da nota vale o primeiro perfil que casar, nesta ordem: atribuído ao produto, à categoria, ao prefixo de NCM (o prefixo mais longo vence) e, por fim, o perfil padrão.

NCM e CEST

O NCM é o código de 8 dígitos que classifica a mercadoria. O CEST é um código adicional exigido quando o produto tem substituição tributária (ICMS ST). Sem NCM válido a nota é rejeitada.

CFOP

O CFOP é o código de 4 dígitos da natureza da operação (5102, 6102...). A matriz de CFOP escolhe o código pelo tipo de operação, pelo destinatário e por a venda ser dentro do estado (intra) ou entre estados (inter).

O assistente fiscal

Quando uma nota é rejeitada, ou quando uma varredura do catálogo acha produtos sem NCM, o assistente registra uma ação proposta (por exemplo "corrigir o NCM deste produto"). Nada muda no catálogo sem a sua aprovação. Veja Ações do assistente.

Endpoints

Erros comuns

1. Esperar emissão automática sem configurar o gatilho. O padrão é manual. Até você gravar on_paid, on_completed ou on_shipped, nenhum pedido entra na fila sozinho.
2. Reenviar um item que já foi autorizado ou que ainda está em andamento. Só failed e abandoned aceitam reenvio; os outros devolvem 422.
3. Reenviar sem corrigir a causa. Um failed por NCM inválido falha de novo. Conserte o produto (veja Validação prévia) e só então reenvie.
4. Usar PUT como se fosse um PATCH. Em estabelecimentos, perfis e na configuração de emissão o PUT regrava os campos enviados e zera os omitidos (endereço, CST, email_customer). Reenvie o objeto inteiro.
5. Cadastrar o CNPJ com e sem pontuação. O CNPJ é gravado como veio; 11.222.333/0001-81 e 11222333000181 são tratados como valores diferentes. Use sempre só os dígitos.
6. Apagar o estabelecimento padrão. A API recusa com 409. Promova outro (PUT com is_default: true) antes.
7. Mandar order_id vazio na validação. Devolve 500 em vez de 400.

Próximos passos