# GeradorPix API B2B

Documentação oficial: https://docs.geradorpix.com/
OpenAPI 3.1: https://docs.geradorpix.com/openapi.json
Base URL: https://api.geradorpix.com/api/v1

## Segurança

A API é somente server-to-server. Nunca exponha Public Key, Secret Key ou segredo de webhook em frontend, aplicativo público, repositório, logs, analytics ou mensagens de erro. Leia as credenciais de variáveis de ambiente.

Headers obrigatórios em todas as rotas, inclusive GET e DELETE:

- User-Agent: GeradorPixB2B/1.0
- Accept: application/json
- Content-Type: application/json
- X-GPix-Public-Key: <GPIX_PUBLIC_KEY>
- X-GPix-Secret-Key: <GPIX_SECRET_KEY>

## Operações

1. POST /pix — gerar cobrança Pix.
2. GET /pix?limit=20 — listar histórico; limite de 1 a 50.
3. GET /pix/{id} — consultar cobrança por UUID.
4. DELETE /pix/{id} — remoção lógica e idempotente.
5. POST /pix/{id}/paid — marcar manualmente como PAGO.
6. POST /pix/{id}/pending — retornar manualmente para PENDENTE.
7. GET /reports/paid-summary — totais PAGO do dia, mês e ano em America/Sao_Paulo.

POST /pix exige Idempotency-Key de 1 a 128 caracteres no formato ^[A-Za-z0-9][A-Za-z0-9._:-]*$. Reutilize a mesma chave e exatamente o mesmo body nos retries da mesma intenção.

Body de POST /pix:

    {
      "mode": "chave_pix",
      "amount": "49.90",
      "description": "Pedido 1842",
      "external_reference": "pedido-1842"
    }

mode aceita chave_pix ou personalizado. amount é string maior que zero no formato ^\d{1,10}\.\d{2}$. description aceita 1–80 caracteres e external_reference 1–120. Não envie campos extras, chave Pix, banco, gateway ou credenciais no body. A seleção do recurso é automática.

Sucesso usa {"ok":true,"data":{},"request_id":"uuid"}. Erro usa {"ok":false,"error":{"code":"...","message":"...","details":{}},"request_id":"uuid"}. Trate 400, 401, 403, 404, 406, 409, 413, 415, 422, 429, 500, 502 e 503. Em 429 respeite Retry-After e os headers X-RateLimit-*.

## Webhooks

Eventos: pix.created, pix.paid, pix.unpaid e pix.deleted. Leia o corpo bruto e valide em tempo constante:

    signed = timestamp + "." + raw_body
    expected = "sha256=" + HMAC_SHA256(GPIX_WEBHOOK_SECRET, signed)

Headers: X-GPix-Event, X-GPix-Event-Id, X-GPix-Webhook-Timestamp, X-GPix-Webhook-Signature e X-GPix-Public-Key. Deduplicate por event_id. webhook.test com data.test=true é apenas teste operacional.

PAGO é uma marcação manual da integração ou operador. Não representa liquidação, confirmação bancária ou comprovante automático.