Tracking API Routes
Sistema de rastreio de encomendas integrado com 17TRACK.
GET /api/tracking
Seção intitulada “GET /api/tracking”Descrição: Lista rastreios com paginação e filtros. Auth: Required
Request:
- Query params:
page,limit,status,platform,search
Response:
- 200:
{ data: { data: Tracking[], total, page, limit } }
POST /api/tracking
Seção intitulada “POST /api/tracking”Descrição: Cria um novo rastreio manualmente. Tenta detectar transportadora e registrar no 17TRACK.
Request:
- Body:
{ tracking_number, carrier_name?, customer_name?, customer_phone?, platform? }
Response:
- 201:
{ data: ShipmentTracking }
Notas: Detecta transportadora automaticamente via detectCarrier() usando padroes regex.
GET /api/tracking/[id]
Seção intitulada “GET /api/tracking/[id]”Descrição: Retorna detalhes de um rastreio com todos os eventos.
Response:
- 200:
{ data: { ...tracking, events: TrackingEvent[] } }
DELETE /api/tracking/[id]
Seção intitulada “DELETE /api/tracking/[id]”Response:
- 204: No Content
GET /api/tracking/counts
Seção intitulada “GET /api/tracking/counts”Descrição: Contagem de rastreios agrupada por status.
Response:
- 200:
{ data: [{ status, count }] }
GET /api/tracking/links
Seção intitulada “GET /api/tracking/links”Descrição: Lista links rastreados com paginação e filtros.
Request:
- Query params:
page,limit,context_type,from,to
POST /api/tracking/links
Seção intitulada “POST /api/tracking/links”Descrição: Cria um link rastreado manualmente.
Request:
- Body:
{ original_url, utm_source?, utm_medium?, utm_campaign?, utm_content?, utm_term? }
GET /api/tracking/links/[id]/clicks
Seção intitulada “GET /api/tracking/links/[id]/clicks”Descrição: Lista cliques de um link rastreado com paginação.
GET /api/tracking/public
Seção intitulada “GET /api/tracking/public”Descrição: Consulta pública de rastreio por número. Não requer autenticação. Auth: Public
Request:
- Query params:
tracking_number
Response:
- 200:
{ tracking: { tracking_number, carrier_name, status, ... }, events: Event[] } - 404: Tracking not found
Notas: Max 50 eventos. Não retorna account_id. Usado pelo widget de rastreio.
POST /api/tracking/refresh
Seção intitulada “POST /api/tracking/refresh”Descrição: Atualiza status de rastreios pendentes consultando a API 17TRACK.
Response:
- 200:
{ data: { updated, error? } }
Notas: Busca até 40 rastreios não-delivered. Mapeamento de status via mapStatus(tag).
GET /api/tracking/settings
Seção intitulada “GET /api/tracking/settings”Descrição: Retorna configurações de rastreamento. Auth: Required (owner ou admin)
Response:
- 200:
{ data: { is_active, auto_register, has_api_key, quota_total, quota_used, webhook_url, widget_color } }
PUT /api/tracking/settings
Seção intitulada “PUT /api/tracking/settings”Descrição: Atualiza configurações de rastreamento (API key, auto_register, widget color).
Notas: Se api_key fornecida, e criptografada com AES-256-GCM e is_active e setado para true.
GET /api/tracking/stats
Seção intitulada “GET /api/tracking/stats”Descrição: Estatísticas de links rastreados e/ou top links mais clicados.
Request:
- Query params:
from,to,top(“true”),limit
POST /api/tracking/webhook
Seção intitulada “POST /api/tracking/webhook”Descrição: Recebé webhooks do 17TRACK com atualizações de status.
Auth: Public (verificação via header sign)
Notas: Busca TODOS os tracking_settings com webhook_secret, verifica assinatura, atualiza status, emite métricas de shipment.
GET /api/tracking/widget
Seção intitulada “GET /api/tracking/widget”Descrição: Retorna widget HTML embeddable para rastreio público. Auth: Public
Request:
- Query params:
color(default “#2563eb”)
Response:
- Content-Type: text/html
- Cache-Control: public, max-age=3600