Convenções da API

Estas regras valem para todas as rotas da API v1. Os detalhes de cada rota estão na Referência da API.

Endereço e formatoCopiar link da seção

• Endereço base: https://minepag.com.br/api/v1
• Formato: JSON em UTF-8. Envie Content-Type: application/json nas rotas com corpo.
• Tamanho do corpo: até 64 KB. Acima disso, a resposta é 413 payload_too_large.
• Dinheiro: inteiros em centavos de real (4990 = R$ 49,90). A moeda é sempre BRL.
• Datas: ISO 8601 em UTC (2026-10-12T14:30:00.000Z). Nos filtros de data, envie o fuso (2026-10-01T00:00:00-03:00 ou …Z).
• Identificadores: UUID. GET /products/{productId} também aceita o endereço (slug) do produto.

Envelope da respostaCopiar link da seção

Toda resposta de sucesso vem dentro de data, com metadados em meta:

{
  "data": { "id": "0193b7c2-5b2f-7d66-8e30-2b3c4d5e6f02", "number": 1042, "status": "paid" },
  "meta": { "requestId": "5b0f7a52-0d8e-4b51-9a57-1f0c6b7e2d10" }
}

Listas trazem um array em data e a paginação em meta.pagination. Erros trazem error com um código estável; veja Erros da API.

Identificador da requisiçãoCopiar link da seção

Cada resposta traz o cabeçalho X-Request-Id e o mesmo valor em meta.requestId. Guarde esse valor nos seus logs e envie ao suporte quando algo der errado.

Para usar o seu próprio identificador, envie X-Correlation-Id com 1 a 128 caracteres (letras, números, ., _ e -). Ele passa a ser o requestId da resposta. Esse cabeçalho só funciona em chamadas feitas pelo servidor, porque o CORS não o libera no navegador.

PaginaçãoCopiar link da seção

As listas usam paginação por cursor:

{
  "data": [{ "id": "…" }, { "id": "…" }],
  "meta": {
    "requestId": "…",
    "pagination": { "limit": 20, "hasMore": true, "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTEwLTEyVDE0OjMwOjAwLjAwMFoiLCJpZCI6Ii4uLiJ9" }
  }
}

Quando hasMore é false, nextCursor vem null e a lista acabou. Trate o cursor como um texto opaco: não monte nem altere o valor.

• Pedidos, reembolsos, clientes, entregas e acessos liberados vêm do mais novo para o mais antigo.
• Produtos vêm na ordem definida pelo lojista no catálogo. Para catálogos muito grandes, use os filtros category e q: a paginação de produtos para depois de 10.000 itens.
• GET /categories devolve todas as categorias de uma vez, sem paginação.

async function listAllOrders() {
  const orders = [];
  let cursor = null;
  do {
    const url = new URL('https://minepag.com.br/api/v1/orders');
    url.searchParams.set('limit', '100');
    url.searchParams.set('paymentStatus', 'paid');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.MINEPAG_SECRET_KEY}` }
    });
    if (!response.ok) throw new Error(`MinePag respondeu ${response.status}`);
    const { data, meta } = await response.json();
    orders.push(...data);
    cursor = meta.pagination.nextCursor;
  } while (cursor);
  return orders;
}

IdempotênciaCopiar link da seção

Rede cai, servidor reinicia, a resposta se perde. Para repetir uma chamada sem cobrar ou reembolsar duas vezes, envie o cabeçalho Idempotency-Key com um valor único por operação, como um UUID gerado no seu sistema.

Como funciona:

1. Primeira chamada: a MinePag executa a operação e guarda a resposta por 24 horas, ligada à chave de API usada.
2. Mesma chave e mesmo corpo: a MinePag devolve a resposta guardada, sem executar de novo, e adiciona o cabeçalho Idempotent-Replayed: true.
3. Mesma chave com outro corpo, método ou rota: 409 idempotency_conflict. Gere outra chave para outra operação.
4. Chamada anterior ainda em andamento: 409 conflict. Espere alguns segundos e repita com a mesma chave.
5. Erros 5xx e 429 não ficam guardados: a repetição executa de verdade.

O valor aceita de 1 a 255 caracteres visíveis, sem espaços. Gere a chave antes da primeira tentativa e reutilize a mesma em todas as repetições daquela operação.

curl https://minepag.com.br/api/v1/refunds \
  -H "Authorization: Bearer $MINEPAG_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reembolso-pedido-1042-1" \
  -d '{ "paymentId": "0193b7c2-5b40-7d66-8e30-2b3c4d5e6f07", "amount": 2000 }'

Limites de requisiçãoCopiar link da seção

Os limites são por janela fixa. Acima do limite, a resposta é 429 rate_limited com o cabeçalho Retry-After (em segundos). Espere esse tempo antes de tentar de novo.

CORSCopiar link da seção

A API aceita chamadas de qualquer domínio (Access-Control-Allow-Origin: *) e não usa cookies: a autenticação é sempre pelo cabeçalho. No navegador, só a chave publicável funciona.

• Cabeçalhos liberados: Authorization, Content-Type, Idempotency-Key, X-API-Key, X-Cart-Token e X-Order-Token.
• Cabeçalhos que o navegador consegue ler na resposta: X-Request-Id, Retry-After, Idempotent-Replayed e X-Cart-Token.

Versão da APICopiar link da seção

A versão faz parte do endereço: /api/v1. Os webhooks informam a versão do formato dos dados no campo apiVersion do envelope (hoje 2026-10-01).

Escreva a integração para tolerar campos novos: ignore campos que você não conhece nas respostas e nos eventos, e trate valores novos de status sem quebrar.

AmbientesCopiar link da seção

A API usa a mesma chave para pedidos de teste e reais. O que decide é o gateway conectado em cada forma de pagamento: com o gateway em Sandbox, os pedidos são de teste e não contam na sua fatura. As formas em Sandbox só aparecem e só aceitam pagamento com a chave secreta; com a chave publicável, GET /payment-methods lista só as de Produção e o checkout numa rota de Sandbox responde 422 payment_method_unavailable. O campo environment dos pedidos (sandbox ou production) mostra a origem. Veja Gateways de pagamento.