CT-e
Issue CT-e
Accepts a model 57 CT-e, road modal, for asynchronous authorization with SEFAZ.
/openapi/v2/empresas/{empresaId}/ctetoken, timestamp and sign signature headers, see Authentication.The CT-e is the electronic fiscal document that covers a freight transport service. Acceptance returns HTTP 200 with no body. Resubmitting the same id: an identical message fingerprint reuses the original task (idempotent), a different fingerprint returns 10017030, and a previous terminal failure reopens the task with the new message. Results are obtained through the query or the webhook. Enum strings are case-insensitive.
Path parameters
empresaId* | string | Company identifier |
* Required field
Request body
id* | string | Request identifier |
ambienteEmissao* | string | Environment |
natureza* | string | Nature of the operation |
cfop* | string | CFOP |
tipo* | string | Document type |
tipoServico* | string | Service type |
modal* | string | Modal |
tomador* | string | Service taker |
indicadorIeTomador* | string | Taker ICMS status |
retiraMercadoria | bool | Pick-up by the receiver |
detalheRetira | string | Pick-up details |
| object | Issuing municipality |
* | object | Origin municipality |
* | object | Destination municipality |
*at least one of `remetente` or `destinatario` | object | Sender |
*at least one of `remetente` or `destinatario` | object | Receiver |
| object | Dispatcher |
| object | Consignee |
*required for `tomador=Outros` | object | Taker outside the parties |
* | object | Cargo |
*required except for `tipo=Complementar` | object | Cargo documents |
*required for subcontracting / redispatch / intermediate redispatch | array | Previous transport documents |
* | object | Road data |
* | object | Freight amount |
* | object | Taxes |
| object | Billing |
*required for `tipo=Substituto` | object | Replaced CT-e |
ctesComplementados*required for `tipo=Complementar` | array | Keys of the complemented CT-e |
| object | Additional characteristics |
| object | Planned route |
| object | Delivery deadline |
observacoes | string | Remarks |
| array | Issuer remarks |
| array | Remarks for the tax authority |
autorizadosXml | array | Parties allowed to download the XML |
* Required field
No response body
The most common case: the carrier moves goods covered by NF-e inside one state and the seller pays the freight. The block below lists only the fields to send; anything not listed stays out.
Full request
{"id": "CTE-ORD-1","ambienteEmissao": "Homologacao","natureza": "PRESTACAO DE SERVICO DE TRANSPORTE","cfop": "5353","tipo": "Normal","tipoServico": "Normal","modal": "Rodoviario","tomador": "Remetente","indicadorIeTomador": "Contribuinte","origem": { "codigoIbge": 3550308 },"destino": { "codigoIbge": 3550308 },"remetente": {"cpfCnpj": "66500544000120", "inscricaoEstadual": "123456789012", "nome": "REMETENTE TESTE LTDA","endereco": { "logradouro": "AVENIDA PAULISTA", "numero": "1000", "bairro": "BELA VISTA", "codigoIbge": 3550308, "cep": "01310100" }},"destinatario": {"cpfCnpj": "12345678909", "nome": "DESTINATARIO TESTE","endereco": { "logradouro": "RUA AUGUSTA", "numero": "10", "bairro": "CONSOLACAO", "codigoIbge": 3550308, "cep": "01305000" }},"carga": { "valor": 500.00, "produtoPredominante": "MERCADORIA DIVERSA","quantidades": [{ "unidade": "Kg", "tipoMedida": "PESO BRUTO", "quantidade": 10 }] },"documentos": { "nfe": [{ "chave": "35260966500544000120550010000001231000000002" }] },"rodoviario": { "rntrc": "12345678" },"valorPrestacao": { "total": 100.00, "aReceber": 100.00, "componentes": [{ "nome": "FRETE PESO", "valor": 100.00 }] },"impostos": { "icms": { "situacaoTributaria": "00" } }}
id* | string | Request identifier |
ambienteEmissao* | string | Environment |
natureza* | string | Nature of the operation |
cfop* | string | CFOP |
tipo* | string | Document type |
tipoServico* | string | Service type |
modal* | string | Modal |
tomador* | string | Taker |
indicadorIeTomador* | string | Taker status |
* | object | Origin municipality |
* | object | Destination municipality |
* | object | Sender |
* | object | Receiver |
* | object | Cargo |
* | object | Cargo documents |
* | object | Road data |
* | object | Freight amount |
* | object | Taxes |
* Required field
Each type requires or forbids one reference: sending the wrong reference returns 10017015.
Normal: ordinary issuance
Do not send ctesComplementados or cteSubstituido; documentos is required.
"tipo": "Normal"
tipo* | string | Document type |
* Required field
Complementar: tops up already authorized CT-e
Send the keys of the complemented CT-e; documentos is not required.
"tipo": "Complementar","ctesComplementados": ["35260940673061000134570010000000011000000016"]
tipo* | string | Document type |
ctesComplementados* | array | Complemented keys |
* Required field
Substituto: replaces an earlier CT-e
Send the replaced CT-e; the other fields follow a normal issuance.
"tipo": "Substituto","cteSubstituido": { "chave": "35260940673061000134570010000000011000000016", "alteraTomador": false }
tipo* | string | Document type |
* | object | Replaced CT-e |
* Required field
Subcontracting, redispatch and intermediate redispatch require documentosAnteriores; the other types forbid it (10017014). Each entry is one previous carrier and carries either ctesEletronicos or papeis, never both.
Normal or VinculadoMultimodal: no previous documents
Do not send documentosAnteriores.
"tipoServico": "Normal"
tipoServico* | string | Service type |
* Required field
Subcontracting or redispatch with electronic previous CT-e
Applies to Subcontratacao, Redespacho and RedespachoIntermediario.
"tipoServico": "Subcontratacao","documentosAnteriores": [{ "cpfCnpj": "40673061000134", "inscricaoEstadual": "123456789012", "uf": "SP", "nome": "TRANSPORTADORA ANTERIOR LTDA","ctesEletronicos": ["35260940673061000134570010000000011000000016"] }]
tipoServico* | string | Service type |
* | array | Previous carriers |
* Required field
Subcontracting or redispatch with paper previous documents
For a previous carrier that does not yet use the electronic CT-e.
"tipoServico": "Redespacho","documentosAnteriores": [{ "cpfCnpj": "40673061000134", "inscricaoEstadual": "ISENTO", "uf": "SP", "nome": "TRANSPORTADORA ANTERIOR LTDA","papeis": [{ "tipo": "10", "serie": "1", "numero": "12345", "dataEmissao": "2026-09-01" }] }]
tipoServico* | string | Service type |
* | array | Previous carriers |
* Required field
The party pointed to by tomador is mandatory (10017012). Contribuinte requires a numeric IE on that party; a numeric IE requires Contribuinte (10017013). remetente or destinatario: at least one of them always.
Taxpayer taker: one of the four parties
Remetente, Expedidor, Recebedor or Destinatario; the matching party carries a numeric IE.
"tomador": "Remetente","indicadorIeTomador": "Contribuinte","remetente": { "cpfCnpj": "66500544000120", "inscricaoEstadual": "123456789012", "nome": "REMETENTE TESTE LTDA", "endereco": { "..." : "..." } }
tomador* | string | Taker |
indicadorIeTomador* | string | Taker status |
* | object | Taker party |
* Required field
Non-taxpayer or exempt taker
NaoContribuinte or Isento: the party carries no numeric IE. On an interstate service with NaoContribuinte, also send impostos.icmsUfFim.
"tomador": "Destinatario","indicadorIeTomador": "NaoContribuinte","destinatario": { "cpfCnpj": "12345678909", "nome": "DESTINATARIO TESTE", "endereco": { "..." : "..." } }
tomador* | string | Taker |
indicadorIeTomador* | string | Taker status |
* | object | Taker party |
* Required field
Outros: taker outside the parties
Send tomadorOutros; with any other tomador value the group is refused (10017013).
"tomador": "Outros","indicadorIeTomador": "Contribuinte","tomadorOutros": { "cpfCnpj": "40673061000134", "inscricaoEstadual": "123456789012", "nome": "PAGADOR DO FRETE LTDA", "endereco": { "..." : "..." } }
tomador* | string | Taker |
indicadorIeTomador* | string | Taker status |
* | object | Taker outside the parties |
* Required field
Required except for tipo=Complementar. Send exactly one of the nfe, nf or outros groups; mixed or missing groups return 10017014.
Electronic NF-e (nfe)
"documentos": {"nfe": [{ "chave": "35260966500544000120550010000001231000000002", "dataPrevistaEntrega": "2026-09-10" }]}
* | object | Cargo documents |
* Required field
Paper invoices (nf)
With no access key, the invoice data goes field by field; the six amounts are mandatory.
"documentos": {"nf": [{ "modelo": "01", "serie": "1", "numero": "12345", "dataEmissao": "2026-09-01","baseIcms": 500.00, "valorIcms": 90.00, "baseIcmsSt": 0, "valorIcmsSt": 0, "valorProdutos": 500.00, "valorTotal": 500.00,"cfop": "5102", "pesoKg": 10 }]}
* | object | Cargo documents |
* Required field
Other documents (outros)
tipo=Outros requires descricao; the other types do not.
"documentos": {"outros": [{ "tipo": "Outros", "descricao": "ROMANEIO DE CARGA", "numero": "778", "dataEmissao": "2026-09-01", "valor": 500.00 }]}
* | object | Cargo documents |
* Required field
Only modal=Rodoviario is accepted in phase one (10017018), and the rodoviario group is always required. The RNTRC needs 8 digits (10017017).
Road with pick-up orders
ordensColeta is optional, up to 10; without orders send only rntrc.
"modal": "Rodoviario","rodoviario": {"rntrc": "12345678","ordensColeta": [{ "serie": "1", "numero": 501, "dataEmissao": "2026-09-01","emitente": { "cnpj": "66500544000120", "inscricaoEstadual": "123456789012", "uf": "SP" } }]}
modal* | string | Modal |
* | object | Road data |
* Required field
Explicit values win; when omitted, the base is the freight total, the rate comes from the intrastate table or the 7% / 12% interstate rule, and the amount is computed. An intrastate service with no rate in the table and no explicit rate returns 10017024. The CST must match the company regime: Simples Nacional only SN, regular regime never SN (10017022).
CST 00: fully taxed
The CST alone is enough. Do not send percentualReducaoBase (10017021).
"impostos": { "icms": { "situacaoTributaria": "00", "aliquota": 12 } }
* | object | Taxes |
* Required field
CST 20: reduced calculation base
percentualReducaoBase is mandatory (10017020); the omitted base is the total already reduced.
"impostos": { "icms": { "situacaoTributaria": "20", "percentualReducaoBase": 20, "codigoBeneficio": "SP123456" } }
* | object | Taxes |
* Required field
CST 40, 41 or 51: exempt, not taxed or deferred
No base or rate; do not send valor (10017021).
"impostos": { "icms": { "situacaoTributaria": "40", "valorDesonerado": 12.00, "codigoBeneficio": "SP123456" } }
* | object | Taxes |
* Required field
CST 60: ICMS withheld earlier
stRetido is mandatory with all three values (10017020).
"impostos": { "icms": { "situacaoTributaria": "60", "stRetido": { "baseCalculo": 100.00, "aliquota": 12, "valor": 12.00 } } }
* | object | Taxes |
* Required field
CST 90: other situations
Everything optional; percentualReducaoBase reduces the base when sent.
"impostos": { "icms": { "situacaoTributaria": "90", "aliquota": 12, "valorCredito": 2.40 } }
* | object | Taxes |
* Required field
90-OutraUF: ICMS owed to another state
The figures go in outraUf; each omitted one falls back to the field of the same name under icms, and the omitted rate is the interstate one.
"impostos": { "icms": { "situacaoTributaria": "90-OutraUF", "outraUf": { "baseCalculo": 100.00, "aliquota": 12, "valor": 12.00 } } }
* | object | Taxes |
* Required field
SN: Simples Nacional company
The only CST accepted for Simples Nacional. Do not send baseCalculo or valor (10017021); icmsUfFim is not required either.
"impostos": { "icms": { "situacaoTributaria": "SN" } }
* | object | Taxes |
* Required field
Besides ICMS, impostos accepts the split with the destination state, the tax burden percentage and a text for the tax authority. ibsCbs is not available in phase one: when sent the document is rejected (10017021).
Interstate service with a non-taxpayer taker (icmsUfFim)
Required when origin and destination are in different states and indicadorIeTomador=NaoContribuinte (10017023), unless CST SN; on an intrastate service it is refused (10017021). Every field is optional and falls back to the destination state table.
"impostos": {"icms": { "situacaoTributaria": "00" },"icmsUfFim": { "aliquotaInterna": 18, "aliquotaInterestadual": 12, "percentualFcp": 2 }}
* | object | Taxes |
* Required field
Tax burden and information for the tax authority
Both optional and independent of the CST.
"impostos": {"icms": { "situacaoTributaria": "00" },"percentualCargaTributaria": 12.5,"informacoesFisco": "ICMS conforme convenio 106/96"}
* | object | Taxes |
* Required field
Optional. Without entrega, SemData and SemHora apply. Date and time are agreed independently: each type asks for its own fields.
NaData, AteData or APartirDe: one date
Send data.
"entrega": { "tipoData": "AteData", "data": "2026-09-10" }
| object | Delivery deadline |
* Required field
NoPeriodo: date range
Send dataInicial and dataFinal.
"entrega": { "tipoData": "NoPeriodo", "dataInicial": "2026-09-08", "dataFinal": "2026-09-12" }
| object | Delivery deadline |
* Required field
NaHora, AteHora or APartirDe: one time
Send hora; it can be combined with any tipoData.
"entrega": { "tipoData": "NaData", "data": "2026-09-10", "tipoHora": "AteHora", "hora": "12:00" }
| object | Delivery deadline |
* Required field
NoIntervalo: time window
Send horaInicial and horaFinal.
"entrega": { "tipoHora": "NoIntervalo", "horaInicial": "08:00", "horaFinal": "12:00" }
| object | Delivery deadline |
* Required field
Optional; only when the freight is billed on credit. Every field is optional.
Bill in two instalments
"cobranca": {"fatura": { "numero": "FAT-2026-001", "valorOriginal": 100.00, "valorDesconto": 0, "valorLiquido": 100.00 },"duplicatas": [{ "numero": "001", "vencimento": "2026-10-30", "valor": 50.00 },{ "numero": "002", "vencimento": "2026-11-30", "valor": 50.00 }]}
| object | Billing |
* Required field
SEFAZ is the state tax authority that authorizes the document. Its rejections during issuance are not HTTP errors: they surface as query status Negada and the cte.rejected webhook, with the return code and reason in motivoStatus / cteMotivoStatus. A terminal task failure (Falha) sends no callback; use the query.
ambienteEmissaoIssue environment
| Values | Meaning |
|---|---|
| Homologacao | SEFAZ test environment; the document has no legal effect |
| Producao | Official environment |
tipoDocument type
| Values | Meaning |
|---|---|
| Normal | Ordinary issuance |
| Complementar | Adds amounts to already authorized CT-e; requires ctesComplementados and waives documentos |
| Substituto | Replaces and corrects an earlier CT-e; requires cteSubstituido |
tipoServicoService type
| Values | Meaning |
|---|---|
| Normal | Freight contracted directly with this carrier |
| Subcontratacao | Another carrier hired this one for the whole haul; requires documentosAnteriores |
| Redespacho | Takes the load from another carrier to finish the trip; requires documentosAnteriores |
| RedespachoIntermediario | Runs a leg in the middle of the trip; requires documentosAnteriores |
| VinculadoMultimodal | Freight tied to a multimodal operator |
modalModal
Other modals are not accepted in phase one and return 10017018.
| Values | Meaning |
|---|---|
| Rodoviario | Road transport |
tomadorService taker
| Values | Meaning |
|---|---|
| Remetente | Who dispatches the goods; requires remetente |
| Expedidor | Who hands the load to this carrier in a redispatch; requires expedidor |
| Recebedor | Who takes the load from this carrier to continue the trip; requires recebedor |
| Destinatario | Who receives the goods at the end of the trip; requires destinatario |
| Outros | Someone other than the four parties; requires tomadorOutros |
indicadorIeTomadorTaker ICMS status
| Values | Meaning |
|---|---|
| Contribuinte | ICMS taxpayer; the taker needs a numeric inscricaoEstadual |
| Isento | Exempt from state registration |
| NaoContribuinte | Non-taxpayer, such as a final consumer; on an interstate service requires impostos.icmsUfFim |
carga.quantidades[].unidadeCargo unit of measure
| Values | Meaning |
|---|---|
| M3 | Cubic metre |
| Kg | Kilogram |
| Ton | Tonne |
| Unidade | Unit or package |
| Litros | Litre |
| MMBTU | Million BTU, energy unit used for gas |
documentos.outros[].tipoOther document type
| Values | Meaning |
|---|---|
| Declaracao | Content declaration |
| Dutoviario | Pipeline transport document |
| CfeSat | Electronic retail receipt issued by SAT equipment |
| Nfce | Electronic consumer invoice |
| Outros | Any other document; requires descricao |
documentosAnteriores[].ufPrevious carrier state
Also applies to rodoviario.ordensColeta[].emitente.uf.
| Values | Meaning |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
documentosAnteriores[].papeis[].tipoPrevious paper document type
| Values | Meaning |
|---|---|
| 07 | ATRE |
| 08 | DTA, customs transit dispatch |
| 09 | Air waybill |
| 10 | CTRC, road freight bill |
| 11 | CTAC, waterway freight bill |
| 12 | CAN, domestic air waybill |
| 13 | CTMC, multimodal freight bill |
| 14 | CTA |
| 15 | CTMA |
| 16 | CPT |
| 17 | BL, bill of lading |
| 18 | CTR |
| 19 | CIT |
impostos.icms.situacaoTributariaICMS CST
A Simples Nacional company only sends SN; the regular regime never sends SN (10017022).
| Values | Meaning |
|---|---|
| 00 | Fully taxed |
| 20 | Taxed with a reduced base; requires percentualReducaoBase |
| 40 | Exempt |
| 41 | Not taxed |
| 51 | Deferred to a later stage |
| 60 | ICMS already withheld earlier under tax substitution; requires stRetido |
| 90 | Other situations |
| 90-OutraUF | ICMS owed to another state; accepts outraUf |
| SN | Simples Nacional company; do not send baseCalculo or valor |
entrega.tipoDataDelivery deadline by date
Omitted means SemData.
| Values | Meaning |
|---|---|
| SemData | No agreed date |
| NaData | On an exact day; requires data |
| AteData | By a deadline; requires data |
| APartirDe | From a day onwards; requires data |
| NoPeriodo | Within a range; requires dataInicial and dataFinal |
entrega.tipoHoraDelivery deadline by time
Omitted means SemHora.
| Values | Meaning |
|---|---|
| SemHora | No agreed time |
| NaHora | At an exact time; requires hora |
| AteHora | By a deadline time; requires hora |
| APartirDe | From a time onwards; requires hora |
| NoIntervalo | Within a window; requires horaInicial and horaFinal |
| Code | HTTP | |
|---|---|---|
| 10003000 | 404 | empresaId not found. |
| 10017004 | 400 | Company cannot issue: not approved or certificate not ready. Wait for approval or link the certificate. |
| 10017005 | 400 | Concurrent duplicate request. Retry later. |
| 10017006 | 400 | Too many pending tasks for the CNPJ. Retry later. |
| 10017007 | 400 | Number series unresolved: none configured, or several enabled without a choice. Configure a model 57 series. |
| 10017010 | 400 | ambienteEmissao differs from the environment of the company. Submit for the company environment. |
| 10017011 | 400 | Municipality IBGE code not found. Check codigoIbge. |
| 10017012 | 400 | Party missing. Add the party referenced by tomador, and at least one of remetente or destinatario. |
| 10017013 | 400 | Taker inconsistent with the IE indicator, or tomadorOutros sent without tomador=Outros. Adjust indicadorIeTomador, the IE of the taker or the group sent. |
| 10017014 | 400 | Invalid document references: missing, bad check digit, mixed groups, or previous documents inconsistent with the service type. |
| 10017015 | 400 | Document type inconsistent with references. Send ctesComplementados / cteSubstituido per tipo. |
| 10017016 | 400 | Components do not sum to the total, or aReceber is greater than the total. Fix the amounts. |
| 10017017 | 400 | Invalid RNTRC or missing rodoviario group. Send 8 digits. |
| 10017018 | 400 | Unsupported modal. Only Rodoviario. |
| 10017019 | 400 | Invalid enum or format; mensagem names the field. |
| 10017020 | 400 | Tax parameter missing: percentualReducaoBase for CST 20 or the full stRetido for CST 60. |
| 10017021 | 400 | Tax parameter not allowed: ibsCbs, icmsUfFim on an intrastate service, percentualReducaoBase with CST 00, valor with CST 40 / 41 / 51, or baseCalculo / valor with SN. |
| 10017022 | 400 | CST inconsistent with the company regime: Simples Nacional only SN; regular regime never SN. |
| 10017023 | 400 | icmsUfFim required for an interstate service with a non-taxpayer taker. |
| 10017024 | 400 | Rate not found in the state table and no explicit rate given. |
| 10017025 | 400 | Unsupported CST. Use one of the values in the enums section. |
| 10017030 | 400 | Same id with a different message. Use a new id or resend the original message. |
| 10017031 | 400 | Production: an active or authorized document already exists for the id. Query the original. |
| 10001001 | 400 | Request field validation failed, one entry per field; fix per mensagem. |