Operações da API de NFC-e

A API de NFC-e (Nota Fiscal de Consumidor Eletrônica, modelo 65) permite emitir, consultar, cancelar e inutilizar notas em todos os estados do país. Todos os processos são síncronos: a nota é autorizada ou rejeitada na mesma requisição, sem polling.

Esta página lista as operações disponíveis, o que cada uma faz e quando usá-la. Para o detalhe de campos de cada requisição, consulte a página de referência da operação.

📘
Base de todas as chamadas
As operações usam a URL base https://api.focusnfe.com.br/v2 (produção) ou https://homologacao.focusnfe.com.br/v2 (homologação), autenticação HTTP Basic com o token no usuário e a senha em branco, e corpo em JSON.

Emissão e ciclo de vida da nota

Emitir — POST /nfce?ref={ref}. Cria a NFC-e e a envia para processamento. O parâmetro ref (referência única da nota no seu sistema) é obrigatório e é por ele que você consulta ou cancela a nota depois. A numeração é definida automaticamente pela API; para controlar à mão, informe numero e serie no corpo. A resposta traz status (autorizado ou erro_autorizacao), a chave_nfe, o qrcode_url, a url_consulta_nf e o caminho da DANFCe (em .html).

Consultar — GET /nfce/{ref}. Retorna o status de processamento da nota, com os caminhos de download do XML e da DANFCe, QR Code e dados de eventos. Use ?completa=1 para incluir toda a requisição e o protocolo de autorização na resposta.

Cancelar — DELETE /nfce/{ref}. Cancela uma NFC-e já autorizada. O cancelamento só é possível em até 30 minutos após a emissão e exige o campo justificativa com 15 a 255 caracteres.

Enviar NFC-e por email — POST /nfce/{ref}/email. Envia uma cópia da nota por email para os destinatários informados no campo emails. Limitado a 10 emails por requisição; o envio ocorre em segundo plano.

Numeração

Inutilizar numeração — POST /nfce/inutilizacao. Inutiliza uma faixa de numeração perante a SEFAZ (números que nunca foram usados e nunca serão, por quebra de sequência). Em situação normal a API controla a numeração sozinha e esta operação não é necessária. Exige cnpj, serie, numero_inicial, numero_final e justificativa (mínimo 15 caracteres).

Consultar inutilizações — GET /nfce/inutilizacoes. Lista os XMLs de numerações inutilizadas. Filtra por cnpj ou cpf (um dos dois é obrigatório), por data de recebimento (data_recebimento_inicial / data_recebimento_final) e por faixa (numero_inicial / numero_final).

📘
Cancelar ≠ Inutilizar
Cancelar desfaz uma nota que foi autorizada (existe e tem valor fiscal). Inutilizar descarta uma faixa de números que nunca gerou nota, para justificar o salto na sequência perante a SEFAZ.

Conciliação Financeira (ECONF)

Evento facultativo que registra a conciliação entre as informações financeiras e o documento fiscal. Todas as operações são síncronas.

Registrar ECONF — POST /nfce/{ref}/econf. Registra o evento para uma NFC-e autorizada. O corpo leva o array detalhes_pagamento (até 100 detalhes), cada um com forma_pagamento, valor_pagamento e data_pagamento obrigatórios. A resposta devolve o numero_protocolo, usado para consultar ou cancelar o evento.

Consultar ECONF — GET /nfce/{ref}/econf/{numero_protocolo}. Consulta um evento de conciliação já registrado pelo número de protocolo.

Cancelar ECONF — DELETE /nfce/{ref}/econf/{numero_protocolo}. Cancela um evento de conciliação. Quando há mais de um evento, o cancelamento deve seguir a ordem dos envios (do mais antigo ao mais recente).

Resumo das operações

Operação	Método e rota	Para quê
Emitir	`POST /nfce?ref={ref}`	Criar e autorizar a nota
Consultar	`GET /nfce/{ref}`	Ver status, XML, DANFCe e QR Code
Cancelar	`DELETE /nfce/{ref}`	Cancelar nota autorizada (até 30 min)
Enviar por email	`POST /nfce/{ref}/email`	Enviar cópia por email (até 10)
Inutilizar numeração	`POST /nfce/inutilizacao`	Descartar faixa de números não usada
Consultar inutilizações	`GET /nfce/inutilizacoes`	Listar numerações inutilizadas
Registrar ECONF	`POST /nfce/{ref}/econf`	Registrar conciliação financeira
Consultar ECONF	`GET /nfce/{ref}/econf/{numero_protocolo}`	Consultar o evento de conciliação
Cancelar ECONF	`DELETE /nfce/{ref}/econf/{numero_protocolo}`	Cancelar o evento de conciliação

Fonte: documentação de referência da API de NFC-e da Focus NFe (v2.0).