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

# Ambiente Sandbox

> Teste sua integração com segurança sem fundos reais

## Visão Geral

O ambiente Sandbox da KillB permite que você teste sua integração sem processar transações reais ou movimentar fundos reais.

<Info>
  Todas as transações no sandbox usam dinheiro falso. Nenhum fundo real será transferido ou cobrado.
</Info>

## Ambientes

<Tabs>
  <Tab title="Sandbox (Teste)">
    **URL Base:** `https://sandbox.killb.app`

    **Recursos:**

    * Teste com dinheiro falso
    * Simule fluxos de pagamento
    * Verificação KYC real não é necessária
    * Processamento instantâneo de transações
    * Funcionalidade completa da API

    **Use para:**

    * Desenvolvimento e testes
    * Verificação de integração
    * Aplicações de demonstração
    * Testes CI/CD
  </Tab>

  <Tab title="Produção (Ao Vivo)">
    **URL Base:** `https://killb.app`

    **Recursos:**

    * Transações com dinheiro real
    * Verificação completa KYC/KYB
    * Processamento de pagamento real
    * Conformidade regulatória
    * Suporte de produção

    **Use para:**

    * Aplicações ao vivo
    * Transações de usuários reais
    * Implantações de produção
  </Tab>
</Tabs>

## Começando com o Sandbox

### Passo 1: Obter Credenciais do Sandbox

1. Cadastre-se em [otc.killb.com](https://otc.killb.com)
2. Navegue até **Configurações** → **Chaves de API**
3. Crie uma **Chave de API Sandbox**
4. Anote seu email e senha do sandbox

### Passo 2: Definir Variáveis de Ambiente

```bash .env theme={null}
KILLB_ENV=sandbox
KILLB_BASE_URL=https://sandbox.killb.app
KILLB_EMAIL=seu-email-sandbox@example.com
KILLB_PASSWORD=sua-senha-sandbox
KILLB_API_KEY=sua-chave-api-sandbox
```

### Passo 3: Autenticar

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/api/v2/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "seu-email-sandbox@example.com",
    "password": "sua-senha-sandbox"
  }'
```

## Recursos de Teste

### Endpoints Faker

O Sandbox fornece endpoints especiais para simular eventos de pagamento:

<AccordionGroup>
  <Accordion title="Cash-In Falso" icon="money-bill-wave" defaultOpen>
    Simule um usuário completando um pagamento fiat (PSE, SPEI, etc.)

    ```bash theme={null}
    POST /api/v2/faker/cash-in
    ```

    **Requisição:**

    ```json theme={null}
    {
      "rampId": "ramp-id-da-criacao"
    }
    ```

    **O que faz:**

    * Marca o cash-in como concluído
    * Aciona o processo de conversão
    * Move o ramp para o próximo status

    **Exemplo:**

    ```bash theme={null}
    curl --request POST \
      --url https://sandbox.killb.app/api/v2/faker/cash-in \
      --header 'Authorization: Bearer SEU_TOKEN_DE_ACESSO' \
      --header 'Content-Type: application/json' \
      --data '{"rampId": "seu-ramp-id"}'
    ```
  </Accordion>

  <Accordion title="Cash-Out Falso" icon="money-bill-transfer">
    Simule a conclusão da conversão cripto para fiat

    ```bash theme={null}
    POST /api/v2/faker/cash-out
    ```

    **Requisição:**

    ```json theme={null}
    {
      "rampId": "ramp-id-da-criacao"
    }
    ```

    **O que faz:**

    * Completa o processo de cash-out
    * Marca o ramp como COMPLETED
    * Aciona webhooks

    **Exemplo:**

    ```bash theme={null}
    curl --request POST \
      --url https://sandbox.killb.app/api/v2/faker/cash-out \
      --header 'Authorization: Bearer SEU_TOKEN_DE_ACESSO' \
      --header 'Content-Type: application/json' \
      --data '{"rampId": "seu-ramp-id"}'
    ```
  </Accordion>
</AccordionGroup>

## Fluxos de Teste

### Teste Completo de On-Ramp

<Steps>
  <Step title="Criar Usuário de Teste">
    Use qualquer dado com aparência válida - nenhuma verificação real no sandbox

    ```json theme={null}
    {
      "firstName": "Teste",
      "lastName": "Usuário",
      "email": "teste@example.com",
      "document": { "type": "PASSPORT", "number": "TEST123" }
    }
    ```
  </Step>

  <Step title="Criar Conta de Carteira">
    Use qualquer formato de endereço de carteira válido

    ```json theme={null}
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "network": "POLYGON",
      "currency": "USDC"
    }
    ```
  </Step>

  <Step title="Criar Cotação">
    Obtenha uma cotação de teste com taxas do sandbox
  </Step>

  <Step title="Criar Ramp">
    Execute a transação ramp
  </Step>

  <Step title="Simular Pagamento">
    Use `/api/v2/faker/cash-in` para simular o pagamento do usuário
  </Step>

  <Step title="Verificar Conclusão">
    Verifique se o status do ramp muda para COMPLETED
  </Step>
</Steps>

### Teste Completo de Off-Ramp

<Steps>
  <Step title="Criar Usuário de Teste">
    O mesmo que o fluxo de on-ramp
  </Step>

  <Step title="Criar Conta Bancária">
    Use detalhes bancários de teste

    ```json theme={null}
    {
      "type": "PSE",
      "accountNumber": "1234567890",
      "bankCode": "0001"
    }
    ```
  </Step>

  <Step title="Criar Cotação">
    Cotação de USDC para COP/MXN
  </Step>

  <Step title="Criar Ramp">
    Execute o ramp com fonte cripto
  </Step>

  <Step title="Simular Conclusão">
    Use `/api/v2/faker/cash-out` para completar o processo
  </Step>

  <Step title="Verificar Status">
    Confirme que o status é COMPLETED e os webhooks foram disparados
  </Step>
</Steps>

## Dados de Teste

### Contas Bancárias de Teste (Colômbia)

| Nome do Banco   | Código do Banco | Tipo de Conta      |
| --------------- | --------------- | ------------------ |
| Bancolombia     | 0001            | poupança, corrente |
| Banco de Bogotá | 0002            | poupança, corrente |
| Davivienda      | 0003            | poupança, corrente |

### Contas Bancárias de Teste (México)

| Nome do Banco | Código do Banco | Formato CLABE        |
| ------------- | --------------- | -------------------- |
| BBVA          | 012             | 012XXXXXXXXXXXXXXXXX |
| Santander     | 014             | 014XXXXXXXXXXXXXXXXX |
| Banorte       | 072             | 072XXXXXXXXXXXXXXXXX |

### Endereços de Carteira de Teste

```
Polygon (MATIC):
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Solana:
5FHwkrdxntdK24hgQU8qgBjn35Y1zwhz1GZwCkP4UJnC

Ethereum:
0x71C7656EC7ab88b098defB751B7401B5f6d8976F

Tron:
TXYZopYRdj2D9XRtbG4uXyrFPRw6sM3pjN
```

<Note>
  Estes são endereços de exemplo para testes. No sandbox, qualquer endereço formatado corretamente funcionará.
</Note>

## Limitações do Sandbox

<Warning>
  Esteja ciente destas diferenças entre sandbox e produção:
</Warning>

| Recurso                    | Sandbox        | Produção           |
| -------------------------- | -------------- | ------------------ |
| Dinheiro real              | ❌ Não          | ✅ Sim              |
| Verificação KYC            | ❌ Simulada     | ✅ Verificação real |
| Processamento de pagamento | ⚡ Instantâneo  | ⏱️ Tempo real      |
| Limites de transação       | ♾️ Sem limites | ✅ Baseado em KYC   |
| Webhooks                   | ✅ Sim          | ✅ Sim              |
| Limites de taxa da API     | 🔓 Relaxados   | 🔒 Aplicados       |

## Depuração no Sandbox

### Habilitar Log Detalhado

```javascript theme={null}
const DEBUG = process.env.KILLB_ENV === 'sandbox';

async function makeRequest(endpoint, options) {
  if (DEBUG) {
    console.log('Requisição:', endpoint, options);
  }
  
  const response = await fetch(endpoint, options);
  const data = await response.json();
  
  if (DEBUG) {
    console.log('Resposta:', data);
  }
  
  return data;
}
```

### Monitorar Status do Ramp

```javascript theme={null}
async function waitForRampCompletion(rampId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const ramp = await fetch(`/api/v2/ramps/${rampId}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    }).then(r => r.json());
    
    console.log(`Tentativa ${i + 1}: Status = ${ramp.status}`);
    
    if (ramp.status === 'COMPLETED') {
      return ramp;
    }
    
    if (['FAILED', 'CANCELED', 'REJECTED'].includes(ramp.status)) {
      throw new Error(`Ramp ${ramp.status}: ${ramp.details}`);
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  
  throw new Error('Timeout de conclusão do ramp');
}
```

## Mudando para Produção

Quando estiver pronto para ir ao vivo:

<Steps>
  <Step title="Atualizar URL Base">
    Mude de `teste-94u93qnn.uc.gateway.dev` para `killb.app`

    ```javascript theme={null}
    const baseUrl = 'https://killb.app';
    ```
  </Step>

  <Step title="Usar Credenciais de Produção">
    Substitua as credenciais do sandbox pelas chaves de API de produção
  </Step>

  <Step title="Remover Chamadas Faker">
    Remova todas as chamadas aos endpoints `/api/v2/faker/*`
  </Step>

  <Step title="Implementar KYC Real">
    Lide com verificação KYC real e uploads de documentos
  </Step>

  <Step title="Adicionar Tratamento de Erros">
    Implemente tratamento de erros e logs de nível de produção
  </Step>

  <Step title="Habilitar Monitoramento">
    Configure monitoramento e alertas para sua integração
  </Step>
</Steps>

## Lista de Verificação de Testes

Antes de ir para produção, teste estes cenários:

<AccordionGroup>
  <Accordion title="Caminho Feliz" icon="check">
    * [ ] Criação de usuário e KYC
    * [ ] Criação de conta (banco e carteira)
    * [ ] Geração de cotação
    * [ ] Conclusão de on-ramp
    * [ ] Conclusão de off-ramp
    * [ ] Recepção de webhook
    * [ ] Geração de recibo
  </Accordion>

  <Accordion title="Cenários de Erro" icon="xmark">
    * [ ] Tratamento de cotação expirada
    * [ ] Detalhes de conta inválidos
    * [ ] Saldo insuficiente
    * [ ] Simulação de pagamento com falha
    * [ ] Erros de rede
    * [ ] Expiração de token
    * [ ] Assinaturas de webhook inválidas
  </Accordion>

  <Accordion title="Casos Extremos" icon="flask">
    * [ ] Valores muito pequenos (\< \$1)
    * [ ] Valores muito grandes (> \$10,000)
    * [ ] Transações concorrentes
    * [ ] Limitação de taxa
    * [ ] Prevenção de duplicatas (externalId)
    * [ ] Múltiplas contas por usuário
  </Accordion>
</AccordionGroup>

## Precisa de Ajuda?

<CardGroup cols={1}>
  <Card title="Suporte por email" icon="envelope" href="mailto:tech@killb.com">
    Entre em contato com nossa equipe
  </Card>
</CardGroup>