API de Resgate Pertroca

1 · COMO FUNCIONA

Trinta segundos de contexto

Pedido: R$ 120,00
Crédito Pertroca: −R$ 100,00
A pagar (cartão/Pix): R$ 20,00

Regra de ouro da conciliação: o número que vale é sempre o debited da resposta — nunca o que você pediu, nunca o que mostrou na tela.

2 · ANTES DE COMEÇAR

Peça e guarde a chave

No painel Pertroca da loja: Integrações → Solicitar acesso à API (canal, unidade, sistema, contato técnico). A Pertroca aprova; a loja gera a chave no painel. Limite de 10 chaves por empresa — revogue as que saíram de uso.

Uma chave = um canal de uma unidade (delivery + 3 PDVs = 4 chaves). Códigos amarrados a um pedido ficam presos à chave que validou — não valide no Delivery e resgate no PDV.

prt_live_K7M2P9XR_9fJ2kL8mNq3RtV5wXy7Za1Bc4De6Fg8H
         ────┬───
         identificador público (aparece nos logs)

Formatos

• amount: número (ou string numérica), > 0, máximo 2 casas decimais, em reais. 1.005 → 400.
• orderId: A-Z a-z 0-9 . _ : -, 1 a 64 caracteres, sensível a maiúsculas. Um por pedido, nunca reutilizado.
• code: string de exatamente 6 dígitos. Tire espaços antes de enviar ("472 913" → "472913").

3 · TESTE A CHAVE

curl -X POST https://pertroca.com.br/api/v1/ping \
  -H "Authorization: Bearer $PERTROCA_KEY"

{ "ok": true, "keyId": "K7M2P9XR",
  "company": { "id": "…", "name": "CER Gastronomia" },
  "label": "Delivery Chez Rejala", "restaurant": "CHEZ REJALA DELIVERY" }

4 · VALIDAR

curl -X POST https://pertroca.com.br/api/v1/validate \
  -H "Authorization: Bearer $PERTROCA_KEY" -H "Content-Type: application/json" \
  -d '{ "code": "472913", "orderId": "PED-2026-000481", "amount": 120.00 }'

Código válido:

{ "valid": true, "balance": 100.00, "applicable": 100.00, "shortfall": 20.00,
  "company": { "id": "…", "name": "CER Gastronomia" },
  "customer": { "firstName": "Victor" },
  "code": { "expiresAt": "2026-09-02T19:02:00.000Z", "boundTo": "PED-2026-000481" },
  "requestId": "…" }

• code.expiresAt é a validade efetiva pra você: com orderId, já reflete os 30 min da amarração.
• Re-validar o mesmo pedido é permitido e não estende o prazo.
• Guarde applicable — é o desconto acordado que você manda no /redeem.
• Sempre mande o orderId. Sem ele, um código já amarrado a outro pedido seu ainda responde valid: true — e o /redeem depois recusa. Com orderId, você descobre no validate (bound_to_other_order) e não promete desconto que não vai sair.
• customer.firstName traz só o primeiro nome, pra conferência no balcão — é tudo que a API expõe do cliente.

Código inválido (HTTP 200 — resultado normal, não erro):

{ "valid": false, "reason": "expired",
  "message": "Código expirado. Peça ao cliente para gerar outro na carteira." }

message já vem em português, pronta pra tela. reason desconhecido (o enum pode crescer) → trate como falha genérica de cupom.

"Peça outro código" não é infinito: a carteira permite cerca de 10 gerações a cada 10 minutos por cliente/loja. Num atendimento normal sobra folga, mas não construa um fluxo que peça código novo em laço.

5 · DEBITAR

Chame com o pedido confirmado — e envie como amount o desconto acordado (min(total, applicable) do validate), não o total do pedido:

curl -X POST https://pertroca.com.br/api/v1/redeem \
  -H "Authorization: Bearer $PERTROCA_KEY" -H "Content-Type: application/json" \
  -d '{ "code": "472913", "orderId": "PED-2026-000481",
        "amount": 100.00, "expectedDebit": 100.00 }'

{ "success": true, "redemptionId": "K7M2P9XR_PED-2026-000481",
  "requested": 100.00, "debited": 100.00, "shortfall": 0.00,
  "balanceAfter": 0.00, "alreadyProcessed": false,
  "requestId": "9b1b66c2-3f68-4d1e-839f-679438cb7bc5" }

Garantias (atômicas no servidor)

• Débito, invalidação do código e recibo do orderId acontecem na mesma transação. Não existe estado intermediário.
• Retry é seguro em qualquer cenário, inclusive após 500/timeout: reenvie o mesmo orderId e receba a resposta original com alreadyProcessed: true — que pode chegar sem você nunca ter visto um 2xx antes. É o comportamento esperado.
• success:false não consome o pedido: o mesmo orderId pode tentar de novo (ex.: código novo após superseded).
• reason:"used" quase sempre significa que o cliente gastou esse mesmo código em outro lugar (no balcão da loja, ou em outro canal) — o crédito saiu, mas não pra você. Trate como recusa: cobre o valor cheio com aviso (§8). A exceção é vir used logo depois de um 5xx no mesmo orderId e a consulta GET /redemptions?orderId= devolver 404: aí sim guarde o requestId e abra suporte antes de cobrar.
• Depois do sucesso o código está morto. Pedido novo = código novo. Nunca guarde códigos pra reutilizar.

6 · PDV / BALCÃO

O caso simples

"Tem crédito Pertroca?" → cliente gera e dita: "472 913"
Operador digita → POST /redeem { code, orderId: <id da venda>, amount: <total> }
→ debited: 100.00, shortfall: 20.00 → cobra R$ 20 no cartão

Tem leitor 2D no PDV? O app também mostra o código como QR: bipe e o leitor digita os 6 dígitos sozinho no campo — sem app da Pertroca, sem digitação.

No balcão pode mandar o total direto como amount — o pagamento é na hora e shortfall diz o que falta. Lance debited como forma de pagamento "Pertroca" no PDV (não como "dinheiro", senão o fechamento do operador não bate).

Neste fluxo o código vale 5 minutos — sem /validate não há amarração, e é a amarração que estica pra 30 min (§7). Numa fila, o código ditado no início pode vencer antes de chegar a vez: se vier expired, é só o cliente tocar em Código pra pagar de novo. Se o seu PDV mostra o desconto antes de fechar a venda, chame /validate com o orderId da venda — aí você ganha os 30 min e descobre problemas antes de prometer desconto.

7 · DELIVERY

Código amarrado ao pedido

Entre "aplicou o cupom" e "pedido confirmado" existe um intervalo — por isso a amarração: /validate com orderId prende o código a este pedido por 30 minutos (prazo fixo, não renova). Nenhuma outra chave ou outro pedido resgata esse código pela API.

Quanto menor a janela entre validate e redeem, menor a chance do §8.

Pedido cancelado depois do redeem: a loja estorna no painel Pertroca (Histórico do crédito → Estornar). Sem endpoint de estorno no v1.

8 · CASOS QUE EXIGEM ATENÇÃO

O crédito continua vivo entre validate e redeem

O cliente pode gastar no caixa físico, transferir, ou o saldo pode vencer. Sem "reserva" — por desenho. Consequências possíveis no /redeem:

Enviando amount = applicable + expectedDebit, os dois últimos casos viram um só e binário. É o fluxo recomendado pro delivery.

9 · ERROS DE REQUEST

HTTP ≠ 200

2xx = a Pertroca respondeu; olhe valid/success. 4xx = a chamada não foi aceita e nada mudou. 5xx é diferente: o débito pode ter acontecido — reenvie o mesmo orderId (§5) ou consulte GET /redemptions?orderId= antes de decidir qualquer coisa. Nunca cobre o cliente por conta própria depois de um 5xx sem consultar.

requestId vem no corpo de TODA resposta (200, 4xx e 5xx). Grave junto do pedido: é a chave de rastreio que o suporte da Pertroca vai pedir.

10 · CONCILIAÇÃO

curl "https://pertroca.com.br/api/v1/redemptions?orderId=PED-2026-000481" \
  -H "Authorization: Bearer $PERTROCA_KEY"

curl "https://pertroca.com.br/api/v1/redemptions?date=2026-09-02" \
  -H "Authorization: Bearer $PERTROCA_KEY"

As duas formas devolvem envelopes DIFERENTES. Não reaproveite o mesmo parser.

?orderId= — consulta de UM pedido. Resposta plana, sem count e sem array:

{ "redemptionId": "K7M2P9XR_PED-2026-000481", "orderId": "PED-2026-000481",
  "requested": 100.00, "debited": 100.00, "shortfall": 0.00, "balanceAfter": 0.00,
  "createdAt": "2026-09-02T18:41:07.312Z",
  "requestId": "…" }

Sem registro pra esse orderId → 404 redemption_not_found (nunca count: 0). É a consulta certa pra "será que aquele débito passou?" depois de um 5xx.

?date= — dia inteiro (data no horário de Brasília). Resposta com envelope:

{ "count": 12, "redemptions": [
  { "redemptionId": "K7M2P9XR_PED-2026-000481", "orderId": "PED-2026-000481",
    "requested": 100.00, "debited": 100.00, "shortfall": 0.00, "balanceAfter": 0.00,
    "createdAt": "2026-09-02T18:41:07.312Z" } ] }

Escopo: somente a sua chave — resgates feitos no caixa físico da Pertroca ou por outra integração não aparecem aqui. A soma de debited é o bruto em crédito Pertroca do seu canal; estornos feitos no painel não aparecem no v1. Datas sempre ISO-8601 UTC com milissegundos; o parâmetro date é a exceção (YYYY-MM-DD, fuso de Brasília).

11 · EXEMPLO COMPLETO

Node.js

const BASE = 'https://pertroca.com.br/api/v1';
const KEY = process.env.PERTROCA_KEY;               // nunca no front-end

async function pertroca(path, body, metodo = 'POST', tentativa = 0) {
  const r = await fetch(BASE + path, { method: metodo,
    headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: metodo === 'GET' ? undefined : JSON.stringify(body) });
  const json = await r.json().catch(() => ({}));
  if (r.status === 429 && tentativa < 1) {           // espera e tenta 1x — só uma
    await new Promise(s => setTimeout(s, (Number(r.headers.get('retry-after')) || 60) * 1000));
    return pertroca(path, body, metodo, tentativa + 1);
  }
  if (!r.ok) throw Object.assign(new Error(json.error || `http_${r.status}`),
    { detail: json, status: r.status, requestId: json.requestId });
  return json;
}

// orderId ÚNICO PRA SEMPRE — nunca número de mesa/comanda que se repete
const orderId = pedido.id;                           // id interno, jamais reciclado

// 1) cupom no carrinho
const digits = (cupom || '').replace(/\D/g, '');
if (!/^\d{6}$/.test(digits)) return mostrarErro('Código inválido');

const v = await pertroca('/validate', { code: digits, orderId, amount: pedido.total });
if (!v.valid) return mostrarErro(v.message);
const acordado = v.applicable;                       // ex.: 100.00
mostrarDesconto(acordado, v.shortfall);              // "−R$100 · a pagar R$20"

// 2) …cliente paga o restante, pedido confirmado…

// 3) débito — amount = acordado, tudo-ou-nada.
// Marque o orderId ANTES, com insert-if-absent atômico (create() no Firestore,
// INSERT ... ON CONFLICT DO NOTHING no SQL): `true` só se ele nunca existiu aqui.
const orderIdInedito = await marcarTentativaRedeem(orderId);
let houveRetry = false;                              // virou true se repetimos a chamada
const corpo = { code: digits, orderId, amount: acordado, expectedDebit: acordado };
let d;
try {
  d = await pertroca('/redeem', corpo);
} catch (e) {
  // 429 NÃO é recusa: é "tente de novo". Nunca cobre cheio por causa dele —
  // no pico do almoço isso viraria cliente com crédito pagando a conta inteira.
  if (e.status === 429) return tentarDeNovoMaisTarde(pedido, orderId);
  // 401/403 = problema da CHAVE (revogada, bloqueada, loja inativa), não do cupom
  // deste cliente. key_blocked se cura sozinho em 15–60 min (veja `blockedUntil`).
  // Cobrar cheio aqui puniria todo cliente com crédito durante o bloqueio.
  if (e.status === 401 || e.status === 403)
    return segurarPedidoEAlertar(pedido, orderId, e.requestId);
  // Demais 4xx = recusado, NÃO repita (repetir não muda nada e mascara o erro).
  // Corpos 4xx trazem `error` (código técnico), não `message`.
  if (e.status && e.status < 500) return descontoRecusado(pedido, e.detail?.error);
  // 5xx/rede = incerto: o débito PODE ter acontecido. Repita o MESMO orderId…
  houveRetry = true;
  try { d = await pertroca('/redeem', corpo); }
  catch (e2) {
    // …e se ainda assim não souber, PERGUNTE em vez de adivinhar:
    try { d = { ...await pertroca(`/redemptions?orderId=${encodeURIComponent(orderId)}`, null, 'GET'), success: true }; }
    catch (e3) {
      // 404 aqui NÃO prova que não debitou: pode ser corrida (o débito ainda
      // não apareceu). Espere e pergunte de novo antes de concluir.
      if (e3.status === 404) {
        await new Promise(s => setTimeout(s, 3000));
        try { d = { ...await pertroca(`/redemptions?orderId=${encodeURIComponent(orderId)}`, null, 'GET'), success: true }; }
        catch (e4) {
          if (e4.status === 404) return descontoRecusado(pedido, 'credito_nao_confirmado');
          return segurarPedidoEAlertar(pedido, orderId, e4.requestId);
        }
      } else return segurarPedidoEAlertar(pedido, orderId, e3.requestId);
    }
  }
}
if (!d.success) {
  // `used` = o crédito saiu, mas não pra você (cliente gastou no balcão/outro canal)
  if (d.reason === 'used') return descontoRecusado(pedido, 'codigo_ja_usado');   // §5, §8
  return descontoRecusado(pedido, d.message);        // §8 — sem desconto fantasma
}
// alreadyProcessed depois de um retry nosso = replay esperado, siga em frente.
// alreadyProcessed na PRIMEIRÍSSIMA chamada de um orderId inédito = colisão (§5):
// esse número já foi liquidado antes, o débito de agora não existe.
if (d.alreadyProcessed && orderIdInedito && !houveRetry)
  return alertarColisaoDeOrderId(pedido, d);
registrarPagamentoPertroca(pedido, d.debited);       // concilie por ESTE número

12 · TESTE DE PONTA A PONTA

Sem sandbox — ensaio real barato

1. A loja emite um crédito de R$ 1,00 para o CPF de alguém da equipe (painel → Novo Crédito).
2. Essa pessoa abre a carteira → Código pra pagar.
3. Rode /validate e /redeem com amount: 1.00 e um orderId novo a cada execução — ex.: TESTE-2026-09-02-1911. Reaproveitar TESTE-001 faz a segunda rodada devolver o recibo da primeira (alreadyProcessed: true) sem debitar nada, e você "testa" um sucesso falso.
4. Confira o débito no painel (Histórico) e em GET /redemptions?orderId=<o que você usou>.
5. Estorne pelo painel pra fechar o ciclo.

13 · CHECKLIST DE HOMOLOGAÇÃO

Antes de ir pra produção

• Chave em variável de ambiente; nenhuma chamada sai do navegador
• ^\d{6}$ validado no seu lado antes de chamar a API
• /ping responde a loja certa
• orderId único pra sempre — nunca número de mesa/comanda reciclado (§5)
• alreadyProcessed: true na primeiríssima chamada de um orderId inédito dispara alerta (colisão); depois de um retry seu, é replay esperado e o pagamento é registrado
• 4xx não é re-tentado; 5xx re-tenta com o MESMO orderId e, na dúvida, consulta ?orderId=
• requestId gravado junto de cada pedido
• /redeem só com pedido confirmado, com amount = applicable e expectedDebit (delivery)
• Retry do mesmo orderId → alreadyProcessed: true, sem débito duplo
• Todos os success:false do §8 tratados sem desconto fantasma
• debited < acordado tratado (se optar por não usar expectedDebit)
• debited lançado como forma de pagamento "Pertroca"
• 429 espera Retry-After; 500 re-tenta com o mesmo orderId
• orderId único por pedido; códigos nunca armazenados pra reuso