Pedidos, clientes e acessos liberados

Este guia mostra as rotas que um sistema de retaguarda usa: um ERP, uma planilha de vendas, um painel de suporte ou o backend do seu servidor de jogo. Todas exigem chave secreta e só podem ser chamadas do seu servidor. Veja Autenticação.

PedidosCopiar link da seção

Listar e filtrarCopiar link da seção

GET /orders (escopo orders:read) lista do mais novo para o mais antigo, com paginação por cursor.

Pedido pending com o prazo de pagamento (expiresAt) vencido já aparece como status: expired e paymentStatus: cancelled, nas respostas e nos filtros, mesmo antes de a expiração em lote fechá-lo. Por isso status=pending não traz pedidos vencidos e status=expired os inclui.

Exemplo: pedidos pagos de outubro, no fuso de São Paulo.

const params = new URLSearchParams({
  paymentStatus: 'paid',
  createdFrom: '2026-10-01T00:00:00-03:00',
  createdTo: '2026-11-01T00:00:00-03:00',
  limit: '100'
});
const response = await fetch(`https://minepag.com.br/api/v1/orders?${params}`, {
  headers: { Authorization: `Bearer ${process.env.MINEPAG_SECRET_KEY}` }
});
const { data: orders, meta } = await response.json();

A lista traz o resumo de cada pedido: número, estados, valores, comprador (customer.id, email e name), source (checkout, api, imported ou subscription_renewal), environment (sandbox ou production) e datas.

Detalhe do pedidoCopiar link da seção

GET /orders/{orderId} acrescenta ao resumo:

• items[]: produto, preço, quantidade, valores e os campos de checkout preenchidos pelo comprador (ex.: nick).
• payments[]: cada tentativa de pagamento, com gateway, forma, estado, valores e instruções de Pix ou boleto.
• refunds[]: os reembolsos do pedido.
• couponCode: o cupom usado, se houver.

Um pedido pode ter mais de um pagamento (ex.: cartão recusado e depois Pix). O pedido está pago quando paymentStatus é paid.

Cancelar um pedido não pagoCopiar link da seção

POST /orders/{orderId}/cancel (escopo orders:write) cancela um pedido que ainda aguarda pagamento: as cobranças abertas são canceladas e o estoque e o cupom reservados voltam. O corpo aceita reason (opcional, até 500 caracteres), que vai para os logs de auditoria.

Pedido que não está pending responde 409 conflict. Isso inclui o pedido com o prazo de pagamento (expiresAt) vencido: ele já aparece como expired, mesmo antes de a expiração em lote fechá-lo, e não pode mais ser cancelado. Pedido pago se resolve com reembolso.

ReembolsarCopiar link da seção

POST /refunds (escopo orders:write) devolve o valor de um pagamento confirmado, não do pedido. Pegue o paymentId em payments[] do detalhe do pedido.

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

Se o gateway recusar, a resposta é 422 refund_not_allowed com o motivo. Valor acima do saldo do pagamento responde 422 refund_amount_exceeded.

GET /refunds (escopo orders:read) lista os reembolsos da loja e aceita os filtros orderId e paymentId.

ClientesCopiar link da seção

O documento do cliente nunca volta inteiro: a API mostra só o tipo e os 4 últimos dígitos (document: { "type": "cpf", "last4": "8909" }).

Acessos liberadosCopiar link da seção

Um acesso liberado é um benefício concedido a um cliente por um pedido ou por uma assinatura: o cargo no Discord, o comando no Minecraft, o download, a chave de licença. GET /entitlements (escopo deliveries:read) responde à pergunta "o que este cliente tem hoje?".

Exemplo: conferir se um cliente tem acesso ativo a um produto antes de liberar algo no seu sistema.

async function hasActiveAccess(customerId, productId) {
  let cursor = null;
  do {
    const params = new URLSearchParams({ customerId, status: 'active', limit: '100' });
    if (cursor) params.set('cursor', cursor);
    const response = await fetch(`https://minepag.com.br/api/v1/entitlements?${params}`, {
      headers: { Authorization: `Bearer ${process.env.MINEPAG_SECRET_KEY}` }
    });
    const { data, meta } = await response.json();
    if (data.some(entitlement => entitlement.productId === productId)) return true;
    cursor = meta.pagination.nextCursor;
  } while (cursor);
  return false;
}

Cada acesso traz benefitType, benefitName, productId, quantity, startsAt, endsAt (null quando não expira) e, se foi revogado, revokedAt e revokeReason.

Para manter uma cópia local sempre em dia, escute entitlement.granted e entitlement.revoked. Veja Eventos.

EntregasCopiar link da seção

Cada acesso liberado gera uma ou mais entregas, uma por canal. GET /deliveries (escopo deliveries:read) mostra em que pé cada uma está.

A resposta mostra attempts e maxAttempts, nextAttemptAt quando há nova tentativa agendada e error com o último código e mensagem. Reenviar ou cancelar uma entrega é feito no painel, em Entregas. Veja Acompanhar entregas.

Se você mantém um serviço externo de entrega, POST /deliveries/{id}/complete e POST /deliveries/{id}/fail confirmam o resultado. Veja Serviços externos.

Conciliação diáriaCopiar link da seção

Uma rotina simples para manter um sistema externo em dia, mesmo que algum webhook se perca:

1. Uma vez por dia, liste GET /orders?paymentStatus=paid com createdFrom de 5 dias atrás. A janela maior cobre boletos, que podem ser pagos dias depois de o pedido ser criado.
2. Para cada pedido que você ainda não tem, busque o detalhe e registre. Os que você já tem, ignore.
3. Liste GET /refunds (do mais novo para o mais antigo) até chegar a um reembolso que você já registrou, e atualize os pedidos correspondentes.