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:{URL_BASE}//revisao-tributaria.cts.app.br/cts-revisao-tributaria` (a CTS informa o host de cada ambiente)
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 '{URL_BASE}/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 '{URL_BASE}/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	confira o token do ambiente
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.

API de envio e recuperação de carga tributária ICMS + IBS/CBS

Visão geral

1. Enviar carga — POST /enviar-carga

Requisição

Exemplo

Retornos

2. Recuperar carga — POST /recuperar-carga

Requisição

Exemplo

Retornos

3. Códigos de erro

4. Como o ERP deve consumir

1. Enviar carga — `POST /enviar-carga`

2. Recuperar carga — `POST /recuperar-carga`