Códigos Fiscais de Produtos

Esta documentação descreve exclusivamente as rotas de clientes para gerenciar os códigos fiscais (ex.: NCM, CSTs e alíquotas) associados a um produto do cliente.

Objetivo

Permitir que o cliente cadastre e mantenha múltiplas configurações fiscais por produto para diferentes cenários de operação (entrada/saida), validando NCM, códigos e regras fiscais.

Exemplos de uso:

Recebimento de remessa de fornecedor

Troca/retorno de produtos com regras fiscais distintas

Importação com alíquotas específicas

Devoluções de clientes e transferências entre filiais

Observações sobre alíquotas:

Quando um campo de alíquota estiver desativado, envie-o como null.

Se enviado como 0, será interpretado como imposto destacado com valor zero.

Campos aceitos na Request (body JSON)

Campos Obrigatórios

Campo	Tipo	Descrição	Validação
fiscal_code	string	Código fiscal único por produto	Máximo 50 caracteres
ncm	string	Código NCM numérico	8-10 dígitos
fiscal_usage_type	string	Tipo de uso fiscal	Valores via enum fiscal-usage-type

Campos Opcionais

Campo	Tipo	Descrição	Validação	Observações
origem	string	Origem do produto	Enum product-origin	-
cst_ipi	string	CST do IPI	Enum cst-ipi	-
cst_icms	string	CST do ICMS	Enum cst-icms	-
cst_pis	string	CST do PIS	Enum cst-pis	-
cst_cofins	string	CST do COFINS	Enum cst-cofins	-
aliquota_ipi	number	Alíquota do IPI	0-100	null = desativado, 0 = destacado com zero
aliquota_icms	number	Alíquota do ICMS	0-100	null = desativado, 0 = destacado com zero
aliquota_pis	number	Alíquota do PIS	0-100	null = desativado, 0 = destacado com zero
aliquota_cofins	number	Alíquota do COFINS	0-100	null = desativado, 0 = destacado com zero
is_active	boolean	Status ativo/inativo	true/false	-
fiscal_notes	string	Observações fiscais	Até 1000 caracteres	-

Validações Importantes

Todos os campos cst_* aceitam apenas valores constantes dos respectivos ENUMs

Alíquotas aceitam valores de 0-100. Envie null quando desativadas (ver observação sobre alíquotas no início do documento)

Enums disponíveis para os campos CST

Os valores válidos para os campos abaixo são obtidos pela API de Enums:

cst_ipi → /api/v1/enums/cst-ipi

cst_icms → /api/v1/enums/cst-icms

cst_pis → /api/v1/enums/cst-pis

cst_cofins → /api/v1/enums/cst-cofins

Exemplo de resposta (cst-cofins):

{
    "success": true,
    "message": "Opções de CstCofins recuperadas com sucesso",
    "data": [
        {
            "value": "01",
            "label": "01 - Operação tributável com alíquota básica",
            "status": "active",
            "description": "Operação tributável com alíquota básica do COFINS"
        },
        {
            "value": "02",
            "label": "02 - Operação tributável com alíquota diferenciada",
            "status": "active",
            "description": "Operação tributável com alíquota diferenciada do COFINS"
        }
    ]
}

Exemplos de uso

Body:

{
    "fiscal_code": "COD_FISCAL",
    "ncm": "12345678",
    "fiscal_usage_type": "saida",
    "origem": "nacional",
    "cst_icms": "00",
    "cst_pis": "01",
    "cst_cofins": "01",
    "aliquota_icms": 18,
    "aliquota_pis": 1.65,
    "aliquota_cofins": 7.6,
    "is_active": true,
    "fiscal_notes": "Regra fiscal padrão de venda"
}

Resposta (201):

{
    "success": true,
    "message": "Código fiscal adicionado com sucesso",
    "data": {
        "fiscal_code": "COD_FISCAL",
        "ncm": "12345678",
        "product_origin": "nacional",
        "product_origin_label": "Nacional",
        "cst_icms": "00",
        "cst_icms_label": "00 - Tributada integralmente",
        "cst_pis": "01",
        "cst_pis_label": "01 - Operação tributável com alíquota básica",
        "cst_cofins": "01",
        "cst_cofins_label": "01 - Operação tributável com alíquota básica",
        "aliquota_icms": 18.0,
        "aliquota_pis": 1.65,
        "aliquota_cofins": 7.6,
        "fiscal_usage_type": "saida",
        "fiscal_usage_type_label": "Saída",
        "is_active": true,
        "fiscal_notes": "Regra fiscal padrão de venda"
    }
}

Objetivo#

Campos aceitos na Request (body JSON)#

Campos Obrigatórios#

Campos Opcionais#

Validações Importantes#

Enums disponíveis para os campos CST#