CT-e
Query CT-e
Returns status, document data, XML / DACTE download links and the event list.
/openapi/v2/empresas/{empresaId}/cte/{cteId}token, timestamp and sign signature headers, see Authentication.This is how you follow what happened to the document after it was submitted. Queries by the id sent at issuance. Download links are short-lived tokens, valid for 10 minutes and re-issued on every query.
Path parameters
empresaId* | string | Company identifier |
cteId* | string | Document identifier |
* Required field
id | string | Document identifier |
status | string | Document status |
motivoStatus | string | Status reason |
numero | int | Document number |
serie | int | Series |
chaveAcesso | string | Access key |
numeroProtocolo | string | Authorization protocol |
dataEmissao | string | Issuance time |
dataAutorizacao | string | Authorization time |
tipoEmissao | string | Issuance path |
protocoloEpec | string | EPEC protocol |
linkXml | string | Authorized XML link |
linkDacte | string | DACTE link |
cte | object | Request echo |
| array | Registered events |
statusDocument status
| Values | Meaning |
|---|---|
| Pendente | Accepted, queued or being sent |
| Autorizada | Authorized by SEFAZ; linkXml is the legal original and linkDacte the DACTE PDF |
| Negada | Rejected by SEFAZ; motivoStatus carries the code and reason |
| Cancelada | Cancelled by event 110111 |
| Contingencia | SEFAZ unavailable; document pending resubmission |
| Falha | Terminal task failure; motivoStatus explains and the same id may be resubmitted |
tipoEmissaoIssuance path
The platform switches path on its own when the state authorizer is down.
| Values | Meaning |
|---|---|
| Normal | Authorizer of the state itself |
| Epec | EPEC contingency: prior event authorization |
| Fsda | FS-DA contingency: security form |
| SvcRs | SVC-RS contingency: virtual authorizer of Rio Grande do Sul |
| SvcSp | SVC-SP contingency: virtual authorizer of São Paulo |
cte.ambienteEmissaoIssue environment
| Values | Meaning |
|---|---|
| Homologacao | SEFAZ test environment; the document has no legal effect |
| Producao | Official environment |
cte.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 |
cte.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 |
cte.modalModal
Only Rodoviario is accepted in phase one; the other values are recognized but return 10017018.
| Values | Meaning |
|---|---|
| Rodoviario | Road transport |
| Aereo | Air transport; not supported yet |
| Aquaviario | Waterway transport; not supported yet |
| Ferroviario | Rail transport; not supported yet |
| Dutoviario | Pipeline transport; not supported yet |
| Multimodal | Multimodal transport; not supported yet |
cte.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 |
cte.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 |
cte.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 |
cte.documentos.nf[].modeloPaper invoice model
The platform only checks the 2 digits; any other value fails the layout validation before sending to SEFAZ.
| Values | Meaning |
|---|---|
| 01 | Invoice model 1 or 1A, including the one issued by the tax authority |
| 04 | Rural producer invoice |
cte.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 |
cte.documentosAnteriores[].ufPrevious carrier state
Also applies to cte.rodoviario.ordensColeta[].emitente.uf. The platform only checks the 2 letters; a code outside the list fails the layout validation.
| 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 |
| EX | Abroad, for operations with foreign countries |
cte.documentosAnteriores[].papeis[].tipoPrevious paper document type
The platform only checks the 2 digits; a code outside the list fails the layout validation before sending to SEFAZ.
| Values | Meaning |
|---|---|
| 07 | ATRE |
| 08 | DTA, customs transit dispatch |
| 09 | International air waybill |
| 10 | International consignment note |
| 11 | Standalone waybill |
| 12 | TIF, international rail transport |
| 13 | BL, bill of lading |
cte.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 |
cte.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 |
cte.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 |
eventos[].tipoEvent type
| Values | Meaning |
|---|---|
| Cancelamento | CT-e cancellation; code 110111 |
| CartaCorrecao | Correction letter; code 110110 |
| Epec | EPEC contingency prior authorization, registered by the platform; code 110113 |
| ComprovanteEntrega | Delivery receipt; code 110180 |
| CancelamentoComprovanteEntrega | Delivery receipt cancellation; code 110181 |
| InsucessoEntrega | Delivery failure; code 110190 |
| CancelamentoInsucessoEntrega | Delivery failure cancellation; code 110191 |
| PrestacaoDesacordo | Service disagreement; code 610110 |
| CancelamentoPrestacaoDesacordo | Service disagreement cancellation; code 610111 |
eventos[].codigoEvent code
| Values | Meaning |
|---|---|
| 110111 | CT-e cancellation (Cancelamento) |
| 110110 | Correction letter (CartaCorrecao) |
| 110113 | EPEC contingency prior authorization, registered by the platform (Epec) |
| 110180 | Delivery receipt (ComprovanteEntrega) |
| 110181 | Delivery receipt cancellation (CancelamentoComprovanteEntrega) |
| 110190 | Delivery failure (InsucessoEntrega) |
| 110191 | Delivery failure cancellation (CancelamentoInsucessoEntrega) |
| 610110 | Service disagreement (PrestacaoDesacordo) |
| 610111 | Service disagreement cancellation (CancelamentoPrestacaoDesacordo) |
eventos[].statusRegistration return code
The platform only returns 200 with one of these codes; any other SEFAZ return becomes 10017043.
| Values | Meaning |
|---|---|
| 134 | Event registered; SEFAZ treats it as success |
| 135 | Event registered and linked to the CT-e |
| 136 | Event registered but not linked to the CT-e |
| Code | HTTP | |
|---|---|---|
| 10017003 | 404 | cteId not found or not owned by the company. Check the id and the empresaId. |
| 10003000 | 404 | empresaId not found. |
