> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavropay.online/llms.txt
> Use this file to discover all available pages before exploring further.

# llms.txt (Guia para Modelos de IA & Agentes)

> Contexto oficial, padronizado e exaustivo da API KavroPay para agentes autônomos, Cursor, Claude e ChatGPT.

> Este documento foi estruturado especificamente para modelos de linguagem (LLMs), agentes de desenvolvimento (Cursor, Windsurf, Claude Code, GitHub Copilot) e automações que precisam de instruções concisas, inequívocas e completas para integrar pagamentos PIX com a KavroPay.
>
> **Versão raw disponível para download e scraping direto em:** [`https://api.kavropay.online/llms.txt`](https://api.kavropay.online/llms.txt)

***

## 1. Visão Geral & Especificações Técnicas

| Item                | Especificação Oficial                                                           |
| :------------------ | :------------------------------------------------------------------------------ |
| **Nome**            | KavroPay API v1                                                                 |
| **Base URL**        | `https://api.kavropay.online/v1`                                                |
| **Protocolo**       | RESTful JSON sobre HTTPS (TLS 1.3 obrigatório)                                  |
| **Autenticação**    | Header `Authorization: Bearer sk_live_...` ou `x-api-key: sk_live_...`          |
| **Tempo Médio PIX** | Sub-segundo (\< 800ms) para retorno do QR Code e código Copia e Cola            |
| **Idempotência**    | Suporte via header `Idempotency-Key` (TTL 24 horas)                             |
| **Rate Limit**      | 120 requisições por minuto por chave/empresa (com bypass de webhooks bancários) |
| **Split Payments**  | Suporte nativo a multi-recebedores por porcentagem e valor fixo                 |

***

## 2. Autenticação e Cabeçalhos

Todas as requisições autenticadas devem enviar:

```http theme={null}
Authorization: Bearer sk_live_SUA_CHAVE_AQUI
Content-Type: application/json
```

Header alternativo aceito:

```http theme={null}
x-api-key: sk_live_SUA_CHAVE_AQUI
```

Para criação de cobranças e saques, envie sempre uma chave de idempotência para evitar duplicidade em timeouts:

```http theme={null}
Idempotency-Key: ped_98124_tentativa_1
```

***

## 3. Formato de Valores Financeiros & Taxas

### Formato de Envio

A API aceita duas formas de especificar valores monetários:

1. **String Decimal em Reais (`amount`)**:
   * Sempre com **duas casas decimais**: `"10.00"` para R\$ 10,00 ou `"0.50"` para 50 centavos.
   * Números inteiros diretos no campo amount (como `10`) retornam erro 400 exigindo casas decimais.
2. **Inteiro em Centavos (`amountCents` ou `amount_cents`)**:
   * `1000` para R$ 10,00 ou `50` para R$ 0,50.

### Estrutura de Taxas Padrão

* \*\*Até R$ 100,00**: 0,99% (99 bps) + R$ 0,50 fixos.
* \*\*Acima de R$ 100,00**: **2,99% (299 bps)** + R$ 0,50 fixos.

***

## 4. Endpoints Principais da API

### 4.1. Cobranças PIX (Inbound)

#### Criar Cobrança PIX (com Split Opcional)

* **Rota**: `POST https://api.kavropay.online/v1/charges` (ou `POST /v1/payments`)
* **Escopo**: `payments:write`
* **Body JSON**:
  ```json theme={null}
  {
    "amount": "150.00",
    "description": "Assinatura Mensal #1029",
    "externalId": "pedido_1029",
    "expiresInMinutes": 30,
    "payment_link": true,
    "customer": {
      "name": "Carlos Eduardo",
      "document": "12345678909",
      "email": "carlos@email.com",
      "phone": "11987654321"
    },
    "split": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage": 20,
        "chargeProcessingFee": false,
        "description": "Comissão Parceiro"
      }
    ],
    "notification_url": "https://seu-servidor.com/webhook"
  }
  ```
* **Campos do pagador (`customer`)**: Opcionais. Se omitidos, a KavroPay preenche fallbacks inteligentes e seguros automaticamente para compatibilidade bancária instantânea.
* **Resposta Sucesso (HTTP 201 Created)**:
  ```json theme={null}
  {
    "id": "PAY048E35EA7272EB1AC328AA",
    "amount": 150.00,
    "fee": 4.99,
    "net": 145.01,
    "status": "waiting_payment",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY048E35EA7272EB1AC328AA...",
    "qr_code_base64": "data:image/svg+xml;base64,...",
    "payment_url": "https://pay.kavropay.online/p/pag_048e35ea7272eb1ac328aa",
    "split": {
      "totalNet": 145.01,
      "originator": {
        "companyId": "a0000000-0000-0000-0000-000000000001",
        "net": 115.01
      },
      "recipients": [
        {
          "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
          "recipientName": "Loja Parceira",
          "amount": 30.00,
          "net": 30.00,
          "status": "pending"
        }
      ]
    },
    "externalId": "pedido_1029",
    "expires_at": "2026-09-28T14:00:00.000Z",
    "created_at": "2026-09-28T13:00:00.000Z"
  }
  ```

#### Consultar Cobrança PIX

* **Rota**: `GET https://api.kavropay.online/v1/charges/:id`
* **Escopo**: `payments:read`
* O parâmetro `:id` aceita tanto o ID KavroPay (`PAY...`) quanto o seu `externalId`.

#### Cancelar Cobrança PIX

* **Rota**: `POST https://api.kavropay.online/v1/charges/:id/cancel`
* **Escopo**: `payments:write`

***

### 4.2. Split de Pagamentos (Multi-Recebedores)

#### Simular / Calcular Split

* **Rota**: `POST https://api.kavropay.online/v1/splits/calculate`
* **Escopo**: `payments:read`
* **Body JSON**:
  ```json theme={null}
  {
    "amount": "150.00",
    "split": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage": 20
      }
    ]
  }
  ```

#### Listar Extrato de Splits

* **Rota**: `GET https://api.kavropay.online/v1/splits?role=all&page=1&limit=20`
* **Escopo**: `payments:read`

#### Detalhes do Split de uma Cobrança

* **Rota**: `GET https://api.kavropay.online/v1/splits/:transactionId`
* **Escopo**: `payments:read`

***

### 4.3. Status Unificado (Polling Ultra-Rápido \< 10ms)

* **Rota**: `GET https://api.kavropay.online/v1/status?idtransaction=PAY048E35EA7272EB1AC328AA`
* **Alternativa**: `POST https://api.kavropay.online/v1/status` com `{"idtransaction": "PAY..."}`
* **Escopo**: `payments:read`

***

### 4.4. Saques PIX (Cashout / Outbound)

#### Solicitar Saque

* **Rota**: `POST https://api.kavropay.online/v1/withdrawals`
* **Escopo**: `withdrawals:write`
* **Tipos de chave aceitos**: `CPF`, `CNPJ`, `EMAIL`, `TELEFONE` (ou `PHONE`), `EVP` (ou `RANDOM`).

***

### 4.5. Saldo da Conta

* **Rota**: `GET https://api.kavropay.online/v1/balance`
* **Escopo**: `payments:read`

***

### 4.6. Webhooks em Tempo Real

A KavroPay despacha eventos via POST para as URLs configuradas:

* `charge.paid`: Cobrança liquidada no Banco Central (saldo creditado e splits rateados atomicamente).
* `charge.expired`: Cobrança expirou sem pagamento.
* `withdrawal.completed`: Saque transferido com sucesso para a chave destinatária.
* `withdrawal.failed`: Saque rejeitado pelo banco receptor (saldo e taxa estornados automaticamente).

***

## 5. Tabela de Status & Códigos HTTP

### Status de Transação

* Cobrança: `waiting_payment` (aguardando), `paid` (paga), `expired` (expirada), `cancelled` (cancelada).
* Saque: `pending` (em fila), `processing` (em liquidação), `completed` / `paid_out` (concluído), `failed` (rejeitado/estornado).

### Códigos de Erro HTTP

* `400 Bad Request`: Erro de validação de payload (ex: amount como inteiro sem amountCents, ou soma de splits > 100%).
* `401 Unauthorized`: Chave de API ausente ou inválida.
* `402 Payment Required`: Saldo insuficiente para saque.
* `403 Forbidden`: Chave de API sem escopo para a rota solicitada.
* `404 Not Found`: Registro não localizado.
* `429 Too Many Requests`: Cota de 120 req/min ultrapassada (consulte header `Retry-After`).
* `500 Server Error`: Instabilidade transitória com failover automático de gateway.