# Meu Rastreio — API de CT-e (referência para modelos de IA)

> Documento em Markdown para agentes e modelos de IA. Versão para pessoas: https://meurastreio.app/pt-BR/api-de-cte

Emita o CT-e na SEFAZ a partir do seu ERP ou TMS pela API do Meu Rastreio: emissão assíncrona, consulta, cancelamento, carta de correção, comprovante de entrega, DACTE, XML e webhooks.

Base URL: `https://painel.meurastreio.app/api/v1`

## Visão geral

A API de CT-e emite o **Conhecimento de Transporte Eletrônico** na SEFAZ a partir do seu sistema (ERP, TMS ou outro), em nome de **uma filial**, com o certificado digital configurado no Meu Rastreio. Ela também consulta o documento, registra os eventos e devolve o XML e o DACTE.

- A emissão é **assíncrona**: o `POST` responde na hora dizendo que o CT-e entrou na fila, e a autorização chega depois, pela consulta ou por webhook.
- A `external_reference` é a chave do CT-e para o seu sistema. Depois de autorizado, a chave de acesso (`access_key`) também serve para localizar o documento.
- Os eventos (cancelamento, carta de correção, comprovante e insucesso de entrega) seguem o mesmo desenho: pedido enfileirado, resultado depois.
- Série, numeração, ambiente e certificado vêm da configuração fiscal da filial.

| método | caminho | o que faz |
|---|---|---|
| `POST` | `/ctes` | Emite um CT-e, ou reenvia o da mesma `external_reference`. |
| `GET` | `/ctes/{external_reference}` | Consulta um CT-e. |
| `GET` | `/ctes?external_reference=` ou `?access_key=` | A mesma consulta, pela query string. |
| `GET` | `/ctes?date_from=&date_to=` | Lista os CT-e do período. |
| `POST` | `/ctes/cancel` | Cancelamento. |
| `POST` | `/ctes/correction-letter` | Carta de correção. |
| `POST` | `/ctes/delivery-receipt` | Comprovante de entrega. |
| `POST` | `/ctes/cancel-delivery-receipt` | Cancelamento do comprovante de entrega. |
| `POST` | `/ctes/delivery-failure` | Insucesso na entrega. |
| `POST` | `/ctes/cancel-delivery-failure` | Cancelamento do insucesso na entrega. |
| `GET` | `/ctes/pdf` | DACTE ou comprovante de um evento, em PDF. |

## Requisitos e ativação

Antes da primeira chamada, confira com o administrador da sua conta no Meu Rastreio:

1. O plano da empresa inclui o módulo **Documentos fiscais**. Sem ele, a API responde `402`.
2. Existe uma integração com o canal **API** na filial que vai emitir. Ela é criada no painel, em **Integrações → nova integração**, por um usuário administrador.
3. A integração está ativa e com a permissão **CT-e** ligada. Sem a permissão, a API responde `401`.
4. A filial tem a **configuração fiscal** preenchida no painel, com **certificado digital** vinculado. Sem ela, a API responde `422 FISCAL_CONFIG_NOT_FOUND`.
5. O RNTRC do emitente está na configuração fiscal, ou será enviado no campo `rntrc` de cada CT-e.

> O ambiente (produção ou homologação), a série e a numeração vêm da configuração fiscal da filial: o corpo da requisição não escolhe ambiente nem número do CT-e.

## Autenticação

Envie o token da integração no cabeçalho `x-api-token` de todas as chamadas.

cabeçalho:

```http
x-api-token: 0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9
```

- O token é um UUID e pertence a **uma integração de uma filial**: tudo o que você emite e consulta com ele é dessa filial. Empresa com várias filiais usa um token por filial.
- Ele aparece na tela da integração, no painel, e não tem validade.
- Para revogar, desative ou exclua a integração, ou substitua o token. O token antigo deixa de funcionar.
- O mesmo token pode ter outras permissões. Esta API exige a permissão **CT-e**.
- Só HTTPS. Nunca envie o token na URL e guarde-o como senha, em cofre de segredos.
- Token ausente ou desconhecido responde `401` com `{"message":"Acesso negado"}`.

## Primeira chamada

Emita um CT-e. Gere um UUID para a `external_reference` e guarde-o: é a sua chave para consultar, reenviar e registrar eventos.

requisição:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "cte": {
    "cfop": "6353",
    "natureza_operacao": "Prestação de serviço de transporte",
    "tomador": "SENDER",
    "origem": {
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "destino": {
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ"
    },
    "remetente": {
      "type": 1,
      "id": "00000000000191",
      "state_inscription": "110042490114",
      "name": "Remetente Exemplo Ltda",
      "address": {
        "zipcode": "01001000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "SP",
        "city": "São Paulo"
      }
    },
    "destinatario": {
      "type": 1,
      "id": "00000000000272",
      "state_inscription": "87654321",
      "name": "Destinatário Exemplo Ltda",
      "address": {
        "zipcode": "20010000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "RJ",
        "city": "Rio de Janeiro"
      }
    },
    "valores": {
      "total_servico": 1500,
      "a_receber": 1500,
      "componentes": [
        {
          "nome": "Frete peso",
          "valor": 1400
        },
        {
          "nome": "Pedágio",
          "valor": 100
        }
      ]
    },
    "icms": {
      "cst": "00",
      "base": 1500,
      "aliquota": 12,
      "valor": 180
    },
    "ibs_cbs": {
      "cst": "000",
      "classificacao_tributaria": "000001",
      "base": 1500,
      "ibs_uf_aliquota": 0.1,
      "ibs_uf_valor": 1.5,
      "ibs_municipal_aliquota": 0,
      "ibs_municipal_valor": 0,
      "ibs_valor": 1.5,
      "cbs_aliquota": 0.9,
      "cbs_valor": 13.5,
      "valor_total_documento": 1500
    },
    "carga": {
      "valor": 85000,
      "produto_predominante": "Eletrônicos",
      "quantidades": [
        {
          "unidade": "01",
          "tipo_medida": "PESO BRUTO",
          "quantidade": 1200
        }
      ]
    },
    "documentos": [
      {
        "chave_nfe": "35261100000000000272550010000456781000045678"
      }
    ],
    "observacao": "Entrega em horário comercial"
  }
}'
```

resposta 201:

```json
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "cte": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PENDING"
  }
}
```

O `201` quer dizer **enfileirado**, não autorizado. `protocol` identifica a chamada. Consulte o resultado alguns segundos depois:

requisição:

```bash
curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
```

Quando `status` for `AUTHORIZED`, a resposta traz chave de acesso, protocolo, `xml_url` e `pdf_url`.

## Emissão

`POST /ctes` recebe um JSON com a referência e o objeto `cte`. Valores monetários são números em reais (`1500.5`), nunca texto.

### Corpo (`raiz`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `external_reference` | string (UUID) | não | A sua chave para o CT-e. Sem ela, o Meu Rastreio gera uma e devolve na resposta. Enviar de novo a mesma referência reenvia o documento (ver Reenvio). |
| `cte` | object | sim | Os dados do conhecimento. |

### CT-e (`cte`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `cfop` | string | sim | CFOP da prestação, com 4 dígitos. |
| `natureza_operacao` | string | sim | Até 60 caracteres. |
| `tipo_servico` | integer | não | Código do tipo de serviço, de `0` a `4`. Padrão `0` (normal). `1` (subcontratação), `2` (redespacho) e `3` (redespacho intermediário) exigem `documentos_anteriores`. |
| `forma_emissao` | string | não | `NORMAL` (padrão), `CONTINGENCY`, `SVC_RS`, `SVC_SP` ou `EPEC`. |
| `justificativa_contingencia` | string | fora da emissão normal | De 15 a 256 caracteres. |
| `data_contingencia` | datetime | não | Entrada em contingência. Só é lida fora da emissão normal. |
| `tipo_documento` | string | não | `NORMAL` (padrão), `COMPLEMENT` (complemento de valores) ou `SUBSTITUTE` (substituição). |
| `chave_referenciada` | string | em complemento e substituição | Chave de 44 posições do CT-e complementado ou substituído. |
| `formato_impressao` | integer | não | Formato do DACTE: `1` ou `2`. |
| `retira` | boolean | não | O recebedor retira a carga. Padrão `false`. |
| `detalhe_retira` | string | com retira | Até 160 caracteres. |
| `tomador` | string | sim | Quem paga o frete: `SENDER` (remetente), `DISPATCHER` (expedidor), `RECEIVER` (recebedor), `RECIPIENT` (destinatário) ou `OTHER` (outro). |
| `origem` | object | sim | Município de início da prestação: `ibge` (7 dígitos), `cidade` e `uf`. |
| `destino` | object | sim | Município de fim da prestação, no mesmo formato. |
| `remetente` | object | sim | Participante (ver tabela). |
| `destinatario` | object | sim | Participante. |
| `expedidor` | object | com tomador DISPATCHER | Participante. |
| `recebedor` | object | com tomador RECEIVER | Participante. |
| `tomador_outros` | object | com tomador OTHER | Participante. Ignorado nos demais tomadores. |
| `valores` | object | sim | Valores da prestação (ver tabela). |
| `icms` | object | sim | ICMS (ver tabela). |
| `ibs_cbs` | object | sim | IBS e CBS (ver tabela). |
| `carga` | object | sim | Carga transportada (ver tabela). |
| `documentos` | array | sim | As NF-e transportadas. Ao menos uma, sem chave repetida. |
| `documentos_anteriores` | array | com tipo_servico 1, 2 ou 3 | Documentos de transporte anteriores (ver tabela). |
| `autorizados` | array | não | Até 10 CPFs/CNPJs autorizados a baixar o XML, sem repetição. |
| `observacoes` | array | não | Observações estruturadas (ver tabela). Até 10 por destino, sem repetir `campo` no mesmo destino. |
| `cobranca` | object | não | Fatura e duplicatas (ver tabela). |
| `rntrc` | string | não | RNTRC com 8 dígitos. Omitido, vale o da configuração fiscal; sem nenhum dos dois: `422 RNTRC_REQUIRED`. |
| `observacao` | string | não | Observações gerais, até 2000 caracteres. |
| `observacao_fisco` | string | não | Informações de interesse do fisco, até 2000 caracteres. |

### Participante (`cte.remetente, cte.destinatario, cte.expedidor, cte.recebedor, cte.tomador_outros`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `type` | number | sim | `0` para pessoa física, `1` para pessoa jurídica. |
| `id` | string | sim | CPF ou CNPJ do participante. |
| `state_inscription` | string | sim | Inscrição estadual. |
| `name` | string | sim | Nome ou razão social. |
| `fantasyName` | string | não | Nome fantasia. |
| `activity` | string | não | `TRANSPORTADOR`, `INDUSTRIA`, `COMERCIO`, `COMUNICACAO`, `ENERGIA`, `PRODUTOR_RURAL`, `NAO_CONTRIBUINTE` ou `DISPENSADO_NF`. |
| `tax_regime` | string | não | `NORMAL`, `SIMPLES_NACIONAL`, `SIMPLES_NACIONAL_EXCESSO` ou `MEI`. |
| `email` | string | não | E-mail válido. |
| `phone` | string | não | Telefone. |
| `address` | object | sim | Endereço (ver tabela). |

### Endereço do participante (`…​.address`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `zipcode` | string | sim | CEP. |
| `street` | string | sim | Logradouro. |
| `number` | string | não | Número. |
| `neighborhood` | string | não | Bairro. |
| `complement` | string | não | Complemento. |
| `country` | string | sim | País, com 2 letras (`BR`). |
| `state` | string | sim | UF. |
| `city` | string | sim | Município. A API precisa identificar o código IBGE dele (`ADDRESS_WITHOUT_IBGE`). |
| `latitude, longitude` | number | não | Coordenadas. |

### Valores (`cte.valores`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `total_servico` | number | sim | Valor total da prestação. |
| `a_receber` | number | não | Padrão: `total_servico`. Não pode ser maior que ele. |
| `componentes` | array | sim | Ao menos um `{ nome, valor }`; `nome` com até 15 caracteres. A soma dos valores deve ser igual a `total_servico`. |

### ICMS (`cte.icms`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `cst` | string | sim | `00`, `20`, `40`, `41`, `51`, `60`, `90`, `SN` (Simples Nacional) ou `OUTRA_UF`. Precisa ser compatível com o regime tributário do emitente (`ICMS_CST_INCOMPATIBLE_WITH_CRT`). |
| `base` | number | não | Base de cálculo. |
| `aliquota` | number | não | Alíquota, em percentual. |
| `valor` | number | não | Valor do ICMS. |
| `percentual_reducao` | number | não | Redução da base, de 0 a 100. |
| `credito` | number | não | Crédito outorgado ou presumido. |
| `total_tributos` | number | não | Valor total aproximado dos tributos. |
| `difal` | object | não | Partilha do ICMS interestadual: `base`, `fcp_aliquota`, `aliquota`, `aliquota_interestadual`, `fcp_valor`, `valor` e `valor_uf_origem`. |

### IBS e CBS (`cte.ibs_cbs`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `cst` | string | sim | CST do IBS/CBS, com 3 dígitos. |
| `classificacao_tributaria` | string | sim | Código de classificação tributária, com 6 dígitos. |
| `base` | number | sim | Base de cálculo. |
| `ibs_uf_aliquota, ibs_uf_valor` | number | sim | Alíquota e valor do IBS estadual. |
| `ibs_municipal_aliquota, ibs_municipal_valor` | number | sim | Alíquota e valor do IBS municipal. |
| `ibs_valor` | number | sim | Valor total do IBS. |
| `cbs_aliquota, cbs_valor` | number | sim | Alíquota e valor da CBS. |
| `valor_total_documento` | number | sim | Valor total do documento fiscal. |

### Carga (`cte.carga`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `valor` | number | sim | Valor total da carga. |
| `valor_averbado` | number | não | Valor da carga para averbação. |
| `produto_predominante` | string | sim | Até 60 caracteres. |
| `outras_caracteristicas` | string | não | Até 30 caracteres. |
| `quantidades` | array | sim | Ao menos uma medida: `unidade` (`00` m³, `01` kg, `02` t, `03` unidade, `04` litros, `05` MMBTU), `tipo_medida` (até 20 caracteres, como `PESO BRUTO`) e `quantidade` (maior que zero). |

### NF-e transportada (`cte.documentos[]`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `chave_nfe` | string | sim | Chave de acesso da NF-e, com 44 posições. |
| `previsao_entrega` | datetime | não | Previsão de entrega. |
| `order_search` | object | não | Como localizar o pedido do Meu Rastreio ligado a esta nota: `external_id` (UUID), `chave_nfe`, `chave_cte`, `order_number` ou `nfe` (`number`, `serie`, `cnpj`). |

### Documento anterior (`cte.documentos_anteriores[]`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `emitente` | object | sim | `cpf_cnpj` (obrigatório), `inscricao_estadual`, `nome` (até 60) e `uf`. |
| `tipo` | string | não | `ELECTRONIC` (padrão) ou `PAPER`. |
| `chave` | string | no tipo ELECTRONIC | Chave de acesso do CT-e anterior, com 44 posições. |
| `papel` | object | no tipo PAPER | `modelo` (até 2), `serie` (até 3), `subserie` (até 2, opcional), `numero` (até 20) e `emitido_em`. |

### Observação estruturada (`cte.observacoes[]`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `destino` | string | sim | `CONTRIBUINTE` ou `FISCO`. |
| `campo` | string | sim | Identificação do campo, até 20 caracteres. |
| `valor` | string | sim | Conteúdo, até 160 caracteres. |

### Cobrança (`cte.cobranca`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `numero` | string | não | Número da fatura, até 20 caracteres. |
| `valor_original, valor_desconto, valor_liquido` | number | não | Valores da fatura. |
| `parcelas` | array | não | Duplicatas: `numero` (até 20, obrigatório), `vencimento` e `valor` (obrigatório). |

corpo de exemplo:

```json
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "cte": {
    "cfop": "6353",
    "natureza_operacao": "Prestação de serviço de transporte",
    "tomador": "SENDER",
    "origem": {
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "destino": {
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ"
    },
    "remetente": {
      "type": 1,
      "id": "00000000000191",
      "state_inscription": "110042490114",
      "name": "Remetente Exemplo Ltda",
      "address": {
        "zipcode": "01001000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "SP",
        "city": "São Paulo"
      }
    },
    "destinatario": {
      "type": 1,
      "id": "00000000000272",
      "state_inscription": "87654321",
      "name": "Destinatário Exemplo Ltda",
      "address": {
        "zipcode": "20010000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "RJ",
        "city": "Rio de Janeiro"
      }
    },
    "valores": {
      "total_servico": 1500,
      "a_receber": 1500,
      "componentes": [
        {
          "nome": "Frete peso",
          "valor": 1400
        },
        {
          "nome": "Pedágio",
          "valor": 100
        }
      ]
    },
    "icms": {
      "cst": "00",
      "base": 1500,
      "aliquota": 12,
      "valor": 180
    },
    "ibs_cbs": {
      "cst": "000",
      "classificacao_tributaria": "000001",
      "base": 1500,
      "ibs_uf_aliquota": 0.1,
      "ibs_uf_valor": 1.5,
      "ibs_municipal_aliquota": 0,
      "ibs_municipal_valor": 0,
      "ibs_valor": 1.5,
      "cbs_aliquota": 0.9,
      "cbs_valor": 13.5,
      "valor_total_documento": 1500
    },
    "carga": {
      "valor": 85000,
      "produto_predominante": "Eletrônicos",
      "quantidades": [
        {
          "unidade": "01",
          "tipo_medida": "PESO BRUTO",
          "quantidade": 1200
        }
      ]
    },
    "documentos": [
      {
        "chave_nfe": "35261100000000000272550010000456781000045678"
      }
    ],
    "observacao": "Entrega em horário comercial"
  }
}
```

resposta 201:

```json
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "cte": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PENDING"
  }
}
```

> **Atenção:** A API valida o formato e as regras que conhece antes de enfileirar, mas quem autoriza é a SEFAZ. Um `201` seguido de `REJECTED` é esperado quando os dados fiscais não fecham; o motivo vem em `c_stat` e `status_reason`.

### Reenvio

O `POST` funciona como criar-ou-substituir pela `external_reference`: referência nova **cria** o CT-e; referência que já existe **substitui os dados e volta o documento para a fila**, zerando protocolo, motivo e arquivos da tentativa anterior.

| status do documento | o que o reenvio faz |
|---|---|
| `PENDING`, `PROCESSING`, `REJECTED` ou `ERROR` | Substitui os dados e enfileira de novo, mantendo série e número. |
| `DENIED` | Substitui e enfileira com **numeração nova**: a denegação inutiliza o número anterior na SEFAZ. |
| `AUTHORIZED`, `CANCELED` ou `CLOSED` | `409 DOCUMENT_ALREADY_PROCESSED`: documento aceito pela SEFAZ não se corrige; cancele e emita outro, com outra referência. |

- Referência que já pertence a outra filial responde `409 DOCUMENT_FROM_ANOTHER_SUBSIDIARY`.
- Se a filial trocou de ambiente (homologação/produção) depois da primeira emissão, o reenvio responde `409 DOCUMENT_ENVIRONMENT_CHANGED`: emita um documento novo.

## Consulta e listagem

| chamada | devolve |
|---|---|
| `GET /ctes/{external_reference}` | O CT-e dessa referência. |
| `GET /ctes?external_reference= ou ?access_key=` | O mesmo CT-e, pela query string. |
| `GET /ctes?date_from=&date_to=` | A lista do período, paginada, do mais novo para o mais antigo. |

A consulta só enxerga documentos da filial do token: referência de outra filial, ou que não existe, responde `404 DOCUMENT_NOT_FOUND`. Na lista, cada item de `data` é o mesmo objeto da consulta individual.

| parâmetro da lista | obrigatório | como usar |
|---|---|---|
| `date_from` | sim | Início do período, em ISO 8601 **com fuso**: `2026-11-01T00:00:00-03:00` ou `2026-11-01T03:00:00Z`. Data sem fuso é recusada. |
| `date_to` | sim | Fim do período, com fuso. Igual ou posterior a `date_from`. |
| `status` | não | Filtra por um ou mais status: `status=AUTHORIZED,CANCELED` ou o parâmetro repetido. Valores aceitos: `PENDING`, `PROCESSING`, `AUTHORIZED`, `DENIED`, `REJECTED`, `CANCELED`, `ERROR`. |
| `page` | não | Página, a partir de 1. Padrão: 1. |
| `per_page` | não | Itens por página, de 1 a 100. Padrão: 10. |

- O período filtra por data de emissão do CT-e; para o que ainda não foi emitido, pela data de criação.
- Sem `date_from` e `date_to`, ou com um status que não existe, a resposta é `422 VALIDATION_ERROR`.
- O `+` do fuso precisa ir codificado como `%2B` na URL. `Z` e `-03:00` não precisam.
- A resposta da lista é `{ data, pagination: { page, per_page, total, total_pages } }`.

consulta:

```bash
curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
```

resposta 200:

```json
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "status": "AUTHORIZED",
  "emission_type": "NORMAL",
  "serie": 1,
  "number": 1234,
  "access_key": "35261100000000000191570010000012341000012345",
  "protocol": "135260000012345",
  "c_stat": 100,
  "status_reason": "Autorizado o uso do documento",
  "issued_at": "2026-11-19T14:01:58.000Z",
  "authorized_at": "2026-11-19T14:02:11.000Z",
  "canceled_at": null,
  "xml_url": "https://painel.meurastreio.app/api/files/3f6f0c2e-0000-4000-8000-000000000000",
  "pdf_url": "https://painel.meurastreio.app/api/v1/ctes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "events": []
}
```

lista:

```bash
curl -s "https://painel.meurastreio.app/api/v1/ctes?date_from=2026-11-01T00:00:00-03:00&date_to=2026-11-30T23:59:59-03:00&status=AUTHORIZED,CANCELED&per_page=100" \
  -H "x-api-token: SEU_TOKEN"
```

### CT-e na resposta (`objeto devolvido`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `external_reference` | string | — | A sua referência. |
| `status` | string | — | Ver a seção Status. |
| `emission_type` | string | — | Forma de emissão. |
| `serie, number` | integer | — | Série e número. `null` até a numeração ser atribuída. |
| `access_key` | string | — | Chave de acesso, com 44 posições. |
| `protocol` | string | — | Protocolo de autorização na SEFAZ. |
| `c_stat` | integer | — | Código de retorno da SEFAZ. |
| `status_reason` | string | — | Motivo devolvido pela SEFAZ, ou a descrição do erro. |
| `issued_at` | datetime | — | Emissão. |
| `authorized_at` | datetime | — | Autorização. |
| `canceled_at` | datetime | — | Cancelamento. |
| `xml_url` | string | — | Link do XML do documento. `null` enquanto não houver XML. |
| `pdf_url` | string | — | Endereço do DACTE na rota `/pdf`. `null` enquanto o PDF não estiver disponível. |
| `events` | array | — | Eventos do documento (ver tabela). |

### Evento na resposta (`events[]`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `type` | string | — | Tipo do evento. |
| `sequence` | integer | — | Sequência do evento dentro do tipo, a partir de 1. |
| `status` | string | — | `PENDING`, `PROCESSING`, `REGISTERED`, `REJECTED` ou `ERROR`. |
| `justification` | string | — | Justificativa enviada, quando o evento tem. |
| `protocol` | string | — | Protocolo de registro do evento na SEFAZ. |
| `c_stat` | integer | — | Código de retorno da SEFAZ para o evento. |
| `status_reason` | string | — | Motivo devolvido pela SEFAZ. |
| `registered_at` | datetime | — | Quando o evento foi registrado. |
| `xml_url` | string | — | Link do XML do evento. |
| `pdf_url` | string | — | Endereço do PDF do evento na rota `/pdf`. `null` enquanto o evento não estiver registrado. |

> Datas saem em ISO 8601, em UTC. Campo sem valor vem `null`. Novos campos podem aparecer com o tempo; ignore o que o seu sistema não conhece.

## Eventos

Evento é o que se registra na SEFAZ **depois** que o CT-e está autorizado. Cada evento tem a sua rota, sempre `POST`.

- O documento é localizado por `external_reference` **ou** `access_key`, enviados no corpo junto com os campos do evento.
- A resposta é `201` com `{ protocol, cte: { external_reference, event: { type, sequence, status } } }`. Como na emissão, **201 quer dizer enfileirado**: o registro na SEFAZ vem depois, em `events` da consulta ou pelos webhooks de evento.
- Todos os eventos exigem o CT-e em `AUTHORIZED`. Fora disso: `409 DOCUMENT_NOT_CANCELABLE` no cancelamento e `409 DOCUMENT_NOT_CHANGEABLE` nos demais.
- Comprovante de entrega, insucesso e os cancelamentos deles exigem o protocolo de autorização do CT-e (`409 DOCUMENT_WITHOUT_PROTOCOL`).
- Acontecem **uma vez** por documento: o cancelamento. Depois de registrados, um novo pedido responde `409`. Podem se repetir: a carta de correção (a SEFAZ aceita até 20 por CT-e), o comprovante de entrega, o insucesso na entrega e os cancelamentos desses dois; cada novo pedido ganha a próxima `sequence`.
- Com um evento do mesmo tipo ainda em `PENDING` ou `PROCESSING`, um novo pedido responde `409` (`EVENT_ALREADY_PENDING`).
- Evento que terminou em `REJECTED` ou `ERROR` pode ser pedido de novo: ele reaproveita a mesma `sequence`, com os dados novos.
- Documento emitido por terceiro e importado é só leitura: `409 IMPORTED_DOCUMENT_READ_ONLY`.

### Identificação do CT-e (`em todo corpo de evento`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `external_reference` | string (UUID) | um dos dois | A referência do documento. |
| `access_key` | string | um dos dois | A chave de acesso, com 44 posições. |

### Cancelamento (`POST /ctes/cancel`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `justificativa` | string | sim | De 15 a 255 caracteres. |

### Carta de correção (`POST /ctes/correction-letter`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `correcoes` | array | sim | De 1 a 15 correções. |
| `correcoes[].grupo` | string | sim | Grupo do XML que contém o campo corrigido, até 20 caracteres. |
| `correcoes[].campo` | string | sim | Campo corrigido, até 20 caracteres. |
| `correcoes[].valor` | string | sim | Novo valor, até 700 caracteres. |
| `correcoes[].item` | integer | não | Número do item, de 1 a 990, quando o grupo se repete. |

### Comprovante de entrega (`POST /ctes/delivery-receipt`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `entregue_em` | datetime | sim | Data e hora da entrega, em ISO 8601 com fuso. |
| `documento_recebedor` | string | sim | Documento de quem recebeu, até 20 caracteres. |
| `nome_recebedor` | string | sim | Até 60 caracteres. |
| `latitude, longitude` | number | não | Local da entrega. |
| `hash_entrega` | string | sim | Hash do comprovante de entrega, em Base64 (de 28 a 256 caracteres). |
| `hash_entrega_em` | datetime | sim | Quando o hash foi gerado, com fuso. |
| `notas` | array | não | Chaves das NF-e entregues (44 posições cada), até 2000. |

### Cancelamento do comprovante de entrega (`POST /ctes/cancel-delivery-receipt`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `protocolo_comprovante` | string | sim | Protocolo (15 dígitos) do comprovante registrado que será cancelado. Sem um comprovante registrado com esse protocolo: `404 EVENT_TO_CANCEL_NOT_FOUND`. |

### Insucesso na entrega (`POST /ctes/delivery-failure`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `tentativa_em` | datetime | sim | Data e hora da tentativa, com fuso. |
| `numero_tentativa` | integer | não | De 1 a 99. |
| `motivo` | integer | sim | `1` recebedor não encontrado, `2` recusa do recebedor, `3` endereço inexistente, `4` outros. |
| `justificativa_motivo` | string | com motivo 4 | De 15 a 256 caracteres. |
| `latitude, longitude` | number | não | Local da tentativa. |
| `hash_tentativa` | string | não | Hash da tentativa, em Base64. Anda junto com `hash_tentativa_em`: ou os dois, ou nenhum. |
| `hash_tentativa_em` | datetime | com hash_tentativa | Quando o hash foi gerado, com fuso. |
| `notas` | array | não | Chaves das NF-e da tentativa, até 2000. |

### Cancelamento do insucesso na entrega (`POST /ctes/cancel-delivery-failure`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `protocolo_insucesso` | string | sim | Protocolo (15 dígitos) do insucesso registrado que será cancelado. Sem um insucesso registrado com esse protocolo: `404 EVENT_TO_CANCEL_NOT_FOUND`. |

cancelar:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes/cancel" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "justificativa": "Emitido com valor de frete incorreto"
}'
```

resposta 201:

```json
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "cte": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "event": {
      "type": "CANCELLATION",
      "sequence": 1,
      "status": "PENDING"
    }
  }
}
```

carta de correção:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes/correction-letter" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "access_key": "35261100000000000191570010000012341000012345",
  "correcoes": [
    {
      "grupo": "compl",
      "campo": "xObs",
      "valor": "Entrega somente pela doca 3"
    }
  ]
}'
```

> Os tipos de evento que aparecem em `events[].type` são `CANCELLATION`, `CORRECTION_LETTER`, `DELIVERY_RECEIPT`, `DELIVERY_RECEIPT_CANCELLATION`, `DELIVERY_FAILURE` e `DELIVERY_FAILURE_CANCELLATION`.

## PDF e XML

### XML

O XML autorizado é baixado pelo endereço em `xml_url`, devolvido na consulta do CT-e. Cada evento registrado tem o próprio `xml_url` dentro de `events`.

### PDF

O DACTE e os comprovantes dos eventos saem da rota de PDF, com o mesmo token:

| parâmetro | obrigatório | como usar |
|---|---|---|
| `external_reference` ou `access_key` | um dos dois | Identifica o CT-e. |
| `event_type` | não | Com ele, a rota devolve o PDF do evento em vez do documento. É o `type` do evento em `events`. |
| `event_sequence` | não | Sequência do evento. Padrão: 1. |

requisição:

```bash
curl -s "https://painel.meurastreio.app/api/v1/ctes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN" \
  -o dacte.pdf
```

- Sucesso: `200` com `Content-Type: application/pdf`.
- O PDF do documento existe quando o CT-e tem XML e está `AUTHORIZED`, `CANCELED` ou `CLOSED`; o do evento, quando o evento está `REGISTERED`. Fora disso a resposta é `409` com `{"message":"PDF_NOT_AVAILABLE"}`.
- Evento que não existe no documento: `404 EVENT_NOT_FOUND`.
- Falha ao gerar o arquivo: `502` com `{"message":"FISCAL_PDF_NOT_GENERATED"}`. Tente de novo.
- O `pdf_url` da consulta já aponta para esta rota com os parâmetros certos; envie o cabeçalho `x-api-token` ao chamá-lo.

## Status

| status | o que quer dizer |
|---|---|
| `PENDING` | Gravado e aguardando a fila. |
| `PROCESSING` | Em envio à SEFAZ, ou emitido em contingência aguardando a transmissão. |
| `AUTHORIZED` | Autorizado. Chave, protocolo, XML e PDF disponíveis. |
| `REJECTED` | Rejeitado. O motivo fica em `c_stat` e `status_reason`. Corrija e reenvie com a mesma referência. |
| `DENIED` | Denegado pela SEFAZ. O número é perdido; o reenvio usa numeração nova. |
| `CANCELED` | Cancelado: o evento de cancelamento foi registrado. |
| `ERROR` | Falha no processamento. O motivo fica em `status_reason`. Pode ser reenviado com a mesma referência. |

### Status dos eventos

| status | o que quer dizer |
|---|---|
| `PENDING` | Pedido gravado, aguardando a fila. |
| `PROCESSING` | Em envio à SEFAZ. |
| `REGISTERED` | Registrado na SEFAZ. `protocol` e `registered_at` preenchidos. |
| `REJECTED` | Recusado pela SEFAZ. O motivo fica em `c_stat` e `status_reason`. |
| `ERROR` | Falha no processamento. Pode ser pedido de novo. |

## Webhooks

O Meu Rastreio tem webhooks para os eventos do CT-e: em vez de consultar o status em laço, o seu sistema é avisado quando ele muda. Os webhooks são **habilitados sob solicitação**: escreva para suporte@meurastreio.app informando a filial, a URL que vai receber as chamadas e quais eventos você quer.

| evento | quando é enviado |
|---|---|
| `CTE_CREATED` | O `POST` da API criou o CT-e. O reenvio da mesma referência não repete o evento. |
| `CTE_AUTHORIZED` | A SEFAZ autorizou. |
| `CTE_REJECTED` | Terminou sem autorização: `REJECTED`, `DENIED` ou `ERROR`. |
| `CTE_CANCELED` | O cancelamento foi registrado. |
| `CTE_EVENT_REGISTERED` | Qualquer evento foi registrado na SEFAZ, cancelamento inclusive. |
| `CTE_EVENT_REJECTED` | Um evento foi recusado pela SEFAZ ou terminou em erro. |

- Cada evento habilitado gera uma chamada `POST` para a sua URL, com `Content-Type: application/json`.
- O corpo é o próprio objeto do CT-e, direto na raiz do JSON, com os campos da tabela abaixo. Os nomes aqui são em `camelCase`, diferentes dos da API.
- Responda com status `2xx`. Em caso de falha, o envio é tentado até **3 vezes**, com espera crescente entre as tentativas.
- Cancelar gera dois avisos: o de cancelamento do documento e o de evento registrado. Quem só precisa saber que o documento foi cancelado escuta o primeiro; quem precisa saber quando um cancelamento foi **recusado** escuta os de evento.
- `PENDING` e `PROCESSING` não geram aviso.

### CT-e no webhook (`corpo do POST`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `id` | integer | — | Identificador do CT-e no Meu Rastreio. |
| `externalReference` | string | — | A sua referência. |
| `companySubsidiaryId` | integer | — | Identificador da filial. |
| `status` | string | — | Status do documento. |
| `statusDescription` | string | — | O status em português. |
| `environment` | string | — | Ambiente em que o documento foi emitido (produção ou homologação). |
| `emissionType` | string | — | Forma de emissão. |
| `emitterCnpj` | string | — | CNPJ do emitente. |
| `serie, number` | integer | — | Série e número. |
| `accessKey` | string | — | Chave de acesso. |
| `protocol` | string | — | Protocolo de autorização. |
| `cStat` | integer | — | Código de retorno da SEFAZ. |
| `statusReason` | string | — | Motivo devolvido pela SEFAZ. |
| `issuedAt, authorizedAt, canceledAt` | datetime | — | Emissão, autorização e cancelamento. |
| `totalServiceValue` | number | — | Valor total da prestação. |
| `event` | object | — | `null` nos eventos do documento. Nos webhooks de evento traz `type`, `typeDescription`, `status`, `statusDescription`, `protocol`, `statusReason` e `justification`. |

corpo recebido:

```json
{
  "id": 90211,
  "externalReference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "companySubsidiaryId": 12,
  "status": "AUTHORIZED",
  "environment": "PRODUCTION",
  "emissionType": "NORMAL",
  "emitterCnpj": "00000000000191",
  "serie": 1,
  "number": 1234,
  "accessKey": "35261100000000000191570010000012341000012345",
  "protocol": "135260000012345",
  "cStat": 100,
  "statusReason": "Autorizado o uso do CT-e",
  "issuedAt": "2026-11-19T14:01:58.000Z",
  "authorizedAt": "2026-11-19T14:02:11.000Z",
  "canceledAt": null,
  "totalServiceValue": 1500,
  "statusDescription": "Autorizado",
  "event": null
}
```

> **Atenção:** As chamadas **não têm cabeçalho de assinatura**. Para confirmar que a chamada veio do Meu Rastreio, peça ao suporte para configurar um cabeçalho personalizado com um segredo seu (por exemplo `x-webhook-secret`) e recuse chamadas sem ele. Use sempre uma URL HTTPS.

> Trate o webhook como aviso: o mesmo evento pode chegar mais de uma vez. Use `externalReference` e `status` para decidir o que fazer e, na dúvida, consulte o documento pela API.

## Limites de uso

| limite | valor | como funciona |
|---|---|---|
| Requisições por minuto | 120 por IP | Vale para todas as rotas da API somadas, contadas pelo IP de origem. |
| Itens por página | 10 (padrão), até 100 | Parâmetro `per_page` das listas. |
| Período da lista | obrigatório | `date_from` e `date_to` sempre informados: não existe listagem sem período. |
| Carta de correção | até 15 correções por carta | A SEFAZ aceita até 20 cartas por CT-e. |
| Autorizados a baixar o XML | até 10 | Campo `autorizados`. |
| Observações estruturadas | até 10 por destino | Campo `observacoes`. |
| NF-e por comprovante ou insucesso | até 2000 | Campo `notas` dos eventos de entrega. |

Passou do limite de requisições, a resposta é `429` e o cabeçalho `Retry-After` diz quantos segundos esperar:

resposta 429:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "message": "TOO_MANY_REQUESTS" }
```

- Respeite o `Retry-After` antes de tentar de novo.
- Para acompanhar o resultado de uma emissão, prefira os webhooks. Se for consultar, espere alguns segundos entre uma consulta e outra.
- Na lista, use `per_page=100` para fazer menos chamadas.

## Erros

O corpo de erro traz `code`, para o seu código decidir o que fazer, e `message`, para leitura de pessoas. Alguns erros trazem campos extras, como `errors` na validação.

resposta 422:

```json
{
  "code": "VALIDATION_ERROR",
  "message": "2 errors occurred",
  "errors": [
    "external_reference must be a valid UUID",
    "deve ser uma data ISO 8601 com fuso, como 2026-10-10T09:00:00-03:00"
  ]
}
```

| status | code | quando acontece |
|---|---|---|
| 401 | — | Token ausente ou desconhecido. O corpo é `{"message":"Acesso negado"}`, sem `code`. |
| 401 | `INTEGRATION_DISABLED` | A integração do token foi desativada pelo administrador. |
| 401 | `CTE_NOT_ALLOWED` | A integração não tem a permissão CT-e. |
| 402 | `PLAN_WITHOUT_FISCAL_DOCUMENTS` | O plano da empresa não inclui o módulo de documentos fiscais. |
| 422 | `FISCAL_CONFIG_NOT_FOUND` | Filial sem configuração fiscal ou sem certificado digital vinculado. |
| 404 | `DOCUMENT_NOT_FOUND` | Documento não encontrado na filial do token. |
| 405 | `METHOD_NOT_ALLOWED` | Método HTTP não aceito pela rota. Em algumas rotas o identificador vem só em `message`. |
| 422 | `VALIDATION_ERROR` | Corpo ou query fora do formato. `errors` lista cada problema encontrado. |
| 429 | — | Limite de requisições. O corpo é `{"message":"TOO_MANY_REQUESTS"}`, com o cabeçalho `Retry-After`. |
| 500 | `INTERNAL_ERROR` | Falha inesperada. Tente de novo; se persistir, fale com o suporte informando o `protocol` ou o horário da chamada. |
| 409 | `DOCUMENT_ALREADY_PROCESSED` | Documento autorizado, cancelado ou encerrado não aceita reenvio. |
| 409 | `DOCUMENT_FROM_ANOTHER_SUBSIDIARY` | A referência externa já pertence a um documento de outra filial. |
| 409 | `DOCUMENT_ENVIRONMENT_CHANGED` | A filial mudou de ambiente desde a emissão; emita um documento novo. |
| 422 | `RNTRC_REQUIRED` | RNTRC ausente no CT-e e na configuração fiscal da filial. |
| 422 | `ADDRESS_WITHOUT_IBGE` | Não foi possível identificar o código IBGE do município de um participante. |
| 422 | `ICMS_CST_INCOMPATIBLE_WITH_CRT` | O CST do ICMS não combina com o regime tributário do emitente. |
| 422 | `PREVIOUS_DOCUMENTS_REQUIRED` | Subcontratação, redespacho e redespacho intermediário exigem `documentos_anteriores`. |
| 404 | `EVENT_TO_CANCEL_NOT_FOUND` | Não há comprovante ou insucesso registrado com o protocolo informado. |
| 404 | `EVENT_NOT_FOUND` | Rota de PDF: o evento pedido não existe no documento. |
| 409 | `DOCUMENT_NOT_CANCELABLE` | O status do documento não permite cancelamento (só `AUTHORIZED`). |
| 409 | `DOCUMENT_NOT_CHANGEABLE` | O status do documento não aceita o evento pedido. |
| 409 | `DOCUMENT_WITHOUT_PROTOCOL` | O evento exige o protocolo de autorização e o documento não tem. |
| 409 | `IMPORTED_DOCUMENT_READ_ONLY` | Documento emitido por terceiro e importado não aceita eventos. |
| 409 | `EVENT_ALREADY_PENDING` | Já existe um evento do mesmo tipo aguardando processamento. |
| 409 | `EVENT_ALREADY_REGISTERED` | O evento só acontece uma vez e já foi registrado. |
| 409 | — | Rota de PDF: `{"message":"PDF_NOT_AVAILABLE"}`, sem `code`. |
| 502 | — | Rota de PDF: `{"message":"FISCAL_PDF_NOT_GENERATED"}`, sem `code`. |

- **401 e 402**: pare e avise uma pessoa. O problema é de token, permissão ou plano; insistir não resolve.
- **404**: confira a referência e se o token é da filial certa.
- **422**: corrija o corpo ou o cadastro apontado em `message` e envie de novo com a mesma `external_reference`.
- **429**: espere o `Retry-After`.
- **409**: leia o `code`. `EVENT_ALREADY_PENDING` pede espera; os demais dizem que o documento não está no status que a operação exige.
- **Rejeição da SEFAZ não é erro HTTP**: a chamada responde `201` e a rejeição aparece depois, no `status`, `c_stat` e `status_reason` do documento ou do evento.

## Exemplos completos

Emitir, acompanhar, baixar o DACTE e cancelar um CT-e com curl:

1. emitir:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "cte": {
    "cfop": "6353",
    "natureza_operacao": "Prestação de serviço de transporte",
    "tomador": "SENDER",
    "origem": {
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "destino": {
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ"
    },
    "remetente": {
      "type": 1,
      "id": "00000000000191",
      "state_inscription": "110042490114",
      "name": "Remetente Exemplo Ltda",
      "address": {
        "zipcode": "01001000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "SP",
        "city": "São Paulo"
      }
    },
    "destinatario": {
      "type": 1,
      "id": "00000000000272",
      "state_inscription": "87654321",
      "name": "Destinatário Exemplo Ltda",
      "address": {
        "zipcode": "20010000",
        "street": "Rua Exemplo",
        "number": "100",
        "neighborhood": "Centro",
        "country": "BR",
        "state": "RJ",
        "city": "Rio de Janeiro"
      }
    },
    "valores": {
      "total_servico": 1500,
      "a_receber": 1500,
      "componentes": [
        {
          "nome": "Frete peso",
          "valor": 1400
        },
        {
          "nome": "Pedágio",
          "valor": 100
        }
      ]
    },
    "icms": {
      "cst": "00",
      "base": 1500,
      "aliquota": 12,
      "valor": 180
    },
    "ibs_cbs": {
      "cst": "000",
      "classificacao_tributaria": "000001",
      "base": 1500,
      "ibs_uf_aliquota": 0.1,
      "ibs_uf_valor": 1.5,
      "ibs_municipal_aliquota": 0,
      "ibs_municipal_valor": 0,
      "ibs_valor": 1.5,
      "cbs_aliquota": 0.9,
      "cbs_valor": 13.5,
      "valor_total_documento": 1500
    },
    "carga": {
      "valor": 85000,
      "produto_predominante": "Eletrônicos",
      "quantidades": [
        {
          "unidade": "01",
          "tipo_medida": "PESO BRUTO",
          "quantidade": 1200
        }
      ]
    },
    "documentos": [
      {
        "chave_nfe": "35261100000000000272550010000456781000045678"
      }
    ],
    "observacao": "Entrega em horário comercial"
  }
}'
```

2. consultar até autorizar:

```bash
curl -s "https://painel.meurastreio.app/api/v1/ctes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
```

3. baixar o DACTE:

```bash
curl -s "https://painel.meurastreio.app/api/v1/ctes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN" \
  -o dacte.pdf
```

4. cancelar:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ctes/cancel" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "justificativa": "Emitido com valor de frete incorreto"
}'
```

Em JavaScript, emitindo e consultando até o status deixar de ser transitório, respeitando o `429`:

JavaScript (Node 20+):

```javascript
const BASE_URL = "https://painel.meurastreio.app/api/v1";
const TOKEN = process.env.MEU_RASTREIO_TOKEN;
const IN_PROGRESS = ["PENDING", "PROCESSING"];
const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function call(path, options = {}) {
  while (true) {
    const response = await fetch(`${BASE_URL}${path}`, {
      ...options,
      headers: { "x-api-token": TOKEN, "Content-Type": "application/json" },
    });

    if (response.status === 429) {
      await wait(Number(response.headers.get("Retry-After") ?? 5));
      continue;
    }

    const body = await response.json();

    if (!response.ok) throw new Error(`${response.status} ${body.code ?? ""} ${body.message}`);

    return body;
  }
}

async function emit(externalReference, cte) {
  // 201 means queued: the final status comes from the GET (or from the webhooks)
  await call("/ctes", {
    method: "POST",
    body: JSON.stringify({ external_reference: externalReference, cte }),
  });

  for (let attempt = 0; attempt < 60; attempt++) {
    await wait(5);

    const document = await call(`/ctes/${externalReference}`);

    if (!IN_PROGRESS.includes(document.status)) return document;
  }

  throw new Error("Ainda em processamento: consulte de novo mais tarde");
}

// cte: the object described in "Emissão"
const document = await emit(crypto.randomUUID(), cte);

console.log(document.status, document.status_reason);
```

## Suporte

Ativação do módulo, configuração fiscal e certificado, permissão da integração, webhooks ou dúvidas sobre uma rejeição: suporte@meurastreio.app. Para contratar: oi@meurastreio.app.
