API atual/Referência completa/Monitoramento de entregas

Radar de entregas

Lista os pedidos com entrega em risco ou atrasada, avisa o cliente (com voucher opcional), dispensa alertas e mostra a pontualidade por transportadora.

O radar compara, a cada hora, a data de entrega prometida de cada pedido em andamento (pendente, em processamento, pago, enviado, em espera ou em reposição) com o que de fato aconteceu, e abre um alerta idempotente quando o pedido está em risco ou atrasado. A equipe de atendimento usa a lista para agir antes de o cliente reclamar.

Listar alertas

Devolve os alertas open e notified, do mais novo para o mais antigo, 50 por página.

GET/api/v1/admin/shipping/delivery-radarAdmin

Lista os alertas do radar de entregas

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

statestring

at_risklate

Filtra pelo risco. Outro valor é ignorado e devolve todos.

pageintegerpadrão: 1

Página, a partir de 1. Cada página tem 50 itens.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/delivery-radar?state=late" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Alertas retornados

json

{
  "alerts": [
    {
      "id": "e7fc7f17-9eb9-4bad-ada5-10f9c667949d",
      "order_id": "2ad4b8db-8268-4355-a33d-1377443843d0",
      "order_number": "PEDIDO-20261009-0002",
      "customer_name": "Maria Souza",
      "carrier": "Correios",
      "promised_delivery_at": "2026-10-24T02:59:59+00",
      "risk_state": "at_risk",
      "cause": "sem movimentação",
      "status": "open",
      "voucher_code": null
    }
  ],
  "total": 1
}

Campos da resposta

alertsarray

Alertas da página. null quando não há nenhum.

iduuid

Id do alerta.

order_iduuid

Pedido.

order_numberstring

Número do pedido.

customer_namestring

Nome do cliente.

carrierstring

Transportadora da primeira remessa do pedido. Vazio se ainda não há remessa.

promised_delivery_atstring

Data prometida, com fuso (AAAA-MM-DDTHH:MM:SS+00).

risk_statestring

at_risklate

at_risk ou late.

causestring

Motivo do alerta, em português.

statusstring

opennotified

open ou notified.

voucher_codestring

Código do voucher já emitido para este alerta. null se não houve.

totalinteger

Total de alertas que atendem ao filtro, em todas as páginas.

Avisar o cliente

Marca o alerta como notified e dispara o aviso de atraso ao comprador (e-mail e WhatsApp, quando configurados). Com with_voucher: true, emite um voucher de uso único, válido por 30 dias, e o devolve em voucher_code. Tipo e valor vêm da configuração da loja; sem configuração, é um voucher de 10%. O voucher é gerado antes do aviso e gravado no alerta: se você avisar de novo, o mesmo código é reaproveitado.

POST/api/v1/admin/shipping/delivery-radar/{alertId}/notifyAdmin

Avisa o cliente de um alerta do radar

Exige manage_shipping.

Parâmetros de caminho

alertIduuidobrigatório

Id do alerta.

Corpo da requisição

with_voucherbooleanpadrão: false

Emite (ou reaproveita) o voucher de compensação. O corpo é opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping/delivery-radar/$ALERT_ID/notify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "with_voucher": true
  }'

Resposta

200Cliente avisado

json

{
  "status": "notified",
  "voucher_code": "ATRASO-7K2M9Q"
}

Campos da resposta

statusstring

Sempre notified.

voucher_codestring

Código do voucher, ou null se não foi emitido (sem with_voucher e sem voucher emitido antes para o alerta).

Dispensar um alerta

Marca o alerta como dismissed: ele sai do radar. Use para falsos positivos ou casos já resolvidos por outro meio. Não avisa o cliente.

POST/api/v1/admin/shipping/delivery-radar/{alertId}/dismissAdmin

Dispensa um alerta do radar

Exige manage_shipping. Sem corpo.

Parâmetros de caminho

alertIduuidobrigatório

Id do alerta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping/delivery-radar/$ALERT_ID/dismiss" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Alerta dispensado

json

{
  "status": "dismissed"
}

Pontualidade por transportadora

Para as remessas entregues nos últimos days dias, de pedidos que tinham data prometida, calcula o percentual entregue dentro do prazo e o atraso médio.

GET/api/v1/admin/shipping/delivery-radar/slaAdmin

Pontualidade por transportadora

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

daysintegerpadrão: 30

Janela em dias, contada para trás a partir de agora. Zero ou negativo vira 30.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/delivery-radar/sla?days=30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pontualidade

json

{
  "carriers": [
    {
      "carrier": "Correios",
      "total": 42,
      "on_time_pct": 88.1,
      "avg_delay_days": 0.6
    }
  ]
}

Campos da resposta

carriersarray

Uma linha por transportadora, da que mais entregou para a que menos. null quando não há entregas no período.

carrierstring

Nome da transportadora; desconhecido quando a remessa não informa.

totalinteger

Remessas entregues no período.

on_time_pctnumber

Percentual entregue até a data prometida (0 a 100).

avg_delay_daysnumber

Atraso médio em dias, contando 0 para as entregues no prazo.

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"]}`
400	Avisar um alerta que não existe, ou falha ao emitir o voucher	`{"error":"notify_failed","detail":"alert not found"}`
500	`alertId` que não é UUID; falha interna	`{"error":"dismiss_failed","detail":"..."}` / `{"error":"radar_failed","detail":"..."}` / `{"error":"sla_failed","detail":"..."}`

As ações exigem manage_shipping; as leituras aceitam view_shipping.

Veja também

API atual/Referência completa/Monitoramento de entregas

Radar de entregas

Lista os pedidos com entrega em risco ou atrasada, avisa o cliente (com voucher opcional), dispensa alertas e mostra a pontualidade por transportadora.

Listar alertas

Devolve os alertas open e notified, do mais novo para o mais antigo, 50 por página.

GET/api/v1/admin/shipping/delivery-radarAdmin

Lista os alertas do radar de entregas

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

statestring

at_risklate

Filtra pelo risco. Outro valor é ignorado e devolve todos.

pageintegerpadrão: 1

Página, a partir de 1. Cada página tem 50 itens.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/delivery-radar?state=late" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Alertas retornados

json

{
  "alerts": [
    {
      "id": "e7fc7f17-9eb9-4bad-ada5-10f9c667949d",
      "order_id": "2ad4b8db-8268-4355-a33d-1377443843d0",
      "order_number": "PEDIDO-20261009-0002",
      "customer_name": "Maria Souza",
      "carrier": "Correios",
      "promised_delivery_at": "2026-10-24T02:59:59+00",
      "risk_state": "at_risk",
      "cause": "sem movimentação",
      "status": "open",
      "voucher_code": null
    }
  ],
  "total": 1
}

Campos da resposta

alertsarray

Alertas da página. null quando não há nenhum.

iduuid

Id do alerta.

order_iduuid

Pedido.

order_numberstring

Número do pedido.

customer_namestring

Nome do cliente.

carrierstring

Transportadora da primeira remessa do pedido. Vazio se ainda não há remessa.

promised_delivery_atstring

Data prometida, com fuso (AAAA-MM-DDTHH:MM:SS+00).

risk_statestring

at_risklate

at_risk ou late.

causestring

Motivo do alerta, em português.

statusstring

opennotified

open ou notified.

voucher_codestring

Código do voucher já emitido para este alerta. null se não houve.

totalinteger

Total de alertas que atendem ao filtro, em todas as páginas.

Avisar o cliente

POST/api/v1/admin/shipping/delivery-radar/{alertId}/notifyAdmin

Avisa o cliente de um alerta do radar

Exige manage_shipping.

Parâmetros de caminho

alertIduuidobrigatório

Id do alerta.

Corpo da requisição

with_voucherbooleanpadrão: false

Emite (ou reaproveita) o voucher de compensação. O corpo é opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping/delivery-radar/$ALERT_ID/notify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "with_voucher": true
  }'

Resposta

200Cliente avisado

json

{
  "status": "notified",
  "voucher_code": "ATRASO-7K2M9Q"
}

Campos da resposta

statusstring

Sempre notified.

voucher_codestring

Código do voucher, ou null se não foi emitido (sem with_voucher e sem voucher emitido antes para o alerta).

Dispensar um alerta

Marca o alerta como dismissed: ele sai do radar. Use para falsos positivos ou casos já resolvidos por outro meio. Não avisa o cliente.

POST/api/v1/admin/shipping/delivery-radar/{alertId}/dismissAdmin

Dispensa um alerta do radar

Exige manage_shipping. Sem corpo.

Parâmetros de caminho

alertIduuidobrigatório

Id do alerta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping/delivery-radar/$ALERT_ID/dismiss" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Alerta dispensado

json

{
  "status": "dismissed"
}

Pontualidade por transportadora

Para as remessas entregues nos últimos days dias, de pedidos que tinham data prometida, calcula o percentual entregue dentro do prazo e o atraso médio.

GET/api/v1/admin/shipping/delivery-radar/slaAdmin

Pontualidade por transportadora

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

daysintegerpadrão: 30

Janela em dias, contada para trás a partir de agora. Zero ou negativo vira 30.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/delivery-radar/sla?days=30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pontualidade

json

{
  "carriers": [
    {
      "carrier": "Correios",
      "total": 42,
      "on_time_pct": 88.1,
      "avg_delay_days": 0.6
    }
  ]
}

Campos da resposta

carriersarray

Uma linha por transportadora, da que mais entregou para a que menos. null quando não há entregas no período.

carrierstring

Nome da transportadora; desconhecido quando a remessa não informa.

totalinteger

Remessas entregues no período.

on_time_pctnumber

Percentual entregue até a data prometida (0 a 100).

avg_delay_daysnumber

Atraso médio em dias, contando 0 para as entregues no prazo.

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"]}`
400	Avisar um alerta que não existe, ou falha ao emitir o voucher	`{"error":"notify_failed","detail":"alert not found"}`
500	`alertId` que não é UUID; falha interna	`{"error":"dismiss_failed","detail":"..."}` / `{"error":"radar_failed","detail":"..."}` / `{"error":"sla_failed","detail":"..."}`

As ações exigem manage_shipping; as leituras aceitam view_shipping.