# API KUBOFY

## Base URL
- `http://127.0.0.1:8000/api/v1` em ambiente local

## Autenticação
As rotas protegidas exigem:

```http
Authorization: Bearer {API_KEY}
X-Kubofy-Secret: {API_SECRET}
Accept: application/json
```

## Criar cobrança Pix
`POST /api/v1/pix/charges`

### Exemplo cURL
```bash
curl -X POST http://127.0.0.1:8000/api/v1/pix/charges \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Kubofy-Secret: {API_SECRET}" \
  -H "Accept: application/json" \
  -d "amount=120.50" \
  -d "description=Assinatura KUBOFY"
```

### Payload
```json
{
  "amount": 120.50,
  "currency": "BRL",
  "txid": "f8c8e9d2b6a04a3a9d4c",
  "description": "Assinatura KUBOFY",
  "expires_in": 900,
  "payer": {
    "name": "João Souza",
    "document": "123.456.789-00"
  }
}
```

## Consultar cobrança
`GET /api/v1/pix/charges/{txid}`

## Reembolso
`POST /api/v1/pix/charges/{txid}/refunds`

## Webhooks outbound
Quando um merchant registra um endpoint ativo, a KUBOFY envia POST assinado com:

```http
X-Kubofy-Event: pix.charge.created
X-Kubofy-Delivery: {uuid}
X-Kubofy-Signature: sha256={hmac}
Content-Type: application/json
```

### Body
```json
{
  "event": "pix.charge.created",
  "timestamp": "2026-04-22T08:30:00Z",
  "delivery_id": "uuid",
  "data": {
    "id": 10,
    "txid": "ABC123",
    "status": "created",
    "amount": "120.50",
    "currency": "BRL"
  }
}
```

### Eventos hoje emitidos pela aplicação
- `pix.charge.created`
- `pix.charge.refunded`

## Webhooks inbound de adquirente
`POST /api/webhooks/acquirer/{acquirer}`

Esse endpoint registra os eventos recebidos em `webhook_events`.