Como automatizar a conciliação financeira

1. Crie um link por pedido, com o ID em src

curl -X POST "$HEROPAY_API_URL/payment_links" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_link": {
      "name": "Pedido 4821",
      "price_cents": 29700,
      "absorbs_fees": true,
      "payment_methods": ["pix", "credit_card", "bank_slip"],
      "src": "pedido-4821"
    }
  }'

A resposta 201 devolve data.offer.url já com ?src=pedido-4821. Grave data.id no pedido. O src aceita letras, números e . _ - ~ até 255 caracteres, então use um formato previsível (pedido-4821, fatura_2026-09_1042).

Por que um link por pedido: o src é uma etiqueta do link, não um ID único de venda. Se o mesmo link atende vários compradores, cart.src diz a campanha, e a chave da transação passa a ser o payment_id.

2. Registre em tempo real pelo webhook

Cadastre spark_payment_confirmed, refunded e chargeback_request com POST /webhook (um cadastro por gatilho). Recorte dos campos que o handler usa (valores ilustrativos, campos reais do template; o payload completo está na documentação de webhooks):

{
  "payment": {
    "id": "8812345",
    "method": "credit_card",
    "net_value_cents": "28663"
  },
  "cart": { "src": "pedido-4821" }
}

No handler: valide X-HeroPay-Signature, busque o pedido por cart.src, grave payment.id e o líquido (net_value_cents) e marque status_conciliacao = "recebido_webhook". O bruto você já tem no pedido (é o price_cents do link), e o job diário do passo 3 confirma o valor cobrado. Trate os valores do payload como texto e converta para inteiro antes de somar. No exemplo, R$ 297 no cartão à vista pagam 3,49% (R$ 10,37) e entram R$ 286,63.

3. Rode o job diário de conferência

O webhook tem retentativa automática, mas nenhuma retentativa cobre um endpoint fora do ar por tempo indefinido. Todo dia, puxe as transações pagas de ontem:

curl -G "$HEROPAY_API_URL/transactions/by_status" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -d "status=paid" \
  -d "start_date=2026-09-22" \
  -d "end_date=2026-09-22" \
  -d "page=1" -d "items=100"

Resposta 200 (recorte do exemplo da OpenAPI):

{
  "data": {
    "data": [
      {
        "transaction_id": "645856_1756598",
        "cart": { "id": 9969670, "src": "pedido-4821", "utm": { "source": null } },
        "transaction": {
          "status": "paid",
          "created_at": "22/09/2026 22:48:10",
          "paid_at": "22/09/2026 22:49:29",
          "payment_id": 1756598,
          "payment_method": "PIX",
          "installments": 1,
          "total_amount": 72.8,
          "net_value": 70.2,
          "amount_paid_buyer": 72.8
        }
      }
    ],
    "pagination": { "current_page": 1, "total_pages": 1, "has_next_page": false }
  },
  "message": "Success"
}

Para cada item: ache o pedido por cart.src; se não houver registro do webhook, grave agora e marque recebido_job; se o valor divergir, marque divergente e alerte. Pagine até has_next_page ser false.

Duas pegadinhas desse endpoint, visíveis no próprio exemplo: valores vêm em reais com decimal (72.8), não em centavos como no resto da API, e datas vêm em DD/MM/AAAA HH:MM:SS, não em ISO 8601. Converta para centavos inteiros antes de comparar com o webhook, e cruze os dois lados por cart.src + valor.

Repita com status=refunded e status=chargeback para baixar estornos e disputas, e com status=waiting_payment para boletos e Pix em aberto.

4. Feche os totais e o caixa

Linha a linha resolve o pedido; o fechamento confere o total. Para o dia ou o mês:

curl -G "$HEROPAY_API_URL/reports/transaction/paid/net_value" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -d "start_date=2026-09-01" -d "end_date=2026-09-30"

Compare com a soma de valor_liquido do seu banco. /reports/transaction/paid/gross_revenue, /reports/transaction/paid/payment_method_distribution e /reports/transaction/refunded/refunded_chargeback_value completam o fechamento. Rode cada relatório uma vez no sandbox e confira o formato da resposta antes de automatizar a comparação; a lista completa está na documentação de relatórios.

O dinheiro fecha em duas chamadas: GET /financial/balance (saldo disponível e a receber, em centavos) e GET /financial/withdrawals (cada saque com amount_cents, fees_cents e status). O saque é o lançamento que aparece no extrato do seu banco: concilie o extrato contra essa lista, não contra as vendas.