Referência interativa disponível

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
• 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}

# Retorna o arquivo XML (Content-Type: application/xml)

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	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	XML autorizado
GET	.../inbound/transportationinvoices/{access_key}/pdf	DACTE

A chave de acesso do CT-e tem 44 dígitos (modelo 57).

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