# 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)

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

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

## 5) Autenticar backend por api_key/api_secret

```bash
curl -X POST "https://pay.pangeialabs.com/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "SUA_API_KEY",
    "api_secret": "SEU_API_SECRET"
  }'
```

## 6) 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`.