Como usar a API REST do LimãoPay

Resposta curta

O LimãoPay expõe uma API REST em /api/v1/ autenticada via API key no header Authorization: Bearer lk_live_.... Use pra consultar pedidos, assinaturas e replay de eventos.

Quando usar API vs webhooks

• Webhooks (push): notificação em tempo real. Use pra reagir a eventos (liberar acesso quando paga).
• REST API (pull): consulta sob demanda. Use pra verificar estado (re-sync no startup, recuperar evento perdido, mostrar status pro usuário no seu app).

Combine os dois: webhooks pra reagir, REST API pra consultar e como fallback.

Passo 1 — Criar a API key

1. Vai em Dashboard → Developers → API Keys
2. Clica em Nova chave
3. Escolhe o modo (live ou test) usando o toggle global
4. Dá um nome (ex: "Servidor de produção")
5. Opcional: adiciona IP allowlist (CIDR separado por vírgula). Ex: 203.0.113.5/32 permite só esse IP. Vazio = qualquer IP.
6. Clica em Criar API key

A chave (lk_live_... ou lk_test_...) é mostrada uma única vez. Salva em variável de ambiente.

Passo 2 — Fazer requests

Todas as rotas exigem o header Authorization: Bearer <chave>.

curl https://api.limaopay.com.br/api/v1/orders \
  -H "Authorization: Bearer lk_live_a3f9b2c4..."

Endpoints

Listar pedidos

GET /api/v1/orders?email=joao@example.com&status=paid&limit=25

Filtros: email, external_customer_id, status, since (ISO date), limit (default 25, max 100), cursor (paginação).

Obter pedido específico

GET /api/v1/orders/:id

Consultar assinaturas de um cliente

Por email:

GET /api/v1/customers/joao%40example.com/subscriptions

Por external_customer_id (se você anexou metadata no checkout):

GET /api/v1/customers/by-external-id/user_123/subscriptions

Obter assinatura específica

GET /api/v1/subscriptions/:id

Replay de eventos (últimos 30 dias)

GET /api/v1/events?event_type=order.paid&since=2026-05-01

Útil pra recuperar eventos que seu webhook perdeu (ex: servidor estava fora do ar).

Formato de resposta

Estilo Stripe (snake_case):

{
  "object": "list",
  "data": [
    {
      "id": "ord_abc",
      "object": "order",
      "status": "paid",
      "amount_total": 4900,
      "currency": "brl",
      "buyer_email": "joao@example.com",
      "external_customer_id": "user_123",
      "external_metadata": { "plan": "pro" },
      "paid_at": "2026-05-11T14:00:00.000Z",
      "created_at": "2026-05-11T13:55:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Rate limit

Por API key:

Excedeu? Retorna 401 Rate limit exceeded. Implemente backoff exponencial.

Modo test vs live

• Chaves test (lk_test_...) e live (lk_live_...) são totalmente isoladas
• Criadas no toggle do dashboard /developers
• Use chaves test em staging/dev pra não gerar tráfego em prod

IP allowlist

Restrinja a chave a IPs específicos (CIDR notation). Útil quando seu servidor tem IP fixo:

203.0.113.5/32, 198.51.100.0/24

Vazio = aceita qualquer IP.

Revogação

Revogue qualquer chave a qualquer momento no dashboard. Efeito imediato — a próxima request com aquela chave retorna 401.

Boas práticas

• ✅ Guardar a chave em variável de ambiente (nunca no código)
• ✅ Criar chaves separadas por ambiente (uma test, uma live, uma pra cada serviço)
• ✅ Usar IP allowlist quando o servidor tem IP fixo
• ✅ Revogar chaves comprometidas imediatamente
• ✅ Rotacionar chaves periodicamente (criar nova → atualizar app → revogar antiga)
• ❌ Nunca usar a chave no frontend / browser
• ❌ Nunca commitar a chave no git
• ❌ Nunca compartilhar em chat/email