API atual/Referência completa/Webhooks e eventos

Nota fiscal

Rota que o emissor de NF-e (FocusNFe) chama para informar que uma nota foi autorizada, rejeitada, cancelada, denegada ou inutilizada.

Depois que a loja envia uma NF-e ao emissor, a SEFAZ leva alguns instantes para decidir. Quando decide, o emissor avisa a loja por esta rota, e a loja grava o novo estado da nota (chave de acesso, número, série, links do XML e do DANFE, ou os erros de rejeição). Há duas formas de URL: a primeira escolhe a loja pelo domínio e a segunda pelo identificador no caminho, útil quando a conta do emissor atende uma única URL central.

Loja pelo domínio

POST/api/v1/webhooks/focusnfePública

Receber status de NF-e (loja pelo domínio)

Cabeçalhos

X-Webhook-Secretstring

Segredo de webhook cadastrado no módulo FocusNFe da loja. Pode ser enviado no parâmetro secret da URL, quando o emissor não permite cabeçalhos.

Parâmetros de consulta

secretstring

Alternativa ao cabeçalho X-Webhook-Secret.

Corpo da requisição

refstringobrigatório

Referência da nota, a mesma que a loja enviou ao emitir.

eventostring

nfe.autorizadanfe.canceladanfe.erro_autorizacaonfe.denegadanfe.inutilizada

Evento do emissor. Quando presente, vale mais que status.

statusstring

processandoautorizadoerrocanceladodenegadoinutilizado

Estado da nota, em contas antigas que não enviam evento.

motivostring

Motivo legível da rejeição, nos eventos de erro.

chave_nfestring

Chave de acesso de 44 dígitos (só quando autorizada).

numerostring

Número da nota (só quando autorizada).

seriestring

Série da nota (só quando autorizada).

caminho_xml_nota_fiscalstring

Caminho do XML assinado no emissor.

caminho_danfestring

Caminho do PDF do DANFE no emissor.

errosarray

Erros de rejeição, cada um com codigo e mensagem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/focusnfe" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $FOCUSNFE_WEBHOOK_SECRET" \
  -d '{"ref":"order-3f73310d","evento":"nfe.autorizada","chave_nfe":"35261012345678000195550010000012341000012345","numero":"1234","serie":"1"}'

Resposta

200Processado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo vazio	`{"error":"empty webhook payload"}`
401	Segredo ausente ou errado	`{"error":"unauthorized","detail":"invalid or missing webhook secret"}`
403	Módulo `focusnfe` desligado	`{"error":"module_disabled","module":"focusnfe"}`
404	`ref` desconhecida (o emissor entrega de novo)	`{"error":"unknown_ref"}`
500	Falha ao gravar	`{"error":"failed to process webhook"}`
503	Loja sem segredo de webhook cadastrado	`{"error":"webhook_not_configured","detail":"webhook secret not configured"}`

Loja pelo caminho

Mesmo contrato da rota anterior, mas a loja é escolhida pelo {tenantID} do caminho e não pelo domínio da chamada. Um identificador desconhecido devolve 404.

POST/api/v1/webhooks/focusnfe/{tenantID}Pública

Receber status de NF-e (loja pelo caminho)

Parâmetros de caminho

tenantIDstringobrigatório

Identificador da loja.

Cabeçalhos

X-Webhook-Secretstring

Segredo de webhook cadastrado no módulo FocusNFe da loja. Pode ser enviado no parâmetro secret da URL, quando o emissor não permite cabeçalhos.

Parâmetros de consulta

secretstring

Alternativa ao cabeçalho X-Webhook-Secret.

Corpo da requisição

refstringobrigatório

Referência da nota, a mesma que a loja enviou ao emitir.

eventostring

nfe.autorizadanfe.canceladanfe.erro_autorizacaonfe.denegadanfe.inutilizada

Evento do emissor. Quando presente, vale mais que status.

statusstring

processandoautorizadoerrocanceladodenegadoinutilizado

Estado da nota, em contas antigas que não enviam evento.

motivostring

Motivo legível da rejeição, nos eventos de erro.

chave_nfestring

Chave de acesso de 44 dígitos (só quando autorizada).

numerostring

Número da nota (só quando autorizada).

seriestring

Série da nota (só quando autorizada).

caminho_xml_nota_fiscalstring

Caminho do XML assinado no emissor.

caminho_danfestring

Caminho do PDF do DANFE no emissor.

errosarray

Erros de rejeição, cada um com codigo e mensagem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/focusnfe/store1" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $FOCUSNFE_WEBHOOK_SECRET" \
  -d '{"ref":"order-3f73310d","evento":"nfe.autorizada","chave_nfe":"35261012345678000195550010000012341000012345","numero":"1234","serie":"1"}'

Resposta

200Processado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo vazio	`{"error":"empty webhook payload"}`
401	Segredo ausente ou errado	`{"error":"unauthorized","detail":"invalid or missing webhook secret"}`
403	Módulo `focusnfe` desligado	`{"error":"module_disabled","module":"focusnfe"}`
404	`ref` desconhecida (o emissor entrega de novo)	`{"error":"unknown_ref"}`
500	Falha ao gravar	`{"error":"failed to process webhook"}`
503	Loja sem segredo de webhook cadastrado	`{"error":"webhook_not_configured","detail":"webhook secret not configured"}`

Veja também

Nota fiscal

Rota que o emissor de NF-e (FocusNFe) chama para informar que uma nota foi autorizada, rejeitada, cancelada, denegada ou inutilizada.

Loja pelo domínio

POST/api/v1/webhooks/focusnfePública

Receber status de NF-e (loja pelo domínio)

Cabeçalhos

X-Webhook-Secretstring

Segredo de webhook cadastrado no módulo FocusNFe da loja. Pode ser enviado no parâmetro secret da URL, quando o emissor não permite cabeçalhos.

Parâmetros de consulta

secretstring

Alternativa ao cabeçalho X-Webhook-Secret.

Corpo da requisição

refstringobrigatório

Referência da nota, a mesma que a loja enviou ao emitir.

eventostring

nfe.autorizadanfe.canceladanfe.erro_autorizacaonfe.denegadanfe.inutilizada

Evento do emissor. Quando presente, vale mais que status.

statusstring

processandoautorizadoerrocanceladodenegadoinutilizado

Estado da nota, em contas antigas que não enviam evento.

motivostring

Motivo legível da rejeição, nos eventos de erro.

chave_nfestring

Chave de acesso de 44 dígitos (só quando autorizada).

numerostring

Número da nota (só quando autorizada).

seriestring

Série da nota (só quando autorizada).

caminho_xml_nota_fiscalstring

Caminho do XML assinado no emissor.

caminho_danfestring

Caminho do PDF do DANFE no emissor.

errosarray

Erros de rejeição, cada um com codigo e mensagem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/focusnfe" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $FOCUSNFE_WEBHOOK_SECRET" \
  -d '{"ref":"order-3f73310d","evento":"nfe.autorizada","chave_nfe":"35261012345678000195550010000012341000012345","numero":"1234","serie":"1"}'

Resposta

200Processado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo vazio	`{"error":"empty webhook payload"}`
401	Segredo ausente ou errado	`{"error":"unauthorized","detail":"invalid or missing webhook secret"}`
403	Módulo `focusnfe` desligado	`{"error":"module_disabled","module":"focusnfe"}`
404	`ref` desconhecida (o emissor entrega de novo)	`{"error":"unknown_ref"}`
500	Falha ao gravar	`{"error":"failed to process webhook"}`
503	Loja sem segredo de webhook cadastrado	`{"error":"webhook_not_configured","detail":"webhook secret not configured"}`

Loja pelo caminho

Mesmo contrato da rota anterior, mas a loja é escolhida pelo {tenantID} do caminho e não pelo domínio da chamada. Um identificador desconhecido devolve 404.

POST/api/v1/webhooks/focusnfe/{tenantID}Pública

Receber status de NF-e (loja pelo caminho)

Parâmetros de caminho

tenantIDstringobrigatório

Identificador da loja.

Cabeçalhos

X-Webhook-Secretstring

Segredo de webhook cadastrado no módulo FocusNFe da loja. Pode ser enviado no parâmetro secret da URL, quando o emissor não permite cabeçalhos.

Parâmetros de consulta

secretstring

Alternativa ao cabeçalho X-Webhook-Secret.

Corpo da requisição

refstringobrigatório

Referência da nota, a mesma que a loja enviou ao emitir.

eventostring

nfe.autorizadanfe.canceladanfe.erro_autorizacaonfe.denegadanfe.inutilizada

Evento do emissor. Quando presente, vale mais que status.

statusstring

processandoautorizadoerrocanceladodenegadoinutilizado

Estado da nota, em contas antigas que não enviam evento.

motivostring

Motivo legível da rejeição, nos eventos de erro.

chave_nfestring

Chave de acesso de 44 dígitos (só quando autorizada).

numerostring

Número da nota (só quando autorizada).

seriestring

Série da nota (só quando autorizada).

caminho_xml_nota_fiscalstring

Caminho do XML assinado no emissor.

caminho_danfestring

Caminho do PDF do DANFE no emissor.

errosarray

Erros de rejeição, cada um com codigo e mensagem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/focusnfe/store1" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $FOCUSNFE_WEBHOOK_SECRET" \
  -d '{"ref":"order-3f73310d","evento":"nfe.autorizada","chave_nfe":"35261012345678000195550010000012341000012345","numero":"1234","serie":"1"}'

Resposta

200Processado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo vazio	`{"error":"empty webhook payload"}`
401	Segredo ausente ou errado	`{"error":"unauthorized","detail":"invalid or missing webhook secret"}`
403	Módulo `focusnfe` desligado	`{"error":"module_disabled","module":"focusnfe"}`
404	`ref` desconhecida (o emissor entrega de novo)	`{"error":"unknown_ref"}`
500	Falha ao gravar	`{"error":"failed to process webhook"}`
503	Loja sem segredo de webhook cadastrado	`{"error":"webhook_not_configured","detail":"webhook secret not configured"}`