# Pangeia PAY API - Examples

Este arquivo traz exemplos práticos de uso dos endpoints documentados em `apidoc/openapi.yaml`.

## Base URL

- Produção: `https://pay.pangeialabs.com`
- Local: `http://localhost:5000`

## 1) Registrar cobrança (conta com PIX ativo)

> O request de `/registrar` não envia `payment_method`; a API define as opções pelo que está ativo na conta (`pix_enabled`, `bitcoin_enabled`, `outracoin_enabled`).

```bash
curl -X POST "https://pay.pangeialabs.com/registrar" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_name": "Joao da Silva",
    "buyer_taxid": "12345678901",
    "order_amount": 149.90,
    "order_id": "PED-10001",
    "api_key": "SUA_API_KEY",
    "redirect_url": "https://seusite.com/retorno"
  }'
```

Resposta esperada (201) para conta com somente PIX ativo:

```json
{
  "order_id": "PED-10001",
  "order_status": "pending",
  "payment_method": "pix",
  "allowed_payment_methods": ["pix"],
  "unique_amount": 149.87,
  "unique_id": "65f5b0b6c2ab1d8b8f6a1234",
  "url": "https://pay.pangeialabs.com/pagar/65f5b0b6c2ab1d8b8f6a1234",
  "pixcode": "...",
  "qrcode": "iVBORw0KGgoAAAANS..."
}
```

## 2) Registrar cobrança Bitcoin

> Este exemplo depende da conta estar com apenas `Bitcoin` ativo.

```bash
curl -X POST "https://pay.pangeialabs.com/registrar" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_name": "Maria Souza",
    "buyer_taxid": "98765432100",
    "order_amount": 250.00,
    "order_id": "PED-BTC-9001",
    "api_key": "SUA_API_KEY",
    "crypto_confirmations": 6
  }'
```

## 2.1) Registrar cobrança com múltiplos métodos (PIX + BTC + OUTRA)

> Para retornar múltiplas opções, ative `pix_enabled`, `bitcoin_enabled` e `outracoin_enabled` na conta.

```bash
curl -X POST "https://pay.pangeialabs.com/registrar" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_name": "Joao da Silva",
    "buyer_taxid": "12345678901",
    "order_amount": 149.90,
    "order_id": "PED-10002",
    "api_key": "SUA_API_KEY",
    "redirect_url": "https://seusite.com/retorno"
  }'
```

Resposta esperada (201) inclui:
- `allowed_payment_methods`
- `order_group_id`
- `checkout_options` (um link de checkout por método)
- `checkout_quote_snapshot` com equivalentes congelados no cadastro para os métodos cripto ativos (ex.: BTC/OUTRA)

## 3) Consultar status

```bash
curl "https://pay.pangeialabs.com/status/65f5b0b6c2ab1d8b8f6a1234"
```

Status possíveis no retorno de `GET /status/{unique_id}`:
- `pending`
- `confirming`
- `paid`
- `canceled`
- `processing`
- `shipped`
- `delivered`
- `expired` (status derivado por tempo de expiração, quando aplicável)

### Janelas de expiração

Duas janelas distintas, configuráveis via env vars no servidor:

- `MINUTES_TO_PAY` (padrão **30 min**): prazo mostrado ao comprador na tela de checkout. Depois disso, `GET /status/{unique_id}` já retorna `status: "expired"` — mas a transação **ainda está `pending`** no banco.
- `MINUTES_TO_EXPIRE` (padrão **60 min**): prazo real até o worker de expiração cancelar a transação (`order_status: "canceled"`) e liberar o `unique_amount` para reuso em outra cobrança. É só nesse momento que o IPN é enviado. **O worker só cancela transações ainda em `pending`** — uma transação em `confirming` (ex.: pagamento cripto já detectado, aguardando confirmações) não é auto-cancelada por tempo e fica pendente até ser resolvida por outro fluxo.

**`expired` nunca chega por IPN.** Não é persistido como `order_status` no banco — é só um valor calculado na hora pelo `GET /status/{unique_id}` enquanto a transação segue `pending`. O único IPN automático de "não pago a tempo" é `order_status: "canceled"`, disparado pelo worker de expiração depois de `MINUTES_TO_EXPIRE`. Não espere/trate um IPN com status `expired` na sua integração — ele não existe.

Ou seja, há uma folga de até 30 min entre o comprador ver "expirado" na tela e a cobrança ser efetivamente cancelada/o IPN de `canceled` chegar no backend do lojista.

## 4) Obter payload/QR da cobrança

```bash
curl "https://pay.pangeialabs.com/pixqrcode/65f5b0b6c2ab1d8b8f6a1234"
```

## 5) Payload de IPN que seu endpoint recebe

Quando uma cobrança muda de status, o Pangeia PAY envia `POST application/json` para a `ipn_url` da conta com este formato:

```json
{
  "order_id": "PIXIA-1772489488-3468fc7e",
  "order_status": "paid",
  "order_amount": 10.0,
  "unique_amount": 10.0,
  "ipn_secret": "SEU_IPN_SECRET_DA_CONTA",
  "paid_on": "2026-03-02T22:23:51.160000",
  "paid_with": "pix",
  "redirect_url": "https://seusite.com/retorno",
  "description": "Pedido XYZ"
}
```

Notas importantes:
- No comportamento atual, **não** há assinatura em header para esse IPN da conta.
- A validação recomendada é conferir `ipn_secret` do payload contra o secret salvo na sua integração.
- O campo de status enviado é `order_status` (não `status`).
- Sua integração deve aceitar qualquer transição de status a qualquer momento (sem restrição de máquina de estados), incluindo `paid -> canceled` e `canceled -> paid`.

Status possíveis em `order_status`:
- `pending`
- `confirming`
- `paid`
- `canceled`
- `processing`
- `shipped`
- `delivered`

Quando o IPN é disparado (comportamento atual):
- Eventos automáticos enviam principalmente `paid` (baixa PIX/cripto) e `canceled` (expiração sem pagamento).
- O dashboard também pode enviar qualquer status manualmente.
- Reenvios e mudanças de status são possíveis a qualquer momento; trate o IPN como evento de estado atual, sem supor progressão fixa.

## Notas de consistência operacional

- `/registrar` não lê mais `payment_method` do payload; as opções de checkout vêm da configuração da conta (`pix_enabled`, `bitcoin_enabled`, `outracoin_enabled`).
- `VALID_PAYMENT_METHODS` efetivo em runtime: `pix`, `bitcoin`, `outracoin`.