Códigos Fiscais de Produtos

Esta documentação descreve as rotas de clientes para gerenciar os códigos fiscais associados a um produto do cliente, no modo Fulfillment.

Objetivo

Permitir que o cliente cadastre e mantenha configurações fiscais por produto para diferentes cenários de operação (entrada/saída), validando NCM e regras fiscais básicas.

Diferenças entre Modos de Operação

Modo Fulfillment:

Não utiliza campos de alíquotas (aliquota_ipi, aliquota_icms, aliquota_pis, aliquota_cofins)

Não utiliza campos de CST (cst_ipi, cst_icms, cst_pis, cst_cofins)

Campos origem, fiscal_unit e fiscal_quantity_conversion são obrigatórios

fiscal_quantity_conversion deve ser no mínimo 1

Para fiscal_usage_type = "entrada_saida", o fiscal_quantity_conversion deve ser exatamente 1

Modo Enterprise:

Inclui todos os campos de alíquotas e CST

Campos fiscais são opcionais (nullable)

fiscal_quantity_conversion pode ser menor que 1 (mínimo 0.000001)

Identificadores

Cada código fiscal possui dois identificadores:

fiscal_id: Identificador único universal (ULID) gerado automaticamente pelo sistema

fiscal_code: Código do produto na nota fiscal definido pelo cliente (máximo 50 caracteres)

Endpoints de Enumeração

Para obter os valores válidos dos campos do tipo enum, utilize os seguintes endpoints:

Endpoint	Descrição
`/api/v1/enums/product-origin`	Origem do produto
`/api/v1/enums/fiscal-usage-type`	Tipo de uso fiscal (entrada/saída)
`/api/v1/enums/product-unit`	Unidade fiscal

Campos Aceitos na Request

Campos Obrigatórios

Campo	Tipo	Descrição	Validação
fiscal_code	string	Código do produto na nota fiscal	Máximo 50 caracteres
ncm	string	Código NCM numérico	8 dígitos
cest	string	Código Especificador da Substituição	Formato ##.###.##
origem	string	Origem do produto	Valores do enum
fiscal_usage_type	string	Tipo de uso fiscal	`entrada`, `saida` ou `entrada_saida`
fiscal_unit	string	Unidade fiscal para conversão	Valores do enum
fiscal_quantity_conversion	number	Fator de conversão da unidade fiscal	Mínimo 1

Campos Opcionais

Campo	Tipo	Descrição	Validação
is_active	boolean	Status ativo/inativo	true/false
fiscal_notes	string	Observações fiscais adicionais	Máximo 1000 caracteres

Estrutura de Respostas

Resposta simplificada:

{
    "success": true,
    "message": "Códigos fiscais recuperados com sucesso",
    "data": [
        {
            "fiscal_id": "01J4Z8K5PQX7Y3M9N2R4T6V8W",
            "fiscal_code": "COD_FISCAL",
            "ncm": "12345678",
            "cest": "21.002.00",
            "origem": "1",
            "fiscal_usage_type": "entrada",
            "is_active": true,
            "fiscal_notes": "Observações fiscais adicionais",
            "fiscal_unit": "cx",
            "fiscal_quantity_conversion": 12
        }
    ]
}

Estrutura dos enums

Define como o código fiscal será utilizado nas operações.

Valor	Label	Descrição	Características Especiais
`saida`	Saída	Configuração fiscal para saídas de produtos	-
`entrada`	Entrada	Configuração fiscal para entradas de produtos	-
`entrada_saida`	Entrada e Saída	Configuração fiscal para entradas e saídas	fiscal_quantity_conversion deve ser exatamente 1

Exemplo de Uso ENTRADA_SAIDA:

{
  "fiscal_usage_type": "entrada_saida",
  "fiscal_quantity_conversion": 1
}

ProductOrigin

Define a origem do produto conforme legislação fiscal brasileira.

Valor	Label	Descrição
`0`	Nacional	Mercadoria ou bem de origem nacional
`1`	Estrangeira - Importação direta	Mercadoria ou bem de origem estrangeira - Importação direta
`2`	Estrangeira - Adquirida no mercado interno	Mercadoria ou bem de origem estrangeira - Adquirida no mercado interno
`3`	Nacional - Conteúdo de importação superior a 40%	Mercadoria ou bem de origem nacional, mercadoria ou bem com Conteúdo de Importação superior a 40%
`4`	Nacional - Cuja produção tenha sido feita em conformidade	Mercadoria ou bem de origem nacional, cuja produção tenha sido feita em conformidade com os processos produtivos básicos
`5`	Nacional - Conteúdo de importação inferior ou igual a 40%	Mercadoria ou bem de origem nacional, mercadoria ou bem com Conteúdo de Importação inferior ou igual a 40%
`6`	Estrangeira - Importação direta, sem similar nacional	Mercadoria ou bem de origem estrangeira - Importação direta, sem similar nacional, constante em lista da CAMEX
`7`	Estrangeira - Adquirida no mercado interno, sem similar nacional	Mercadoria ou bem de origem estrangeira - Adquirida no mercado interno, sem similar nacional, constante em lista da CAMEX
`8`	Nacional - Conteúdo de importação superior a 70%	Mercadoria ou bem de origem nacional, mercadoria ou bem com Conteúdo de Importação superior a 70%

ProductUnit

Define as unidades de medida disponíveis para produtos.

Valor	Label	Descrição
`un`	Unidade	Unidade
`kg`	Quilograma	Quilograma
`cx`	Caixa	Caixa
`pc`	Peça	Peça
`lt`	Litro	Litro
`mt`	Metro	Metro
`m2`	Metro quadrado	Metro quadrado
`m3`	Metro cúbico	Metro cúbico
`ton`	Tonelada	Tonelada
`g`	Grama	Grama
`ml`	Mililitro	Mililitro
`cm`	Centímetro	Centímetro
`mm`	Milímetro	Milímetro
`par`	Par	Par
`dz`	Dúzia	Dúzia
`cento`	Cento	Cento
`milheiro`	Milheiro	Milheiro

Objetivo#

Diferenças entre Modos de Operação#

Identificadores#

Endpoints de Enumeração#

Campos Aceitos na Request#

Campos Obrigatórios#

Campos Opcionais#

Estrutura de Respostas#

Estrutura dos enums#

ProductOrigin#

ProductUnit#