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
POSTresponde 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étodo | caminho | o que faz |
|---|---|---|
POST | /ctes | Emite 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/cancel | Cancelamento. |
POST | /ctes/correction-letter | Carta de correção. |
POST | /ctes/delivery-receipt | Comprovante de entrega. |
POST | /ctes/cancel-delivery-receipt | Cancelamento do comprovante de entrega. |
POST | /ctes/delivery-failure | Insucesso na entrega. |
POST | /ctes/cancel-delivery-failure | Cancelamento do insucesso na entrega. |
GET | /ctes/pdf | DACTE 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:
- O plano da empresa inclui o módulo Documentos fiscais. Sem ele, a API responde
402. - 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.
- A integração está ativa e com a permissão CT-e ligada. Sem a permissão, a API responde
401. - A filial tem a configuração fiscal preenchida no painel, com certificado digital vinculado. Sem ela, a API responde
422 FISCAL_CONFIG_NOT_FOUND. - O RNTRC do emitente está na configuração fiscal, ou será enviado no campo
rntrcde cada CT-e.
Autenticação
Envie o token da integração no cabeçalho x-api-token de todas as chamadas.
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
401com{"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.
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"
}
}'{
"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:
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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
external_reference | string (UUID) | não | A 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). |
cte | object | sim | Os dados do conhecimento. |
CT-e cte
| campo | tipo | obrigatório | regras |
|---|---|---|---|
cfop | string | sim | CFOP da prestação, com 4 dígitos. |
natureza_operacao | string | sim | Até 60 caracteres. |
tipo_servico | integer | não | Có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_emissao | string | não | NORMAL (padrão), CONTINGENCY, SVC_RS, SVC_SP ou EPEC. |
justificativa_contingencia | string | fora da emissão normal | De 15 a 256 caracteres. |
data_contingencia | datetime | não | Entrada em contingência. Só é lida fora da emissão normal. |
tipo_documento | string | não | NORMAL (padrão), COMPLEMENT (complemento de valores) ou SUBSTITUTE (substituição). |
chave_referenciada | string | em complemento e substituição | Chave de 44 posições do CT-e complementado ou substituído. |
formato_impressao | integer | não | Formato do DACTE: 1 ou 2. |
retira | boolean | não | O recebedor retira a carga. Padrão false. |
detalhe_retira | string | com retira | Até 160 caracteres. |
tomador | string | sim | Quem paga o frete: SENDER (remetente), DISPATCHER (expedidor), RECEIVER (recebedor), RECIPIENT (destinatário) ou OTHER (outro). |
origem | object | sim | Município de início da prestação: ibge (7 dígitos), cidade e uf. |
destino | object | sim | Município de fim da prestação, no mesmo formato. |
remetente | object | sim | Participante (ver tabela). |
destinatario | object | sim | Participante. |
expedidor | object | com tomador DISPATCHER | Participante. |
recebedor | object | com tomador RECEIVER | Participante. |
tomador_outros | object | com tomador OTHER | Participante. Ignorado nos demais tomadores. |
valores | object | sim | Valores da prestação (ver tabela). |
icms | object | sim | ICMS (ver tabela). |
ibs_cbs | object | sim | IBS e CBS (ver tabela). |
carga | object | sim | Carga transportada (ver tabela). |
documentos | array | sim | As NF-e transportadas. Ao menos uma, sem chave repetida. |
documentos_anteriores | array | com tipo_servico 1, 2 ou 3 | Documentos de transporte anteriores (ver tabela). |
autorizados | array | não | Até 10 CPFs/CNPJs autorizados a baixar o XML, sem repetição. |
observacoes | array | não | Observações estruturadas (ver tabela). Até 10 por destino, sem repetir campo no mesmo destino. |
cobranca | object | não | Fatura e duplicatas (ver tabela). |
rntrc | string | não | RNTRC com 8 dígitos. Omitido, vale o da configuração fiscal; sem nenhum dos dois: 422 RNTRC_REQUIRED. |
observacao | string | não | Observações gerais, até 2000 caracteres. |
observacao_fisco | string | não | Informações de interesse do fisco, até 2000 caracteres. |
Participante cte.remetente, cte.destinatario, cte.expedidor, cte.recebedor, cte.tomador_outros
| campo | tipo | obrigatório | regras |
|---|---|---|---|
type | number | sim | 0 para pessoa física, 1 para pessoa jurídica. |
id | string | sim | CPF ou CNPJ do participante. |
state_inscription | string | sim | Inscrição estadual. |
name | string | sim | Nome ou razão social. |
fantasyName | string | não | Nome fantasia. |
activity | string | não | TRANSPORTADOR, INDUSTRIA, COMERCIO, COMUNICACAO, ENERGIA, PRODUTOR_RURAL, NAO_CONTRIBUINTE ou DISPENSADO_NF. |
tax_regime | string | não | NORMAL, SIMPLES_NACIONAL, SIMPLES_NACIONAL_EXCESSO ou MEI. |
email | string | não | E-mail válido. |
phone | string | não | Telefone. |
address | object | sim | Endereço (ver tabela). |
Endereço do participante ….address
| campo | tipo | obrigatório | regras |
|---|---|---|---|
zipcode | string | sim | CEP. |
street | string | sim | Logradouro. |
number | string | não | Número. |
neighborhood | string | não | Bairro. |
complement | string | não | Complemento. |
country | string | sim | País, com 2 letras (BR). |
state | string | sim | UF. |
city | string | sim | Município. A API precisa identificar o código IBGE dele (ADDRESS_WITHOUT_IBGE). |
latitude, longitude | number | não | Coordenadas. |
Valores cte.valores
| campo | tipo | obrigatório | regras |
|---|---|---|---|
total_servico | number | sim | Valor total da prestação. |
a_receber | number | não | Padrão: total_servico. Não pode ser maior que ele. |
componentes | array | sim | Ao menos um { nome, valor }; nome com até 15 caracteres. A soma dos valores deve ser igual a total_servico. |
ICMS cte.icms
| campo | tipo | obrigatório | regras |
|---|---|---|---|
cst | string | sim | 00, 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). |
base | number | não | Base de cálculo. |
aliquota | number | não | Alíquota, em percentual. |
valor | number | não | Valor do ICMS. |
percentual_reducao | number | não | Redução da base, de 0 a 100. |
credito | number | não | Crédito outorgado ou presumido. |
total_tributos | number | não | Valor total aproximado dos tributos. |
difal | object | não | Partilha do ICMS interestadual: base, fcp_aliquota, aliquota, aliquota_interestadual, fcp_valor, valor e valor_uf_origem. |
IBS e CBS cte.ibs_cbs
| campo | tipo | obrigatório | regras |
|---|---|---|---|
cst | string | sim | CST do IBS/CBS, com 3 dígitos. |
classificacao_tributaria | string | sim | Código de classificação tributária, com 6 dígitos. |
base | number | sim | Base de cálculo. |
ibs_uf_aliquota, ibs_uf_valor | number | sim | Alíquota e valor do IBS estadual. |
ibs_municipal_aliquota, ibs_municipal_valor | number | sim | Alíquota e valor do IBS municipal. |
ibs_valor | number | sim | Valor total do IBS. |
cbs_aliquota, cbs_valor | number | sim | Alíquota e valor da CBS. |
valor_total_documento | number | sim | Valor total do documento fiscal. |
Carga cte.carga
| campo | tipo | obrigatório | regras |
|---|---|---|---|
valor | number | sim | Valor total da carga. |
valor_averbado | number | não | Valor da carga para averbação. |
produto_predominante | string | sim | Até 60 caracteres. |
outras_caracteristicas | string | não | Até 30 caracteres. |
quantidades | array | sim | Ao 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[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
chave_nfe | string | sim | Chave de acesso da NF-e, com 44 posições. |
previsao_entrega | datetime | não | Previsão de entrega. |
order_search | object | não | Como 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[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
emitente | object | sim | cpf_cnpj (obrigatório), inscricao_estadual, nome (até 60) e uf. |
tipo | string | não | ELECTRONIC (padrão) ou PAPER. |
chave | string | no tipo ELECTRONIC | Chave de acesso do CT-e anterior, com 44 posições. |
papel | object | no tipo PAPER | modelo (até 2), serie (até 3), subserie (até 2, opcional), numero (até 20) e emitido_em. |
Observação estruturada cte.observacoes[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
destino | string | sim | CONTRIBUINTE ou FISCO. |
campo | string | sim | Identificação do campo, até 20 caracteres. |
valor | string | sim | Conteúdo, até 160 caracteres. |
Cobrança cte.cobranca
| campo | tipo | obrigatório | regras |
|---|---|---|---|
numero | string | não | Número da fatura, até 20 caracteres. |
valor_original, valor_desconto, valor_liquido | number | não | Valores da fatura. |
parcelas | array | não | Duplicatas: numero (até 20, obrigatório), vencimento e valor (obrigatório). |
{
"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"
}
}{
"protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
"cte": {
"external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"status": "PENDING"
}
}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 documento | o que o reenvio faz |
|---|---|
PENDING, PROCESSING, REJECTED ou ERROR | Substitui os dados e enfileira de novo, mantendo série e número. |
DENIED | Substitui e enfileira com numeração nova: a denegação inutiliza o número anterior na SEFAZ. |
AUTHORIZED, CANCELED ou CLOSED | 409 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
| chamada | devolve |
|---|---|
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 lista | obrigatório | como usar |
|---|---|---|
date_from | sim | Iní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_to | sim | Fim do período, com fuso. Igual ou posterior a date_from. |
status | não | Filtra por um ou mais status: status=AUTHORIZED,CANCELED ou o parâmetro repetido. Valores aceitos: PENDING, PROCESSING, AUTHORIZED, DENIED, REJECTED, CANCELED, ERROR. |
page | não | Página, a partir de 1. Padrão: 1. |
per_page | não | Itens 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_fromedate_to, ou com um status que não existe, a resposta é422 VALIDATION_ERROR. - O
+do fuso precisa ir codificado como%2Bna URL.Ze-03:00não precisam. - A resposta da lista é
{ data, pagination: { page, per_page, total, total_pages } }.
curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
-H "x-api-token: SEU_TOKEN"{
"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": []
}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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
external_reference | string | — | A sua referência. |
status | string | — | Ver a seção Status. |
emission_type | string | — | Forma de emissão. |
serie, number | integer | — | Série e número. null até a numeração ser atribuída. |
access_key | string | — | Chave de acesso, com 44 posições. |
protocol | string | — | Protocolo de autorização na SEFAZ. |
c_stat | integer | — | Código de retorno da SEFAZ. |
status_reason | string | — | Motivo devolvido pela SEFAZ, ou a descrição do erro. |
issued_at | datetime | — | Emissão. |
authorized_at | datetime | — | Autorização. |
canceled_at | datetime | — | Cancelamento. |
xml_url | string | — | Link do XML do documento. null enquanto não houver XML. |
pdf_url | string | — | Endereço do DACTE na rota /pdf. null enquanto o PDF não estiver disponível. |
events | array | — | Eventos do documento (ver tabela). |
Evento na resposta events[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
type | string | — | Tipo do evento. |
sequence | integer | — | Sequência do evento dentro do tipo, a partir de 1. |
status | string | — | PENDING, PROCESSING, REGISTERED, REJECTED ou ERROR. |
justification | string | — | Justificativa enviada, quando o evento tem. |
protocol | string | — | Protocolo de registro do evento na SEFAZ. |
c_stat | integer | — | Código de retorno da SEFAZ para o evento. |
status_reason | string | — | Motivo devolvido pela SEFAZ. |
registered_at | datetime | — | Quando o evento foi registrado. |
xml_url | string | — | Link do XML do evento. |
pdf_url | string | — | Endereço do PDF do evento na rota /pdf. null enquanto o evento não estiver registrado. |
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_referenceouaccess_key, enviados no corpo junto com os campos do evento. - A resposta é
201com{ protocol, cte: { external_reference, event: { type, sequence, status } } }. Como na emissão, 201 quer dizer enfileirado: o registro na SEFAZ vem depois, emeventsda consulta ou pelos webhooks de evento. - Todos os eventos exigem o CT-e em
AUTHORIZED. Fora disso:409 DOCUMENT_NOT_CANCELABLEno cancelamento e409 DOCUMENT_NOT_CHANGEABLEnos 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óximasequence. - Com um evento do mesmo tipo ainda em
PENDINGouPROCESSING, um novo pedido responde409(EVENT_ALREADY_PENDING). - Evento que terminou em
REJECTEDouERRORpode ser pedido de novo: ele reaproveita a mesmasequence, 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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
external_reference | string (UUID) | um dos dois | A referência do documento. |
access_key | string | um dos dois | A chave de acesso, com 44 posições. |
Cancelamento POST /ctes/cancel
| campo | tipo | obrigatório | regras |
|---|---|---|---|
justificativa | string | sim | De 15 a 255 caracteres. |
Carta de correção POST /ctes/correction-letter
| campo | tipo | obrigatório | regras |
|---|---|---|---|
correcoes | array | sim | De 1 a 15 correções. |
correcoes[].grupo | string | sim | Grupo do XML que contém o campo corrigido, até 20 caracteres. |
correcoes[].campo | string | sim | Campo corrigido, até 20 caracteres. |
correcoes[].valor | string | sim | Novo valor, até 700 caracteres. |
correcoes[].item | integer | não | Número do item, de 1 a 990, quando o grupo se repete. |
Comprovante de entrega POST /ctes/delivery-receipt
| campo | tipo | obrigatório | regras |
|---|---|---|---|
entregue_em | datetime | sim | Data e hora da entrega, em ISO 8601 com fuso. |
documento_recebedor | string | sim | Documento de quem recebeu, até 20 caracteres. |
nome_recebedor | string | sim | Até 60 caracteres. |
latitude, longitude | number | não | Local da entrega. |
hash_entrega | string | sim | Hash do comprovante de entrega, em Base64 (de 28 a 256 caracteres). |
hash_entrega_em | datetime | sim | Quando o hash foi gerado, com fuso. |
notas | array | não | Chaves das NF-e entregues (44 posições cada), até 2000. |
Cancelamento do comprovante de entrega POST /ctes/cancel-delivery-receipt
| campo | tipo | obrigatório | regras |
|---|---|---|---|
protocolo_comprovante | string | sim | Protocolo (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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
tentativa_em | datetime | sim | Data e hora da tentativa, com fuso. |
numero_tentativa | integer | não | De 1 a 99. |
motivo | integer | sim | 1 recebedor não encontrado, 2 recusa do recebedor, 3 endereço inexistente, 4 outros. |
justificativa_motivo | string | com motivo 4 | De 15 a 256 caracteres. |
latitude, longitude | number | não | Local da tentativa. |
hash_tentativa | string | não | Hash da tentativa, em Base64. Anda junto com hash_tentativa_em: ou os dois, ou nenhum. |
hash_tentativa_em | datetime | com hash_tentativa | Quando o hash foi gerado, com fuso. |
notas | array | não | Chaves das NF-e da tentativa, até 2000. |
Cancelamento do insucesso na entrega POST /ctes/cancel-delivery-failure
| campo | tipo | obrigatório | regras |
|---|---|---|---|
protocolo_insucesso | string | sim | Protocolo (15 dígitos) do insucesso registrado que será cancelado. Sem um insucesso registrado com esse protocolo: 404 EVENT_TO_CANCEL_NOT_FOUND. |
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"
}'{
"protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
"cte": {
"external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"event": {
"type": "CANCELLATION",
"sequence": 1,
"status": "PENDING"
}
}
}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"
}
]
}'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.
O DACTE e os comprovantes dos eventos saem da rota de PDF, com o mesmo token:
| parâmetro | obrigatório | como usar |
|---|---|---|
external_reference ou access_key | um dos dois | Identifica o CT-e. |
event_type | não | Com ele, a rota devolve o PDF do evento em vez do documento. É o type do evento em events. |
event_sequence | não | Sequência do evento. Padrão: 1. |
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:
200comContent-Type: application/pdf. - O PDF do documento existe quando o CT-e tem XML e está
AUTHORIZED,CANCELEDouCLOSED; o do evento, quando o evento estáREGISTERED. Fora disso a resposta é409com{"message":"PDF_NOT_AVAILABLE"}. - Evento que não existe no documento:
404 EVENT_NOT_FOUND. - Falha ao gerar o arquivo:
502com{"message":"FISCAL_PDF_NOT_GENERATED"}. Tente de novo. - O
pdf_urlda consulta já aponta para esta rota com os parâmetros certos; envie o cabeçalhox-api-tokenao chamá-lo.
Status
| status | o que quer dizer |
|---|---|
PENDING | Gravado e aguardando a fila. |
PROCESSING | Em envio à SEFAZ, ou emitido em contingência aguardando a transmissão. |
AUTHORIZED | Autorizado. Chave, protocolo, XML e PDF disponíveis. |
REJECTED | Rejeitado. O motivo fica em c_stat e status_reason. Corrija e reenvie com a mesma referência. |
DENIED | Denegado pela SEFAZ. O número é perdido; o reenvio usa numeração nova. |
CANCELED | Cancelado: o evento de cancelamento foi registrado. |
ERROR | Falha no processamento. O motivo fica em status_reason. Pode ser reenviado com a mesma referência. |
Status dos eventos
| status | o que quer dizer |
|---|---|
PENDING | Pedido gravado, aguardando a fila. |
PROCESSING | Em envio à SEFAZ. |
REGISTERED | Registrado na SEFAZ. protocol e registered_at preenchidos. |
REJECTED | Recusado pela SEFAZ. O motivo fica em c_stat e status_reason. |
ERROR | Falha 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.
| evento | quando é enviado |
|---|---|
CTE_CREATED | O POST da API criou o CT-e. O reenvio da mesma referência não repete o evento. |
CTE_AUTHORIZED | A SEFAZ autorizou. |
CTE_REJECTED | Terminou sem autorização: REJECTED, DENIED ou ERROR. |
CTE_CANCELED | O cancelamento foi registrado. |
CTE_EVENT_REGISTERED | Qualquer evento foi registrado na SEFAZ, cancelamento inclusive. |
CTE_EVENT_REJECTED | Um evento foi recusado pela SEFAZ ou terminou em erro. |
- Cada evento habilitado gera uma chamada
POSTpara a sua URL, comContent-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.
PENDINGePROCESSINGnão geram aviso.
CT-e no webhook corpo do POST
| campo | tipo | obrigatório | regras |
|---|---|---|---|
id | integer | — | Identificador do CT-e no Meu Rastreio. |
externalReference | string | — | A sua referência. |
companySubsidiaryId | integer | — | Identificador da filial. |
status | string | — | Status do documento. |
statusDescription | string | — | O status em português. |
environment | string | — | Ambiente em que o documento foi emitido (produção ou homologação). |
emissionType | string | — | Forma de emissão. |
emitterCnpj | string | — | CNPJ do emitente. |
serie, number | integer | — | Série e número. |
accessKey | string | — | Chave de acesso. |
protocol | string | — | Protocolo de autorização. |
cStat | integer | — | Código de retorno da SEFAZ. |
statusReason | string | — | Motivo devolvido pela SEFAZ. |
issuedAt, authorizedAt, canceledAt | datetime | — | Emissão, autorização e cancelamento. |
totalServiceValue | number | — | Valor total da prestação. |
event | object | — | null nos eventos do documento. Nos webhooks de evento traz type, typeDescription, status, statusDescription, protocol, statusReason e justification. |
{
"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
}x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.externalReference e status para decidir o que fazer e, na dúvida, consulte o documento pela API.Limites de uso
| limite | valor | como funciona |
|---|---|---|
| Requisições por minuto | 120 por IP | Vale para todas as rotas da API somadas, contadas pelo IP de origem. |
| Itens por página | 10 (padrão), até 100 | Parâmetro per_page das listas. |
| Período da lista | obrigatório | date_from e date_to sempre informados: não existe listagem sem período. |
| Carta de correção | até 15 correções por carta | A SEFAZ aceita até 20 cartas por CT-e. |
| Autorizados a baixar o XML | até 10 | Campo autorizados. |
| Observações estruturadas | até 10 por destino | Campo observacoes. |
| NF-e por comprovante ou insucesso | até 2000 | Campo notas dos eventos de entrega. |
Passou do limite de requisições, a resposta é 429 e o cabeçalho Retry-After diz quantos segundos esperar:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
{ "message": "TOO_MANY_REQUESTS" }- Respeite o
Retry-Afterantes 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=100para 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.
{
"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"
]
}| status | code | quando acontece |
|---|---|---|
| 401 | — | Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code. |
| 401 | INTEGRATION_DISABLED | A integração do token foi desativada pelo administrador. |
| 401 | CTE_NOT_ALLOWED | A integração não tem a permissão CT-e. |
| 402 | PLAN_WITHOUT_FISCAL_DOCUMENTS | O plano da empresa não inclui o módulo de documentos fiscais. |
| 422 | FISCAL_CONFIG_NOT_FOUND | Filial sem configuração fiscal ou sem certificado digital vinculado. |
| 404 | DOCUMENT_NOT_FOUND | Documento não encontrado na filial do token. |
| 405 | METHOD_NOT_ALLOWED | Método HTTP não aceito pela rota. Em algumas rotas o identificador vem só em message. |
| 422 | VALIDATION_ERROR | Corpo 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. |
| 500 | INTERNAL_ERROR | Falha inesperada. Tente de novo; se persistir, fale com o suporte informando o protocol ou o horário da chamada. |
| 409 | DOCUMENT_ALREADY_PROCESSED | Documento autorizado, cancelado ou encerrado não aceita reenvio. |
| 409 | DOCUMENT_FROM_ANOTHER_SUBSIDIARY | A referência externa já pertence a um documento de outra filial. |
| 409 | DOCUMENT_ENVIRONMENT_CHANGED | A filial mudou de ambiente desde a emissão; emita um documento novo. |
| 422 | RNTRC_REQUIRED | RNTRC ausente no CT-e e na configuração fiscal da filial. |
| 422 | ADDRESS_WITHOUT_IBGE | Não foi possível identificar o código IBGE do município de um participante. |
| 422 | ICMS_CST_INCOMPATIBLE_WITH_CRT | O CST do ICMS não combina com o regime tributário do emitente. |
| 422 | PREVIOUS_DOCUMENTS_REQUIRED | Subcontratação, redespacho e redespacho intermediário exigem documentos_anteriores. |
| 404 | EVENT_TO_CANCEL_NOT_FOUND | Não há comprovante ou insucesso registrado com o protocolo informado. |
| 404 | EVENT_NOT_FOUND | Rota de PDF: o evento pedido não existe no documento. |
| 409 | DOCUMENT_NOT_CANCELABLE | O status do documento não permite cancelamento (só AUTHORIZED). |
| 409 | DOCUMENT_NOT_CHANGEABLE | O status do documento não aceita o evento pedido. |
| 409 | DOCUMENT_WITHOUT_PROTOCOL | O evento exige o protocolo de autorização e o documento não tem. |
| 409 | IMPORTED_DOCUMENT_READ_ONLY | Documento emitido por terceiro e importado não aceita eventos. |
| 409 | EVENT_ALREADY_PENDING | Já existe um evento do mesmo tipo aguardando processamento. |
| 409 | EVENT_ALREADY_REGISTERED | O 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
messagee envie de novo com a mesmaexternal_reference. - 429: espere o
Retry-After. - 409: leia o
code.EVENT_ALREADY_PENDINGpede 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
201e a rejeição aparece depois, nostatus,c_statestatus_reasondo documento ou do evento.
Exemplos completos
Emitir, acompanhar, baixar o DACTE e cancelar um CT-e com curl:
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"
}
}'curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
-H "x-api-token: SEU_TOKEN"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.pdfcurl -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:
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].