API atual/Referência completa/Fiscal (NF-e e NFC-e)

Ações do assistente fiscal

Lista as correções propostas pelo assistente fiscal, aprova ou recusa cada uma e dispara a varredura do catálogo.

O assistente fiscal observa três fontes e, quando acha algo a corrigir, registra uma ação proposta, sem alterar nada por conta própria:

uma nota rejeitada pela SEFAZ (trigger_kind: rejection_event), com a explicação do código de rejeição;
o monitor de certificado digital (cert_monitor), que alerta sobre estabelecimento sem empresa provisionada ou certificado perto de vencer;
a varredura do catálogo (catalog_scan), que você dispara à mão.

Nada muda no catálogo ou na fila até uma pessoa aprovar. Uma ação não aprovada expira em 7 dias. Exigem o módulo focusnfe e o privilégio manage_nfe, manage_taxes ou manage_settings. O nível de iniciativa do assistente é ajustado em Autonomia do assistente.

Proposta→Aprovada→Aplicada

`status`	Significado
`proposed`	Aguardando decisão.
`approved`	Aprovada, em aplicação. Estado passageiro.
`applied`	Aplicada.
`rejected`	Recusada por uma pessoa.
`expired`	Ninguém decidiu em 7 dias.
`invalidated`	O dado mudou depois da proposta (por exemplo, o NCM foi editado), então a correção foi descartada.
`failed`	A aplicação falhou (por exemplo, proposta sem valor).

`action_type`	O que acontece ao aprovar
`fix_ncm`, `fix_cest`	Grava o valor de `proposal.proposed` no NCM ou CEST do produto `target_id`. Recusa valor vazio.
`retry_emission`	Reenvia o item da fila `target_id`, marcando a origem como `agent`.
`diagnostic`, `cert_alert`, `resend_email`, `fix_customer_ie`, `fix_customer_address`, `fix_profile`	Nenhuma mudança automática: servem de alerta ou explicação para uma pessoa resolver.

Listar ações

Devolve as ações, as mais novas primeiro.

GET/api/v1/admin/fiscal/agent/actionsAdmin

Lista as ações do assistente fiscal

Parâmetros de consulta

statusstring

proposedapprovedappliedrejectedexpiredinvalidatedfailed

Filtra pelo estado.

establishment_iduuid

Só ações ligadas a este estabelecimento.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora disso volta para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/fiscal/agent/actions?status=proposed" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ações devolvidas

json

{
  "items": [
    {
      "id": "1f193880-512c-4956-958e-4483230d2fd8",
      "action_type": "fix_ncm",
      "status": "proposed",
      "trigger_kind": "rejection_event",
      "nfe_record_id": "9c2e7a14-3b5d-4f60-8a1e-6d0b4c8f2e73",
      "rejection_code": "778",
      "target_entity": "product",
      "target_id": "e3a71800-294f-4167-a755-cabedcf094b4",
      "evidence": {
        "rejection_code": "778",
        "message": "Rejeição 778: NCM inválido",
        "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68"
      },
      "proposal": {
        "field": "ncm_code",
        "current": "",
        "proposed": "84716052",
        "reason": "Sugestão baseada nos produtos similares do próprio catálogo (mesma categoria)."
      },
      "precondition": { "products.ncm_code": "" },
      "created_at": "2026-10-10T14:02:20Z",
      "expires_at": "2026-10-17T14:02:20Z"
    }
  ],
  "total": 1
}

Campos da resposta

itemsarray

Ações da página. Pode vir null quando vazio.

totalinteger

Total que casa com os filtros.

iduuid

Id da ação.

action_typestring

Tipo, conforme a tabela acima.

statusstring

Estado da ação.

trigger_kindstring

rejection_eventcert_monitorcatalog_scan

O que originou a ação.

nfe_record_iduuid

Nota relacionada, quando houver.

queue_item_iduuid

Item da fila relacionado, quando houver.

establishment_iduuid

Estabelecimento relacionado, quando houver.

target_entitystring

Tipo do alvo da correção (product). Ausente quando não há alvo.

target_iduuid

Alvo da correção. Ausente quando não há.

rejection_codestring

Código de rejeição da SEFAZ que originou a ação, quando houver.

evidenceobject

Por que a ação foi proposta (mensagem, pedido, nome do produto...). O formato varia por tipo.

proposalobject

A correção sugerida: field, current, proposed e reason. Vazio ({}) nas ações só informativas.

preconditionobject

Condição que precisa continuar verdadeira para aplicar, por exemplo {"products.ncm_code": ""}. Se o campo mudou, a ação é invalidated.

created_atstring

Criação, RFC 3339.

expires_atstring

Quando expira se ninguém decidir, RFC 3339.

Erros

Status	Quando	Corpo
500	Falha de consulta	`{"error":"failed to list actions","detail":"..."}`
401 / 403	Sem token, sem privilégio, módulo desligado	`{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_taxes","manage_settings"]}`

Varrer o catálogo

Procura produtos sem NCM ou com NCM inválido e registra uma ação proposed para cada um, sem esperar o próximo ciclo automático. Produtos que já têm uma ação proposta do mesmo tipo são pulados, então rodar de novo não duplica.

POST/api/v1/admin/fiscal/agent/scan-catalogAdmin

Varre o catálogo e propõe ações

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/agent/scan-catalog" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Varredura concluída

json

{ "created": 120 }

Campos da resposta

createdinteger

Quantas ações novas foram registradas.

Erros

Status	Quando	Corpo
500	Falha ao varrer	`{"error":"failed to scan catalog","detail":"..."}`

Aprovar uma ação

Marca a ação como aprovada e a aplica na hora. O que acontece depende do action_type (tabela acima). Se a condição de precondition mudou desde a proposta, a ação é descartada como invalidated.

POST/api/v1/admin/fiscal/agent/actions/{id}/approveAdmin

Aprova e aplica uma ação do assistente

Parâmetros de caminho

iduuidobrigatório

Id da ação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/agent/actions/1f193880-512c-4956-958e-4483230d2fd8/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ação decidida

json

{ "id": "1f193880-512c-4956-958e-4483230d2fd8", "status": "applied" }

Campos da resposta

statusstring

appliedfailedinvalidated

Resultado da aplicação. failed e invalidated também voltam com 200: confira o campo antes de assumir sucesso.

Erros

Status	Quando	Corpo
422	Ação que não existe ou que não está `proposed`	`{"error":"failed to approve","detail":"fiscal: action not found or not pending"}`

Recusar uma ação

Marca a ação como rejected, com um motivo opcional. Nada é alterado no catálogo.

POST/api/v1/admin/fiscal/agent/actions/{id}/rejectAdmin

Recusa uma ação do assistente

Parâmetros de caminho

iduuidobrigatório

Id da ação.

Corpo da requisição (opcional)

reasonstring

Motivo da recusa, guardado junto da ação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/agent/actions/1f193880-512c-4956-958e-4483230d2fd8/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "O NCM sugerido não é o do fabricante" }'

Resposta

200Ação recusada

json

{ "id": "1f193880-512c-4956-958e-4483230d2fd8", "status": "rejected" }

Erros

Status	Quando	Corpo
422	Falha ao gravar (por exemplo, id que não é UUID)	`{"error":"failed to reject","detail":"..."}`

Veja também

API atual/Referência completa/Fiscal (NF-e e NFC-e)

Ações do assistente fiscal

Lista as correções propostas pelo assistente fiscal, aprova ou recusa cada uma e dispara a varredura do catálogo.

O assistente fiscal observa três fontes e, quando acha algo a corrigir, registra uma ação proposta, sem alterar nada por conta própria:

uma nota rejeitada pela SEFAZ (trigger_kind: rejection_event), com a explicação do código de rejeição;
o monitor de certificado digital (cert_monitor), que alerta sobre estabelecimento sem empresa provisionada ou certificado perto de vencer;
a varredura do catálogo (catalog_scan), que você dispara à mão.

Proposta→Aprovada→Aplicada

`status`	Significado
`proposed`	Aguardando decisão.
`approved`	Aprovada, em aplicação. Estado passageiro.
`applied`	Aplicada.
`rejected`	Recusada por uma pessoa.
`expired`	Ninguém decidiu em 7 dias.
`invalidated`	O dado mudou depois da proposta (por exemplo, o NCM foi editado), então a correção foi descartada.
`failed`	A aplicação falhou (por exemplo, proposta sem valor).

`action_type`	O que acontece ao aprovar
`fix_ncm`, `fix_cest`	Grava o valor de `proposal.proposed` no NCM ou CEST do produto `target_id`. Recusa valor vazio.
`retry_emission`	Reenvia o item da fila `target_id`, marcando a origem como `agent`.
`diagnostic`, `cert_alert`, `resend_email`, `fix_customer_ie`, `fix_customer_address`, `fix_profile`	Nenhuma mudança automática: servem de alerta ou explicação para uma pessoa resolver.

Listar ações

Devolve as ações, as mais novas primeiro.

GET/api/v1/admin/fiscal/agent/actionsAdmin

Lista as ações do assistente fiscal

Parâmetros de consulta

statusstring

proposedapprovedappliedrejectedexpiredinvalidatedfailed

Filtra pelo estado.

establishment_iduuid

Só ações ligadas a este estabelecimento.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora disso volta para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/fiscal/agent/actions?status=proposed" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ações devolvidas

json

{
  "items": [
    {
      "id": "1f193880-512c-4956-958e-4483230d2fd8",
      "action_type": "fix_ncm",
      "status": "proposed",
      "trigger_kind": "rejection_event",
      "nfe_record_id": "9c2e7a14-3b5d-4f60-8a1e-6d0b4c8f2e73",
      "rejection_code": "778",
      "target_entity": "product",
      "target_id": "e3a71800-294f-4167-a755-cabedcf094b4",
      "evidence": {
        "rejection_code": "778",
        "message": "Rejeição 778: NCM inválido",
        "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68"
      },
      "proposal": {
        "field": "ncm_code",
        "current": "",
        "proposed": "84716052",
        "reason": "Sugestão baseada nos produtos similares do próprio catálogo (mesma categoria)."
      },
      "precondition": { "products.ncm_code": "" },
      "created_at": "2026-10-10T14:02:20Z",
      "expires_at": "2026-10-17T14:02:20Z"
    }
  ],
  "total": 1
}

Campos da resposta

itemsarray

Ações da página. Pode vir null quando vazio.

totalinteger

Total que casa com os filtros.

iduuid

Id da ação.

action_typestring

Tipo, conforme a tabela acima.

statusstring

Estado da ação.

trigger_kindstring

rejection_eventcert_monitorcatalog_scan

O que originou a ação.

nfe_record_iduuid

Nota relacionada, quando houver.

queue_item_iduuid

Item da fila relacionado, quando houver.

establishment_iduuid

Estabelecimento relacionado, quando houver.

target_entitystring

Tipo do alvo da correção (product). Ausente quando não há alvo.

target_iduuid

Alvo da correção. Ausente quando não há.

rejection_codestring

Código de rejeição da SEFAZ que originou a ação, quando houver.

evidenceobject

Por que a ação foi proposta (mensagem, pedido, nome do produto...). O formato varia por tipo.

proposalobject

A correção sugerida: field, current, proposed e reason. Vazio ({}) nas ações só informativas.

preconditionobject

Condição que precisa continuar verdadeira para aplicar, por exemplo {"products.ncm_code": ""}. Se o campo mudou, a ação é invalidated.

created_atstring

Criação, RFC 3339.

expires_atstring

Quando expira se ninguém decidir, RFC 3339.

Erros

Status	Quando	Corpo
500	Falha de consulta	`{"error":"failed to list actions","detail":"..."}`
401 / 403	Sem token, sem privilégio, módulo desligado	`{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_taxes","manage_settings"]}`

Varrer o catálogo

POST/api/v1/admin/fiscal/agent/scan-catalogAdmin

Varre o catálogo e propõe ações

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/agent/scan-catalog" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Varredura concluída

json

{ "created": 120 }

Campos da resposta

createdinteger

Quantas ações novas foram registradas.

Erros

Status	Quando	Corpo
500	Falha ao varrer	`{"error":"failed to scan catalog","detail":"..."}`

Aprovar uma ação

POST/api/v1/admin/fiscal/agent/actions/{id}/approveAdmin

Aprova e aplica uma ação do assistente

Parâmetros de caminho

iduuidobrigatório

Id da ação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/agent/actions/1f193880-512c-4956-958e-4483230d2fd8/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ação decidida

json

{ "id": "1f193880-512c-4956-958e-4483230d2fd8", "status": "applied" }

Campos da resposta

statusstring

appliedfailedinvalidated

Resultado da aplicação. failed e invalidated também voltam com 200: confira o campo antes de assumir sucesso.

Erros

Status	Quando	Corpo
422	Ação que não existe ou que não está `proposed`	`{"error":"failed to approve","detail":"fiscal: action not found or not pending"}`

Recusar uma ação

Marca a ação como rejected, com um motivo opcional. Nada é alterado no catálogo.

POST/api/v1/admin/fiscal/agent/actions/{id}/rejectAdmin

Recusa uma ação do assistente

Parâmetros de caminho

iduuidobrigatório

Id da ação.

Corpo da requisição (opcional)

reasonstring

Motivo da recusa, guardado junto da ação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/agent/actions/1f193880-512c-4956-958e-4483230d2fd8/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "O NCM sugerido não é o do fabricante" }'

Resposta

200Ação recusada

json

{ "id": "1f193880-512c-4956-958e-4483230d2fd8", "status": "rejected" }

Erros

Status	Quando	Corpo
422	Falha ao gravar (por exemplo, id que não é UUID)	`{"error":"failed to reject","detail":"..."}`