API - Classificação Fiscal (V1)
Manual contendo as últimas atualizações efetuadas em 12/09/2025
Introdução
A API de classificação fiscal permite realizar de forma integrada esse importante serviço que é a determinação correta da NCM de mercadorias. A correta classificação da NCM é fator determinante para se chegar na tributação precisa de qualquer material.
Essa API permite que através do seu sistema, seja possível realizar as mesmas atividades que normalmente são realizadas no através do Portal CFM, o portal de classificação fiscal da Systax.
O fluxo de acesso inicia pela autenticação, sendo necessário primeiramente obter um token, que será passado no header de todas as outras requisições.
Através dos serviços de cadastro e alteração, pode-se enviar mercadorias para a classificação, enviar as respostas às dúvidas técnicas e confirmar a NCM definitiva.
Com os serviços de consulta de NCM Sugerida, e Dúvidas Técnicas, pode-se listar respectivamente, a NCM sugerida pelo time Systax e as dúvidas técnicas levantadas por eles.
O serviço de consulta permite a listagem dos itens já classificados e todas as informações produzidas.
Acessos
Swagger
https://app.systax.com.br/cfm/swagger
Para acessar, é necessário ter uma conta de usuário válida no Portal CFM da Systax.
Autenticação
Passo a passo
Todas as API's são autenticadas através de um token, obtida através de um serviço próprio.
O usuário e senha são passados através do HTTP Basic Authentication e sem nenhuma informação no corpo da mensagem.
GET
http://app.systax.com.br/cfm/auth/access-token
Request
O retorno da API será um token, que deverá ser utilizado em todas as demais API's do serviço de classificação fiscal.
Como utilizar o token
Em todas as demais API's, o token deverá ser passado no Header da mensagem em um campo chamado token.
Validade do token
O token tem um tempo de vida padrão de 1 hora. Após esse período, um novo token deverá ser obtido.
Caso o token esteja expirado, a mensagem "Provided token is expired." será retornada em qualquer uma das API's.
Serviços
Cadastro
O serviço de cadastro permite o envio de mercadorias para classificação.
Método: POST
URL: http://app.systax.com.br/cfm/products
Request
Os campos que podem ser enviados são:
| Nome | Tipo | Descrição | Obrigatório |
| cod_interno | Texto | Código do material no cadastro do cliente | Sim |
| origem_produto | Inteiro | Origem do material de 0 a 8 conforme tabela oficial | Sim |
| descricao | Texto | Descrição da mercadoria, importante para o processo de classificação | Sim |
| complemento | Texto | Informações adicionais importantes para se determina a natureza do material | Não |
| ean | Inteiro | Número GTIN (EAN) se disponível | Não |
| ncm_original | Inteiro | A NCM atual da mercadoria | Não |
| ex_tipi_original | Inteiro | O EX da TIPI atual da mercadoria | Não |
JSON do request
{
"cod_interno": "00001",
"origem_produto": 0,
"complemento": "Complemento ",
"ean": "",
"ncm_original": "04064000",
"ex_tipi_original": "",
"descricao": "Descrição"
}
Response
Em caso de sucesso a api retornará o campo status com a descrição "Criado" e o ID, que é o código da base de dados da Systax.
Caso a mercadoria já tenha sido cadastrada a API retornará o campo "error" com a mensagem: "Já existe um produto com o mesmo cod_interno e origem_produto"
JSON do response.
{
"status": "Criado",
"id": 7233611
}
Exemplo de request e response
Alteração
O serviço de alteração permite o envio de alterações de produtos já cadastrados, bem como o envio de aprovação de NCM e respostas das dúvidas dos analistas Systax.
Método: PUT
URL: http://app.systax.com.br/cfm/products/{id}
O id é o mesmo código retornado no serviço de cadastro.
Request
Os campos que podem ser enviados são:
| Nome | Tipo | Descrição |
| descricao | Texto | Descrição da mercadoria, importante para o processo de classificação |
| complemento | Texto | Informações adicionais importantes para se determina a natureza do material |
| ean | Inteiro | Número GTIN (EAN) se disponível |
| ncm_original | Inteiro | A NCM atual da mercadoria |
| ex_tipi_original | Inteiro | O EX da TIPI atual da mercadoria |
| ncm_definitiva | Inteiro | A confirmação da NCM que será utilizada. |
| ex_tipi_definitiva | Inteiro | A confirmação da EX que será utilizada, caso necessário. |
| resposta_tecnica | Texto | A resposta dada ao questionamento do analista da Systax. |
Importante: A NCM e EX definitas podem ser iguais ou diferentes à NCM sugerida pelo analista da Systax.
JSON do request{
"descricao": "Descrição da mercadoria",
"complemento": "Complemento",
"ean": "0",
"ncm_original": "04064000",
"ex_tipi_original": "",
"ncm_definitiva": "04064000",
"ex_tipi_definitiva": "",
"resposta_tecnica": "Resposta"
}
Response
Em caso de sucesso a API retornará o campo status com a descrição "Atualizado".
JSON do response.
{
"status": "Atualizado"
}
Em caso de falha o retorno será o campo "error" com a descrição apropriada como no exemplo abaixo:
Exemplo de request e response
Informações
O serviço de Informações lista os itens já classificados, ou seja, que contenham NCM definitiva.
Método: GET
URL: https://app.systax.com.br/cfm/products
Request
Os campos que podem ser enviados são:
| Nome | Tipo | Descrição |
| tipo_retorno | Texto | Define quais informações devem ser retornadas. Opções possíveis: ncm, duvida ou infos (default).
|
| id | Inteiro | ID do produto. Se esse filtro for utilizado, todos os outros filtros serão ignorados, caso sejam utilizados ao mesmo tempo |
| list_ids | Texto | Lista de id's separados por vírgula. Se enviado, os parâmetros cod_interno e origem_produto serão ignorados. |
| data_criacao | Texto | Permite filtrar o dia exato 15/08/2019 ou uma faixa 20/04/2019a27/12/2019 |
| param | Array[Texto] | Array de parâmetros para filtrar os produtos. Deve ser combinado com o parâmetro value[]. Opções: cod_interno, origem_produto, ean, descricao, complemento, ncm_original, ex_tipi_original, ncm_sugerida, ex_tipi_sugerida, ncm_definitiva, ex_tipi_definitiva, status_atual. |
| value | Array[Texto] | Array de valores para filtrar os produtos. Deve ser combinado com o parâmetro param[] Para o filtro status_atual, utilizar os valores: novo, classificado, pendente ou aguardando-ncm-definitiva. |
| pagina_atual | Inteiro | Página que se deseja consultar. |
| por_pagina | Inteiro | Quantidade de registros por página. |
| order_by | Inteiro | Define a ordenação dos resultados. Opções: id, cod_interno, descricao e data_criacao. Acrescente .ASC ou .DESC se necessário. Exemplos cod_interno, id.DESC, descricao.ASC |
Importante: Os parâmetros deverão ser enviados na query string da url.
Paginação
Se a quantidade de itens retornados for maior do que uma página, um bloco adicional "paginacao" será devolvido contendo algumas informações importantes para a leitura dos itens paginados.
Esse bloco conterá as seguintes informações:
| Nome | Tipo | Descrição |
| total_registros | Texto | A quantidade total de registros disponíveis para consulta. |
| num_paginas | Texto | A quantidade total de páginas em que esses registros se distribuem. |
| por_pagina | Inteiro | A quantidade de itens por págian informada na requisição. |
| pagina_atual | Inteiro | A página que se está consultando no momento. |
| itens_da_pagina | Inteiro | A quantidade de itens retornados na página atual. Será menor do que o tamanho da página quando se estiver lendo a última |
Request consuntando NCM
http://app.systax.com.br/cfm/products/?por_pagina=3&tipo_retorno=ncm&order_by=data_criacao.ASC
Request consultando dúvida:
http://app.systax.com.br/cfm/products/?por_pagina=3&tipo_retorno=duvida&order_by=data_criacao.DESC
Request e Response
Dúvidas técnicas
O serviço de dúvidas técnicas permite listar as dúvidas técnicas registradas pelos dos analistas Systax. Essas informações adicionais são importantes para se determinar a classificação fiscal corretamente.
Método: GET
URL: http://app.systax.com.br/cfm/products/duvida_tecnica
Request
Os campos que podem ser enviados são:
| Nome | Tipo | Descrição |
| list_ids | Texto | Lista de id's separados por vírgula. Se enviado, os parâmetros cod_interno e origem_produto serão ignorados. |
| cod_interno | Texto | Código do material enviado no cadastro. |
| origem_produto | Inteiro | Origem da mercadoria enviada no cadastro. |
| pagina_atual | Inteiro | Página que se deseja consultar. |
| por_pagina | Inteiro | Quantidade de registros por página. |
JSON do request - Exemplo 1 - Consultando por id produto.
{
"list_ids": "7233611",
"pagina_atual": "1",
"por_pagina": "50"
}
JSON do request - Exemplo 2 - Consultando por código do material.
{
"cod_interno": "00001",
"origem_produto": "0",
"pagina_atual": "1",
"por_pagina": "20"
}
Importante: É permitido não informar lista de id's ou códigos de produto, nesse caso serão retornadas todas os materiais da página.
Response
Em caso de sucesso a API retornará o campo a lista de materiais com dúvidas técnicas.
{
"produtos": [
{
"id": "7233611",
"cod_interno": "00001",
"origem_produto": "0",
"duvida_tecnica": "Uma dúvida",
"resposta_tecnica": ""
},
{
"id": "4890228",
"cod_interno": "123456",
"origem_produto": "0",
"duvida_tecnica": "",
"resposta_tecnica": ""
}
],
"paginacao": {
"total_registros": 5,
"num_paginas": 3,
"por_pagina": 2,
"pagina_atual": 1,
"itens_da_pagina": 2
}
}
Paginação
Se a quantidade de itens retornados for maior do que uma página, um bloco adicional "paginacao" será devolvido contendo algumas informações importantes para a leitura dos itens paginados.
Esse bloco conterá as seguintes informações:
| Nome | Tipo | Descrição |
| total_registros | Texto | A quantidade total de registros disponíveis para consulta. |
| num_paginas | Texto | A quantidade total de páginas em que esses registros se distribuem. |
| por_pagina | Inteiro | A quantidade de itens por página informada na requisição. |
| pagina_atual | Inteiro | A página que se está consultando no momento. |
| itens_da_pagina | Inteiro | A quantidade de itens retornados na página atual. Será menor do que o tamanho da página quando se estiver lendo a última |
Resquest e response
Busca completa:
Busca por ID:
NCM Sugerida
O serviço de NCM sugerida permite listar as NCM's registradas pelos dos analistas Systax e identificadas como correta segundo sua análise. Com base nessas informações o cliente poderá aceita-la ou recusa-la.
Para aceitar, basta que o cliente reenvie a NCM sugerida como definitiva através do serviço de Alteração, para recusar, o cliente poderá enviar a NCM original ou mesmo uma terceira como NCM definitiva.
Método: GET
URL: http://app.systax.com.br/cfm/products/ncm_sugerida
Request
Os campos que podem ser enviados são:
| Nome | Tipo | Descrição |
| list_ids | Texto | Lista de id's separados por vírgula. Se enviado, os parâmetros cod_interno e origem_produto serão ignorados. |
| cod_interno | Texto | Código do material enviado no cadastro. |
| origem_produto | Inteiro | Origem da mercadoria enviada no cadastro. |
| pagina_atual | Inteiro | Página que se deseja consultar. |
| por_pagina | Inteiro | Quantidade de registros por página. |
JSON do request - Exemplo 1 - Consultando por id produto.
{
"list_ids": "7233611",
"pagina_atual": "1",
"por_pagina": "50"
}
JSON do request - Exemplo 2 - Consultando por código do material.
{
"cod_interno": "00001",
"origem_produto": "0",
"pagina_atual": "1",
"por_pagina": "20"
}
Importante: É permitido não informar lista de id's ou códigos de produto, nesse caso serão retornadas todas os materiais da página.
Response
Em caso de sucesso a API retornará a lista de materiais com sugestão de NCM.
{
"produtos": [
{
"id": "7233611",
"cod_interno": "00001",
"origem_produto": "0",
"ncm_original": "04064000",
"ex_tipi_original": "",
"ncm_sugerida": "04064000",
"ex_tipi_sugerida": "",
"ncm_definitiva": "",
"ex_tipi_definitiva": "",
"status_atual": "novo",
"informacao_extra": "NCM Sugerida Preenchida"
}
]
}
Paginação
Se a quantidade de itens retornados for maior do que uma página, um bloco adicional "paginacao" será devolvido contendo algumas informações importantes para a leitura dos itens paginados.
Esse bloco conterá as seguintes informações:
| Nome | Tipo | Descrição |
| total_registros | Texto | A quantidade total de registros disponíveis para consulta. |
| num_paginas | Texto | A quantidade total de páginas em que esses registros se distribuem. |
| por_pagina | Inteiro | A quantidade de itens por págian informada na requisição. |
| pagina_atual | Inteiro | A página que se está consultando no momento. |
| itens_da_pagina | Inteiro | A quantidade de itens retornados na página atual. Será menor do que o tamanho da página quando se estiver lendo a última |
Response
{
"produtos": [
{
"id": "7233611",
"cod_interno": "00001",
"origem_produto": "0",
"ncm_original": "04064000",
"ex_tipi_original": "",
"ncm_sugerida": "04064000",
"ex_tipi_sugerida": "",
"ncm_definitiva": "",
"ex_tipi_definitiva": "",
"status_atual": "novo",
"informacao_extra": "NCM Sugerida Preenchida"
},
{
"id": "7233561",
"cod_interno": "cdigo",
"origem_produto": "0",
"ncm_original": "09786112",
"ex_tipi_original": "",
"ncm_sugerida": "04064000",
"ex_tipi_sugerida": "",
"ncm_definitiva": "",
"ex_tipi_definitiva": "",
"status_atual": "novo",
"informacao_extra": "NCM Sugerida Preenchida"
}
],
"paginacao": {
"total_registros": 3,
"num_paginas": 2,
"por_pagina": 2,
"pagina_atual": 1,
"itens_da_pagina": 2
}
}
Request e Response
