Para spec OpenAPI completa, schemas e "Try it" inline, use a API Reference — Consulta CT-e v2. Esta página documenta o uso prático; a referência tem o contrato completo.
Endpoints de CT-e
Referência dos endpoints HTTP do serviço NFe/CTe Inbound para operações com CT-e (modelo 57).
Sumário
- Ativar e Configurar CT-e
- Buscar Metadados de um CT-e
- Baixar XML de um CT-e
- Baixar XML de um evento de CT-e
- Filtrar o webhook por papel da empresa
- Reprocessar Webhooks de CT-e
- Reprocessar NSUs Específicos
- Consolidação de Batch
Ativar e Configurar CT-e
Veja Ativar via API — o processo é idêntico ao NF-e mas no endpoint /transportationinvoices. O corpo de ativação de CT-e aceita, além dos campos comuns, o filtro InterestedPartyRoles.
Filtrar o webhook por papel da empresa
PUT /v2/companies/{company_id}/inbound/transportationinvoices/webhook/filter
Authorization: ApiKey {api_key}
Content-Type: application/json
{
"InterestedPartyRoles": ["Taker"]
}
Restringe a entrega de webhook aos CT-e em que o CNPJ da empresa aparece em um dos papéis informados. Array vazio remove o filtro; campo ausente ou null retorna 400. Documentos suprimidos pelo filtro não são bilhetados como captura efetiva.
Resposta (200): a configuração de inbound resultante.
Papéis aceitos: Taker, Sender, Dispatcher, Receiver, Recipient — a semântica de cada um, o comportamento fail-open e o efeito na bilhetagem estão em Ativar via API.
Buscar Metadados de um CT-e
GET /v2/companies/{company_id}/inbound/{access_key}
Authorization: ApiKey {api_key}
Resposta (200):
{
"id": "abc123",
"accessKey": "35240198765432000100570010000009871234567890",
"createdOn": "2024-03-15T14:22:10Z",
"nsu": 10042,
"type": "transportationInvoice",
"description": "Autorizado o uso do CT-e",
"company": {
"id": "comp_123",
"federalTaxNumber": "98765432000100"
},
"issuer": {
"federalTaxNumber": "11111111000100",
"name": "Transportadora ABC LTDA"
},
"taker": {
"federalTaxNumber": "98765432000100",
"name": "Minha Empresa S.A."
},
"totalAmount": 350.00,
"issuedOn": "2024-03-15T10:00:00Z",
"xmlUrl": "https://storage.nfe.io/temp/cte/..."
}
Campos específicos do CT-e:
| Campo | Tipo | Descrição |
|---|---|---|
issuer | object | A transportadora que emitiu o CT-e |
taker | object | Tomador do serviço de transporte |
totalAmount | decimal | Valor do serviço de transporte |
issuedOn | DateTime | Data de emissão do CT-e |
xmlUrl | string | URL temporária para download do XML (expira em 1 hora) |
Baixar XML de um CT-e
GET /v2/companies/{company_id}/inbound/{access_key}/xml
Authorization: ApiKey {api_key}
Resposta (200): JSON com a URL temporária de leitura do XML. Baixe o arquivo logo depois de obtê-la.
{
"publicTemporaryUri": "https://..."
}
As rotas genéricas /v2/companies/{company_id}/inbound/{access_key}/... (metadados, XML, PDF, eventos e manifestação) validam o access_key antes de qualquer consulta: ele precisa ter 44 dígitos numéricos. Chave com outro tamanho ou com caractere não numérico responde 400, nunca 500. As rotas de metadados também aceitam, no lugar do access_key, um identificador de evento com mais de 44 caracteres.
As rotas de XML de documento CT-e servem somente a chave de acesso de 44 dígitos. Nas rotas dedicadas da tabela abaixo, chave com outro tamanho também responde 400. Corpo da resposta:
{
"errors": [
{ "message": "access key must have 44 digits" }
]
}
As rotas de XML de documento não servem XML de evento. Para o XML de um evento (cancelamento, carta de correção etc.), use a rota de XML de evento.
Rotas específicas de CT-e
Além da rota genérica acima (que serve NF-e e CT-e pela chave), existem rotas dedicadas ao CT-e:
| Método | Path | Retorna |
|---|---|---|
GET | /v2/companies/{company_id}/inbound/cte/{access_key}/xml | Redireciona (302) para o XML autorizado do CT-e |
GET | /v2/companies/{company_id}/inbound/cte/{access_key}/pdf | DACTE |
GET | .../inbound/transportationinvoices/{access_key}/json | CT-e em JSON (conversão do XML autorizado) — paridade com o endpoint de NF-e |
GET | .../inbound/transportationinvoices/{access_key}/xml | Redireciona (302) para o XML autorizado |
GET | .../inbound/transportationinvoices/{access_key}/pdf | DACTE |
A chave de acesso do CT-e tem 44 dígitos (modelo 57). As duas rotas de XML dedicadas respondem com redirecionamento (302, header Location) para a URL temporária do XML, em vez do JSON da rota genérica.
Baixar XML de um evento de CT-e
GET /v2/companies/{company_id}/inbound/{access_key}/events/{event_key}/xml
Authorization: ApiKey {api_key}
| Parâmetro | Descrição |
|---|---|
company_id | ID da empresa na NFE.io |
access_key | Chave de acesso do CT-e pai (44 dígitos numéricos), a que o evento se refere |
event_key | Identificador do evento. No leiaute 4.00 do CT-e, tem 55 caracteres: prefixo ID + código do tipo do evento (6 dígitos) + chave do CT-e (44 dígitos) + sequência (3 dígitos) |
Exemplo de event_key de cancelamento (110111), sequência 001, do CT-e 35240198765432000100570010000009871234567890:
ID11011135240198765432000100570010000009871234567890001
xmlUrl do webhookNão monte a URL à mão. O webhook de evento de CT-e (transportation_invoice_inbound / event_raised_successfully) já traz em xmlUrl a URL desta rota: o parentAccessKey do webhook vai em access_key, e o accessKey do webhook (o identificador do evento) vai em event_key. Veja Webhook events.
Resposta (200): JSON com a URL temporária de leitura do XML do evento.
{
"publicTemporaryUri": "https://..."
}
Resposta (404): o corpo traz a mensagem do erro. Os casos são:
- o evento não existe para a empresa. Um
event_keymalformado cai aqui também: ele não é validado à parte e simplesmente não é encontrado; - o evento existe, mas é de outro CT-e, diferente do informado em
access_key; - o evento existe, mas o arquivo XML não foi encontrado.
Exemplo:
{
"errors": [
{
"message": "transportation invoice event ID11011135240198765432000100570010000009871234567890001 not found for company comp_123"
}
]
}
Resposta (400): access_key sem 44 dígitos numéricos ("access key must have 44 digits") ou empresa sem a distribuição de CT-e ativa.
O formato do corpo de erro está em Códigos HTTP e erros. Os códigos de tipo de evento de CT-e estão em Tipos e enums.
Reprocessar Webhooks de CT-e
POST /v2/companies/{company_id}/inbound/transportationinvoices/reprocess/webhook
Authorization: ApiKey {api_key}
Content-Type: application/json
{
"Key": "35240198765432000100570010000009871234567890",
"Date": "2024-03-15"
}
Resposta de sucesso (204): sem corpo; operação agendada/processada em background.
Reprocessar NSUs Específicos
Útil quando um NSU falhou no processamento:
PUT /v2/companies/{company_id}/inbound/transportationinvoices/reprocess/item
Authorization: ApiKey {api_key}
Content-Type: application/json
[10042, 10043, 10044]
Resposta de sucesso (204): sem corpo; operação agendada/processada em background.
Consolidação de Batch
Consolida batches em um intervalo de NSU:
PUT /v2/companies/{company_id}/inbound/transportationinvoices/batch/consolidation
Authorization: ApiKey {api_key}
Content-Type: application/json
{
"StartNSU": 10000,
"EndNSU": 10500
}
Resposta de sucesso (204): sem corpo; operação agendada/processada em background.
Veja também
- Endpoints de NF-e
- Tipos e enums — papéis do filtro de webhook
- Consultar com OData
- Webhook events + HMAC
- Tipos e enums
- Ativar via API