API de BI

A API de BI entrega os dados de uma filial para ferramentas como Power BI, Looker, Metabase, planilhas, ETLs e data lakes. Ela é somente leitura: todas as rotas são GET e nada que você chame altera a operação.

• Cada recurso (pedidos, romaneios, CT-e…) é uma lista paginada por data de alteração.
• Você busca o que mudou num intervalo de tempo e grava no seu banco. Na próxima execução, busca só o que mudou depois.
• Os limites de uso protegem a operação: o BI nunca deixa o sistema lento para quem está trabalhando nele.
• Opcionalmente, o Meu Rastreio envia todo dia um arquivo Parquet por recurso, por FTP ou e-mail.

A API de BI é ativada pela equipe do Meu Rastreio. O caminho é:

1. Preencha o formulário de solicitação com a filial, os recursos que o BI precisa e os IPs fixos de onde as chamadas vão sair. Ele abre um chamado direto para a nossa equipe.
2. A equipe instala a extensão na filial, libera os recursos e os IPs e gera o token.
3. Você recebe o token (ele é mostrado uma única vez) e já pode fazer a primeira chamada.

Envie o token no cabeçalho Authorization, no formato Bearer. O cabeçalho x-api-token também é aceito.

Authorization: Bearer mrbi_6b3f0c2e-...-9d1a_4f7c...e21b

• O token tem o formato mrbi_<identificador da instalação>_<segredo>. Guarde-o como senha: em cofre de segredos, nunca no código nem em planilha compartilhada.
• Gerar um token novo invalida o anterior na hora. Revogar faz todas as chamadas responderem 401.
• Além do token, o IP de origem precisa estar na lista liberada (IP único ou faixa CIDR, IPv4 ou IPv6). Token certo com IP fora da lista responde 403 IP_NOT_ALLOWED.
• Só HTTPS. Nunca envie o token na URL.
• Muitos tokens inválidos seguidos do mesmo IP (20 em 10 minutos) bloqueiam esse IP por 1 hora.

A raiz da API confirma que o token funciona e mostra o que está liberado para ele: recursos, limites e quanto resta da cota do dia.

curl -s "https://painel.meurastreio.app/api/bi/v1" \
  -H "Authorization: Bearer mrbi_SEU_TOKEN"

{
  "subsidiary_id": 12,
  "time_zone": "America/Sao_Paulo",
  "resources": ["orders", "order-movements", "shipments"],
  "limits": {
    "max_concurrency": 1,
    "burst": 10,
    "per_minute": 20,
    "per_day": 2000,
    "max_per_page": 200,
    "max_window_days": 31
  },
  "remaining_today": 1987
}

Depois, peça um recurso. Exemplo: pedidos alterados no dia 3 de novembro, no horário de Brasília.

curl -s "https://painel.meurastreio.app/api/bi/v1/orders?updated_from=2026-11-03T00:00:00-03:00&updated_to=2026-11-04T00:00:00-03:00&per_page=100" \
  -H "Authorization: Bearer mrbi_SEU_TOKEN"

{
  "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"
  }
}

Cada recurso é liberado individualmente na instalação. Os que dependem de um módulo também exigem esse módulo no plano da empresa. Abra cada um para ver todos os campos.

Toda lista devolve os registros que mudaram (campo updated_at) dentro de uma janela, do mais antigo para o mais novo.

A resposta não traz total nem número de página. Ela traz has_more, que diz se há mais registros, e next_cursor, que você devolve para buscar a próxima página:

curl -s "https://painel.meurastreio.app/api/bi/v1/orders?cursor=eyJmIjoiMjAyNi0xMS0wM1QwMzowMDowMC4wMDBaIi...&per_page=100" \
  -H "Authorization: Bearer mrbi_SEU_TOKEN"

1. Chame com updated_from, updated_to e per_page.
2. Grave os registros de data.
3. Enquanto has_more for true, chame de novo só com cursor e per_page.
4. Quando has_more for false, a janela acabou.

Fixe o updated_to no começo da leitura (por exemplo, o horário em que o job começou). Se você deixar em branco, cada consulta nova usa um "agora" diferente.

O jeito recomendado de manter o BI em dia:

1. Guarde, por recurso, o fim da última janela lida com sucesso.
2. Na próxima execução, use esse valor como updated_from e o horário atual como updated_to.
3. Grave com upsert usando id como chave: o mesmo registro pode voltar em janelas seguintes sempre que for alterado.
4. Leia um recurso de cada vez: o token aceita uma requisição por vez.

ultima_execucao = carregar_marca("orders")          # ex.: "2026-11-03T10:00:00.000Z"
agora = datetime.now(timezone.utc).isoformat()

for pedido in fetch_all("orders", ultima_execucao, agora):
    upsert("pedidos", chave=pedido["id"], valores=pedido)

salvar_marca("orders", agora)

Uma execução a cada 15 ou 30 minutos mantém o BI praticamente em tempo real gastando poucas dezenas de requisições por dia.

Os limites existem para que a leitura do BI nunca concorra com a operação. Estes são os valores padrão; a equipe do Meu Rastreio pode ajustá-los por instalação, e a raiz da API mostra os valores que valem para o seu token.

Toda resposta aceita traz o quanto ainda resta:

Passou do limite, a resposta é 429 e diz quanto esperar:

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
}

Boas práticas

• Não paralelize: uma requisição de cada vez, recurso depois de recurso.
• Use per_page=200 para fazer menos chamadas.
• Agende o job; não chame a cada clique de um painel.
• Use janelas curtas no incremental (horas, não semanas).
• Para volumes grandes, use a exportação em Parquet.

O corpo de erro sempre traz code, para o seu código decidir o que fazer, e message, para leitura de pessoas. Alguns erros trazem campos extras, como field, max ou retry_after.

• 401 e 403: pare e avise uma pessoa. Insistir não resolve.
• 422: corrija os parâmetros.
• 429: espere o Retry-After e continue de onde parou.
• 503: diminua a janela ou o per_page (QUERY_TIMEOUT) ou tente de novo depois de alguns segundos (SERVICE_UNAVAILABLE).

Além da API, a instalação pode enviar todo dia um arquivo Apache Parquet por recurso, com tudo o que mudou no dia anterior. Parquet é um formato colunar, compacto e tipado, que Power BI, Excel (Power Query), pandas, DuckDB, Spark e data lakes leem direto.

• Roda uma vez por dia, no horário combinado, com os registros alterados no dia anterior (fuso da empresa).
• Um arquivo por recurso liberado: orders_2026-11-03.parquet, shipments_2026-11-03.parquet… Recurso sem alteração no dia não gera arquivo.
• FTP: os arquivos vão para a pasta combinada, dentro de uma subpasta do dia (/bi/2026-11-03/).
• E-mail: os arquivos vão anexados, até 25 MB no total. Acima disso o e-mail chega sem anexos, e o recomendado é passar para FTP.
• Não conta no limite de requisições da API.

import json

import pandas as pd

pedidos = pd.read_parquet("orders_2026-11-03.parquet")
pedidos["customer"] = pedidos["customer"].map(lambda texto: json.loads(texto) if texto else None)
print(pedidos[["id", "order_number", "service_status", "finished_at"]].head())

SELECT service_status, count(*) AS pedidos, sum(total_freight) AS frete
FROM read_parquet('exportacao/2026-11-*/orders_*.parquet')
GROUP BY service_status
ORDER BY pedidos DESC;

No Power BI, use Obter dados > Pasta apontando para a pasta do FTP sincronizada, e combine os arquivos do mesmo recurso. Como no incremental pela API, trate id como chave: o mesmo registro aparece de novo no arquivo de cada dia em que for alterado.

A API foi feita para o incremental. Para trazer meses ou anos de histórico na primeira carga, o Meu Rastreio gera os arquivos Parquet do passado e envia pelo mesmo destino da exportação diária. Depois, siga pela API.

1. Peça no formulário de acesso ou ao suporte, informando desde quando precisa do histórico.
2. Escolha o tamanho de cada arquivo: um por mês, por semana ou por dia. Mês é o mais prático para anos de histórico; dia, para manter o mesmo formato da exportação diária.
3. A geração roda em segundo plano, um período de um recurso por vez, sem pesar na operação. Nossa equipe acompanha o progresso e avisa quando terminar.

• Cada registro entra no período da sua última alteração (updated_at), como na API. Somando todos os arquivos, nenhum registro se repete; um pedido de 2024 alterado ontem aparece no período de ontem.
• A carga vai até o dia anterior. Dali em diante valem a exportação diária e a API.
• Por e-mail, chega um e-mail por arquivo, com o mesmo limite de 25 MB. Para anos de histórico, prefira FTP.
• As colunas e os tipos são os mesmos da exportação diária.
• Para algo pontual, os relatórios em Excel do painel continuam disponíveis: pedidos e romaneios podem ser exportados por período direto no Meu Rastreio.

Leitura de um recurso inteiro dentro de uma janela, respeitando o 429.

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"])

const BASE_URL = "https://painel.meurastreio.app/api/bi/v1";
const TOKEN = "mrbi_SEU_TOKEN";
const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function* fetchAll(resource, updatedFrom, updatedTo) {
  let params = new URLSearchParams({ updated_from: updatedFrom, updated_to: updatedTo, per_page: "200" });

  while (true) {
    const response = await fetch(`${BASE_URL}/${resource}?${params}`, {
      headers: { Authorization: `Bearer ${TOKEN}` },
    });

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

    if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

    const body = await response.json();
    yield* body.data;

    if (!body.pagination.has_more) return;

    params = new URLSearchParams({ cursor: body.pagination.next_cursor, per_page: "200" });
  }
}

for await (const shipment of fetchAll("shipments", "2026-11-01T00:00:00-03:00", "2026-11-04T00:00:00-03:00")) {
  console.log(shipment.id, shipment.status);
}

Escolha os recursos e informe os IPs. A solicitação abre um chamado para a equipe do Meu Rastreio, que ativa o módulo, libera o acesso e envia o token.

Ativação, novos recursos, mudança de IP, troca de token ou ajuste de limites: [email protected]. Para contratar: [email protected].