# Meu Rastreio — API de BI (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-bi

## Resumo

- API somente leitura (GET) para levar dados de uma filial do Meu Rastreio a ferramentas de BI, ETL e data lake.
- Base URL: `https://painel.meurastreio.app/api/bi/v1`
- Escopo: um token = uma instalação da extensão "API de BI" = uma filial. Pedidos pertencem sempre à filial de origem.
- Ativação: pelo formulário em https://meurastreio.app/pt-BR/api-de-bi#solicitar-acesso (abre um chamado) ou por suporte@meurastreio.app. Só a equipe do Meu Rastreio instala, gera token, libera IPs e recursos.
- Carga histórica não é feita pela API: a equipe do Meu Rastreio gera os arquivos Parquet do passado (ver "Carga histórica em Parquet"). A API é para o incremental.

## Autenticação

- Header: `Authorization: Bearer <token>` (aceito também `x-api-token: <token>`).
- Formato do token: `mrbi_<uuid da instalação>_<segredo de 64 caracteres hex>`. É mostrado uma única vez ao ser gerado.
- Trocar o token invalida o anterior na hora. Revogar faz todas as chamadas responderem 401.
- O IP de origem precisa estar na lista de IPs/faixas CIDR liberados da instalação (IPv4 e IPv6). Lista vazia bloqueia tudo (403 IP_NOT_ALLOWED).
- Só HTTPS. Nunca envie o token em query string.

## Endpoints

- `GET https://painel.meurastreio.app/api/bi/v1`: recursos liberados, limites e cota restante do dia. Conta na cota.
- `GET https://painel.meurastreio.app/api/bi/v1/<recurso>`: lista paginada de um recurso.

| recurso | nome | módulo do plano exigido | conteúdo |
|---|---|---|---|
| `orders` | Pedidos | — | Pedidos da filial, com status, prazos, valores, frete, cliente, destino e notas fiscais. |
| `order-movements` | Movimentações dos pedidos | — | Cada evento de status do pedido (coleta, rota, entrega, ocorrência), com localização e comprovante. |
| `shipments` | Romaneios | — | Romaneios da filial, com motorista, veículo, distância, KM, frete e a sequência dos pedidos. |
| `shipment-movements` | Movimentações dos romaneios | — | Eventos do romaneio registrados pelo motorista ou pela operação. |
| `shipment-closings` | Fechamentos | Fechamento de frete | Fechamentos de frete dos romaneios. |
| `carrier-invoices` | Faturas de frete | Fechamento de frete | Faturas das transportadoras, com conferência, divergências e os CT-e cobrados. |
| `nfses` | NFS-e | NFS-e | Notas fiscais de serviço da filial. |
| `ctes` | CT-e | Documentos fiscais | Conhecimentos de transporte da filial, com valores, origem, destino e eventos. |
| `mdfes` | MDF-e | Documentos fiscais | Manifestos da filial, com carga, UFs e o romaneio ligado. |
| `ciots` | CIOT | CIOT | Operações de transporte declaradas, com frete, rotas, pedágios e histórico. |
| `checkouts` | Checkouts | Checkouts | Cobranças geradas para pedidos (PIX, cartão), com pagamento e taxas. |

Cada recurso precisa estar ligado na instalação; recurso desligado responde 403 RESOURCE_DISABLED.

## Parâmetros de lista

| parâmetro | obrigatório | regra |
|---|---|---|
| `updated_from` | sim, sem cursor | ISO 8601 com fuso (`2026-11-03T00:00:00-03:00` ou `...Z`). Data sem fuso responde 422 INVALID_DATE |
| `updated_to` | não | ISO 8601 com fuso. Padrão: agora. Valor no futuro vira agora |
| `per_page` | não | inteiro de 1 a 200. Padrão 100 |
| `cursor` | não | `next_cursor` da página anterior. Com cursor, `updated_from`/`updated_to` são ignorados; reenvie `per_page` |

- Janela máxima entre `updated_from` e `updated_to`: 31 dias (422 WINDOW_TOO_LARGE).
- Os registros vêm em ordem crescente de `updated_at` e, no empate, de `id`.
- Filtro e ordenação usam sempre `updated_at` (última alteração), não a data de criação.

## Resposta de lista

```json
{
  "data": [
    {
      "id": 481203,
      "external_reference": "6f1c2a7e-1d1b-4d55-9a1e-2b7f0c9d4e11",
      "order_number": "PV-102938",
      "service_status": "FINISHED",
      "is_canceled": false,
      "total_price": 1849.9,
      "total_price_currency": "BRL",
      "total_freight": 42.5,
      "sold_at": "2026-11-02T13:10:00.000Z",
      "deadline_at": "2026-11-04T02:59:59.999Z",
      "finished_at": "2026-11-03T17:42:11.000Z",
      "customer": { "id": 9921, "name": "Mercado Bom Preço", "cpf_cnpj": "12345678000190" },
      "destination": { "city": "Serra", "state": "ES", "zipcode": "29160000", "ibge": "3205002", "neighborhood": "Centro" },
      "carrier": null,
      "route": { "id": 14, "name": "Serra Norte" },
      "invoices": [{ "type": "NFE", "number": 58812, "serie": 1, "key": "3226...", "value": 1849.9, "currency": "BRL", "issued_at": "2026-11-02T13:00:00.000Z" }],
      "created_at": "2026-11-02T13:10:04.000Z",
      "updated_at": "2026-11-03T17:42:12.000Z"
    }
  ],
  "pagination": {
    "per_page": 100,
    "has_more": true,
    "next_cursor": "eyJmIjoiMjAyNi0xMS0wM1QwMzowMDowMC4wMDBaIi..."
  },
  "window": {
    "updated_from": "2026-11-03T03:00:00.000Z",
    "updated_to": "2026-11-04T03:00:00.000Z"
  }
}
```

- `pagination.has_more`: há mais páginas. `pagination.next_cursor`: string opaca para a próxima página, `null` na última.
- Não existe `total` nem número de página.
- `window`: a janela efetiva, em UTC.
- Datas em ISO 8601 UTC. Campos ausentes vêm `null`.

## Algoritmo de paginação

1. Chame com `updated_from`, `updated_to` (fixe um valor; não deixe "agora" variar entre páginas) e `per_page`.
2. Processe `data`.
3. Se `has_more` for `true`, chame de novo só com `cursor=<next_cursor>` e `per_page`.
4. Pare quando `has_more` for `false`.
5. Uma requisição por vez por token. Não paralelize recursos nem páginas.
6. Grave por upsert usando `id` como chave: um registro alterado durante a leitura pode aparecer de novo numa janela posterior.
7. Incremental: guarde o `updated_to` da última execução completa e use como `updated_from` da próxima.

```python
import time
import requests

BASE_URL = "https://painel.meurastreio.app/api/bi/v1"
TOKEN = "mrbi_SEU_TOKEN"


def fetch_all(resource, updated_from, updated_to):
    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {TOKEN}"
    params = {"updated_from": updated_from, "updated_to": updated_to, "per_page": 200}

    while True:
        response = session.get(f"{BASE_URL}/{resource}", params=params, timeout=60)

        if response.status_code == 429:
            time.sleep(int(response.headers.get("Retry-After", "5")))
            continue

        response.raise_for_status()
        body = response.json()
        yield from body["data"]

        if not body["pagination"]["has_more"]:
            return

        params = {"cursor": body["pagination"]["next_cursor"], "per_page": 200}


for order in fetch_all("orders", "2026-11-03T00:00:00-03:00", "2026-11-04T00:00:00-03:00"):
    print(order["id"], order["updated_at"])
```

## Rate limit

| limite | valor padrão | detalhe |
|---|---|---|
| Requisições simultâneas | 1 | Só uma requisição por token roda de cada vez. A segunda recebe 429 na hora. |
| Por minuto | 20 (rajada de 10) | Até 10 seguidas; depois, uma nova a cada 3 segundos. |
| Por dia | 2.000 | Zera à meia-noite no fuso da empresa. |
| Registros por página | 100 (padrão), até 200 | Parâmetro per_page. |
| Janela de consulta | até 31 dias | Entre updated_from e updated_to. |
| Tempo de consulta | 10 segundos | Consulta mais longa responde 503 QUERY_TIMEOUT: diminua a janela ou o per_page. |
| Bloqueio por insistência | 15 minutos | 50 respostas 429 em 5 minutos bloqueiam o token. |
| Token inválido | 1 hora | 20 tokens inválidos do mesmo IP em 10 minutos bloqueiam o IP. |

Os valores padrão podem ser ajustados por instalação pela equipe do Meu Rastreio; consulte `GET /api/bi/v1` para os valores efetivos.

| header | significado |
|---|---|
| `RateLimit-Limit` | Requisições por minuto do token. |
| `RateLimit-Remaining` | Quantas ainda cabem agora sem esperar. |
| `X-RateLimit-Daily-Limit` | Cota diária. |
| `X-RateLimit-Daily-Remaining` | Quanto resta da cota hoje. |
| `Retry-After` | Só no 429: segundos a esperar antes de tentar de novo. |

No 429, espere exatamente `Retry-After` segundos antes de tentar de novo. Continuar chamando durante o bloqueio leva ao bloqueio de 15 minutos (`limit: "penalty"`). Validação com erro (422) também consome cota.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 20
X-RateLimit-Daily-Limit: 2000

{
  "code": "RATE_LIMITED",
  "message": "Limite de requisições atingido (minute). Tente de novo em 3 s.",
  "limit": "minute",
  "retry_after": 3
}
```

## Erros

Corpo: `{ "code": "<CÓDIGO>", "message": "<texto>", ...campos extras }`. Use `code` para decidir; `message` é para leitura humana.

| status | code | quando |
|---|---|---|
| 401 | `INVALID_TOKEN` | Token ausente, inválido, revogado ou trocado. |
| 403 | `IP_NOT_ALLOWED` | O IP de origem não está na lista liberada da instalação. |
| 403 | `IP_BLOCKED` | IP bloqueado por 1 hora após muitos tokens inválidos. |
| 403 | `EXTENSION_INACTIVE` | A instalação da API de BI está desativada. |
| 403 | `PLAN_EXPIRED` | Empresa ou filial desativada. |
| 403 | `PLAN_WITHOUT_EXTENSIONS` | O plano não inclui extensões. |
| 403 | `RESOURCE_DISABLED` | O recurso não foi liberado nesta instalação. |
| 403 | `RESOURCE_NOT_IN_PLAN` | O plano não inclui o módulo do recurso. |
| 404 | `RESOURCE_NOT_FOUND` | Caminho de recurso que não existe. |
| 405 | `METHOD_NOT_ALLOWED` | A API só aceita GET. |
| 422 | `UPDATED_FROM_REQUIRED` | Faltou updated_from (sem cursor). |
| 422 | `INVALID_DATE` | Data fora do ISO 8601 com fuso. O campo vem em field. |
| 422 | `INVALID_WINDOW` | updated_to anterior a updated_from. |
| 422 | `WINDOW_TOO_LARGE` | Janela maior que o máximo, que vem em max. |
| 422 | `INVALID_PER_PAGE` | per_page fora de 1 até o máximo, que vem em max. |
| 422 | `INVALID_CURSOR` | Cursor alterado ou de outra consulta. |
| 429 | `RATE_LIMITED` | Limite atingido. limit diz qual (concurrency, minute, day, penalty) e retry_after, quanto esperar. |
| 503 | `QUERY_TIMEOUT` | A consulta passou de 10 segundos. |
| 503 | `SERVICE_UNAVAILABLE` | Instabilidade momentânea. Tente de novo em instantes. |

Reação recomendada: 401/403 → parar e avisar uma pessoa; 422 → corrigir parâmetros; 429 → esperar `Retry-After`; 503 → reduzir janela/per_page (QUERY_TIMEOUT) ou tentar de novo com espera crescente (SERVICE_UNAVAILABLE).

## Exportação diária em Parquet

- Opcional, ligada pela equipe do Meu Rastreio na instalação.
- Todo dia, no horário configurado, exporta os registros com `updated_at` dentro do dia anterior (fuso da empresa), de cada recurso liberado.
- Um arquivo por recurso com dados: `<recurso>_<AAAA-MM-DD>.parquet` (ex.: `orders_2026-11-03.parquet`). Recurso sem alteração no dia não gera arquivo.
- Destino FTP: pasta configurada + `/<AAAA-MM-DD>/`. Destino e-mail: anexos, até 25 MB no total; acima disso o e-mail chega sem anexos, avisando para usar FTP.
- Colunas: os mesmos campos da API. Tipos: datas → TIMESTAMP (UTC, milissegundos); inteiros → INT64; decimais → DOUBLE; booleanos → BOOLEAN; objetos e listas → texto JSON.
- Use os arquivos para carga histórica e conciliação; aplique o mesmo upsert por `id`.

## Carga histórica em Parquet

- Solicitada pelo formulário de acesso ou por suporte@meurastreio.app; a equipe do Meu Rastreio inicia e acompanha.
- Período escolhido, até o dia anterior. Depois disso valem a exportação diária e a API.
- Um arquivo por recurso e por período. Granularidade à escolha: mês (`orders_2026-03.parquet`), semana ISO (`orders_2026-W10.parquet`) ou dia (`orders_2026-03-05.parquet`).
- FTP: `<pasta>/historico/<período>/<recurso>_<período>.parquet`. E-mail: um e-mail por arquivo, até 25 MB de anexo.
- O registro entra no período do seu `updated_at` (última alteração). A soma de todos os arquivos não repete registros. Carregue com upsert por `id`.
- Mesmas colunas e tipos da exportação diária.

## Campos por recurso

### `orders` — Pedidos

Pedidos da filial, com status, prazos, valores, frete, cliente, destino e notas fiscais.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador do pedido. |
| `external_reference` | string | UUID público do pedido. |
| `order_number` | string | Número do pedido. |
| `parent_order_number` | string | Número do pedido pai (pedidos desmembrados). |
| `shop` | object | Loja: id e name. |
| `service_status` | string | Status de atendimento. |
| `finished_status` | string | Situação de prazo da entrega. |
| `expedition_status` | string | Situação de prazo da expedição. |
| `delivery_status` | string | Situação de prazo da entrega pela filial. |
| `is_canceled` | boolean | Pedido cancelado. |
| `has_occurrence` | boolean | Teve ocorrência. |
| `has_sinister` | boolean | Teve sinistro. |
| `has_reverse` | boolean | Teve logística reversa. |
| `has_missing_items` | boolean | Teve falta de itens. |
| `freight_type` | string | Tipo de frete. |
| `need_to_be_collected` | boolean | Precisa de coleta. |
| `total_weight` | number | Peso total. |
| `total_price` | number | Valor total. |
| `total_price_currency` | string | Moeda do valor total. |
| `total_volumes` | integer | Volumes. |
| `total_freight` | number | Frete do pedido. |
| `total_freight_currency` | string | Moeda do frete. |
| `total_freight_by_system` | number | Frete calculado pelo sistema. |
| `total_freight_by_carrier` | number | Frete cobrado pela transportadora. |
| `total_freight_paid` | number | Frete pago. |
| `total_freight_manual` | number | Frete informado manualmente. |
| `sold_at` | datetime | Data da venda. |
| `requested_delivery_date` | datetime | Data de entrega pedida. |
| `collected_at` | datetime | Coleta. |
| `in_transfer_at` | datetime | Entrada em transferência. |
| `in_route_at` | datetime | Saída para rota. |
| `expedited_at` | datetime | Expedição concluída. |
| `expedition_at` | datetime | Data de expedição. |
| `finished_at` | datetime | Finalização (entrega ou devolução). |
| `deadline_days` | integer | Prazo em dias. |
| `deadline_at` | datetime | Prazo de entrega. |
| `expedition_deadline_at` | datetime | Prazo de expedição. |
| `delivery_deadline_at` | datetime | Prazo de entrega da filial. |
| `is_within_cutoff_time` | boolean | Entrou dentro do horário de corte. |
| `observation` | string | Observação. |
| `current_subsidiary_id` | integer | Filial onde o pedido está agora (transferências). O pedido sempre pertence à filial de origem. |
| `customer` | object | Cliente: id, name, cpf_cnpj. |
| `destination` | object | Destino: city, state, zipcode, ibge, neighborhood. |
| `carrier` | object | Transportadora: id e name. |
| `route` | object | Rota: id e name. |
| `invoices` | array | Notas fiscais: type, number, serie, key, value, currency, issued_at. |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `order-movements` — Movimentações dos pedidos

Cada evento de status do pedido (coleta, rota, entrega, ocorrência), com localização e comprovante.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador da movimentação. |
| `order_id` | integer | Pedido (id em orders). |
| `order_number` | string | Número do pedido. |
| `order_external_reference` | string | UUID público do pedido. |
| `code` | integer | Código do evento. |
| `description` | string | Descrição do evento. |
| `sub_description` | string | Detalhe do evento. |
| `is_partial` | boolean | Entrega parcial. |
| `observation` | string | Observação. |
| `file_url` | string | Comprovante (foto ou arquivo). |
| `latitude` | number | Latitude. |
| `longitude` | number | Longitude. |
| `temperature` | number | Temperatura registrada. |
| `date` | datetime | Quando o evento aconteceu. |
| `user_id` | integer | Usuário que registrou. |
| `shipment_order_id` | integer | Vínculo do pedido com o romaneio. |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `shipments` — Romaneios

Romaneios da filial, com motorista, veículo, distância, KM, frete e a sequência dos pedidos.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador do romaneio. |
| `external_reference` | string | Referência externa. |
| `trip_number` | integer | Número da viagem. |
| `date` | datetime | Data do romaneio. |
| `status` | string | Status do romaneio. |
| `driver` | object | Motorista: id e name. |
| `driver_support` | object | Ajudante: id e name. |
| `vehicle` | object | Veículo: id e plate. |
| `distance_in_meters` | integer | Distância planejada. |
| `duration_in_seconds` | integer | Duração planejada. |
| `start_km` | integer | KM inicial. |
| `end_km` | integer | KM final. |
| `total_orders` | integer | Pedidos no romaneio. |
| `total_success` | integer | Entregues. |
| `total_errors` | integer | Com problema. |
| `predicted_freight` | number | Frete previsto. |
| `predicted_freight_currency` | string | Moeda do frete previsto. |
| `paid_freight` | number | Frete pago. |
| `paid_freight_currency` | string | Moeda do frete pago. |
| `paid_freight_at` | datetime | Pagamento do frete. |
| `shipment_closing_id` | integer | Fechamento (id em shipment-closings). |
| `transfered_to_id` | integer | Romaneio para onde foi transferido. |
| `started_at` | datetime | Início. |
| `finished_at` | datetime | Fim. |
| `observation` | string | Observação. |
| `orders` | array | Pedidos do romaneio: order_id, sequence, type, status, arrived_at, departed_at, delivery_prevision, predicted_freight, manual_freight. |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `shipment-movements` — Movimentações dos romaneios

Eventos do romaneio registrados pelo motorista ou pela operação.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador da movimentação. |
| `shipment_id` | integer | Romaneio (id em shipments). |
| `description` | string | Descrição do evento. |
| `observation` | string | Observação. |
| `file_url` | string | Arquivo anexado. |
| `latitude` | number | Latitude. |
| `longitude` | number | Longitude. |
| `user_id` | integer | Usuário que registrou. |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `shipment-closings` — Fechamentos

Fechamentos de frete dos romaneios.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador do fechamento. |
| `external_reference` | string | Referência externa. |
| `name` | string | Nome do fechamento. |
| `status` | string | Status. |
| `total_shipments` | integer | Romaneios no fechamento. |
| `total_expenses` | integer | Despesas. |
| `total_discounts` | integer | Descontos. |
| `total_amount` | number | Valor total. |
| `currency` | string | Moeda. |
| `paid_at` | datetime | Pagamento. |
| `paid_by_user_id` | integer | Quem pagou. |
| `canceled_at` | datetime | Cancelamento. |
| `cancellation_reason` | string | Motivo do cancelamento. |
| `shipment_ids` | array | Romaneios do fechamento (ids em shipments). |
| `nfse_ids` | array | NFS-e do fechamento (ids em nfses). |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `carrier-invoices` — Faturas de frete

Faturas das transportadoras, com conferência, divergências e os CT-e cobrados.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador da fatura. |
| `external_reference` | string | Referência externa. |
| `carrier_id` | integer | Transportadora. |
| `status` | string | Status da conferência. |
| `number` | string | Número da fatura. |
| `serie` | string | Série. |
| `document_type` | string | Tipo do documento. |
| `carrier_cnpj` | string | CNPJ da transportadora. |
| `carrier_name` | string | Nome da transportadora. |
| `issued_at` | datetime | Emissão. |
| `due_at` | datetime | Vencimento. |
| `total_value` | number | Valor da fatura. |
| `currency` | string | Moeda. |
| `discount_deadline_at` | datetime | Prazo do desconto. |
| `discount_value` | number | Valor do desconto. |
| `icms_value` | number | ICMS. |
| `iss_value` | number | ISS. |
| `conferred_at` | datetime | Conferência. |
| `has_divergence` | boolean | Tem divergência. |
| `items_total_value` | number | Soma dos itens. |
| `expected_value` | number | Valor esperado. |
| `cte_value` | number | Valor dos CT-e. |
| `divergence_value` | number | Divergência. |
| `cte_divergence_value` | number | Divergência contra os CT-e. |
| `divergent_items_count` | integer | Itens divergentes. |
| `unmatched_items_count` | integer | Itens sem correspondência. |
| `reviewed_at` | datetime | Revisão. |
| `items` | array | Itens: id, cte_number, cte_serie, cte_issued_at, charged_value, currency, sender_cnpj, recipient_cnpj, issuer_cnpj, is_return. |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `nfses` — NFS-e

Notas fiscais de serviço da filial.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador da NFS-e. |
| `number` | string | Número. |
| `origin` | string | Origem. |
| `city_hall` | string | Prefeitura. |
| `verification_code` | string | Código de verificação. |
| `issued_at` | datetime | Emissão. |
| `competence` | datetime | Competência. |
| `status` | string | Status. |
| `services_value` | number | Valor dos serviços. |
| `iss_value` | number | ISS. |
| `iss_withheld` | string | ISS retido. |
| `iss_rate` | string | Alíquota. |
| `service_code` | string | Código do serviço. |
| `tax_base` | number | Base de cálculo. |
| `net_value` | number | Valor líquido. |
| `description` | string | Discriminação. |
| `service_location` | string | Local da prestação. |
| `provider` | object | Prestador: cnpj e name. |
| `taker` | object | Tomador: cnpj e name. |
| `shipment_closing_id` | integer | Fechamento ligado (id em shipment-closings). |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `ctes` — CT-e

Conhecimentos de transporte da filial, com valores, origem, destino e eventos.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador do documento no Meu Rastreio. |
| `external_reference` | string | Referência externa do documento. |
| `status` | string | Status do documento no Meu Rastreio. |
| `emission_type` | string | Tipo de emissão (normal ou contingência). |
| `serie` | integer | Série. |
| `number` | integer | Número. |
| `access_key` | string | Chave de acesso de 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. |
| `issued_at` | datetime | Emissão. |
| `authorized_at` | datetime | Autorização. |
| `canceled_at` | datetime | Cancelamento. |
| `xml_url` | string | Link do XML. |
| `pdf_url` | string | Link do PDF, quando houver. |
| `events` | array | Eventos do documento: type, sequence, status, justification, protocol, c_stat, status_reason, registered_at, xml_url, pdf_url. |
| `environment` | string | Ambiente (produção ou homologação). |
| `origin` | string | Origem: emitido no Meu Rastreio, importado ou baixado da SEFAZ. |
| `emitter_cnpj` | string | CNPJ do emitente. |
| `emitter_name` | string | Nome do emitente. |
| `cfop` | string | CFOP. |
| `taker` | string | Tomador do serviço. |
| `origin_city` | string | Cidade de origem. |
| `origin_state` | string | UF de origem. |
| `origin_ibge` | string | IBGE de origem. |
| `destination_city` | string | Cidade de destino. |
| `destination_state` | string | UF de destino. |
| `destination_ibge` | string | IBGE de destino. |
| `total_service_value` | number | Valor da prestação. |
| `receivable_value` | number | Valor a receber. |
| `cargo_value` | number | Valor da carga. |
| `icms_value` | number | ICMS. |
| `total_taxes_value` | number | Tributos. |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `mdfes` — MDF-e

Manifestos da filial, com carga, UFs e o romaneio ligado.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador do documento no Meu Rastreio. |
| `external_reference` | string | Referência externa do documento. |
| `status` | string | Status do documento no Meu Rastreio. |
| `emission_type` | string | Tipo de emissão (normal ou contingência). |
| `serie` | integer | Série. |
| `number` | integer | Número. |
| `access_key` | string | Chave de acesso de 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. |
| `issued_at` | datetime | Emissão. |
| `authorized_at` | datetime | Autorização. |
| `canceled_at` | datetime | Cancelamento. |
| `xml_url` | string | Link do XML. |
| `pdf_url` | string | Link do PDF, quando houver. |
| `events` | array | Eventos do documento: type, sequence, status, justification, protocol, c_stat, status_reason, registered_at, xml_url, pdf_url. |
| `environment` | string | Ambiente (produção ou homologação). |
| `origin` | string | Origem: emitido no Meu Rastreio, importado ou baixado da SEFAZ. |
| `emitter_cnpj` | string | CNPJ do emitente. |
| `emitter_name` | string | Nome do emitente. |
| `closed_at` | datetime | Encerramento. |
| `origin_state` | string | UF de origem. |
| `destination_state` | string | UF de destino. |
| `trip_start_at` | datetime | Início da viagem. |
| `cargo_value` | number | Valor da carga. |
| `cargo_unit` | string | Unidade da carga. |
| `cargo_quantity` | number | Quantidade da carga. |
| `shipment_id` | integer | Romaneio ligado (id em shipments). |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `ciots` — CIOT

Operações de transporte declaradas, com frete, rotas, pedágios e histórico.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador do CIOT. |
| `external_reference` | string | Referência externa. |
| `status` | string | Status. |
| `status_reason` | string | Motivo do status. |
| `environment` | string | Ambiente. |
| `operation_type` | string | Tipo de operação. |
| `ciot` | string | Número do CIOT formatado. |
| `number` | string | Número. |
| `verification_code` | string | Código de verificação. |
| `transporter_cpf_cnpj` | string | CPF/CNPJ do transportador. |
| `trip_start_at` | datetime | Início da viagem. |
| `trip_end_at` | datetime | Fim da viagem. |
| `declared_at` | datetime | Declaração. |
| `canceled_at` | datetime | Cancelamento. |
| `cancel_reason` | string | Motivo do cancelamento. |
| `closed_at` | datetime | Encerramento. |
| `freight_value` | number | Valor do frete. |
| `provider` | string | Provedor que emitiu. |
| `distance_km` | number | Distância em km. |
| `mdfe_id` | integer | MDF-e ligado (id em mdfes). |
| `routes` | array | Rotas: id, name, toll_value, map_url, selected e tolls (name, concessionaire, highway, state, city, value). |
| `shipment_external_references` | array | Referências externas dos romaneios. |
| `mdfe_external_reference` | string | Referência externa do MDF-e. |
| `history` | array | Histórico: type, source, user, integration, route_name, route_mode, at. |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

### `checkouts` — Checkouts

Cobranças geradas para pedidos (PIX, cartão), com pagamento e taxas.

| campo | tipo | descrição |
|---|---|---|
| `id` | integer | Identificador do checkout. |
| `external_reference` | string | Referência externa. |
| `status` | string | Status. |
| `payment_method` | string | Meio de pagamento. |
| `provider` | string | Provedor de pagamento. |
| `amount_in_cents` | integer | Valor em centavos. |
| `fees_in_cents` | integer | Taxas em centavos. |
| `currency` | string | Moeda. |
| `installments` | integer | Parcelas. |
| `transaction_id` | string | Transação no provedor. |
| `nsu` | string | NSU. |
| `authorization_code` | string | Código de autorização. |
| `card_last4` | string | Final do cartão. |
| `return_code` | string | Código de retorno. |
| `return_message` | string | Mensagem de retorno. |
| `paid_at` | datetime | Pagamento. |
| `expires_at` | datetime | Expiração. |
| `created_by_user_id` | integer | Quem gerou. |
| `order_ids` | array | Pedidos cobrados (ids em orders). |
| `created_at` | datetime | Quando o registro foi criado. |
| `updated_at` | datetime | Última alteração. É o campo usado na paginação e no incremental. |

## Contato

- Suporte: suporte@meurastreio.app
- Comercial: oi@meurastreio.app