Rally Partner API v1

21 endpoints REST · Auth Bearer · Rate limit 60 req/min · v1 estável desde 2026-04-24.

Sobre a Partner API

A Partner API v1 é o canal oficial pra integrações externas — apps mobile, dashboards de BI, automações no-code (Zapier, n8n, Make), serviços de contabilidade, etc. Você lê dados (anúncios, pedidos, estoque) e dispara ações controladas (notificações pro lojista). Tudo escopado pelo token: vendedor só vê seus próprios dados; fornecedor (drop) só vê os vendedores vinculados.

Autenticação

Bearer token pessoal (PAT) gerado pelo lojista em /painel/parceiro/hub → "Gerar token". O token começa com ptk_ seguido de 48 caracteres hex.

curl https://api.rallydevendas.com.br/v1/partner/health \
  -H "Authorization: Bearer ptk_AbCdEf1234567890abcdef1234567890abcdef1234567890"

Rate limit

Endpoint	Limite	Janela
Default (GET)	60	1 min / token
POST mutativos	20	1 min / token
/orders/remind-all	1	5 min / token

Headers de resposta:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1715923200

Endpoints Lojista (10)

Método	Rota	O que faz
GET	/health	Ping + identifica o usuário do token
GET	/stores	Lista contas ML conectadas
GET	/stores/{ml_id}/metrics	Métricas agregadas (vendas, reputação, anúncios ativos)
GET	/orders?status=paid&limit=50	Lista pedidos (paginação + filtros)
GET	/products	Catálogo interno do lojista
GET	/announcements	Anúncios publicados nas contas ML
GET	/stock	Saldo de estoque + movimentações
GET	/notifications	Histórico de notificações enviadas
POST	/notify	Dispara notificação pro lojista (Telegram/Email/Push)
GET	/usage	Consumo da API no mês

Exemplo — listar pedidos pagos

curl "https://api.rallydevendas.com.br/v1/partner/orders?status=paid&limit=20" \
  -H "Authorization: Bearer ptk_..."

# Response 200
{
  "data": [
    {
      "order_id": "20000123456789",
      "ml_id": "MLB123...",
      "status": "paid",
      "total_amount": 199.90,
      "buyer_nickname": "JOAO123",
      "date_created": "2026-05-16T14:32:00",
      "shipping": {
        "id": "412345678",
        "status": "ready_to_ship",
        "logistic_type": "drop_off"
      }
    }
  ],
  "pagination": { "total": 156, "limit": 20, "offset": 0 }
}

Exemplo — disparar notificação

curl -X POST https://api.rallydevendas.com.br/v1/partner/notify \
  -H "Authorization: Bearer ptk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "event": "custom",
    "title": "Backup concluído",
    "body": "Snapshot de pedidos exportado pra S3."
  }'

Endpoints Fornecedor (Drop) (11)

Requer token de usuário com role drop + vínculo ativo com pelo menos 1 vendedor.

Método	Rota	O que faz
GET	/drop/health	Ping + lista vendedores vinculados
GET	/drop/catalog/audit	Auditoria de SKU/EAN sem match nos seus catálogos
GET	/drop/catalog/products	Lista seus produtos disponíveis pros vendedores
POST	/drop/catalog/links	Vincula MLB do vendedor a produto seu (manual)
POST	/drop/catalog/links/bulk	Vínculo em lote (CSV up to 500)
POST	/drop/catalog/links/unlink	Remove vínculo
GET	/drop/orders	Pedidos drop vinculados aos seus produtos
POST	/drop/orders/remind	Lembra vendedor de pagar pedido drop específico
POST	/drop/orders/remind-all	Lembra todos vendedores com pedidos atrasados (1x/5min)
GET	/drop/ml/label?ship_id=X&seller_id=Y	Proxy etiqueta ML (valida vínculo)
GET	/drop/ml/invoice?order_id=X&seller_id=Y	Proxy NF-e ML do pedido

Códigos de erro

HTTP	Significado	Como agir
200	OK	—
400	Body inválido	Verifique payload contra spec
401	Token ausente/inválido	Confirme header Authorization: Bearer
403	Sem permissão (role ou binding)	Verifique role do user dono do token + vínculos ativos
404	Recurso não existe	ID errado OU não pertence ao escopo do token
429	Rate limit	Aguarde X-RateLimit-Reset
500	Erro Rally	Reporte com x-request-id da response

Webhooks roadmap

Webhooks pra parceiros estão no roadmap Q3 2026. Por enquanto, integre via polling dos endpoints /orders e /notifications com cache local e If-Modified-Since.

SDKs

Não temos SDK oficial — a API é REST puro JSON, qualquer cliente HTTP serve. Exemplos community em PHP, Python e Node em github.com/andrehocsis/rally-partner-examples (em construção).

Modelo de auth + retry (qualquer linguagem)

// Pseudocódigo
GET https://api.rallydevendas.com.br/v1/partner/orders?status=paid
Headers:
  Authorization: Bearer ptk_xxxxxxxxxxxxxxxxxxxx
  Accept: application/json

Em caso de 429:
  Espere até X-RateLimit-Reset (epoch segundos)
  Tente de novo (máx 3x)

Em caso de 5xx:
  Backoff exponencial 1s, 2s, 4s
  Após 3 tentativas, log + alerta

Suporte

Dúvidas técnicas: dev@rallydevendas.com.br
Status da API: rallydevendas.com.br/status
Changelog: DOCUMENTACAO/API/03_ENDPOINTS.md

v1.0 — última atualização 2026-05-17 · Termos de uso da API