Emitir CT-e
O CT-e (Conhecimento de Transporte Eletrônico, modelo 57) documenta o transporte de
carga. O CT-e OS (modelo 67) documenta o transporte de pessoas, valores ou excesso de
bagagem. Os dois são emitidos pela API do FazNota com o certificado da empresa e seguem o
mesmo fluxo: você envia o pedido, recebe um recibo e consulta o resultado.
Contrato completo e consulta por recibo desde a versão 3.21.0.
| CT-e (57) | CT-e OS (67) | |
|---|---|---|
| Emissão | POST /cte/emissao | POST /cte-os/emissao |
| Resultado | GET /cte/{recibo} | GET /cte-os/{recibo} |
| Cancelamento | POST /cte/cancelamento | POST /cte-os/cancelamento |
| Carta de correção | POST /cte/carta-correcao | POST /cte-os/carta-correcao |
| Eventos | entrega, insucesso, desacordo, multimodal, GTV | desacordo, GTV |
O modelo é escolhido pelo endereço: tudo em /cte-os é modelo 67, e /cte aceita o CT-e
normal (tp-doc N, padrão) e o Simplificado (tp-doc S). Recibo de um modelo consultado na
rota do outro responde 500.
Pré-requisitos no cadastro da empresa (FazNota)
- Certificado digital A1. O A3 não serve: exige o token físico para assinar.
- RNTRC em Dados da empresa → Informações para CT-e e CIOT, para o CT-e rodoviário
(modal
01). Sem ele a emissão é recusada na hora. - O ambiente (homologação ou produção) e a UF seguem a configuração da empresa.
Emitir e acompanhar
-
Emitir
Terminal window curl -X POST $BASE/cte/emissao \-H "Authorization: Token $TOKEN" \-H "Content-Type: application/json" \-d '{"numero-origem": "VIAGEM-2026-1021","cfop": "5353","serie": "1","modal": "01","tp-serv": "0","mun-ini": "4106902","mun-fim": "4113700","remetente": {"cnpj": "12345678000199", "x-nome": "Industria Exemplo Ltda", "ie": "1234567890","ender": { "x-lgr": "Rua XV de Novembro", "nro": "100", "x-bairro": "Centro","c-mun": "4106902", "x-mun": "Curitiba", "uf": "PR", "cep": "80020310" }},"destinatario": {"cnpj": "98765432000155", "x-nome": "Comercio Exemplo Ltda","ender": { "x-lgr": "Av. Brasil", "nro": "2000", "x-bairro": "Centro","c-mun": "4113700", "x-mun": "Londrina", "uf": "PR", "cep": "86010000" }},"tomador": "0","prestacao": { "vl-total": "1500.00", "vl-receber": "1500.00","componentes": [ { "nome": "FRETE PESO", "valor": "1500.00" } ] },"icms": { "cst": "00", "vl-bc": "1500.00", "aliquota": "12.00", "vl-icms": "180.00" },"carga": { "vl-carga": "30000.00", "produto-predominante": "Eletronicos","unidade": "01", "quantidade": "1200.0000" },"documentos": [ { "tipo": "NFe", "chave": "41261112345678000199550010000012341000012345" } ]}'Resposta:
{ "status": "001", "descricao": "Conhecimento de transporte registrado com sucesso.","data": { "recibo": "..." } }Se algum campo estiver ausente ou fora do formato, a resposta é
400na hora, com o campo:{ "status": "400","descricao": "Informe ao menos um documento transportado em documentos (NF-e, NF ou outros): a SEFAZ exige para tp-serv 0, 1 e 2 (rejeição 693).","data": { "campo": "documentos", "erro": "Informe ao menos um documento transportado..." } } -
Consultar o resultado
Faça polling com intervalo mínimo de 2 segundos:
Terminal window curl $BASE/cte/{recibo} -H "Authorization: Token $TOKEN"Autorizado:
{"status": "004","descricao": "CT-e autorizado pela SEFAZ.","data": {"recibo": "...", "processo": "emissao", "modelo": "57","chave": "41261112345678000199570010000000101123456780","protocolo": "141260000000001", "numero": "10", "serie": "1","tp-amb": "1", "dh-recbto": "2026-11-15T10:00:00","c-stat": "100", "x-motivo": "Autorizado o uso do CT-e", "cancelado": false}}Recusado pela SEFAZ:
{ "status": "900", "descricao": "A SEFAZ recusou o CT-e.","data": { "processo": "emissao", "c-stat": "693", "x-motivo": "Grupo Documentos Transportados deve ser informado..." } }
status da consulta | O que fazer |
|---|---|
002 | Na fila. Continue o polling. |
004 | Autorizado (ou evento registrado). Guarde chave e protocolo. |
010 | CT-e cancelado. |
900 | Recusado. Corrija o que x-motivo aponta e reenvie com o mesmo numero-origem. |
999 | Erro técnico ou desfecho indeterminado. Reenvie o mesmo pedido. |
500 | Recibo inexistente nesta empresa, ou do outro modelo. |
A consulta não devolve XML, e a API não gera DACTE.
Campos da emissão do CT-e (57)
| Campo | Obrigatório | Regra |
|---|---|---|
numero-origem | recomendado | Até 60 caracteres. Veja Reenvio |
cfop | sim | 4 dígitos. Ajustado para 5932/6932 quando a prestação começa fora da UF do emitente |
serie | sim | 1 a 3 dígitos |
n-ct | não | Ausente, o número sai do contador da série |
dh-emi | não | AAAA-MM-DDThh:mm:ss-03:00. Ausente, o momento do envio |
tp-serv | não | 0 normal (padrão), 1 subcontratação, 2 redespacho, 3 redespacho intermediário, 4 vinculado a multimodal |
tp-cte | não | 0 normal (padrão) ou 3 substituto (exige ref-cte) |
modal | não | 01 rodoviário (padrão), 02 aéreo, 03 ferroviário, 04 aquaviário, 05 dutoviário, 06 multimodal |
mun-ini, mun-fim | sim | Código IBGE (7 dígitos) ou {c-mun, x-mun, uf} |
remetente, destinatario | sim | cnpj ou cpf, x-nome e ender (x-lgr, nro, x-bairro, c-mun, x-mun, uf, cep) — ou só o documento, se o participante estiver no cadastro de clientes da empresa com endereço |
expedidor, recebedor | não | Mesma forma |
tomador | sim | Código do papel: 0 remetente, 1 expedidor, 2 recebedor, 3 destinatário, 4 outros (com tomador-doc, tomador-nome e tomador-ender) |
prestacao | sim | vl-total, vl-receber, componentes[] (nome, valor) |
icms | não | cst 00, 20, 40, 41, 51, 60 ou 90 e os valores. Ausente numa empresa do Simples, sai ICMSSN |
carga | sim | vl-carga, produto-predominante, quantidade (maior que zero), unidade (01 KG, padrão) |
documentos | em tp-serv 0, 1 e 2 | Ao menos um documento transportado: NFe (chave), NF (nota em papel) ou outros. Sem ele a SEFAZ recusa com 693 |
doc-anterior | em tp-serv 1, 2 e 3 | [{ "chave": "..." }] do CT-e anterior. Na subcontratação e no redespacho a SEFAZ exige os dois: o CT-e anterior e a NF-e |
modal-aereo, modal-ferrov, modal-aquav, modal-duto, modal-multimodal | no modal correspondente | d-prev-aereo; tp-traf; x-navio; d-ini e d-fim; cotm |
Não envie id-cte (o FazNota decide quando reaproveitar um CT-e; se vier, é descartado).
CT-e Simplificado
Com "tp-doc": "S": várias entregas de um tomador num documento, modal rodoviário. Em vez
de remetente e destinatário, informe tomador (objeto com papel e cnpj ou cpf), carga e
entregas[], cada uma com mun-ini, mun-fim, vl-prestacao e nfes (as chaves das NF-e).
CT-e OS (67)
curl -X POST $BASE/cte-os/emissao \ -H "Authorization: Token $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "numero-origem": "FRET-2026-55", "cfop": "5357", "serie": "1", "tp-serv": "6", "modal": "01", "mun-ini": "4106902", "mun-fim": "4113700", "tomador": { "cnpj": "12345678000199", "x-nome": "Empresa Contratante Ltda", "ender": { "x-lgr": "Rua XV de Novembro", "nro": "100", "x-bairro": "Centro", "c-mun": "4106902", "x-mun": "Curitiba", "uf": "PR", "cep": "80020310" } }, "prestacao": { "vl-total": "800.00", "vl-receber": "800.00" }, "icms": { "cst": "40" }, "servico": { "descricao": "Fretamento eventual", "quantidade": "40" }, "modal-rodo-os": { "taf": "123456789012", "placa": "ABC1D23", "uf": "PR" } }'| Campo | Obrigatório | Regra |
|---|---|---|
tp-serv | sim | 6 transporte de pessoas, 7 transporte de valores, 8 excesso de bagagem |
tp-cte | não | 0 normal, 1 complementar (exige ch-cte-comp), 3 substituto (exige ch-cte-sub) |
modal | não | 01 rodoviário (padrão), 02 aéreo, 03 aquaviário, 04 ferroviário |
tomador | sim | Objeto (cnpj ou cpf, x-nome, ender) — ou só o documento, se estiver no cadastro |
servico | sim (exceto complementar) | descricao (até 30 caracteres) e quantidade |
modal-rodo-os | no modal 01 | taf ou nr-reg-estadual |
documentos-ref | em tp-serv 8 | Ao menos um item com ch-bpe (o BP-e que gerou o excesso) |
icms | não | CST 00, 20, 40, 41, 51 ou 90 (o CT-e OS não tem o CST 60) |
cfop, serie, mun-ini, mun-fim e prestacao seguem as regras do CT-e. O tp-doc é
carimbado pela rota. O RNTRC não é exigido.
Reenvio e numero-origem
| Última tentativa com a mesma origem | O que acontece |
|---|---|
| Na fila | Devolve o mesmo recibo |
| Autorizada | Devolve o mesmo recibo — nunca emite de novo |
Recusada (900) ou com erro (999) | Aceita o reenvio e corrige o mesmo CT-e (mesmo número e série), em vez de emitir outro |
| Com erro, mas o CT-e já autorizado | Devolve o mesmo recibo, que passa a responder 004 |
Depois de um 999 por timeout da SEFAZ, a SEFAZ pode ter autorizado o CT-e sem que a resposta
chegasse. O reenvio com a mesma numero-origem descobre isso (a SEFAZ responde duplicidade, e o
FazNota confere que o documento autorizado é o desta tentativa) e devolve o CT-e como autorizado —
não emite outro.
A origem é separada por modelo: a mesma numero-origem pode existir num CT-e e num CT-e OS.
Cancelar
Cancela na SEFAZ um CT-e autorizado. Identifique-o pelo recibo da emissão (ou pela chave).
curl -X POST $BASE/cte/cancelamento \ -H "Authorization: Token $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "recibo": "RECIBO-DA-EMISSAO", "motivo": "Valor do frete informado incorretamente" }'motivo: 15 a 255 caracteres, obrigatório.- O protocolo de autorização sai do cadastro — não envie.
- Resultado em
GET /cte/{recibo-do-cancelamento}:010quando cancelado,900se a SEFAZ recusar (por exemplo, fora do prazo).
Carta de correção
curl -X POST $BASE/cte/carta-correcao \ -H "Authorization: Token $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "recibo": "RECIBO-DA-EMISSAO", "correcoes": [ { "grupo": "compl", "campo": "xObs", "valor": "Entrega no período da tarde" } ] }'Cada correção tem grupo e campo (nomes do leiaute da SEFAZ) e valor; nro-item só quando
o campo pertence a uma lista. O número sequencial da carta é calculado pelo FazNota.
Resultado: 004 registrada, 900 recusada.
Eventos
Todos identificam o CT-e pelo recibo da emissão ou pela chave e são assíncronos (resultado
em GET /cte/{recibo-do-evento}, 004 registrado ou 900 recusado). O protocolo de
autorização (n-prot) e o número sequencial do evento são preenchidos pelo FazNota — não
envie.
| Rota | Evento | Campos |
|---|---|---|
/cte/comprovante-entrega | 110180 | dh-entrega, n-doc e x-nome de quem recebeu, hash-entrega (SHA-1 em Base64 da chave + imagem do comprovante), dh-hash-entrega; latitude/longitude e inf-entrega (chaves das NF-e entregues) opcionais |
/cte/comprovante-entrega/cancelamento | 110181 | recibo-evento: o recibo do comprovante |
/cte/insucesso-entrega | 110190 | dh-tentativa, tp-motivo (1 recusa do recebedor, 2 não atendimento, 3 endereço inexistente, 4 outros, com x-just-motivo de 15 a 256 caracteres); n-tentativa, latitude/longitude opcionais |
/cte/insucesso-entrega/cancelamento | 110191 | recibo-evento: o recibo do insucesso |
/cte/registro-multimodal | 110160 | x-registro (15 a 1000 caracteres); n-doc opcional |
/cte/informacoes-gtv e /cte-os/informacoes-gtv | 110170 | gtv[]: n-doc, id, d-emi, n-dv, q-carga, especies[] (tp-especie, v-especie), rem e dest (cnpj ou cpf, uf, x-nome) |
/cte/desacordo e /cte-os/desacordo | 610110 | chave e x-obs (15 a 255 caracteres) |
/cte/desacordo/cancelamento e /cte-os/desacordo/cancelamento | 610111 | recibo-evento: o recibo do desacordo |
Exemplo — comprovante de entrega e o cancelamento dele:
curl -X POST $BASE/cte/comprovante-entrega \ -H "Authorization: Token $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "recibo": "RECIBO-DA-EMISSAO", "dh-entrega": "2026-11-15T10:00:00-03:00", "n-doc": "12345678901", "x-nome": "Joao da Silva", "hash-entrega": "2jmj7l5rSw0yVb/vlWAYkK/YBwk=", "dh-hash-entrega": "2026-11-15T10:00:00-03:00" }'
curl -X POST $BASE/cte/comprovante-entrega/cancelamento \ -H "Authorization: Token $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "recibo-evento": "RECIBO-DO-COMPROVANTE" }'O EPEC (/cte/epec) foi extinto pela NT 2026.004 e é recusado na hora.