IAEsta documentação também existe 100% adaptada para modelos de IA: /api-de-cte.md

Documentação

API de CT-e

Emita o CT-e na SEFAZ a partir do seu ERP ou TMS pela API do Meu Rastreio: emissão assíncrona, consulta, cancelamento, carta de correção, comprovante de entrega, DACTE, XML e webhooks.

Base URLhttps://painel.meurastreio.app/api/v1
Requisitos e ativação
Nesta página

Visão geral

A API de CT-e emite o Conhecimento de Transporte Eletrônico na SEFAZ a partir do seu sistema (ERP, TMS ou outro), em nome de uma filial, com o certificado digital configurado no Meu Rastreio. Ela também consulta o documento, registra os eventos e devolve o XML e o DACTE.

  • A emissão é assíncrona: o POST responde na hora dizendo que o CT-e entrou na fila, e a autorização chega depois, pela consulta ou por webhook.
  • A external_reference é a chave do CT-e para o seu sistema. Depois de autorizado, a chave de acesso (access_key) também serve para localizar o documento.
  • Os eventos (cancelamento, carta de correção, comprovante e insucesso de entrega) seguem o mesmo desenho: pedido enfileirado, resultado depois.
  • Série, numeração, ambiente e certificado vêm da configuração fiscal da filial.
métodocaminhoo que faz
POST/ctesEmite um CT-e, ou reenvia o da mesma external_reference.
GET/ctes/{external_reference}Consulta um CT-e.
GET/ctes?external_reference= ou ?access_key=A mesma consulta, pela query string.
GET/ctes?date_from=&date_to=Lista os CT-e do período.
POST/ctes/cancelCancelamento.
POST/ctes/correction-letterCarta de correção.
POST/ctes/delivery-receiptComprovante de entrega.
POST/ctes/cancel-delivery-receiptCancelamento do comprovante de entrega.
POST/ctes/delivery-failureInsucesso na entrega.
POST/ctes/cancel-delivery-failureCancelamento do insucesso na entrega.
GET/ctes/pdfDACTE ou comprovante de um evento, em PDF.

Requisitos e ativação

Antes da primeira chamada, confira com o administrador da sua conta no Meu Rastreio:

  1. O plano da empresa inclui o módulo Documentos fiscais. Sem ele, a API responde 402.
  2. Existe uma integração com o canal API na filial que vai emitir. Ela é criada no painel, em Integrações → nova integração, por um usuário administrador.
  3. A integração está ativa e com a permissão CT-e ligada. Sem a permissão, a API responde 401.
  4. A filial tem a configuração fiscal preenchida no painel, com certificado digital vinculado. Sem ela, a API responde 422 FISCAL_CONFIG_NOT_FOUND.
  5. O RNTRC do emitente está na configuração fiscal, ou será enviado no campo rntrc de cada CT-e.
O ambiente (produção ou homologação), a série e a numeração vêm da configuração fiscal da filial: o corpo da requisição não escolhe ambiente nem número do CT-e.

Autenticação

Envie o token da integração no cabeçalho x-api-token de todas as chamadas.

cabeçalho
x-api-token: 0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9
  • O token é um UUID e pertence a uma integração de uma filial: tudo o que você emite e consulta com ele é dessa filial. Empresa com várias filiais usa um token por filial.
  • Ele aparece na tela da integração, no painel, e não tem validade.
  • Para revogar, desative ou exclua a integração, ou substitua o token. O token antigo deixa de funcionar.
  • O mesmo token pode ter outras permissões. Esta API exige a permissão CT-e.
  • Só HTTPS. Nunca envie o token na URL e guarde-o como senha, em cofre de segredos.
  • Token ausente ou desconhecido responde 401 com {"message":"Acesso negado"}.

Primeira chamada

Emita um CT-e. Gere um UUID para a external_reference e guarde-o: é a sua chave para consultar, reenviar e registrar eventos.

requisição
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "cte": {
    "cfop": "6353",
    "natureza_operacao": "Prestação de serviço de transporte",
    "tomador": "SENDER",
    "origem": {
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "destino": {
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ"
    },
    "remetente": {
      "type": 1,
      "id": "00000000000191",
      "state_inscription": "110042490114",
      "name": "Remetente Exemplo Ltda",
      "address": {
        "zipcode": "01001000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "SP",
        "city": "São Paulo"
      }
    },
    "destinatario": {
      "type": 1,
      "id": "00000000000272",
      "state_inscription": "87654321",
      "name": "Destinatário Exemplo Ltda",
      "address": {
        "zipcode": "20010000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "RJ",
        "city": "Rio de Janeiro"
      }
    },
    "valores": {
      "total_servico": 1500,
      "a_receber": 1500,
      "componentes": [
        {
          "nome": "Frete peso",
          "valor": 1400
        },
        {
          "nome": "Pedágio",
          "valor": 100
        }
      ]
    },
    "icms": {
      "cst": "00",
      "base": 1500,
      "aliquota": 12,
      "valor": 180
    },
    "ibs_cbs": {
      "cst": "000",
      "classificacao_tributaria": "000001",
      "base": 1500,
      "ibs_uf_aliquota": 0.1,
      "ibs_uf_valor": 1.5,
      "ibs_municipal_aliquota": 0,
      "ibs_municipal_valor": 0,
      "ibs_valor": 1.5,
      "cbs_aliquota": 0.9,
      "cbs_valor": 13.5,
      "valor_total_documento": 1500
    },
    "carga": {
      "valor": 85000,
      "produto_predominante": "Eletrônicos",
      "quantidades": [
        {
          "unidade": "01",
          "tipo_medida": "PESO BRUTO",
          "quantidade": 1200
        }
      ]
    },
    "documentos": [
      {
        "chave_nfe": "35261100000000000272550010000456781000045678"
      }
    ],
    "observacao": "Entrega em horário comercial"
  }
}'
resposta 201
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "cte": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PENDING"
  }
}

O 201 quer dizer enfileirado, não autorizado. protocol identifica a chamada. Consulte o resultado alguns segundos depois:

requisição
curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"

Quando status for AUTHORIZED, a resposta traz chave de acesso, protocolo, xml_url e pdf_url.

Emissão

POST /ctes recebe um JSON com a referência e o objeto cte. Valores monetários são números em reais (1500.5), nunca texto.

Corpo raiz
campotipoobrigatórioregras
external_referencestring (UUID)nãoA sua chave para o CT-e. Sem ela, o Meu Rastreio gera uma e devolve na resposta. Enviar de novo a mesma referência reenvia o documento (ver Reenvio).
cteobjectsimOs dados do conhecimento.
CT-e cte
campotipoobrigatórioregras
cfopstringsimCFOP da prestação, com 4 dígitos.
natureza_operacaostringsimAté 60 caracteres.
tipo_servicointegernãoCódigo do tipo de serviço, de 0 a 4. Padrão 0 (normal). 1 (subcontratação), 2 (redespacho) e 3 (redespacho intermediário) exigem documentos_anteriores.
forma_emissaostringnãoNORMAL (padrão), CONTINGENCY, SVC_RS, SVC_SP ou EPEC.
justificativa_contingenciastringfora da emissão normalDe 15 a 256 caracteres.
data_contingenciadatetimenãoEntrada em contingência. Só é lida fora da emissão normal.
tipo_documentostringnãoNORMAL (padrão), COMPLEMENT (complemento de valores) ou SUBSTITUTE (substituição).
chave_referenciadastringem complemento e substituiçãoChave de 44 posições do CT-e complementado ou substituído.
formato_impressaointegernãoFormato do DACTE: 1 ou 2.
retirabooleannãoO recebedor retira a carga. Padrão false.
detalhe_retirastringcom retiraAté 160 caracteres.
tomadorstringsimQuem paga o frete: SENDER (remetente), DISPATCHER (expedidor), RECEIVER (recebedor), RECIPIENT (destinatário) ou OTHER (outro).
origemobjectsimMunicípio de início da prestação: ibge (7 dígitos), cidade e uf.
destinoobjectsimMunicípio de fim da prestação, no mesmo formato.
remetenteobjectsimParticipante (ver tabela).
destinatarioobjectsimParticipante.
expedidorobjectcom tomador DISPATCHERParticipante.
recebedorobjectcom tomador RECEIVERParticipante.
tomador_outrosobjectcom tomador OTHERParticipante. Ignorado nos demais tomadores.
valoresobjectsimValores da prestação (ver tabela).
icmsobjectsimICMS (ver tabela).
ibs_cbsobjectsimIBS e CBS (ver tabela).
cargaobjectsimCarga transportada (ver tabela).
documentosarraysimAs NF-e transportadas. Ao menos uma, sem chave repetida.
documentos_anterioresarraycom tipo_servico 1, 2 ou 3Documentos de transporte anteriores (ver tabela).
autorizadosarraynãoAté 10 CPFs/CNPJs autorizados a baixar o XML, sem repetição.
observacoesarraynãoObservações estruturadas (ver tabela). Até 10 por destino, sem repetir campo no mesmo destino.
cobrancaobjectnãoFatura e duplicatas (ver tabela).
rntrcstringnãoRNTRC com 8 dígitos. Omitido, vale o da configuração fiscal; sem nenhum dos dois: 422 RNTRC_REQUIRED.
observacaostringnãoObservações gerais, até 2000 caracteres.
observacao_fiscostringnãoInformações de interesse do fisco, até 2000 caracteres.
Participante cte.remetente, cte.destinatario, cte.expedidor, cte.recebedor, cte.tomador_outros
campotipoobrigatórioregras
typenumbersim0 para pessoa física, 1 para pessoa jurídica.
idstringsimCPF ou CNPJ do participante.
state_inscriptionstringsimInscrição estadual.
namestringsimNome ou razão social.
fantasyNamestringnãoNome fantasia.
activitystringnãoTRANSPORTADOR, INDUSTRIA, COMERCIO, COMUNICACAO, ENERGIA, PRODUTOR_RURAL, NAO_CONTRIBUINTE ou DISPENSADO_NF.
tax_regimestringnãoNORMAL, SIMPLES_NACIONAL, SIMPLES_NACIONAL_EXCESSO ou MEI.
emailstringnãoE-mail válido.
phonestringnãoTelefone.
addressobjectsimEndereço (ver tabela).
Endereço do participante …​.address
campotipoobrigatórioregras
zipcodestringsimCEP.
streetstringsimLogradouro.
numberstringnãoNúmero.
neighborhoodstringnãoBairro.
complementstringnãoComplemento.
countrystringsimPaís, com 2 letras (BR).
statestringsimUF.
citystringsimMunicípio. A API precisa identificar o código IBGE dele (ADDRESS_WITHOUT_IBGE).
latitude, longitudenumbernãoCoordenadas.
Valores cte.valores
campotipoobrigatórioregras
total_serviconumbersimValor total da prestação.
a_recebernumbernãoPadrão: total_servico. Não pode ser maior que ele.
componentesarraysimAo menos um { nome, valor }; nome com até 15 caracteres. A soma dos valores deve ser igual a total_servico.
ICMS cte.icms
campotipoobrigatórioregras
cststringsim00, 20, 40, 41, 51, 60, 90, SN (Simples Nacional) ou OUTRA_UF. Precisa ser compatível com o regime tributário do emitente (ICMS_CST_INCOMPATIBLE_WITH_CRT).
basenumbernãoBase de cálculo.
aliquotanumbernãoAlíquota, em percentual.
valornumbernãoValor do ICMS.
percentual_reducaonumbernãoRedução da base, de 0 a 100.
creditonumbernãoCrédito outorgado ou presumido.
total_tributosnumbernãoValor total aproximado dos tributos.
difalobjectnãoPartilha do ICMS interestadual: base, fcp_aliquota, aliquota, aliquota_interestadual, fcp_valor, valor e valor_uf_origem.
IBS e CBS cte.ibs_cbs
campotipoobrigatórioregras
cststringsimCST do IBS/CBS, com 3 dígitos.
classificacao_tributariastringsimCódigo de classificação tributária, com 6 dígitos.
basenumbersimBase de cálculo.
ibs_uf_aliquota, ibs_uf_valornumbersimAlíquota e valor do IBS estadual.
ibs_municipal_aliquota, ibs_municipal_valornumbersimAlíquota e valor do IBS municipal.
ibs_valornumbersimValor total do IBS.
cbs_aliquota, cbs_valornumbersimAlíquota e valor da CBS.
valor_total_documentonumbersimValor total do documento fiscal.
Carga cte.carga
campotipoobrigatórioregras
valornumbersimValor total da carga.
valor_averbadonumbernãoValor da carga para averbação.
produto_predominantestringsimAté 60 caracteres.
outras_caracteristicasstringnãoAté 30 caracteres.
quantidadesarraysimAo menos uma medida: unidade (00 m³, 01 kg, 02 t, 03 unidade, 04 litros, 05 MMBTU), tipo_medida (até 20 caracteres, como PESO BRUTO) e quantidade (maior que zero).
NF-e transportada cte.documentos[]
campotipoobrigatórioregras
chave_nfestringsimChave de acesso da NF-e, com 44 posições.
previsao_entregadatetimenãoPrevisão de entrega.
order_searchobjectnãoComo localizar o pedido do Meu Rastreio ligado a esta nota: external_id (UUID), chave_nfe, chave_cte, order_number ou nfe (number, serie, cnpj).
Documento anterior cte.documentos_anteriores[]
campotipoobrigatórioregras
emitenteobjectsimcpf_cnpj (obrigatório), inscricao_estadual, nome (até 60) e uf.
tipostringnãoELECTRONIC (padrão) ou PAPER.
chavestringno tipo ELECTRONICChave de acesso do CT-e anterior, com 44 posições.
papelobjectno tipo PAPERmodelo (até 2), serie (até 3), subserie (até 2, opcional), numero (até 20) e emitido_em.
Observação estruturada cte.observacoes[]
campotipoobrigatórioregras
destinostringsimCONTRIBUINTE ou FISCO.
campostringsimIdentificação do campo, até 20 caracteres.
valorstringsimConteúdo, até 160 caracteres.
Cobrança cte.cobranca
campotipoobrigatórioregras
numerostringnãoNúmero da fatura, até 20 caracteres.
valor_original, valor_desconto, valor_liquidonumbernãoValores da fatura.
parcelasarraynãoDuplicatas: numero (até 20, obrigatório), vencimento e valor (obrigatório).
corpo de exemplo
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "cte": {
    "cfop": "6353",
    "natureza_operacao": "Prestação de serviço de transporte",
    "tomador": "SENDER",
    "origem": {
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "destino": {
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ"
    },
    "remetente": {
      "type": 1,
      "id": "00000000000191",
      "state_inscription": "110042490114",
      "name": "Remetente Exemplo Ltda",
      "address": {
        "zipcode": "01001000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "SP",
        "city": "São Paulo"
      }
    },
    "destinatario": {
      "type": 1,
      "id": "00000000000272",
      "state_inscription": "87654321",
      "name": "Destinatário Exemplo Ltda",
      "address": {
        "zipcode": "20010000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "RJ",
        "city": "Rio de Janeiro"
      }
    },
    "valores": {
      "total_servico": 1500,
      "a_receber": 1500,
      "componentes": [
        {
          "nome": "Frete peso",
          "valor": 1400
        },
        {
          "nome": "Pedágio",
          "valor": 100
        }
      ]
    },
    "icms": {
      "cst": "00",
      "base": 1500,
      "aliquota": 12,
      "valor": 180
    },
    "ibs_cbs": {
      "cst": "000",
      "classificacao_tributaria": "000001",
      "base": 1500,
      "ibs_uf_aliquota": 0.1,
      "ibs_uf_valor": 1.5,
      "ibs_municipal_aliquota": 0,
      "ibs_municipal_valor": 0,
      "ibs_valor": 1.5,
      "cbs_aliquota": 0.9,
      "cbs_valor": 13.5,
      "valor_total_documento": 1500
    },
    "carga": {
      "valor": 85000,
      "produto_predominante": "Eletrônicos",
      "quantidades": [
        {
          "unidade": "01",
          "tipo_medida": "PESO BRUTO",
          "quantidade": 1200
        }
      ]
    },
    "documentos": [
      {
        "chave_nfe": "35261100000000000272550010000456781000045678"
      }
    ],
    "observacao": "Entrega em horário comercial"
  }
}
resposta 201
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "cte": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PENDING"
  }
}
A API valida o formato e as regras que conhece antes de enfileirar, mas quem autoriza é a SEFAZ. Um 201 seguido de REJECTED é esperado quando os dados fiscais não fecham; o motivo vem em c_stat e status_reason.

Reenvio

O POST funciona como criar-ou-substituir pela external_reference: referência nova cria o CT-e; referência que já existe substitui os dados e volta o documento para a fila, zerando protocolo, motivo e arquivos da tentativa anterior.

status do documentoo que o reenvio faz
PENDING, PROCESSING, REJECTED ou ERRORSubstitui os dados e enfileira de novo, mantendo série e número.
DENIEDSubstitui e enfileira com numeração nova: a denegação inutiliza o número anterior na SEFAZ.
AUTHORIZED, CANCELED ou CLOSED409 DOCUMENT_ALREADY_PROCESSED: documento aceito pela SEFAZ não se corrige; cancele e emita outro, com outra referência.
  • Referência que já pertence a outra filial responde 409 DOCUMENT_FROM_ANOTHER_SUBSIDIARY.
  • Se a filial trocou de ambiente (homologação/produção) depois da primeira emissão, o reenvio responde 409 DOCUMENT_ENVIRONMENT_CHANGED: emita um documento novo.

Consulta e listagem

chamadadevolve
GET /ctes/{external_reference}O CT-e dessa referência.
GET /ctes?external_reference= ou ?access_key=O mesmo CT-e, pela query string.
GET /ctes?date_from=&date_to=A lista do período, paginada, do mais novo para o mais antigo.

A consulta só enxerga documentos da filial do token: referência de outra filial, ou que não existe, responde 404 DOCUMENT_NOT_FOUND. Na lista, cada item de data é o mesmo objeto da consulta individual.

parâmetro da listaobrigatóriocomo usar
date_fromsimInício do período, em ISO 8601 com fuso: 2026-11-01T00:00:00-03:00 ou 2026-11-01T03:00:00Z. Data sem fuso é recusada.
date_tosimFim do período, com fuso. Igual ou posterior a date_from.
statusnãoFiltra por um ou mais status: status=AUTHORIZED,CANCELED ou o parâmetro repetido. Valores aceitos: PENDING, PROCESSING, AUTHORIZED, DENIED, REJECTED, CANCELED, ERROR.
pagenãoPágina, a partir de 1. Padrão: 1.
per_pagenãoItens por página, de 1 a 100. Padrão: 10.
  • O período filtra por data de emissão do CT-e; para o que ainda não foi emitido, pela data de criação.
  • Sem date_from e date_to, ou com um status que não existe, a resposta é 422 VALIDATION_ERROR.
  • O + do fuso precisa ir codificado como %2B na URL. Z e -03:00 não precisam.
  • A resposta da lista é { data, pagination: { page, per_page, total, total_pages } }.
consulta
curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
resposta 200
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "status": "AUTHORIZED",
  "emission_type": "NORMAL",
  "serie": 1,
  "number": 1234,
  "access_key": "35261100000000000191570010000012341000012345",
  "protocol": "135260000012345",
  "c_stat": 100,
  "status_reason": "Autorizado o uso do documento",
  "issued_at": "2026-11-19T14:01:58.000Z",
  "authorized_at": "2026-11-19T14:02:11.000Z",
  "canceled_at": null,
  "xml_url": "https://painel.meurastreio.app/api/files/3f6f0c2e-0000-4000-8000-000000000000",
  "pdf_url": "https://painel.meurastreio.app/api/v1/ctes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "events": []
}
lista
curl -s "https://painel.meurastreio.app/api/v1/ctes?date_from=2026-11-01T00:00:00-03:00&date_to=2026-11-30T23:59:59-03:00&status=AUTHORIZED,CANCELED&per_page=100" \
  -H "x-api-token: SEU_TOKEN"
CT-e na resposta objeto devolvido
campotipoobrigatórioregras
external_referencestring—A sua referência.
statusstring—Ver a seção Status.
emission_typestring—Forma de emissão.
serie, numberinteger—Série e número. null até a numeração ser atribuída.
access_keystring—Chave de acesso, com 44 posições.
protocolstring—Protocolo de autorização na SEFAZ.
c_statinteger—Código de retorno da SEFAZ.
status_reasonstring—Motivo devolvido pela SEFAZ, ou a descrição do erro.
issued_atdatetime—Emissão.
authorized_atdatetime—Autorização.
canceled_atdatetime—Cancelamento.
xml_urlstring—Link do XML do documento. null enquanto não houver XML.
pdf_urlstring—Endereço do DACTE na rota /pdf. null enquanto o PDF não estiver disponível.
eventsarray—Eventos do documento (ver tabela).
Evento na resposta events[]
campotipoobrigatórioregras
typestring—Tipo do evento.
sequenceinteger—Sequência do evento dentro do tipo, a partir de 1.
statusstring—PENDING, PROCESSING, REGISTERED, REJECTED ou ERROR.
justificationstring—Justificativa enviada, quando o evento tem.
protocolstring—Protocolo de registro do evento na SEFAZ.
c_statinteger—Código de retorno da SEFAZ para o evento.
status_reasonstring—Motivo devolvido pela SEFAZ.
registered_atdatetime—Quando o evento foi registrado.
xml_urlstring—Link do XML do evento.
pdf_urlstring—Endereço do PDF do evento na rota /pdf. null enquanto o evento não estiver registrado.
Datas saem em ISO 8601, em UTC. Campo sem valor vem null. Novos campos podem aparecer com o tempo; ignore o que o seu sistema não conhece.

Eventos

Evento é o que se registra na SEFAZ depois que o CT-e está autorizado. Cada evento tem a sua rota, sempre POST.

  • O documento é localizado por external_reference ou access_key, enviados no corpo junto com os campos do evento.
  • A resposta é 201 com { protocol, cte: { external_reference, event: { type, sequence, status } } }. Como na emissão, 201 quer dizer enfileirado: o registro na SEFAZ vem depois, em events da consulta ou pelos webhooks de evento.
  • Todos os eventos exigem o CT-e em AUTHORIZED. Fora disso: 409 DOCUMENT_NOT_CANCELABLE no cancelamento e 409 DOCUMENT_NOT_CHANGEABLE nos demais.
  • Comprovante de entrega, insucesso e os cancelamentos deles exigem o protocolo de autorização do CT-e (409 DOCUMENT_WITHOUT_PROTOCOL).
  • Acontecem uma vez por documento: o cancelamento. Depois de registrados, um novo pedido responde 409. Podem se repetir: a carta de correção (a SEFAZ aceita até 20 por CT-e), o comprovante de entrega, o insucesso na entrega e os cancelamentos desses dois; cada novo pedido ganha a próxima sequence.
  • Com um evento do mesmo tipo ainda em PENDING ou PROCESSING, um novo pedido responde 409 (EVENT_ALREADY_PENDING).
  • Evento que terminou em REJECTED ou ERROR pode ser pedido de novo: ele reaproveita a mesma sequence, com os dados novos.
  • Documento emitido por terceiro e importado é só leitura: 409 IMPORTED_DOCUMENT_READ_ONLY.
Identificação do CT-e em todo corpo de evento
campotipoobrigatórioregras
external_referencestring (UUID)um dos doisA referência do documento.
access_keystringum dos doisA chave de acesso, com 44 posições.
Cancelamento POST /ctes/cancel
campotipoobrigatórioregras
justificativastringsimDe 15 a 255 caracteres.
Carta de correção POST /ctes/correction-letter
campotipoobrigatórioregras
correcoesarraysimDe 1 a 15 correções.
correcoes[].grupostringsimGrupo do XML que contém o campo corrigido, até 20 caracteres.
correcoes[].campostringsimCampo corrigido, até 20 caracteres.
correcoes[].valorstringsimNovo valor, até 700 caracteres.
correcoes[].itemintegernãoNúmero do item, de 1 a 990, quando o grupo se repete.
Comprovante de entrega POST /ctes/delivery-receipt
campotipoobrigatórioregras
entregue_emdatetimesimData e hora da entrega, em ISO 8601 com fuso.
documento_recebedorstringsimDocumento de quem recebeu, até 20 caracteres.
nome_recebedorstringsimAté 60 caracteres.
latitude, longitudenumbernãoLocal da entrega.
hash_entregastringsimHash do comprovante de entrega, em Base64 (de 28 a 256 caracteres).
hash_entrega_emdatetimesimQuando o hash foi gerado, com fuso.
notasarraynãoChaves das NF-e entregues (44 posições cada), até 2000.
Cancelamento do comprovante de entrega POST /ctes/cancel-delivery-receipt
campotipoobrigatórioregras
protocolo_comprovantestringsimProtocolo (15 dígitos) do comprovante registrado que será cancelado. Sem um comprovante registrado com esse protocolo: 404 EVENT_TO_CANCEL_NOT_FOUND.
Insucesso na entrega POST /ctes/delivery-failure
campotipoobrigatórioregras
tentativa_emdatetimesimData e hora da tentativa, com fuso.
numero_tentativaintegernãoDe 1 a 99.
motivointegersim1 recebedor não encontrado, 2 recusa do recebedor, 3 endereço inexistente, 4 outros.
justificativa_motivostringcom motivo 4De 15 a 256 caracteres.
latitude, longitudenumbernãoLocal da tentativa.
hash_tentativastringnãoHash da tentativa, em Base64. Anda junto com hash_tentativa_em: ou os dois, ou nenhum.
hash_tentativa_emdatetimecom hash_tentativaQuando o hash foi gerado, com fuso.
notasarraynãoChaves das NF-e da tentativa, até 2000.
Cancelamento do insucesso na entrega POST /ctes/cancel-delivery-failure
campotipoobrigatórioregras
protocolo_insucessostringsimProtocolo (15 dígitos) do insucesso registrado que será cancelado. Sem um insucesso registrado com esse protocolo: 404 EVENT_TO_CANCEL_NOT_FOUND.
cancelar
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes/cancel" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "justificativa": "Emitido com valor de frete incorreto"
}'
resposta 201
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "cte": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "event": {
      "type": "CANCELLATION",
      "sequence": 1,
      "status": "PENDING"
    }
  }
}
carta de correção
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes/correction-letter" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "access_key": "35261100000000000191570010000012341000012345",
  "correcoes": [
    {
      "grupo": "compl",
      "campo": "xObs",
      "valor": "Entrega somente pela doca 3"
    }
  ]
}'
Os tipos de evento que aparecem em events[].type são CANCELLATION, CORRECTION_LETTER, DELIVERY_RECEIPT, DELIVERY_RECEIPT_CANCELLATION, DELIVERY_FAILURE e DELIVERY_FAILURE_CANCELLATION.

PDF e XML

XML

O XML autorizado é baixado pelo endereço em xml_url, devolvido na consulta do CT-e. Cada evento registrado tem o próprio xml_url dentro de events.

PDF

O DACTE e os comprovantes dos eventos saem da rota de PDF, com o mesmo token:

parâmetroobrigatóriocomo usar
external_reference ou access_keyum dos doisIdentifica o CT-e.
event_typenãoCom ele, a rota devolve o PDF do evento em vez do documento. É o type do evento em events.
event_sequencenãoSequência do evento. Padrão: 1.
requisição
curl -s "https://painel.meurastreio.app/api/v1/ctes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN" \
  -o dacte.pdf
  • Sucesso: 200 com Content-Type: application/pdf.
  • O PDF do documento existe quando o CT-e tem XML e está AUTHORIZED, CANCELED ou CLOSED; o do evento, quando o evento está REGISTERED. Fora disso a resposta é 409 com {"message":"PDF_NOT_AVAILABLE"}.
  • Evento que não existe no documento: 404 EVENT_NOT_FOUND.
  • Falha ao gerar o arquivo: 502 com {"message":"FISCAL_PDF_NOT_GENERATED"}. Tente de novo.
  • O pdf_url da consulta já aponta para esta rota com os parâmetros certos; envie o cabeçalho x-api-token ao chamá-lo.

Status

statuso que quer dizer
PENDINGGravado e aguardando a fila.
PROCESSINGEm envio à SEFAZ, ou emitido em contingência aguardando a transmissão.
AUTHORIZEDAutorizado. Chave, protocolo, XML e PDF disponíveis.
REJECTEDRejeitado. O motivo fica em c_stat e status_reason. Corrija e reenvie com a mesma referência.
DENIEDDenegado pela SEFAZ. O número é perdido; o reenvio usa numeração nova.
CANCELEDCancelado: o evento de cancelamento foi registrado.
ERRORFalha no processamento. O motivo fica em status_reason. Pode ser reenviado com a mesma referência.

Status dos eventos

statuso que quer dizer
PENDINGPedido gravado, aguardando a fila.
PROCESSINGEm envio à SEFAZ.
REGISTEREDRegistrado na SEFAZ. protocol e registered_at preenchidos.
REJECTEDRecusado pela SEFAZ. O motivo fica em c_stat e status_reason.
ERRORFalha no processamento. Pode ser pedido de novo.

Webhooks

O Meu Rastreio tem webhooks para os eventos do CT-e: em vez de consultar o status em laço, o seu sistema é avisado quando ele muda. Os webhooks são habilitados sob solicitação: escreva para [email protected] informando a filial, a URL que vai receber as chamadas e quais eventos você quer.

eventoquando é enviado
CTE_CREATEDO POST da API criou o CT-e. O reenvio da mesma referência não repete o evento.
CTE_AUTHORIZEDA SEFAZ autorizou.
CTE_REJECTEDTerminou sem autorização: REJECTED, DENIED ou ERROR.
CTE_CANCELEDO cancelamento foi registrado.
CTE_EVENT_REGISTEREDQualquer evento foi registrado na SEFAZ, cancelamento inclusive.
CTE_EVENT_REJECTEDUm evento foi recusado pela SEFAZ ou terminou em erro.
  • Cada evento habilitado gera uma chamada POST para a sua URL, com Content-Type: application/json.
  • O corpo é o próprio objeto do CT-e, direto na raiz do JSON, com os campos da tabela abaixo. Os nomes aqui são em camelCase, diferentes dos da API.
  • Responda com status 2xx. Em caso de falha, o envio é tentado até 3 vezes, com espera crescente entre as tentativas.
  • Cancelar gera dois avisos: o de cancelamento do documento e o de evento registrado. Quem só precisa saber que o documento foi cancelado escuta o primeiro; quem precisa saber quando um cancelamento foi recusado escuta os de evento.
  • PENDING e PROCESSING não geram aviso.
CT-e no webhook corpo do POST
campotipoobrigatórioregras
idinteger—Identificador do CT-e no Meu Rastreio.
externalReferencestring—A sua referência.
companySubsidiaryIdinteger—Identificador da filial.
statusstring—Status do documento.
statusDescriptionstring—O status em português.
environmentstring—Ambiente em que o documento foi emitido (produção ou homologação).
emissionTypestring—Forma de emissão.
emitterCnpjstring—CNPJ do emitente.
serie, numberinteger—Série e número.
accessKeystring—Chave de acesso.
protocolstring—Protocolo de autorização.
cStatinteger—Código de retorno da SEFAZ.
statusReasonstring—Motivo devolvido pela SEFAZ.
issuedAt, authorizedAt, canceledAtdatetime—Emissão, autorização e cancelamento.
totalServiceValuenumber—Valor total da prestação.
eventobject—null nos eventos do documento. Nos webhooks de evento traz type, typeDescription, status, statusDescription, protocol, statusReason e justification.
corpo recebido
{
  "id": 90211,
  "externalReference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "companySubsidiaryId": 12,
  "status": "AUTHORIZED",
  "environment": "PRODUCTION",
  "emissionType": "NORMAL",
  "emitterCnpj": "00000000000191",
  "serie": 1,
  "number": 1234,
  "accessKey": "35261100000000000191570010000012341000012345",
  "protocol": "135260000012345",
  "cStat": 100,
  "statusReason": "Autorizado o uso do CT-e",
  "issuedAt": "2026-11-19T14:01:58.000Z",
  "authorizedAt": "2026-11-19T14:02:11.000Z",
  "canceledAt": null,
  "totalServiceValue": 1500,
  "statusDescription": "Autorizado",
  "event": null
}
As chamadas não têm cabeçalho de assinatura. Para confirmar que a chamada veio do Meu Rastreio, peça ao suporte para configurar um cabeçalho personalizado com um segredo seu (por exemplo x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.
Trate o webhook como aviso: o mesmo evento pode chegar mais de uma vez. Use externalReference e status para decidir o que fazer e, na dúvida, consulte o documento pela API.

Limites de uso

limitevalorcomo funciona
Requisições por minuto120 por IPVale para todas as rotas da API somadas, contadas pelo IP de origem.
Itens por página10 (padrão), até 100Parâmetro per_page das listas.
Período da listaobrigatóriodate_from e date_to sempre informados: não existe listagem sem período.
Carta de correçãoaté 15 correções por cartaA SEFAZ aceita até 20 cartas por CT-e.
Autorizados a baixar o XMLaté 10Campo autorizados.
Observações estruturadasaté 10 por destinoCampo observacoes.
NF-e por comprovante ou insucessoaté 2000Campo notas dos eventos de entrega.

Passou do limite de requisições, a resposta é 429 e o cabeçalho Retry-After diz quantos segundos esperar:

resposta 429
HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "message": "TOO_MANY_REQUESTS" }
  • Respeite o Retry-After antes de tentar de novo.
  • Para acompanhar o resultado de uma emissão, prefira os webhooks. Se for consultar, espere alguns segundos entre uma consulta e outra.
  • Na lista, use per_page=100 para fazer menos chamadas.

Erros

O corpo de erro traz code, para o seu código decidir o que fazer, e message, para leitura de pessoas. Alguns erros trazem campos extras, como errors na validação.

resposta 422
{
  "code": "VALIDATION_ERROR",
  "message": "2 errors occurred",
  "errors": [
    "external_reference must be a valid UUID",
    "deve ser uma data ISO 8601 com fuso, como 2026-10-10T09:00:00-03:00"
  ]
}
statuscodequando acontece
401—Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code.
401INTEGRATION_DISABLEDA integração do token foi desativada pelo administrador.
401CTE_NOT_ALLOWEDA integração não tem a permissão CT-e.
402PLAN_WITHOUT_FISCAL_DOCUMENTSO plano da empresa não inclui o módulo de documentos fiscais.
422FISCAL_CONFIG_NOT_FOUNDFilial sem configuração fiscal ou sem certificado digital vinculado.
404DOCUMENT_NOT_FOUNDDocumento não encontrado na filial do token.
405METHOD_NOT_ALLOWEDMétodo HTTP não aceito pela rota. Em algumas rotas o identificador vem só em message.
422VALIDATION_ERRORCorpo ou query fora do formato. errors lista cada problema encontrado.
429—Limite de requisições. O corpo é {"message":"TOO_MANY_REQUESTS"}, com o cabeçalho Retry-After.
500INTERNAL_ERRORFalha inesperada. Tente de novo; se persistir, fale com o suporte informando o protocol ou o horário da chamada.
409DOCUMENT_ALREADY_PROCESSEDDocumento autorizado, cancelado ou encerrado não aceita reenvio.
409DOCUMENT_FROM_ANOTHER_SUBSIDIARYA referência externa já pertence a um documento de outra filial.
409DOCUMENT_ENVIRONMENT_CHANGEDA filial mudou de ambiente desde a emissão; emita um documento novo.
422RNTRC_REQUIREDRNTRC ausente no CT-e e na configuração fiscal da filial.
422ADDRESS_WITHOUT_IBGENão foi possível identificar o código IBGE do município de um participante.
422ICMS_CST_INCOMPATIBLE_WITH_CRTO CST do ICMS não combina com o regime tributário do emitente.
422PREVIOUS_DOCUMENTS_REQUIREDSubcontratação, redespacho e redespacho intermediário exigem documentos_anteriores.
404EVENT_TO_CANCEL_NOT_FOUNDNão há comprovante ou insucesso registrado com o protocolo informado.
404EVENT_NOT_FOUNDRota de PDF: o evento pedido não existe no documento.
409DOCUMENT_NOT_CANCELABLEO status do documento não permite cancelamento (só AUTHORIZED).
409DOCUMENT_NOT_CHANGEABLEO status do documento não aceita o evento pedido.
409DOCUMENT_WITHOUT_PROTOCOLO evento exige o protocolo de autorização e o documento não tem.
409IMPORTED_DOCUMENT_READ_ONLYDocumento emitido por terceiro e importado não aceita eventos.
409EVENT_ALREADY_PENDINGJá existe um evento do mesmo tipo aguardando processamento.
409EVENT_ALREADY_REGISTEREDO evento só acontece uma vez e já foi registrado.
409—Rota de PDF: {"message":"PDF_NOT_AVAILABLE"}, sem code.
502—Rota de PDF: {"message":"FISCAL_PDF_NOT_GENERATED"}, sem code.
  • 401 e 402: pare e avise uma pessoa. O problema é de token, permissão ou plano; insistir não resolve.
  • 404: confira a referência e se o token é da filial certa.
  • 422: corrija o corpo ou o cadastro apontado em message e envie de novo com a mesma external_reference.
  • 429: espere o Retry-After.
  • 409: leia o code. EVENT_ALREADY_PENDING pede espera; os demais dizem que o documento não está no status que a operação exige.
  • Rejeição da SEFAZ não é erro HTTP: a chamada responde 201 e a rejeição aparece depois, no status, c_stat e status_reason do documento ou do evento.

Exemplos completos

Emitir, acompanhar, baixar o DACTE e cancelar um CT-e com curl:

1. emitir
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "cte": {
    "cfop": "6353",
    "natureza_operacao": "Prestação de serviço de transporte",
    "tomador": "SENDER",
    "origem": {
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "destino": {
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ"
    },
    "remetente": {
      "type": 1,
      "id": "00000000000191",
      "state_inscription": "110042490114",
      "name": "Remetente Exemplo Ltda",
      "address": {
        "zipcode": "01001000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "SP",
        "city": "São Paulo"
      }
    },
    "destinatario": {
      "type": 1,
      "id": "00000000000272",
      "state_inscription": "87654321",
      "name": "Destinatário Exemplo Ltda",
      "address": {
        "zipcode": "20010000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "RJ",
        "city": "Rio de Janeiro"
      }
    },
    "valores": {
      "total_servico": 1500,
      "a_receber": 1500,
      "componentes": [
        {
          "nome": "Frete peso",
          "valor": 1400
        },
        {
          "nome": "Pedágio",
          "valor": 100
        }
      ]
    },
    "icms": {
      "cst": "00",
      "base": 1500,
      "aliquota": 12,
      "valor": 180
    },
    "ibs_cbs": {
      "cst": "000",
      "classificacao_tributaria": "000001",
      "base": 1500,
      "ibs_uf_aliquota": 0.1,
      "ibs_uf_valor": 1.5,
      "ibs_municipal_aliquota": 0,
      "ibs_municipal_valor": 0,
      "ibs_valor": 1.5,
      "cbs_aliquota": 0.9,
      "cbs_valor": 13.5,
      "valor_total_documento": 1500
    },
    "carga": {
      "valor": 85000,
      "produto_predominante": "Eletrônicos",
      "quantidades": [
        {
          "unidade": "01",
          "tipo_medida": "PESO BRUTO",
          "quantidade": 1200
        }
      ]
    },
    "documentos": [
      {
        "chave_nfe": "35261100000000000272550010000456781000045678"
      }
    ],
    "observacao": "Entrega em horário comercial"
  }
}'
2. consultar até autorizar
curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
3. baixar o DACTE
curl -s "https://painel.meurastreio.app/api/v1/ctes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN" \
  -o dacte.pdf
4. cancelar
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes/cancel" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "justificativa": "Emitido com valor de frete incorreto"
}'

Em JavaScript, emitindo e consultando até o status deixar de ser transitório, respeitando o 429:

JavaScript (Node 20+)
const BASE_URL = "https://painel.meurastreio.app/api/v1";
const TOKEN = process.env.MEU_RASTREIO_TOKEN;
const IN_PROGRESS = ["PENDING", "PROCESSING"];
const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function call(path, options = {}) {
  while (true) {
    const response = await fetch(`${BASE_URL}${path}`, {
      ...options,
      headers: { "x-api-token": TOKEN, "Content-Type": "application/json" },
    });

    if (response.status === 429) {
      await wait(Number(response.headers.get("Retry-After") ?? 5));
      continue;
    }

    const body = await response.json();

    if (!response.ok) throw new Error(`${response.status} ${body.code ?? ""} ${body.message}`);

    return body;
  }
}

async function emit(externalReference, cte) {
  // 201 means queued: the final status comes from the GET (or from the webhooks)
  await call("/ctes", {
    method: "POST",
    body: JSON.stringify({ external_reference: externalReference, cte }),
  });

  for (let attempt = 0; attempt < 60; attempt++) {
    await wait(5);

    const document = await call(`/ctes/${externalReference}`);

    if (!IN_PROGRESS.includes(document.status)) return document;
  }

  throw new Error("Ainda em processamento: consulte de novo mais tarde");
}

// cte: the object described in "Emissão"
const document = await emit(crypto.randomUUID(), cte);

console.log(document.status, document.status_reason);

Suporte

Ativação do módulo, configuração fiscal e certificado, permissão da integração, webhooks ou dúvidas sobre uma rejeição: [email protected]. Para contratar: [email protected].