# KavroPay API - Contexto Oficial para Modelos de IA e Agentes Autônomos
# Versão da API: v1
# Base URL Primária: https://api.kavropay.com.br/v1
# Base URL Legada (em transição): https://api.kavropay.online/v1
# Documentação Web Oficial: https://docs.kavropay.com.br (e https://docs.kavropay.online)

> KavroPay é uma plataforma de pagamentos de alta performance especializada em PIX instantâneo no Brasil (Inbound e Outbound), equipada com motor de roteamento inteligente multi-adquirente, split payments automático entre múltiplos recebedores, conciliação em tempo real e verificação de status com latência inferior a 10ms.

---

## 1. Padrões de Autenticação e Cabeçalhos HTTP

Todas as chamadas à API devem ser feitas via HTTPS e autenticadas.

- Header Padrão: `Authorization: Bearer sk_live_...` (ou `Bearer sk_test_...` em Sandbox)
- Header Alternativo: `x-api-key: sk_live_...`
- Content-Type: `application/json` (obrigatório para requisições POST, PUT e PATCH)
- Idempotência: `Idempotency-Key: <UUID_v4>` (recomendado para prevenir cobranças ou saques duplicados em caso de retentativa de rede)

### Escopos de Chave de API
- `payments:write`: Criar cobranças PIX, links de checkout, simular splits e criar clientes.
- `payments:read`: Consultar cobranças, extrato de splits, status unificado, saldo e histórico de clientes.
- `withdrawals:write`: Criar solicitações de saque/transferência PIX externa.
- `withdrawals:read`: Consultar histórico e status de saques efetuados.

---

## 2. Regra Crítica: Formato de Valores Financeiros & Taxas

### Formato de Envio
A API KavroPay suporta dois formatos de envio de valor nas rotas POST /v1/charges e POST /v1/withdrawals:

1. **Decimal em String (Recomendado)**:
   - Campo: `amount`
   - Tipo: string com exatamente 2 casas decimais separadas por ponto.
   - Exemplo: `"amount": "49.90"` ou `"amount": "150.00"`
   - IMPORTANTE: Enviar `amount: 10` como inteiro puro causará erro HTTP 400.

2. **Centavos em Inteiro**:
   - Campo: `amountCents`
   - Tipo: integer positivo representando centavos.
   - Exemplo: `"amountCents": 4990` (equivale a R$ 49,90) ou `"amountCents": 15000` (R$ 150,00).

### 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 (reduzido de 3,99% para 2,99%).

---

## 3. Endpoints Principais (API Reference)

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

#### POST /v1/charges
Gera uma cobrança PIX com QR Code dinâmico, código Copia e Cola, link de checkout opcional e split automático.
Escopo: `payments:write`

Payload Completo com Split:
```json
{
  "amount": "150.00",
  "description": "Pedido Marketplace #10293",
  "externalId": "PED-10293",
  "expiresInMinutes": 30,
  "payment_link": true,
  "customer": {
    "name": "Maria Silva",
    "document": "12345678909",
    "email": "maria@email.com",
    "phone": "11988887777"
  },
  "split": [
    {
      "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "percentage": 20,
      "chargeProcessingFee": false,
      "description": "Comissão Vendedor Parceiro"
    },
    {
      "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
      "amount": "15.00",
      "chargeProcessingFee": true,
      "description": "Logística e Frete"
    }
  ]
}
```

Resposta de Sucesso (HTTP 201):
```json
{
  "id": "PAY8F7A1B2C3D4E5F6G",
  "amount": 150.00,
  "fee": 4.99,
  "net": 145.01,
  "status": "waiting_payment",
  "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUg...",
  "payment_link": "https://pay.kavropay.com.br/p/PAY8F7A1B2C3D4E5F6G",
  "split": {
    "totalNet": 145.01,
    "originator": {
      "companyId": "a0000000-0000-0000-0000-000000000001",
      "companyName": "Minha Empresa",
      "net": 100.51
    },
    "recipients": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "recipientName": "Vendedor Parceiro",
        "type": "percentage",
        "percentage": 20,
        "amount": 30.00,
        "fee": 0.00,
        "net": 30.00,
        "chargeProcessingFee": false,
        "description": "Comissão Vendedor Parceiro",
        "status": "pending"
      },
      {
        "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
        "recipientName": "Co-produtor",
        "type": "percentage",
        "percentage": 10,
        "amount": 15.00,
        "fee": 0.50,
        "net": 14.50,
        "chargeProcessingFee": true,
        "description": "Comissão Co-produtor",
        "status": "pending"
      }
    ]
  },
  "expires_at": "2026-09-28T14:00:00.000Z",
  "created_at": "2026-09-28T13:00:00.000Z",
  "externalId": "PED-10293"
}
```

#### GET /v1/charges/{id}
Consulta os dados, status e split de uma cobrança por ID interno (PAY...) ou externalId.
Escopo: `payments:read`

#### POST /v1/charges/{id}/cancel
Cancela uma cobrança pendente e invalida o QR Code associado.
Escopo: `payments:write`

---

### 3.2. Split Payments (Divisão de Recebíveis)

#### POST /v1/splits/calculate
Simula e calcula exatamente a partilha financeira de uma cobrança antes de gerá-la.
Escopo: `payments:read`

Payload de Simulação:
```json
{
  "amount": "150.00",
  "split": [
    {
      "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "percentage": 20
    }
  ]
}
```

#### GET /v1/splits
Lista o histórico de splits enviados ou recebidos pela empresa autenticada.
Query params: `role` ('all', 'originator', 'recipient'), `page`, `limit`.
Escopo: `payments:read`

#### GET /v1/splits/{transactionId}
Obtém o detalhamento de rateio de uma transação específica.
Escopo: `payments:read`

---

### 3.3. Verificação de Status Ultrarrápida (< 10ms)

#### GET /v1/status?idtransaction=PAY...
#### POST /v1/status {"idtransaction": "PAY..."}
Consulta ultra-otimizada diretamente em cache de alta velocidade para confirmação imediata de checkout ou polling de tela. Funciona tanto para cobranças (`PAY...`) quanto para saques (`WIT...`) ou `externalId`.
Escopo: `payments:read`

---

### 3.4. Saques e Transferências PIX (Outbound)

#### POST /v1/withdrawals
Transfere saldo disponível para uma chave PIX externa.
Escopo: `withdrawals:write`

Tipos de Chave Suportados (`pix_key_type`):
- `CPF`: 11 dígitos numéricos
- `CNPJ`: 14 dígitos numéricos
- `EMAIL`: endereço de e-mail válido
- `TELEFONE` ou `PHONE`: DDD + número (ex: `11999998888`)
- `EVP` ou `RANDOM`: chave aleatória UUID

#### GET /v1/withdrawals/{id}
Consulta o estado de liquidação do saque (`pending`, `processing`, `paid_out`, `failed`).
Escopo: `withdrawals:read`

---

### 3.5. Consulta de Saldo da Conta

#### GET /v1/balance
Escopo: `payments:read`

Resposta:
```json
{
  "available": 3450.00,
  "blocked": 0.00,
  "currency": "BRL"
}
```

---

### 3.6. Gestão de Clientes (Customers API)

- `POST /v1/customers`: Cadastrar cliente (`name`, `email`, `document`, `phone`, `country`).
- `GET /v1/customers`: Listar clientes cadastrados (`page`, `limit`, `search`).
- `GET /v1/customers/{id}`: Obter detalhes de um cliente.
- `PATCH /v1/customers/{id}`: Atualizar dados cadastrais.
- `DELETE /v1/customers/{id}`: Remover cliente.

---

### 3.7. Subcontas & Gestão White-label (Subaccounts API)

A KavroPay suporta nativamente tanto as rotas no plural `/v1/subaccounts/*` quanto no singular `/v1/subaccount/*` para máxima flexibilidade de integração da sua plataforma.
Escopos: `payments:write`, `payments:read`.

#### Visão Geral e Métricas Consolidadas:
- `GET /v1/subaccounts/summary`: Resumo financeiro consolidado de todas as subcontas da conta Master (total de contas ativas/bloqueadas, saldo consolidado total disponível e bloqueado, volume total processado e sacado).

#### Gestão de Subcontas:
- `POST /v1/subaccounts`: Criar subconta (`name`, `document`, `email`, `phone`, `externalReference`, `markupFixed`, `markupPercent`, `withdrawalFee`, `dailyLimit`, `maxTransaction`, `webhookUrl`, `metadata`).
- `GET /v1/subaccounts`: Listar subcontas da conta Master (`page`, `limit`, `search`, `status`).
- `GET /v1/subaccounts/{id}`: Obter detalhes cadastrais da subconta (aceita UUID ou `externalReference`).
- `GET /v1/subaccounts/{id}/balance`: Consultar saldo específico da subconta (`available`, `availableCents`, `locked`, `lockedCents`, `currency`).
- `PUT /v1/subaccounts/{id}`: Atualizar dados cadastrais e webhook da subconta.
- `DELETE /v1/subaccounts/{id}`: Excluir subconta (protegida: bloqueia exclusão se houver saldo positivo > 0).

#### Transferências Internas (Double-Entry Ledger):
- `POST /v1/subaccounts/{id}/add-balance`: Aporte da Master para Subconta (`amount`, `description`).
- `POST /v1/subaccounts/{id}/remove-balance`: Resgate da Subconta para Master (`amount`, `description`).
- `POST /v1/subaccounts/transfer`: Transferência direta entre subcontas (`sourceSubaccountId`, `targetSubaccountId`, `amount`, `description`).

#### Precificação, Markup Spread & Margem da Master:
- `PUT /v1/subaccounts/{id}/pricing`: Definir taxas da subconta (`markupFixed`, `markupPercent`, `withdrawalFee`). O lucro de spread é creditado automaticamente na Master em cada PIX pago.
- `GET /v1/subaccounts/{id}/pricing`: Consultar margem de lucro e taxas vigentes da subconta.

#### Travas Operacionais & Limites:
- `POST /v1/subaccounts/{id}/lock`: Pausar operações da subconta.
- `POST /v1/subaccounts/{id}/unlock`: Desbloquear subconta.
- `PUT /v1/subaccounts/{id}/limits`: Configurar limites (`dailyLimit`, `monthlyLimit`, `maxTransaction`).

#### Cobranças, Saques e Extratos da Subconta:
- Cobrança PIX para Subconta: Incluir `subaccountId` (ou `subaccount_id`) no payload de `POST /v1/charges`.
- Saque PIX de Subconta: Incluir `subaccountId` (ou `subaccount_id`) no payload de `POST /v1/withdrawals`.
- `GET /v1/subaccounts/{id}/charges`: Listar cobranças PIX emitidas especificamente para esta subconta (`page`, `limit`, `status`).
- `GET /v1/subaccounts/{id}/withdrawals`: Listar saques solicitados especificamente por esta subconta (`page`, `limit`, `status`).
- `GET /v1/subaccounts/{id}/statement`: Extrato contábil auditado de movimentações da subconta (partida dobrada).

---

## 4. Webhooks e Assinatura Criptográfica

A KavroPay envia notificações automáticas em tempo real para as URLs cadastradas.

### Cabeçalhos de Segurança no Webhook:
- `x-kavro-signature`: Hash HMAC-SHA256 gerado a partir do corpo bruto (raw body) da requisição utilizando a sua chave secreta como segredo.
- `x-kavro-event`: Nome do evento disparado (ex: `charge.paid`).

### Verificação de Assinatura em Node.js:
```javascript
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secretKey) {
  const calculated = crypto.createHmac('sha256', secretKey).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(calculated));
}
```

---

## 5. Dicionário de Status

### Cobranças PIX (Inbound):
- `waiting_payment`: Aguardando pagamento pelo pagador.
- `paid`: Liquidado e confirmado com sucesso. Saldo liberado na conta (e splits distribuídos atomicamente).
- `expired`: Expirado sem pagamento.
- `cancelled`: Cancelado manualmente antes do vencimento.

### Saques PIX (Outbound):
- `pending`: Em fila para processamento.
- `processing`: Em transmissão pelo adquirente / Banco Central.
- `paid_out` ou `completed`: Concluído e creditado na conta de destino.
- `failed`: Falha na liquidação; valor estornado integralmente para o saldo.

---

## 6. Códigos de Erro HTTP Comuns

- `400 Bad Request`: Parâmetro inválido (ex: amount como inteiro não-string sem amountCents, ou soma de splits > 100%).
- `401 Unauthorized`: API Key ausente, expirada ou inválida.
- `402 Payment Required`: Saldo insuficiente para efetuar o saque.
- `403 Forbidden`: API Key não tem o escopo exigido para a rota.
- `404 Not Found`: Transação, empresa ou recurso não encontrado.
- `429 Too Many Requests`: Limite de requisições excedido (120 req/min). Respeite o header Retry-After.
- `500 / 502 / 503`: Falha temporária em adquirente. A KavroPay faz failover automático para gateways redundantes.