API de CT-e (modelo 57) — conhecimento de transporte

CT-e · Conhecimento de Transporte · modelo 57 chave ace_

POST /cte/emitir

Documenta a prestação do serviço de frete (modal rodoviário): remetente, destinatário, tomador do serviço, valores da prestação e componentes, ICMS, e as chaves de NF-e transportadas. Usa o mesmo certificado dos demais + RNTRC (série serie_cte). Cobra 1 unidade por CT-e autorizado e por CC-e aceita.

Requer emitente credenciado como transportador na SEFAZ da sua UF. Sem o credenciamento, a SEFAZ recusa com [203] emitente não habilitado — é uma regra fiscal, não erro da API. Config: {"ambiente":2,"serie_cte":1,"rntrc":"12345678"}.

Endpoints

PUT  /cte/configuracao   # serie, ambiente, rntrc
POST /cte/emitir
GET  /cte/{id}/xml · /cte/{id}/dacte
POST /cte/{id}/cancelar
POST /cte/{id}/carta-correcao
GET  /cte · /cte/{id}

Trecho e partes

Campo		Descrição
`cfop`	obrig.	Ex.: 5352/6352 (transporte a estabelecimento)
`uf_inicio, uf_fim`	obrig.	UF de início/fim da prestação
`municipio_inicio_cod/nome`, `municipio_fim_cod/nome`	obrig.	IBGE 7 díg + nome
`remetente`, `destinatario`	obrig.	{nome, cnpj/cpf, ie, logradouro, numero, bairro, cod_municipio, cidade, uf, cep}
`tomador_tipo`	0	0=remetente, 1=expedidor, 2=recebedor, 3=destinatário, 4=outros
`tomador`, `expedidor`, `recebedor`	opc.	`tomador` só quando `tomador_tipo=4`
`rntrc`, `tipo_servico`, `tipo_cte`	opc.	RNTRC (ou da config); tipo_servico "normal"; tipo_cte "normal"

Trecho + partes

{
  "cfop": "5352", "uf_inicio": "RJ", "uf_fim": "SP",
  "municipio_inicio_cod": "3304557",
  "municipio_inicio_nome": "RIO DE JANEIRO",
  "municipio_fim_cod": "3550308",
  "municipio_fim_nome": "SAO PAULO",
  "rntrc": "12345678", "tomador_tipo": 0,
  "remetente": { "cnpj": "11222333000181",
    "ie": "ISENTO", "nome": "REMETENTE LTDA",
    "cod_municipio": "3304557", "cidade": "RIO DE JANEIRO",
    "uf": "RJ", "cep": "20090003" },
  "destinatario": { "cnpj": "44555666000199",
    "ie": "ISENTO", "nome": "DESTINATARIO LTDA",
    "cod_municipio": "3550308", "cidade": "SAO PAULO",
    "uf": "SP", "cep": "01001000" }
}

Valores, carga e ICMS

Campo		Descrição
`documentos[]`	obrig.	{tipo:"nfe"\|"cte", chave (44)} — transportados
`valor_total_servico`	obrig.	Valor do frete
`valor_carga, peso_bruto`	obrig.	Valor e peso da carga
`componentes_valor[]`	opc.	[{nome, valor}] — padrão FRETE VALOR = total
`produto_predominante`	opc.	Descrição da carga
`impostos.cst_icms`	opc.	Ver tabela abaixo

ICMS (impostos.cst_icms)

`00` normal	exige `aliquota_icms` (vICMS calculado)
`20`	BC reduzida (`reducao_base_calculo`+`aliquota_icms`)
`40/41/51`	isento / não trib. / diferido (só CST)
`60`	ST (`base_calculo_icms_st`, `valor_icms_st`, `aliquota_icms_st`)
`90`	outros
`SN`	Simples Nacional (padrão p/ emitente Simples — sem ICMS destacado)

Valores + emitir

curl -X POST .../api/v1/cte/emitir \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -d '{
    ... (trecho + partes) ...,
    "documentos": [{"tipo":"nfe","chave":"33260...(44)"}],
    "valor_total_servico": 150.00,
    "valor_carga": 3000.00, "peso_bruto": 500.000,
    "produto_predominante": "MERCADORIAS EM GERAL",
    "componentes_valor": [{"nome":"FRETE VALOR","valor":150.00}],
    "impostos": {"cst_icms":"00","aliquota_icms":12}
  }'

$ct = $cli->cte()->emitir($payload);
$id = $ct['cte_id'];
$cli->cte()->dacte($id, 'dacte.pdf');
$cli->cte()->cartaCorrecao($id, [
  ['grupo'=>'ide','campo'=>'xMunFim','valor'=>'SAO PAULO']
]);
$cli->cte()->cancelar($id, 'Erro na prestacao');

R := Api.EmitirCTe(JSONFromStr(Json));
Api.BaixarPDF('cte', R.Int('cte_id'), 'dacte.pdf');

200 · data

{ "cte_id": 12, "numero": 8, "serie": 1,
  "chave": "33260...(44)",
  "protocolo": "...", "status": "autorizada" }

Operações & erros

POST /cte/{id}/cancelar — justificativa 15+

POST /cte/{id}/carta-correcao cobra 1 un.

CC-e recebe {"correcoes":[{"grupo":"ide","campo":"xMunFim","valor":"SAO PAULO"}]} — não altera valores/impostos nem troca emitente/tomador/remetente/destinatário. XML/DACTE devolvem o arquivo direto.

HTTP · code	Quando
422 `emissao_rejeitada`	SEFAZ recusou (`[203]` emitente não credenciado, CFOP, IE do tomador)
422 `correcao_rejeitada`	CC-e recusada / sem `correcoes`
422 `cancelamento_rejeitado` · `justificativa_curta`	Fora de prazo ou < 15
403 `produto_nao_vinculado`	Empresa sem o produto cte

Carta de correção

curl -X POST .../api/v1/cte/12/carta-correcao \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -d '{"correcoes":[
    {"grupo":"ide","campo":"xMunFim","valor":"SAO PAULO"}
  ]}'

$cli->cte()->cartaCorrecao(12, [
  ['grupo'=>'ide', 'campo'=>'xMunFim', 'valor'=>'SAO PAULO'],
]);

Api.Post('cte/12/carta-correcao',
  JSONFromStr('{"correcoes":[{"grupo":"ide",'+
  '"campo":"xMunFim","valor":"SAO PAULO"}]}')).Free;

Não achou o que procurava? Índice da documentação · tabela de erros · servidor MCP · contexto para IA · suporte · [email protected]