API API de envio e recuperação de carga tributária ICMS + IBS/CBS Visão geral O ERP envia os produtos com a tributação atual em POST /enviar-carga, a CTS revisa de forma assíncrona e o ERP busca o resultado em POST /recuperar-carga. As duas chamadas usam o mesmo token e o mesmo CNPJ. Item Valor URL base https://revisao-tributaria.cts.app.br/cts-revisao-tributaria Formato JSON, UTF-8, header Content-Type: application/json Autenticação header token com o token do sistema cadastrado na CTS CNPJ raiz do CNPJ, 8 primeiros dígitos, só números (ex.: 92565464) Limite por chamada 5000 produtos, nas duas rotas Nos exemplos, troque {URL_BASE}, SEU_TOKEN e o CNPJ pelos valores do seu ambiente. 1. Enviar carga — POST /enviar-carga Recebe até 5000 produtos por chamada e responde 202 assim que a carga é aceita. A revisão acontece depois; o resultado sai no recuperar-carga. Requisição Campo Onde Obrigatório Regra token header sim token do sistema na CTS operacao body sim só S (saída) uf body sim sigla do estado, ex.: RS cnpj body sim raiz do CNPJ, 8 dígitos produtos body sim lista com 1 a 5000 produtos Codigo produto sim código do produto no ERP EAN produto sim código de barras produtoDescricao produto sim descrição do produto ncm produto sim NCM atual demais campos trib* e cest produto não tributação atual no ERP; envie vazio quando não houver Os nomes dos campos diferenciam maiúsculas de minúsculas: Codigo e EAN são escritos assim. O body inteiro pode ter até cerca de 12,8 MB (5000 × 2560 bytes); acima disso a carga é recusada sem ser lida. Exemplo curl -i -X POST 'https://revisao-tributaria.cts.app.br/cts-revisao-tributaria/enviar-carga' \ -H 'Content-Type: application/json' \ -H 'token: SEU_TOKEN' \ -d '{ "operacao": "S", "uf": "RS", "cnpj": "92565464", "produtos": [ { "Codigo": 96820, "EAN": "7898922378726", "produtoDescricao": "MAMAO LB 1 Un FORMOSA", "ncm": "08072000", "cest": "", "tribRegraCfop": "5102", "tribIcmsCst": "40", "tribIcmsReducao": "0.0", "tribIcmsAliq": "0.0", "tribIcmsStAliq": "0.0", "tribIcmsStPauta": "0", "tribIcmsStMva": "0.0", "tribFcpAliq": "0.0", "tribDifalAliq": "0", "tribPisCst": "06", "tribPisReducao": "", "tribPisAliq": "0.000", "tribIbsCbsCst": "200", "tribRedCbs": 100, "tribRedIbs": 100, "tribAliqCbs": 0.9, "tribAliqIbs": 0.1, "tribCclassTrib": "200014" } ] }' Retornos 202 Accepted — carga recebida. Guarde o idRequisicao para falar com o suporte da CTS. { "idRequisicao": 6052, "totalProdutos": 1, "mensagem": "Carga recebida com sucesso." } 400 — campos obrigatórios faltando. A CTS confere todos os produtos e devolve todos os problemas de uma vez. Em details, produto é a posição na lista (começa em 1), seguido dos dados que identificam o produto como foram enviados ( null quando faltam) e da lista campos com o que faltou. Nenhum produto da carga é gravado. { "code": 331, "message": "Campos obrigatórios não informados.", "details": [ { "produto": 1, "Codigo": "96820", "EAN": "7898922378726", "produtoDescricao": "MAMAO LB 1 Un FORMOSA", "campos": ["ncm"] } ] } 400 — acima do limite. Mais de 5000 produtos, ou body maior que o teto. Divida a carga em lotes menores e envie de novo. { "code": 327, "message": "050 - O máximo permitido 5000 produtos, por requisição." } Os outros erros (token, CNPJ, operação, UF, JSON inválido) estão na tabela de códigos de erro, mais abaixo. A ordem das validações é: limite, token, CNPJ e acesso, operação, UF, lista e campos dos produtos. 2. Recuperar carga — POST /recuperar-carga Devolve até limite produtos já revisados pela CTS e os baixa na mesma chamada: um produto devolvido não volta em chamadas seguintes. Por isso grave a resposta no ERP antes de chamar de novo. Requisição Campo Onde Obrigatório Regra token header sim o mesmo do enviar-carga cnpj body sim raiz do CNPJ, 8 dígitos limite body sim de 1 a 5000 produtos por chamada Exemplo curl -i -X POST 'https://revisao-tributaria.cts.app.br/cts-revisao-tributaria/recuperar-carga' \ -H 'Content-Type: application/json' \ -H 'token: SEU_TOKEN' \ -d '{ "cnpj": "92565464", "limite": 200 }' Retornos 200 OK — com produtos. Os campos usam a mesma nomenclatura do enviar-carga, com os valores revisados pela CTS. { "produtos": [ { "operacao": "S", "uf": "RS", "cnpj": "92565464", "Codigo": 96820, "EAN": "7898922378726", "produtoDescricao": "MAMAO LB 1 Un FORMOSA", "ncm": "08072000", "tribCfop": "5102", "tribIcmsCst": "40", "tribIcmsReducao": "0.0", "tribIcmsAliq": "0.0", "tribIcmsStAliq": "0.0", "tribIcmsStPauta": "0.0", "tribIcmsStMva": "0.0", "tribFcpAliq": "0.0", "tribDifalAliq": "0.0", "tribPisCst": "06", "tribPisReducao": "0.0", "tribPisAliq": "0.0", "tribIbsCbsCst": "200", "tribRedCbs": 100.0, "tribRedIbs": 100.0, "tribAliqCbs": 0.9, "tribAliqIbs": 0.1, "tribCclassTrib": "200014" } ], "TotalProdutoSolicitados": 200, "TotalProdutosRestante": 350 } Campo Significado produtos produtos revisados desta chamada; some da resposta quando não há nenhum TotalProdutoSolicitados o limite enviado na chamada (não é a quantidade devolvida; conte os itens de produtos) TotalProdutosRestante quantos produtos ainda esperam ser recuperados; chame de novo enquanto for maior que zero Codigo volta como número quando o código é só dígitos, senão como texto 200 OK — nada pendente. A carga ainda está em processamento na CTS, ou tudo já foi recuperado. { "TotalProdutoSolicitados": 200, "TotalProdutosRestante": 0 } 409 Conflict — chamada em andamento. Já existe um recuperar-carga rodando com o mesmo CNPJ e token. Espere a primeira terminar e chame de novo; não faça chamadas em paralelo. { "code": 335, "message": "Já existe uma requisição em andamento para este CNPJ e token, aguarde a conclusão." } 400 — limite inválido. limite ausente ou menor que 1 devolve o código 334; acima de 5000 devolve o 327, o mesmo do enviar-carga. { "code": 334, "message": "O limite deve ser informado e maior que zero." } 3. Códigos de erro Todo erro volta com o status HTTP e um JSON com code e message; alguns trazem também details. Trate pelo code, não pelo texto da mensagem. { "code": 317, "message": "022 - Token nao Localizado no Ambiente Selecionado." } HTTP code Mensagem Quando acontece Rotas O que fazer 400 101 A lista de produtos não foi informado. body vazio, ou produtos ausente ou vazio enviar envie ao menos 1 produto 400 202 O Cnpj não foi informado. cnpj ausente ou vazio as duas informe a raiz do CNPJ 401 317 022 - Token nao Localizado no Ambiente Selecionado. header token ausente as duas envie o header token 403 324 021 - Cliente não cadastrado no Sistema. CNPJ não está ligado a esse token as duas confira o CNPJ; peça o cadastro à CTS 401 325 Sistema não Encontrado. token não existe na CTS as duas fale com a CTS 403 326 024 - Token Desabilitado token inativo as duas fale com a CTS 400 327 050 - O máximo permitido 5000 produtos, por requisição. mais de 5000 produtos, body acima do teto, ou limite acima de 5000 as duas divida em lotes ou reduza o limite 400 330 Operação inválida, informe S. operacao diferente de S enviar envie "operacao": "S" 400 331 Campos obrigatórios não informados. produto sem Codigo, EAN, produtoDescricao ou ncm enviar corrija os produtos listados em details 400 332 A UF deve ser informada. uf ausente enviar informe a sigla do estado 400 333 UF inválida, informe a sigla do estado (ex.: RS). uf não é uma das 27 siglas enviar corrija a sigla 400 334 O limite deve ser informado e maior que zero. limite ausente ou menor que 1 recuperar envie limite de 1 a 5000 409 335 Já existe uma requisição em andamento para este CNPJ e token, aguarde a conclusão. outra chamada igual ainda está rodando recuperar espere e chame de novo 400 400 Parâmetros de requisição inválidos. JSON mal formado ou que não é um objeto; details traz o motivo as duas corrija o JSON 500 401 Erro interno, favor contactar o administrador. falha inesperada na CTS as duas tente de novo; se repetir, fale com a CTS 4. Como o ERP deve consumir Envie a carga em lotes de até 5000 produtos pelo enviar-carga e guarde o idRequisicao de cada lote. Aguarde o processamento da CTS; ele é assíncrono e pode levar alguns minutos. Chame o recuperar-carga com um limite fixo, por exemplo 200. Grave os produtos recebidos no ERP antes da próxima chamada: eles não serão devolvidos de novo. Repita o passo 3 enquanto TotalProdutosRestante for maior que zero. Com TotalProdutosRestante igual a zero e nenhum produto na resposta, pare e tente de novo mais tarde. Faça uma chamada de recuperar-carga por vez para cada CNPJ e token; chamadas em paralelo recebem 409. Em 409 ou 500, espere alguns segundos antes de repetir. Erros 400, 401 e 403 não se resolvem repetindo: corrija a chamada. Use sempre o mesmo token e a mesma raiz de CNPJ no envio e na recuperação.