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

# Pix Out

> Envie transferências PIX programaticamente para qualquer chave PIX

O PIX OUT permite enviar transferências instantâneas para qualquer chave PIX de forma programática. Ideal para pagamentos a fornecedores, transferências para afiliados, estornos e qualquer situação onde você precisa enviar dinheiro.

## 🎯 Como Funciona

O PIX OUT funciona através do envio direto para chaves PIX, sem necessidade de dados bancários complexos:

<CardGroup cols={2}>
  <Card title="🔑 Chave PIX" color="#ff7e00" icon="key">
    Use qualquer tipo de chave: CPF, CNPJ, email, telefone ou aleatória
  </Card>

  <Card title="⚡ Transferência Instantânea" color="#ff7e00" icon="bolt">
    Dinheiro é transferido instantaneamente, 24/7
  </Card>

  <Card title="🔒 Segurança Total" color="#ff7e00" icon="shield-check">
    Validação automática de chaves e dados
  </Card>

  <Card title="📊 Confirmação Imediata" color="#ff7e00" icon="check-circle">
    Receba confirmação via webhook em tempo real
  </Card>
</CardGroup>

## 🛠️ Implementação Rápida

### 1. Enviar Transferência PIX

```bash theme={null}
curl -X POST 'https://api.avanttifinance.com/v1/pix/out/transfer' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -H 'X-Idempotency-Key: transfer_20241201_001' \
  -d '{
    "pixKey": "brunoribeirovale@gmail.com",
    "amount": 300,
    "password": "111111"
}'
```

### 2. Resposta de Sucesso

```json theme={null}
{
    "success": true,
    "data": {
        "id": "cmij05x240000ubhwgb0dd365",
        "companyId": "cmiivyxev0000hww1j9l4ckc8",
        "adquirenceId": 1,
        "status": "pending_analysis",
        "pixKey": "brunoribeirovale@gmail.com",
        "amount": 300,
        "netAmount": 275,
        "fees": 25,
        "providerFees": 0,
        "requestSource": "api",
        "type": "send_analysis",
        "method": "manual",
        "idempotencyKey": "local-cmij05x240000ubhwgb0dd365",
        "companyIdempotencyKey": "idempotencykey222222ssssssssssss2",
        "debtorAccount": null,
        "creditorAccount": null,
        "externalId": null,
        "endToendId": null,
        "requestedBy": null,
        "approvedBy": null,
        "refusedBy": null,
        "message": null,
        "description": "Transferência de R$3.00 para brunoribeirovale@gmail.com",
        "createdAt": "2025-11-28T15:13:45.629Z",
        "updatedAt": "2025-11-28T15:13:45.629Z",
        "processedAt": null
    }
}
```

### 3. Confirmação via Webhook

```json theme={null}
{
  "id": "wh_75g9b3c2d4e5f6g7h8i9j0k1",
  "type": "transfer",
  "event": "transfer_completed",
  "scope": "user",
  "transfer": {
    "id": "cln1a2b3c4567890defghijk",
    "amount": 150000,
    "status": "completed",
    "pix": {
      "endToEndId": "E87654321202412011145543210ZY987X",
      "creditorAccount": {
        "bank": "341",
        "branch": "1234",
        "account": "567890"
      }
    }
  }
}
```

## 🔑 Tipos de Chave PIX Suportados

### CPF e CNPJ

```bash theme={null}
# CPF (apenas números)
"pixKey": "12345678901"

# CNPJ (apenas números)  
"pixKey": "12345678000195"
```

### Email

```bash theme={null}
# Email válido
"pixKey": "pagamentos@empresa.com.br"
"pixKey": "joao.silva@gmail.com"
```

### Telefone

```bash theme={null}
# Formato: +5511999999999
"pixKey": "+5511987654321"
"pixKey": "+5521988888888"
```

### Chave Aleatória (EVP)

```bash theme={null}
# UUID gerado pelo banco
"pixKey": "123e4567-e89b-12d3-a456-426614174000"
"pixKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
```

## 📊 Parâmetros Detalhados

### Campos Obrigatórios

| Campo      | Tipo     | Descrição            |
| ---------- | -------- | -------------------- |
| `pixKey`   | `string` | Chave PIX de destino |
| `amount`   | `number` | Valor em centavos    |
| `password` | `string` | senha de transação   |

### Headers Importantes

| Header              | Obrigatório | Descrição                          |
| ------------------- | ----------- | ---------------------------------- |
| `Authorization`     | ✅           | Token Bearer                       |
| `Content-Type`      | ✅           | `application/json`                 |
| `X-Idempotency-Key` | 🔶          | Chave única para evitar duplicação |

<Warning>
  **Importante**: Use sempre o header `X-Idempotency-Key` para evitar transferências duplicadas acidentais.
</Warning>

## 📋 Status das Transferências

| Status       | Descrição                       | Tempo Esperado | Próximo Passo           |
| ------------ | ------------------------------- | -------------- | ----------------------- |
| `created`    | Transferência criada e validada | Imediato       | Aguardar processamento  |
| `processing` | Em processamento pelo sistema   | 1-3 segundos   | Aguardar conclusão      |
| `completed`  | Transferência concluída         | 3-10 segundos  | Transferência realizada |
| `canceled`   | Cancelada pelo sistema          | Imediato       | Verificar motivo        |
| `refused`    | Recusada pela instituição       | 5-15 segundos  | Verificar dados         |

## 🛡️ Segurança e Boas Práticas

### Validação de Chaves PIX

```javascript theme={null}
function validarChavePIX(chave) {
  // Remover espaços e caracteres especiais
  chave = chave.trim()
  
  // CPF (11 dígitos)
  if (/^\d{11}$/.test(chave)) {
    return validarCPF(chave)
  }
  
  // CNPJ (14 dígitos)
  if (/^\d{14}$/.test(chave)) {
    return validarCNPJ(chave)
  }
  
  // Email
  if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(chave)) {
    return true
  }
  
  // Telefone (+5511999999999)
  if (/^\+55\d{10,11}$/.test(chave)) {
    return true
  }
  
  // Chave aleatória (UUID)
  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(chave)) {
    return true
  }
  
  return false
}
```

### Controle de Concorrência

```javascript theme={null}
// Cache para evitar transferências duplicadas
const transferenciasEmAndamento = new Map()

async function enviarComControle(dados) {
  const chaveControle = `${dados.pixKey}_${dados.amount}`
  
  if (transferenciasEmAndamento.has(chaveControle)) {
    throw new Error('Transferência similar já em andamento')
  }
  
  try {
    transferenciasEmAndamento.set(chaveControle, true)
    const resultado = await enviarTransferencia(dados)
    return resultado
  } finally {
    transferenciasEmAndamento.delete(chaveControle)
  }
}
```

### Auditoria e Logs

```javascript theme={null}
function logarTransferencia(transferencia, status, detalhes = {}) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    transferId: transferencia.id,
    pixKey: transferencia.pixKey,
    amount: transferencia.amount,
    status: status,
    userId: transferencia.userId,
    ...detalhes
  }
  
  // Salvar no sistema de auditoria
  console.log('Transfer Log:', JSON.stringify(logEntry))
  
  // Enviar para sistema de monitoramento
  if (status === 'refused' || status === 'canceled') {
    alertSystem.notify('transfer_failed', logEntry)
  }
}
```

## 🚨 Tratamento de Erros

### Códigos de Erro Comuns

| Código | Erro               | Causa                 | Solução                        |
| ------ | ------------------ | --------------------- | ------------------------------ |
| `400`  | Chave PIX inválida | Formato incorreto     | Validar formato da chave       |
| `402`  | Saldo insuficiente | Não há saldo na conta | Verificar saldo disponível     |
| `422`  | Valor inválido     | Fora dos limites      | Verificar limites operacionais |
| `429`  | Rate limit         | Muitas requisições    | Implementar retry com delay    |

### Exemplo de Tratamento

```javascript theme={null}
async function enviarComTratamento(dados) {
  try {
    return await enviarTransferencia(dados)
  } catch (error) {
    switch (error.status) {
      case 400:
        throw new Error('Verifique os dados da transferência')
      case 402:
        throw new Error('Saldo insuficiente para realizar a transferência')
      case 422:
        throw new Error('Valor fora dos limites permitidos')
      case 429:
        // Aguardar e tentar novamente
        await new Promise(resolve => setTimeout(resolve, 1000))
        return await enviarTransferencia(dados)
      default:
        throw new Error('Erro interno. Tente novamente em alguns minutos.')
    }
  }
}
```

## 📊 Casos de Uso Comuns

### Pagamento a Fornecedores

```javascript theme={null}
async function pagarFornecedor(fornecedor, valorNota, numeroNF) {
  const transferencia = {
    pixKey: fornecedor.chavePix,
    amount: valorNota,
    description: `Pagamento NF ${numeroNF} - ${fornecedor.nome}`
  }
  
  return await enviarTransferencia(transferencia)
}
```

### Transferência para Afiliados

```javascript theme={null}
async function pagarAfiliado(afiliado, comissao, periodo) {
  const transferencia = {
    pixKey: afiliado.chavePix,
    amount: comissao,
    description: `Comissão ${periodo} - Afiliado ${afiliado.id}`
  }
  
  return await enviarTransferencia(transferencia)
}
```

### Estorno para Cliente

```javascript theme={null}
async function estornarCliente(cliente, valorEstorno, motivo) {
  const transferencia = {
    pixKey: cliente.chavePix,
    amount: valorEstorno,
    description: `Estorno: ${motivo}`
  }
  
  return await enviarTransferencia(transferencia)
}
```

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="📝 Enviar PIX" color="#ff7e00" icon="paper-plane" href="/pages/pix-out/send-pixkey">
    Guia detalhado para enviar transferências PIX
  </Card>

  <Card title="🔗 Configurar Webhooks" color="#ff7e00" icon="webhook" href="/webhook">
    Configure notificações de transferências
  </Card>

  <Card title="💰 PIX IN" color="#ff7e00" icon="qrcode" href="/pages/pix-in/overview">
    Aprenda a receber pagamentos PIX
  </Card>

  <Card title="📊 Monitoramento" color="#ff7e00" icon="chart-line" href="/pages/reference/status-codes">
    Monitore suas transferências
  </Card>
</CardGroup>