API atual/Referência completa/Monitoramento de entregas

Relatórios de frete

Três relatórios de leitura: pontualidade por transportadora, margem entre frete cobrado e pago, e cobertura da tabela de contingência.

Os relatórios respondem a perguntas de gestão: as transportadoras estão cumprindo o prazo? Estou ganhando ou perdendo dinheiro com o frete? Se a transportadora ficar fora do ar, para quais regiões a loja ainda consegue cotar? Todos aceitam view_shipping ou manage_shipping.

Prazo prometido x realizado

Por transportadora, no período: quantas remessas foram entregues, qual percentual chegou até a data prometida e quanto tempo levou em média do envio à entrega. Só entram remessas que têm data de envio e de entrega.

GET/api/v1/admin/shipping/sla-reportAdmin

Relatório de prazo por transportadora

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

fromstring

Primeiro dia (inclusive), AAAA-MM-DD, contado pela data de entrega. Padrão: 90 dias atrás.

tostring

Último dia (inclusive), AAAA-MM-DD. Padrão: agora.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/sla-report?from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório

json

{
  "carriers": [
    {
      "carrier": "Correios",
      "shipments": 120,
      "on_time_pct": 91.7,
      "avg_transit_days": 3.8
    }
  ]
}

Campos da resposta

carriersarray

Uma linha por transportadora, da que mais entregou para a que menos. [] quando não há remessas.

carrierstring

Transportadora; desconhecido quando a remessa não informa.

shipmentsinteger

Remessas entregues no período.

on_time_pctnumber

Percentual entregue até a data prometida. null se nenhum pedido tinha data prometida.

avg_transit_daysnumber

Média de dias entre envio e entrega.

Frete cobrado x pago

Agrupa os pedidos do período por método de envio (padrão) ou por área de tarifa e soma o frete cobrado do cliente e o frete pago à transportadora. Pedidos cancelados, falhos, anulados e com chargeback ficam de fora. Todos os valores são em centavos.

GET/api/v1/admin/shipping/margin-reportAdmin

Relatório de margem de frete

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

fromstring

Início do período, data ou data-hora ISO 8601 (2026-01-01 ou 2026-01-01T00:00:00-03:00), pela data de criação do pedido. Omitido = sem limite.

tostring

Fim do período, no mesmo formato. Omitido = sem limite.

group_bystring

areamethod

area agrupa pela área de tarifa do CEP de entrega (sem área se nenhuma cobrir). Qualquer outro valor agrupa por método de envio.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/margin-report?group_by=area&from=2026-01-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório

json

{
  "rows": [
    {
      "key": "Entrega Expressa",
      "orders": 10171,
      "charged_cents": 9194030,
      "paid_cents": 0,
      "margin_cents": 9194030
    },
    {
      "key": "PAC",
      "orders": 10276,
      "charged_cents": 8869200,
      "paid_cents": 0,
      "margin_cents": 8869200
    }
  ]
}

Campos da resposta

rowsarray

Uma linha por grupo, do maior frete cobrado para o menor. [] sem pedidos.

keystring

Nome do método (desconhecido se o pedido não o guardou) ou da área.

ordersinteger

Quantidade de pedidos no grupo.

charged_centsinteger

Frete cobrado dos clientes, em centavos.

paid_centsinteger

Frete pago, em centavos. É uma estimativa: a mediana das cotações registradas do mesmo método, aplicada a cada pedido. Fica 0 quando a loja não tem cotações registradas.

margin_centsinteger

charged_cents menos paid_cents.

Cobertura da contingência

Quando uma transportadora em tempo real não responde, a loja pode cotar com uma tabela de contingência aprendida das cotações anteriores: um preço por área de tarifa e faixa de peso. Este relatório mostra, por área, as faixas já aprendidas. Uma área com bands: [] é uma lacuna: sem a transportadora, não há preço de contingência para ela.

GET/api/v1/admin/shipping/fallback-coverageAdmin

Cobertura da tabela de contingência

Exige view_shipping ou manage_shipping. Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/fallback-coverage" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobertura

json

{
  "areas": [
    {
      "rate_area_id": "32ffd693-895b-47a7-832a-ae6794de249e",
      "name": "Centro-Oeste",
      "bands": [
        {
          "weight_from_g": 0,
          "weight_to_g": 1000,
          "cost_cents": 2490,
          "sample_count": 37
        }
      ]
    },
    {
      "rate_area_id": "1cb5ac9d-4ae2-4824-87ee-a26fde7240c8",
      "name": "Nordeste",
      "bands": []
    }
  ]
}

Campos da resposta

areasarray

Todas as áreas de tarifa da loja, por nome.

rate_area_iduuid

Id da área.

namestring

Nome da área.

bandsarray

Faixas de peso aprendidas. [] quando não há.

weight_from_ginteger

Início da faixa, em gramas.

weight_to_ginteger

Fim da faixa, em gramas.

cost_centsinteger

Preço de contingência da faixa, em centavos.

sample_countinteger

Quantas cotações sustentam o valor.

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping","view_shipping"]}`
500	`from`/`to` em formato que o banco não entende; falha interna	`{"error":"failed to build margin report","detail":"o valor \"ontem\" não é um timestamp with time zone válido..."}` / `{"error":"sla_report_failed","detail":"..."}` / `{"error":"failed to load coverage","detail":"..."}`

Veja também

API atual/Referência completa/Monitoramento de entregas

Relatórios de frete

Três relatórios de leitura: pontualidade por transportadora, margem entre frete cobrado e pago, e cobertura da tabela de contingência.

Prazo prometido x realizado

GET/api/v1/admin/shipping/sla-reportAdmin

Relatório de prazo por transportadora

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

fromstring

Primeiro dia (inclusive), AAAA-MM-DD, contado pela data de entrega. Padrão: 90 dias atrás.

tostring

Último dia (inclusive), AAAA-MM-DD. Padrão: agora.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/sla-report?from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório

json

{
  "carriers": [
    {
      "carrier": "Correios",
      "shipments": 120,
      "on_time_pct": 91.7,
      "avg_transit_days": 3.8
    }
  ]
}

Campos da resposta

carriersarray

Uma linha por transportadora, da que mais entregou para a que menos. [] quando não há remessas.

carrierstring

Transportadora; desconhecido quando a remessa não informa.

shipmentsinteger

Remessas entregues no período.

on_time_pctnumber

Percentual entregue até a data prometida. null se nenhum pedido tinha data prometida.

avg_transit_daysnumber

Média de dias entre envio e entrega.

Frete cobrado x pago

GET/api/v1/admin/shipping/margin-reportAdmin

Relatório de margem de frete

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

fromstring

Início do período, data ou data-hora ISO 8601 (2026-01-01 ou 2026-01-01T00:00:00-03:00), pela data de criação do pedido. Omitido = sem limite.

tostring

Fim do período, no mesmo formato. Omitido = sem limite.

group_bystring

areamethod

area agrupa pela área de tarifa do CEP de entrega (sem área se nenhuma cobrir). Qualquer outro valor agrupa por método de envio.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/margin-report?group_by=area&from=2026-01-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório

json

{
  "rows": [
    {
      "key": "Entrega Expressa",
      "orders": 10171,
      "charged_cents": 9194030,
      "paid_cents": 0,
      "margin_cents": 9194030
    },
    {
      "key": "PAC",
      "orders": 10276,
      "charged_cents": 8869200,
      "paid_cents": 0,
      "margin_cents": 8869200
    }
  ]
}

Campos da resposta

rowsarray

Uma linha por grupo, do maior frete cobrado para o menor. [] sem pedidos.

keystring

Nome do método (desconhecido se o pedido não o guardou) ou da área.

ordersinteger

Quantidade de pedidos no grupo.

charged_centsinteger

Frete cobrado dos clientes, em centavos.

paid_centsinteger

Frete pago, em centavos. É uma estimativa: a mediana das cotações registradas do mesmo método, aplicada a cada pedido. Fica 0 quando a loja não tem cotações registradas.

margin_centsinteger

charged_cents menos paid_cents.

Cobertura da contingência

GET/api/v1/admin/shipping/fallback-coverageAdmin

Cobertura da tabela de contingência

Exige view_shipping ou manage_shipping. Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/fallback-coverage" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobertura

json

{
  "areas": [
    {
      "rate_area_id": "32ffd693-895b-47a7-832a-ae6794de249e",
      "name": "Centro-Oeste",
      "bands": [
        {
          "weight_from_g": 0,
          "weight_to_g": 1000,
          "cost_cents": 2490,
          "sample_count": 37
        }
      ]
    },
    {
      "rate_area_id": "1cb5ac9d-4ae2-4824-87ee-a26fde7240c8",
      "name": "Nordeste",
      "bands": []
    }
  ]
}

Campos da resposta

areasarray

Todas as áreas de tarifa da loja, por nome.

rate_area_iduuid

Id da área.

namestring

Nome da área.

bandsarray

Faixas de peso aprendidas. [] quando não há.

weight_from_ginteger

Início da faixa, em gramas.

weight_to_ginteger

Fim da faixa, em gramas.

cost_centsinteger

Preço de contingência da faixa, em centavos.

sample_countinteger

Quantas cotações sustentam o valor.

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping","view_shipping"]}`
500	`from`/`to` em formato que o banco não entende; falha interna	`{"error":"failed to build margin report","detail":"o valor \"ontem\" não é um timestamp with time zone válido..."}` / `{"error":"sla_report_failed","detail":"..."}` / `{"error":"failed to load coverage","detail":"..."}`