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

Atribuições de perfil fiscal

Liga um perfil fiscal a um produto, a uma categoria ou a um prefixo de NCM e remove essas ligações.

Uma atribuição diz qual perfil vale para qual alvo. Para cada item de uma nota a plataforma procura, nesta ordem, e para no primeiro que achar:

Uma atribuição ao produto do item.
Uma atribuição a uma das categorias do produto.
Uma atribuição a um prefixo de NCM que comece o NCM do produto. Com mais de um prefixo valendo, o mais longo vence (8471 ganha de 84).
O perfil padrão.

Só perfis active entram na busca. Exigem o módulo focusnfe e o privilégio manage_taxes ou manage_settings. Não há rota para listar atribuições: o perfil resolvido de um pedido aparece na validação prévia.

Atribuir um perfil

POST/api/v1/admin/fiscal/profiles/{id}/assignmentsAdmin

Atribui um perfil fiscal a um alvo

Parâmetros de caminho

iduuidobrigatório

Id do perfil.

Corpo da requisição

target_typestringobrigatório

productcategoryncm_prefix

Tipo de alvo. Preencha também o campo correspondente abaixo.

product_iduuid

Produto, quando target_type é product.

category_iduuid

Categoria, quando target_type é category.

ncm_prefixstring

Início do NCM (por exemplo 8471; a API não valida o formato), quando target_type é ncm_prefix. Espaços nas pontas são removidos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/profiles/be441f7e-9c43-4602-a43c-4724a5d8ce04/assignments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "target_type": "ncm_prefix", "ncm_prefix": "8471" }'

Resposta

201Atribuição criada

json

{ "id": "4b8e2d10-7a3c-49f5-b6d1-0c9a5e7f2a38" }

Campos da resposta

iduuid

Id da atribuição. Guarde-o: é o único jeito de removê-la.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid body","detail":"..."}`
422	`target_type` fora da lista, produto ou categoria inexistente, perfil inexistente, id que não é UUID	`{"error":"failed to add assignment","detail":"..."}`

Remover uma atribuição

Apaga a atribuição de vez (não é exclusão lógica). O alvo volta a ser resolvido pelas regras seguintes da ordem acima.

DELETE/api/v1/admin/fiscal/assignments/{id}Admin

Remove uma atribuição de perfil fiscal

Parâmetros de caminho

iduuidobrigatório

Id da atribuição, devolvido na criação.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/fiscal/assignments/4b8e2d10-7a3c-49f5-b6d1-0c9a5e7f2a38" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Atribuição removida

text

(sem corpo)

Erros

Status	Quando	Corpo
500	Id que não é UUID	`{"error":"failed to delete assignment","detail":"..."}`

Um UUID válido que não existe também devolve 204: a remoção é idempotente e não avisa se não havia nada a remover.

Veja também

Atribuições de perfil fiscal

Liga um perfil fiscal a um produto, a uma categoria ou a um prefixo de NCM e remove essas ligações.

Uma atribuição diz qual perfil vale para qual alvo. Para cada item de uma nota a plataforma procura, nesta ordem, e para no primeiro que achar:

Uma atribuição ao produto do item.
Uma atribuição a uma das categorias do produto.
Uma atribuição a um prefixo de NCM que comece o NCM do produto. Com mais de um prefixo valendo, o mais longo vence (8471 ganha de 84).
O perfil padrão.

Atribuir um perfil

POST/api/v1/admin/fiscal/profiles/{id}/assignmentsAdmin

Atribui um perfil fiscal a um alvo

Parâmetros de caminho

iduuidobrigatório

Id do perfil.

Corpo da requisição

target_typestringobrigatório

productcategoryncm_prefix

Tipo de alvo. Preencha também o campo correspondente abaixo.

product_iduuid

Produto, quando target_type é product.

category_iduuid

Categoria, quando target_type é category.

ncm_prefixstring

Início do NCM (por exemplo 8471; a API não valida o formato), quando target_type é ncm_prefix. Espaços nas pontas são removidos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/profiles/be441f7e-9c43-4602-a43c-4724a5d8ce04/assignments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "target_type": "ncm_prefix", "ncm_prefix": "8471" }'

Resposta

201Atribuição criada

json

{ "id": "4b8e2d10-7a3c-49f5-b6d1-0c9a5e7f2a38" }

Campos da resposta

iduuid

Id da atribuição. Guarde-o: é o único jeito de removê-la.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid body","detail":"..."}`
422	`target_type` fora da lista, produto ou categoria inexistente, perfil inexistente, id que não é UUID	`{"error":"failed to add assignment","detail":"..."}`

Remover uma atribuição

Apaga a atribuição de vez (não é exclusão lógica). O alvo volta a ser resolvido pelas regras seguintes da ordem acima.

DELETE/api/v1/admin/fiscal/assignments/{id}Admin

Remove uma atribuição de perfil fiscal

Parâmetros de caminho

iduuidobrigatório

Id da atribuição, devolvido na criação.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/fiscal/assignments/4b8e2d10-7a3c-49f5-b6d1-0c9a5e7f2a38" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Atribuição removida

text

(sem corpo)

Erros

Status	Quando	Corpo
500	Id que não é UUID	`{"error":"failed to delete assignment","detail":"..."}`

Um UUID válido que não existe também devolve 204: a remoção é idempotente e não avisa se não havia nada a remover.