Documentação da API

A base de todas as chamadas é a URL abaixo. Toda resposta vem em JSON, com os dados sob a chave data. Datas seguem o padrão ISO 8601 e valores monetários vêm em centavos.

https://app.blindapix.com/api/v1

As listagens são paginadas pelos parâmetros page (começa em 1) e limit (máximo 100, padrão 50).

Gere uma chave em Painel > Integrações > Chaves de API e escolha os escopos que ela pode usar. A chave aparece uma única vez na criação: guarde em local seguro, ela não pode ser recuperada depois.

Envie a chave no header Authorization como Bearer token. Toda chave começa com pk_live_.

curl https://app.blindapix.com/api/v1/orders \
  -H "Authorization: Bearer pk_live_sua_chave_aqui"

Escopos disponíveis

Uma chamada sem o escopo necessário retorna 403. Nunca exponha a chave no frontend: use sempre do lado do servidor.

Cada chave aceita até 60 requisições por minuto. Ao estourar, a resposta é 429. Toda resposta traz os headers abaixo pra você acompanhar o consumo.

Erros usam os códigos HTTP padrão e trazem uma mensagem curta no corpo. Detalhes sensíveis ficam só no log do servidor.

{
  "error": "Missing required scope: read:orders"
}

Em chamadas POST (reembolso, criação de webhook), envie o header Idempotency-Key com um valor único por operação. Se a requisição for repetida com a mesma chave, a API devolve a resposta original em vez de executar de novo. Isso evita reembolso ou webhook duplicado num retry de rede.

curl -X POST https://app.blindapix.com/api/v1/orders/{id}/refund \
  -H "Authorization: Bearer pk_live_sua_chave_aqui" \
  -H "Idempotency-Key: 2f9a1c7e-..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cliente desistiu" }'

Lista os produtos do seu tenant, com os planos e preços de cada um.

Filtros: status (active, draft, archived), page, limit. Escopo: read:products.

{
  "data": {
    "id": "8f2c...",
    "name": "Mentoria PRO",
    "slug": "mentoria-pro",
    "type": "payment_link",
    "status": "active",
    "product_plans": [
      { "id": "a1b2...", "name": "Único", "price": 19900, "billing": "one_time" }
    ]
  }
}

Lista e consulta pedidos. O valor (amount) vem em centavos.

Filtros: status (pending, paid, refunded, disputed, cancelled), created_after (ISO 8601), page, limit. Escopo: read:orders.

{
  "data": {
    "id": "d4e5...",
    "status": "paid",
    "amount": 19900,
    "currency": "BRL",
    "payment_method": "pix",
    "product_id": "8f2c...",
    "buyer_email": "[email protected]",
    "buyer_name": "Maria",
    "created_at": "2026-06-05T12:00:00Z"
  }
}

Abre uma solicitação de reembolso pra um pedido pago. O pedido precisa estar com status paid e sem reembolso pendente ou aprovado.

Corpo: { "reason": "..." } (1 a 500 caracteres). Escopo: refunds:create. Suporta Idempotency-Key.

{
  "data": {
    "id": "r1f2...",
    "status": "pending",
    "created_at": "2026-06-05T12:30:00Z"
  }
}

Cadastre uma URL pra receber eventos em tempo real. A criação devolve um secret (uma única vez): guarde pra verificar a assinatura das entregas.

Corpo: url (https público) e events (lista). Escopo: write:webhooks.

curl -X POST https://app.blindapix.com/api/v1/webhooks \
  -H "Authorization: Bearer pk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-site.com/webhooks/blindapix",
    "events": ["order.paid", "refund.requested"]
  }'

{
  "data": {
    "id": "wh01...",
    "url": "https://seu-site.com/webhooks/blindapix",
    "events": ["order.paid", "refund.requested"],
    "is_active": true
  },
  "secret": "guarde_este_valor_com_seguranca"
}

Eventos que você pode assinar ao criar um webhook:

Toda entrega chega via POST com o corpo abaixo e dois headers. A assinatura é um HMAC SHA-256 do corpo cru, usando o secret do webhook.

{
  "event": "order.paid",
  "data": { "id": "d4e5...", "amount": 19900 },
  "timestamp": "2026-06-05T12:00:00Z"
}

Compare a assinatura usando comparação em tempo constante. Use sempre o corpo cru (raw), antes de qualquer parse.

import crypto from "crypto";

function verificarAssinatura(corpoRaw, assinatura, secret) {
  const esperado =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(corpoRaw).digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(assinatura),
    Buffer.from(esperado),
  );
}

Responda 2xx rápido. Entregas que falham são reenviadas automaticamente com backoff.