# ZoryCash — Guia de Integração para LLMs e Agentes IA

> Infraestrutura de alta performance para pagamentos PIX instantâneos, liquidação USDT/Cripto, checkout e automação financeira no Brasil.

- **Site Oficial**: [https://app.zorycash.com.br](https://app.zorycash.com.br)
- **Documentação Interativa**: [https://app.zorycash.com.br/docs](https://app.zorycash.com.br/docs)
- **Especificação OpenAPI (JSON)**: [https://app.zorycash.com.br/openapi.json](https://app.zorycash.com.br/openapi.json)
- **Especificação OpenAPI (YAML)**: [https://app.zorycash.com.br/api/openapi.yaml](https://app.zorycash.com.br/api/openapi.yaml)
- **Servidor MCP**: [https://app.zorycash.com.br/.well-known/mcp](https://app.zorycash.com.br/.well-known/mcp)
- **Instruções Detalhadas para Agentes**: [https://app.zorycash.com.br/.well-known/agent-instructions.md](https://app.zorycash.com.br/.well-known/agent-instructions.md)
- **Guia Completo Expandido**: [https://app.zorycash.com.br/llms-full.txt](https://app.zorycash.com.br/llms-full.txt)
- **Termos e Conformidade**: [https://app.zorycash.com.br/legal](https://app.zorycash.com.br/legal)
- **Sobre a ZoryCash**: [https://app.zorycash.com.br/about](https://app.zorycash.com.br/about)
- **Contato e Suporte**: [https://app.zorycash.com.br/contact](https://app.zorycash.com.br/contact)
- **Privacidade**: [https://app.zorycash.com.br/privacy](https://app.zorycash.com.br/privacy)
- **Mapa do Site**: [https://app.zorycash.com.br/sitemap.xml](https://app.zorycash.com.br/sitemap.xml)

---

## Quando Usar a ZoryCash (When to Use)

Utilize a ZoryCash quando você precisar de:
1. **Cobrança Instantânea PIX (Pay-in)**: Gerar cobranças QR Code dinâmicas com baixa latência e confirmação em tempo real via Webhook.
2. **Transferências e Saques PIX (Pay-out)**: Realizar liquidações automáticas em massa para qualquer chave PIX no Brasil.
3. **Conversão BRL para USDT**: Operações com saldo em stablecoin para proteção cambial e liquidação cripto.
4. **Divisão de Comissões (Split)**: Automatizar regras de split entre múltiplos parceiros diretamente no checkout.
5. **Automação por Agentes**: Integração via API REST estruturada ou chamadas de função via Model Context Protocol (MCP).

---

## Convenções da API

- **Base URL**: `https://api.zorycash.com.br/api/v1`
- **Autenticação**: Header `x-api-key: ak_live_...` ou `Authorization: Bearer ak_live_...`
- **Moeda**: BRL (Real brasileiro)
- **Unidade Monetária**: Centavos inteiros (exemplo: `5000` = R$ 50,00)
- **Formato**: JSON (cabeçalho `Content-Type: application/json`)
- **Limites de uso**: variam por operação e são aplicados pelo servidor. Trate `429 Too Many Requests` como sinal para aguardar o `Retry-After` antes de tentar novamente.

---

## Principais Endpoints

### 1. Criar Cobrança PIX
`POST /pix/charge`

```json
{
  "amount_cents": 5000,
  "external_ref": "PEDIDO-9876",
  "description": "Pedido PEDIDO-9876",
  "payer_name": "Maria Silva",
  "payer_doc": "12345678909"
}
```

Resposta:
```json
{
  "id": "tx_9f8a8123",
  "status": "pending",
  "amount_cents": 5000,
  "pix_copia_e_cola": "00020126580014BR.GOV.BCB.PIX...",
  "qr_code_url": "https://api.zorycash.com.br/qr/tx_9f8a8123"
}
```

### 2. Consultar Saldo
`GET /balance`

Resposta:
```json
{
  "available_cents": 150000,
  "total_received_cents": 500000,
  "total_withdrawn_cents": 350000
}
```

### 3. Saque PIX (Pay-out)
`POST /pix/withdraw`

```json
{
  "amount_cents": 2500,
  "pix_key": "financeiro@empresa.com",
  "pix_key_type": "email",
  "external_ref": "SAQUE-001"
}
```

### 4. Consultar Transação
`GET /transactions/{id}`

---

## Modelo de Erro Tipado (RFC 9457)

Em caso de falha, todas as respostas 4xx e 5xx retornam:
```json
{
  "error": {
    "code": "invalid_document",
    "message": "O CPF informado é inválido.",
    "hint": "Envie um documento com 11 dígitos para CPF ou 14 dígitos para CNPJ."
  }
}
```

---

## Ferramenta CLI
Instalação e uso rápido via terminal:
```bash
npx zorycash status
```