Pular para o conteúdo

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ãoPOST /cte/emissaoPOST /cte-os/emissao
ResultadoGET /cte/{recibo}GET /cte-os/{recibo}
CancelamentoPOST /cte/cancelamentoPOST /cte-os/cancelamento
Carta de correçãoPOST /cte/carta-correcaoPOST /cte-os/carta-correcao
Eventosentrega, insucesso, desacordo, multimodal, GTVdesacordo, 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

  1. 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 é 400 na 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..." } }
  2. 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 consultaO que fazer
002Na fila. Continue o polling.
004Autorizado (ou evento registrado). Guarde chave e protocolo.
010CT-e cancelado.
900Recusado. Corrija o que x-motivo aponta e reenvie com o mesmo numero-origem.
999Erro técnico ou desfecho indeterminado. Reenvie o mesmo pedido.
500Recibo 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)

CampoObrigatórioRegra
numero-origemrecomendadoAté 60 caracteres. Veja Reenvio
cfopsim4 dígitos. Ajustado para 5932/6932 quando a prestação começa fora da UF do emitente
seriesim1 a 3 dígitos
n-ctnãoAusente, o número sai do contador da série
dh-eminãoAAAA-MM-DDThh:mm:ss-03:00. Ausente, o momento do envio
tp-servnão0 normal (padrão), 1 subcontratação, 2 redespacho, 3 redespacho intermediário, 4 vinculado a multimodal
tp-ctenão0 normal (padrão) ou 3 substituto (exige ref-cte)
modalnão01 rodoviário (padrão), 02 aéreo, 03 ferroviário, 04 aquaviário, 05 dutoviário, 06 multimodal
mun-ini, mun-fimsimCódigo IBGE (7 dígitos) ou {c-mun, x-mun, uf}
remetente, destinatariosimcnpj 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, recebedornãoMesma forma
tomadorsimCódigo do papel: 0 remetente, 1 expedidor, 2 recebedor, 3 destinatário, 4 outros (com tomador-doc, tomador-nome e tomador-ender)
prestacaosimvl-total, vl-receber, componentes[] (nome, valor)
icmsnãocst 00, 20, 40, 41, 51, 60 ou 90 e os valores. Ausente numa empresa do Simples, sai ICMSSN
cargasimvl-carga, produto-predominante, quantidade (maior que zero), unidade (01 KG, padrão)
documentosem tp-serv 0, 1 e 2Ao menos um documento transportado: NFe (chave), NF (nota em papel) ou outros. Sem ele a SEFAZ recusa com 693
doc-anteriorem 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-multimodalno modal correspondented-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)

Terminal window
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" }
}'
CampoObrigatórioRegra
tp-servsim6 transporte de pessoas, 7 transporte de valores, 8 excesso de bagagem
tp-ctenão0 normal, 1 complementar (exige ch-cte-comp), 3 substituto (exige ch-cte-sub)
modalnão01 rodoviário (padrão), 02 aéreo, 03 aquaviário, 04 ferroviário
tomadorsimObjeto (cnpj ou cpf, x-nome, ender) — ou só o documento, se estiver no cadastro
servicosim (exceto complementar)descricao (até 30 caracteres) e quantidade
modal-rodo-osno modal 01taf ou nr-reg-estadual
documentos-refem tp-serv 8Ao menos um item com ch-bpe (o BP-e que gerou o excesso)
icmsnãoCST 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 origemO que acontece
Na filaDevolve o mesmo recibo
AutorizadaDevolve 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á autorizadoDevolve 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).

Terminal window
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}: 010 quando cancelado, 900 se a SEFAZ recusar (por exemplo, fora do prazo).

Carta de correção

Terminal window
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.

RotaEventoCampos
/cte/comprovante-entrega110180dh-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/cancelamento110181recibo-evento: o recibo do comprovante
/cte/insucesso-entrega110190dh-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/cancelamento110191recibo-evento: o recibo do insucesso
/cte/registro-multimodal110160x-registro (15 a 1000 caracteres); n-doc opcional
/cte/informacoes-gtv e /cte-os/informacoes-gtv110170gtv[]: 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/desacordo610110chave e x-obs (15 a 255 caracteres)
/cte/desacordo/cancelamento e /cte-os/desacordo/cancelamento610111recibo-evento: o recibo do desacordo

Exemplo — comprovante de entrega e o cancelamento dele:

Terminal window
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.