Boas práticas

Conciliar pagamentos

O webhook é o jeito principal de saber do pagamento. A conciliação é a rede de segurança: uma rotina sua que confere de tempos em tempos se nenhuma venda ficou sem tratar.

Por que conciliar

  • O seu servidor pode ficar fora do ar por mais tempo do que as tentativas de reenvio cobrem (cerca de 22 horas).
  • Um erro no seu código pode ter tratado o evento pela metade.
  • Você pode ter ativado a integração depois de algumas vendas já existirem.

A conciliação não substitui o webhook: ela só pega o que escapou.

A rotina

1. Liste as cobranças pendentes do seu sistema

Pegue no seu banco os pedidos que ainda estão aguardando pagamento e cuja cobrança já foi criada há mais de 2 minutos (dê tempo ao webhook chegar).

2. Consulte cada uma na API

Chame GET /charges/{id}. Se está pendente, a consulta pergunta ao banco na hora (no máximo a cada 20 segundos por cobrança). Para muitas de uma vez, use GET /charges com status=pago e limite=100.

3. Trate o resultado como se fosse o webhook

pago: libere o acesso (se ainda não liberou). expirado: cancele o pedido. med, contestado ou reembolsado: ajuste o acesso. O mesmo código de tratamento serve para os dois caminhos, e a conferência de repetição evita tratar duas vezes.

4. Repita num ritmo suave

A cada 5 a 15 minutos para o que é recente e uma varredura maior uma vez por dia. Nunca em loop apertado: o limite de pedidos da chave existe (veja Limites).

Espera crescente quando der erro

Se a API devolver 429, 503 ou 500, espere e tente de novo, dobrando a espera a cada falha, com um pouco de variação aleatória. Erro 4xx que não é 429 não melhora tentando de novo: corrija o pedido.

<?php
function consultar(string $id, int $max = 5): array {
    $espera = 1;
    for ($i = 1; $i <= $max; $i++) {
        $ch = curl_init("https://app.grinnypay.com/api/v1/charges/$id");
        curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10,
            CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GRINNY_KEY')]]);
        $corpo = curl_exec($ch);
        $http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        if ($http === 200) {
            return json_decode($corpo, true);
        }
        if (!in_array($http, [0, 429, 500, 503], true)) {
            throw new RuntimeException("Erro $http: não adianta repetir");
        }
        sleep($espera + random_int(0, 1)); // 1, 2, 4, 8 s (+ até 1 s)
        $espera *= 2;
    }
    throw new RuntimeException('API indisponível: tente na próxima rodada');
}

// Rotina: pedidos aguardando pagamento há mais de 2 minutos
foreach ($pedidosPendentes as $pedido) {
    $c = consultar($pedido['cobranca_id']);
    if ($c['status'] === 'pago') {
        liberarAcesso($pedido, $c); // a mesma função que o webhook usa, com a conferência de repetição
    } elseif ($c['status'] === 'expirado') {
        cancelarPedido($pedido);
    }
}

Idempotência: o mesmo pedido nunca vira dois

  • Ao criar: mande sempre Idempotency-Key com um código do seu pedido (ex.: pedido-1042). Se a conexão cair, repita com a mesma chave: você recebe a mesma cobrança, não outra. Veja Repetição segura.
  • Ao receber: grave o id do evento e a sequencia. Webhook e conciliação podem trazer o mesmo pagamento: o segundo a chegar não faz nada.
  • Ao liberar: a trava deve ser o status do pedido no seu banco (UPDATE ... WHERE status = 'aguardando'), não só a memória do processo.

Conferir o dinheiro

No fim do dia, some o liquido das cobranças pago do período (use status=pago na listagem) e compare com o que o seu sistema registrou. Diferença quase sempre é uma venda não tratada, um MED ou um reembolso. O saldo da conta está em GET /balance; o extrato completo está no painel, em Relatórios.

Ao achar uma venda pago que o seu sistema não tem, trate-a como um venda.aprovada atrasado e anote o motivo. Se acontece mais de uma vez, olhe o histórico de envios em Integrações › Webhooks: ali aparece o código que o seu servidor devolveu.