Documentação da API Recompra

Plataforma de consulta com billing por requisição. Esta página cobre autenticação, formato de requisição/resposta e códigos de erro. Para gerar um token, crie uma conta e acesse /login.

Autenticação
Todas as requisições usam Authorization: Bearer TOKEN. O token identifica o projeto automaticamente e é gerado na dashboard (Tokens → Gerar token). O valor completo aparece uma única vez — apenas o hash é armazenado.

• Respostas incluem o header X-Request-ID para rastreamento e suporte.

• Envie Idempotency-Key (opcional) para evitar cobrança dupla em retries de rede.

• Aceita GET (params na querystring) ou POST (params no body JSON).

Endpoint
Rota: POST /api/v1/{CODIGO} — o código de cada produto contratado fica visível na dashboard, em Developers.
CONSULTA_TESTEexemplo
cURL
curl -X POST https://recompra.dev/api/v1/CONSULTA_TESTE \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: um-id-unico-opcional" \
  -d '{"documento": "..."}'
JavaScript
const response = await fetch("https://recompra.dev/api/v1/CONSULTA_TESTE", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RECOMPRA_API_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ documento: "..." })
});

const data = await response.json();
if (!data.success) {
  console.error(data.error.code, data.error.message, data.requestId);
}
TypeScript
type ApiResponse<T> =
  | { success: true; data: T; requestId: string }
  | { success: false; error: { code: string; message: string }; requestId: string };

async function consultar<T>(code: string, params: Record<string, string>): Promise<T> {
  const response = await fetch(`https://recompra.dev/api/v1/${code}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RECOMPRA_API_TOKEN!}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(params)
  });
  const body = (await response.json()) as ApiResponse<T>;
  if (!body.success) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body.data;
}
Formato de resposta

Sucesso

{ "success": true, "data": { /* ... */ }, "requestId": "..." }

Erro

{ "success": false, "error": { "code": "...", "message": "..." }, "requestId": "..." }
Códigos de erro
Valor de error.code e HTTP status correspondente.
codestatussignificado
INVALID_TOKEN401Token inválido.
TOKEN_EXPIRED401Token expirado.
TOKEN_REVOKED401Token revogado.
CUSTOMER_BLOCKED403Conta suspensa ou bloqueada. Contate o suporte.
PROJECT_BLOCKED403Projeto pausado ou bloqueado.
PRODUCT_NOT_FOUND404Produto não encontrado.
PRODUCT_NOT_ALLOWED403Este projeto não tem permissão para este produto.
PRODUCT_UNAVAILABLE503Produto temporariamente indisponível.
INSUFFICIENT_BALANCE402Saldo insuficiente. Adicione créditos.
IP_NOT_ALLOWED403IP não autorizado para este projeto.
RATE_LIMIT_EXCEEDED429Limite de requisições excedido.
BUDGET_EXCEEDED402Orçamento do projeto excedido.
INVALID_PARAMETERS400Parâmetros inválidos.
IDEMPOTENCY_CONFLICT409Requisição com esta Idempotency-Key ainda está em processamento.
PROVIDER_TIMEOUT504A API externa não respondeu a tempo.
PROVIDER_REJECTED422A API externa rejeitou a consulta (dados inválidos para o fornecedor).
PROVIDER_NOT_FOUND404Registro não encontrado na API externa.
PROVIDER_AUTH_ERROR502Falha de autenticação com a API externa. Contate o administrador da plataforma.
PROVIDER_UNAVAILABLE503A API externa está indisponível no momento.
PROVIDER_ERROR502Erro na API externa.
INTERNAL_ERROR500Erro interno.