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

Validação prévia

Confere se um pedido tem tudo o que a nota exige e lista os produtos do catálogo com NCM faltando ou inválido.

A maioria das rejeições da SEFAZ vem de dados que a loja já poderia ter conferido: produto sem NCM, cliente sem CPF ou CNPJ, endereço incompleto. Estas duas rotas fazem essa conferência antes de emitir. Exigem o módulo focusnfe e o privilégio manage_taxes ou manage_settings.

Validar um pedido

Roda as verificações num pedido e devolve a lista de problemas. Nada é gravado e nenhuma nota é emitida. Os textos dos problemas vêm em português.

GET/api/v1/admin/fiscal/validateAdmin

Confere um pedido antes de emitir a nota

Parâmetros de consulta

order_iduuidobrigatório

Id do pedido. Vazio ou fora do formato UUID devolve 500.

vendor_iduuid

Seller da nota. É aceito, mas hoje não muda o resultado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/fiscal/validate?order_id=615b4147-6cb2-4057-9e25-ee82281b9d68" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedido conferido

json

{
  "can_emit": false,
  "issues": [
    {
      "code": "MISSING_NCM",
      "severity": "error",
      "message": "Produto sem NCM: Teclado Pro Cinza",
      "product_id": "e3a71800-294f-4167-a755-cabedcf094b4",
      "field": "ncm_code"
    },
    {
      "code": "NO_PROFILE",
      "severity": "warning",
      "message": "Nenhum perfil fiscal resolvido para o produto: Mouse Pro Preto, a nota usará os padrões (5102/6102, CSOSN 400).",
      "product_id": "cb60662e-7871-4699-832f-f9a106dd9bac",
      "field": "fiscal_profile"
    }
  ]
}

Campos da resposta

can_emitboolean

true quando não há nenhum problema com severity igual a error. Avisos (warning) não impedem.

issuesarray

Problemas encontrados. É null (não []) quando não há nenhum.

codestring

Código estável do problema (tabela abaixo).

severitystring

errorwarning

error impede a emissão; warning só avisa.

messagestring

Descrição em português.

product_iduuid

Produto envolvido. Ausente nos problemas do pedido ou do cliente.

fieldstring

Campo a corrigir, por exemplo ncm_code. Ausente em alguns casos.

`code`	Gravidade	O que significa e como corrigir
`ZERO_ITEMS`	error	O pedido não tem itens com quantidade positiva. Também é o resultado para um id de pedido que não existe.
`MISSING_NCM`	error	Produto sem NCM. Preencha o NCM no cadastro do produto.
`INVALID_NCM`	error	O NCM não tem 8 dígitos.
`MISSING_CEST`	error	O perfil fiscal do produto liga a substituição tributária, mas o produto não tem CEST.
`NO_PROFILE`	warning	Nenhum perfil fiscal casou com o produto. A nota sai com os padrões (CFOP 5102/6102, CSOSN 400). Só é verificado quando a loja tem ao menos um perfil ativo.
`MISSING_CUSTOMER_DOC`	error	O cliente não tem CPF nem CNPJ.
`B2B_MISSING_IE`	error	Cliente pessoa jurídica de uma conta corporativa sem inscrição estadual.
`MISSING_ADDRESS`	error	O endereço de entrega do pedido não tem logradouro, cidade, UF e CEP.

Erros

Status	Quando	Corpo
500	`order_id` ausente ou que não é UUID	`{"error":"validation failed","detail":"..."}`
401 / 403	Sem token, sem privilégio, módulo desligado	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`

Achar problemas no catálogo

Lista os produtos (não excluídos) cujo NCM está vazio ou não tem exatamente 8 dígitos. É a limpeza que evita rejeições antes mesmo de existir um pedido.

GET/api/v1/admin/fiscal/catalog-issuesAdmin

Lista produtos com NCM faltando ou inválido

Parâmetros de consulta

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/catalog-issues?per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Problemas do catálogo

json

{
  "items": [
    {
      "product_id": "7d0788c6-8af0-4805-83c4-e873b763961b",
      "product_name": "Air Fryer Clássico Branco",
      "code": "MISSING_NCM",
      "message": "Produto sem NCM"
    }
  ],
  "total": 4985
}

Campos da resposta

itemsarray

Produtos com problema, por nome. null quando não há nenhum.

totalinteger

Total de produtos com problema, em todas as páginas.

product_iduuid

Produto.

product_namestring

Nome do produto.

codestring

MISSING_NCMINVALID_NCM

MISSING_NCM quando o NCM está vazio, INVALID_NCM quando não tem 8 dígitos.

messagestring

Descrição em português.

Erros

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

Veja também

Validação prévia

Confere se um pedido tem tudo o que a nota exige e lista os produtos do catálogo com NCM faltando ou inválido.

Validar um pedido

Roda as verificações num pedido e devolve a lista de problemas. Nada é gravado e nenhuma nota é emitida. Os textos dos problemas vêm em português.

GET/api/v1/admin/fiscal/validateAdmin

Confere um pedido antes de emitir a nota

Parâmetros de consulta

order_iduuidobrigatório

Id do pedido. Vazio ou fora do formato UUID devolve 500.

vendor_iduuid

Seller da nota. É aceito, mas hoje não muda o resultado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/fiscal/validate?order_id=615b4147-6cb2-4057-9e25-ee82281b9d68" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedido conferido

json

{
  "can_emit": false,
  "issues": [
    {
      "code": "MISSING_NCM",
      "severity": "error",
      "message": "Produto sem NCM: Teclado Pro Cinza",
      "product_id": "e3a71800-294f-4167-a755-cabedcf094b4",
      "field": "ncm_code"
    },
    {
      "code": "NO_PROFILE",
      "severity": "warning",
      "message": "Nenhum perfil fiscal resolvido para o produto: Mouse Pro Preto, a nota usará os padrões (5102/6102, CSOSN 400).",
      "product_id": "cb60662e-7871-4699-832f-f9a106dd9bac",
      "field": "fiscal_profile"
    }
  ]
}

Campos da resposta

can_emitboolean

true quando não há nenhum problema com severity igual a error. Avisos (warning) não impedem.

issuesarray

Problemas encontrados. É null (não []) quando não há nenhum.

codestring

Código estável do problema (tabela abaixo).

severitystring

errorwarning

error impede a emissão; warning só avisa.

messagestring

Descrição em português.

product_iduuid

Produto envolvido. Ausente nos problemas do pedido ou do cliente.

fieldstring

Campo a corrigir, por exemplo ncm_code. Ausente em alguns casos.

`code`	Gravidade	O que significa e como corrigir
`ZERO_ITEMS`	error	O pedido não tem itens com quantidade positiva. Também é o resultado para um id de pedido que não existe.
`MISSING_NCM`	error	Produto sem NCM. Preencha o NCM no cadastro do produto.
`INVALID_NCM`	error	O NCM não tem 8 dígitos.
`MISSING_CEST`	error	O perfil fiscal do produto liga a substituição tributária, mas o produto não tem CEST.
`NO_PROFILE`	warning	Nenhum perfil fiscal casou com o produto. A nota sai com os padrões (CFOP 5102/6102, CSOSN 400). Só é verificado quando a loja tem ao menos um perfil ativo.
`MISSING_CUSTOMER_DOC`	error	O cliente não tem CPF nem CNPJ.
`B2B_MISSING_IE`	error	Cliente pessoa jurídica de uma conta corporativa sem inscrição estadual.
`MISSING_ADDRESS`	error	O endereço de entrega do pedido não tem logradouro, cidade, UF e CEP.

Erros

Status	Quando	Corpo
500	`order_id` ausente ou que não é UUID	`{"error":"validation failed","detail":"..."}`
401 / 403	Sem token, sem privilégio, módulo desligado	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`

Achar problemas no catálogo

Lista os produtos (não excluídos) cujo NCM está vazio ou não tem exatamente 8 dígitos. É a limpeza que evita rejeições antes mesmo de existir um pedido.

GET/api/v1/admin/fiscal/catalog-issuesAdmin

Lista produtos com NCM faltando ou inválido

Parâmetros de consulta

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/catalog-issues?per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Problemas do catálogo

json

{
  "items": [
    {
      "product_id": "7d0788c6-8af0-4805-83c4-e873b763961b",
      "product_name": "Air Fryer Clássico Branco",
      "code": "MISSING_NCM",
      "message": "Produto sem NCM"
    }
  ],
  "total": 4985
}

Campos da resposta

itemsarray

Produtos com problema, por nome. null quando não há nenhum.

totalinteger

Total de produtos com problema, em todas as páginas.

product_iduuid

Produto.

product_namestring

Nome do produto.

codestring

MISSING_NCMINVALID_NCM

MISSING_NCM quando o NCM está vazio, INVALID_NCM quando não tem 8 dígitos.

messagestring

Descrição em português.

Erros

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