CT-e

Overview

The CT-e API issues electronic transport documents (CT-e, model 57, road modal) on behalf of carriers, queries their status, cancels them and registers post-authorization events (correction letter, delivery receipt, delivery failure, service disagreement). Company registration, certificate association and webhook registration are shared with NF-e and only referenced here.

Path convention: the resource segment is the document category cte; every document-level operation lives under /openapi/v2/empresas/{empresaId}/cte/{cteId}, where cteId is the id you sent at issuance.

Onboarding flow

Prerequisites

• The company must be approved with a usable certificate, and its CNPJ must be enabled for CT-e at the state tax authority (IE registered as a transport service provider and CT-e accreditation completed). Without it SEFAZ returns 230 - IE do emitente não cadastrada, which the platform cannot resolve.
• The company must have a CT-e number series (model 57). If none is configured, or several are enabled and the request does not pick one, the API returns 10017007.
• Phase one supports the road modal (Rodoviario) only; other modals are rejected at acceptance (10017018).
• ambienteEmissao must match the current environment of the company (10017010), see Environments.

Authentication

Identical to NF-e: headers token / timestamp / sign, with sign = MD5(token + path + body + timestamp) as lowercase hex; path includes the /openapi prefix and path variables and excludes the query string; GET without a body uses an empty string; POST signs the raw JSON with CR/LF removed (a body-less POST signs the empty string). Algorithm details, reference implementations and troubleshooting are in Authentication.

Endpoints

All paths are relative to /openapi/v2/empresas/{empresaId}/cte.

Every event is sent synchronously and, on success, returns the event object (chaveAcesso, tipo, codigo, sequencia, status, motivo, protocolo, data, linkXml). Text fields are sanitized (accents stripped, whitespace collapsed) before length validation; coordinates are registered with six decimals.

Note: the service disagreement endpoints are the only ones addressed by the access key of a CT-e issued by someone else: this company acts as receiver / taker of that document, and the event is routed to the state of that document.

Webhook payload

Webhook registration and signature headers are shared with NF-e, see Webhooks. Four event codes are emitted for CT-e:

cte.authorized, cte.rejected, cte.canceled

The three document-result events use the compatibility payload (tipo="CT-e", fixed field order), parallel to the NF-e nfe* fields:

{ "tipo": "CT-e", "empresaId": "1934811222334455", "cteId": "CTE-ORD-1", "cteStatus": "Autorizada", "cteMotivoStatus": null,
  "cteLinkDacte": "https://.../openapi/files/dacte/3526...?token=...", "cteLinkXml": "https://.../openapi/files/xml/7?token=...", "cteNumero": "1", "cteSerie": "1",
  "cteChaveAcesso": "3526...", "cteDataEmissao": "2026-09-06T12:00:00Z", "cteDataAutorizacao": "2026-09-06T12:00:03Z",
  "cteNumeroProtocolo": "135260000000001", "cteDigestValue": "..." }

cteLinkDacte and cteLinkXml are usable as soon as the authorization callback arrives; links need no signature headers, redirect with 302, and their validity and error codes are described in File download.

cte.event.registered

Emitted when any post-authorization event other than cancellation is registered (correction letter, delivery receipt, delivery failure, service disagreement and their cancellations). It uses the platform envelope (version / event_id / event_type / occurred_at / data):

{
  "version": "1.0",
  "event_id": "7312345678901234567",
  "event_type": "cte.event.registered",
  "occurred_at": "2026-09-06T13:00:00Z",
  "data": {
    "cte_id": "1001",
    "chave": "35260940673061000134570010000000011000000016",
    "external_ref": "CTE-ORD-1",
    "event_code": "110110",
    "n_seq": 1,
    "protocolo": "135260000000099"
  }
}

Error model

Same shapes as NF-e: business errors are [{ "codigo", "mensagem" }] (HTTP 400; a missing document / task is HTTP 404 with codigo CTe0001); authentication-layer errors use the platform envelope (401 / 403 / 429, see Authentication).

SEFAZ rejections during issuance are not HTTP errors: they surface as query status Negada and the cte.rejected webhook.

Scope and limitations

• Model 57 CT-e 4.00, road modal; normal / complementary / substitute documents; all five service types.
• Tax groups ICMS 00 / 20 / 40 / 41 / 51 / 60 / 90 / OutraUF / SN + ICMSUFFim + vTotTrib; IBS/CBS in phase two.
• Contingency: SVC (SVC-RS / SVC-SP) and EPEC are switched by the platform per state, transparently to integrators; tipoEmissao in the query shows it. Events for documents authorized under contingency are still sent to the regular authorizer of the state.
• Not supported: other modals, multimodal, GTV, CT-e OS (model 67), inbound document distribution (DistDFe).

Integration checklist

1. In the certification environment: company registered, certificate linked, CT-e number series configured.
2. Issue a minimal CT-e (the example on Issue CT-e), query it as Autorizada, download the XML and the DACTE.
3. Resend the same id once and confirm HTTP 200 with no second document created.
4. Register one correction letter and one delivery receipt, see them in the event list, then cancel the delivery receipt.
5. Issue a second CT-e and cancel that one, query it as Cancelada, receive the cte.canceled callback. A document with a registered correction letter can no longer be cancelled, so this step uses a separate document.
6. Send deliberate errors (modal Aereo, component sum mismatch) and confirm the 400 error array.