Webhooks

Um webhook é uma notificação que a Focus envia ao seu sistema quando um evento acontece — em vez de você consultar a API repetidamente (polling) para saber se uma nota foi autorizada, você cadastra uma URL e a Focus chama ela assim que o evento ocorre. É o mecanismo recomendado para acompanhar o ciclo assíncrono dos documentos fiscais.

Como cadastrar

O cadastro de um gatilho é feito pela API de Webhooks:

POST /v2/hooks — cria um gatilho que passa a receber as notificações de um evento.
GET /v2/hooks — lista os gatilhos cadastrados.
GET /v2/hooks/{id} — consulta um gatilho específico.
DELETE /v2/hooks/{id} — remove um gatilho.

Campos do cadastro (POST /v2/hooks):

Campo	Obrigatório	Descrição
`event`	Sim	Evento a ser monitorado (ver tabela abaixo).
`url`	Sim	URL do seu sistema que receberá as notificações.
`cnpj`	—	CNPJ da empresa.
`cpf`	—	CPF do prestador de serviço.
`authorization`	—	Valor enviado no cabeçalho de autorização da chamada.
`authorization_header`	—	Nome do cabeçalho HTTP usado para enviar o `authorization`.

📘
Proteja sua URL de recebimento
Use authorization + authorization_header para que a Focus envie um cabeçalho de autenticação na chamada ao seu endpoint. Assim seu sistema valida que a notificação veio da Focus, e não de um terceiro.

Eventos disponíveis

Cada gatilho monitora um evento. Os eventos cobrem três grupos: autorização de documentos emitidos, recebimento de documentos de terceiros, e eventos específicos da NFC-e.

Autorização de documentos emitidos

Disparados quando o documento é autorizado. A notificação traz os mesmos dados da consulta GET do documento.

Evento	Documento
`nfe`	NF-e (modelo 55) autorizada.
`nfce`	NFC-e (modelo 65) autorizada.
`nfse`	NFS-e municipal autorizada.
`nfsen`	NFS-e Nacional autorizada.
`cte`	CT-e autorizado.
`mdfe`	MDF-e autorizado.
`nfcom`	NFCom autorizada.
`inutilizacao`	Inutilização de numeração concluída.
`dce`	DC-e autorizada.

Recebimento de documentos de terceiros

Notificam quando um documento é recebido em nome da empresa.

Evento	Objetivo
`nfe_recebida`	Recebimento de MDe (notas de produto NF-e modelo 55).
`nfe_recebida_falha_consulta`	Falha nas consultas de MDe (notas de produto NF-e modelo 55).
`cte_recebida`	Recebimento de CT-es.
`nfsen_recebida`	Recebimento de NFS-e Nacional (notas fiscais de serviço nacional recebidas).

Eventos específicos da NFC-e

A NFC-e tem dois eventos próprios ligados à contingência e à consulta automática.

`nfce_contingencia`

Disparado nas situações de contingência e no desfecho da nota original:

NFC-e em contingência efetivada — mesmo quando ainda não se sabe se a nota original foi emitida ou não.
NFC-e em contingência com erro — mesmo quando ainda não se sabe se a nota original foi emitida ou não.
NFC-e original cancelada ou com erro de cancelamento.

Esse evento é o que permite ao seu sistema acompanhar o fecho da contingência offline sem ficar consultando a API.

`nfce_consulta_automatica`

Permite ao cliente assumir o controle da contingência do seu lado, usando outra referência, quando prefere não delegar o processo à API.

Campo da empresa: habilita_consulta_automatica_nfce.

Funcionamento: se a contingência offline estiver desabilitada e habilita_consulta_automatica_nfce = true, a API dispara automaticamente uma consulta da nota sempre que a SEFAZ responder com o erro:

-1 Ocorreu um erro na conexão com o SEFAZ. Por favor tente novamente mais tarde ou contacte o suporte técnico.

Quando a consulta é realizada — com sucesso ou não — a Focus envia o webhook com o evento nfce_consulta_automatica. Com isso, o cliente sabe o desfecho real da nota e pode implementar a contingência offline do próprio lado, emitindo em outra referência.

📘
Dois caminhos para a contingência da NFC-e
A Focus controla: contingência offline habilitada — a API emite offline, retransmite e concilia (cancela ou inutiliza) sozinha, notificando por nfce_contingencia.
O cliente controla: contingência offline desabilitada + habilita_consulta_automatica_nfce = true — a API só dispara a consulta e notifica por nfce_consulta_automatica, e o cliente reemite em outra referência.

Reenvio de notificação

Se seu sistema não recebeu ou não processou uma notificação, cada tipo de documento oferece uma operação de solicitar reenvio da notificação (POST .../hook), disponível em NF-e, NFC-e, NFS-e, NFS-e Nacional, CT-e, MDF-e, NFCom, DC-e e nos documentos recebidos. Use-a para reprocessar um evento perdido sem precisar reemitir o documento.