> ## 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

> Prueba tu integración de forma segura sin fondos reales

## Visión General

El ambiente Sandbox de KillB te permite probar tu integración sin procesar transacciones reales o mover fondos reales.

<Info>
  Todas las transacciones en sandbox usan dinero falso. No se transferirán ni cobrarán fondos reales.
</Info>

## Ambientes

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

    **Características:**

    * Prueba con dinero falso
    * Simula flujos de pago
    * Verificación KYC real no requerida
    * Procesamiento instantáneo de transacciones
    * Funcionalidad completa de la API

    **Usar para:**

    * Desarrollo y pruebas
    * Verificación de integración
    * Aplicaciones de demostración
    * Pruebas CI/CD
  </Tab>

  <Tab title="Producción (En Vivo)">
    **URL Base:** `https://killb.app`

    **Características:**

    * Transacciones con dinero real
    * Verificación completa KYC/KYB
    * Procesamiento de pago real
    * Cumplimiento regulatorio
    * Soporte de producción

    **Usar para:**

    * Aplicaciones en vivo
    * Transacciones de usuarios reales
    * Despliegues de producción
  </Tab>
</Tabs>

## Comenzando con Sandbox

### Paso 1: Obtener Credenciales de Sandbox

1. Regístrate en [otc.killb.com](https://otc.killb.com)
2. Navega a **Configuración** → **Claves de API**
3. Crea una **Clave de API Sandbox**
4. Anota tu email y contraseña del sandbox

### Paso 2: Configurar Variables de Entorno

```bash .env theme={null}
KILLB_ENV=sandbox
KILLB_BASE_URL=https://sandbox.killb.app
KILLB_EMAIL=tu-email-sandbox@example.com
KILLB_PASSWORD=tu-contraseña-sandbox
KILLB_API_KEY=tu-clave-api-sandbox
```

### Paso 3: Autenticar

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

## Características de Prueba

### Endpoints Faker

Sandbox proporciona endpoints especiales para simular eventos de pago:

<AccordionGroup>
  <Accordion title="Cash-In Falso" icon="money-bill-wave" defaultOpen>
    Simula que un usuario completa un pago fiat (PSE, SPEI, etc.)

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

    **Solicitud:**

    ```json theme={null}
    {
      "rampId": "ramp-id-de-creacion"
    }
    ```

    **Lo que hace:**

    * Marca el cash-in como completado
    * Activa el proceso de conversión
    * Mueve el ramp al siguiente estado

    **Ejemplo:**

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

  <Accordion title="Cash-Out Falso" icon="money-bill-transfer">
    Simula la finalización de la conversión cripto a fiat

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

    **Solicitud:**

    ```json theme={null}
    {
      "rampId": "ramp-id-de-creacion"
    }
    ```

    **Lo que hace:**

    * Completa el proceso de cash-out
    * Marca el ramp como COMPLETED
    * Activa webhooks

    **Ejemplo:**

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

## Flujos de Prueba

### Prueba Completa de On-Ramp

<Steps>
  <Step title="Crear Usuario de Prueba">
    Usa cualquier dato de aspecto válido - sin verificación real en sandbox

    ```json theme={null}
    {
      "firstName": "Prueba",
      "lastName": "Usuario",
      "email": "prueba@example.com",
      "document": { "type": "PASSPORT", "number": "TEST123" }
    }
    ```
  </Step>

  <Step title="Crear Cuenta de Billetera">
    Usa cualquier formato de dirección de billetera válido

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

  <Step title="Crear Cotización">
    Obtén una cotización de prueba con tasas del sandbox
  </Step>

  <Step title="Crear Ramp">
    Ejecuta la transacción ramp
  </Step>

  <Step title="Simular Pago">
    Usa `/api/v2/faker/cash-in` para simular el pago del usuario
  </Step>

  <Step title="Verificar Finalización">
    Verifica que el estado del ramp cambie a COMPLETED
  </Step>
</Steps>

### Prueba Completa de Off-Ramp

<Steps>
  <Step title="Crear Usuario de Prueba">
    Lo mismo que el flujo de on-ramp
  </Step>

  <Step title="Crear Cuenta Bancaria">
    Usa detalles bancarios de prueba

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

  <Step title="Crear Cotización">
    Cotización de USDC a COP/MXN
  </Step>

  <Step title="Crear Ramp">
    Ejecuta el ramp con fuente cripto
  </Step>

  <Step title="Simular Finalización">
    Usa `/api/v2/faker/cash-out` para completar el proceso
  </Step>

  <Step title="Verificar Estado">
    Confirma que el estado es COMPLETED y los webhooks se activaron
  </Step>
</Steps>

## Datos de Prueba

### Cuentas Bancarias de Prueba (Colombia)

| Nombre del Banco | Código del Banco | Tipo de Cuenta     |
| ---------------- | ---------------- | ------------------ |
| Bancolombia      | 0001             | ahorros, corriente |
| Banco de Bogotá  | 0002             | ahorros, corriente |
| Davivienda       | 0003             | ahorros, corriente |

### Cuentas Bancarias de Prueba (México)

| Nombre del Banco | Código del Banco | Formato CLABE        |
| ---------------- | ---------------- | -------------------- |
| BBVA             | 012              | 012XXXXXXXXXXXXXXXXX |
| Santander        | 014              | 014XXXXXXXXXXXXXXXXX |
| Banorte          | 072              | 072XXXXXXXXXXXXXXXXX |

### Direcciones de Billetera de Prueba

```
Polygon (MATIC):
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Solana:
5FHwkrdxntdK24hgQU8qgBjn35Y1zwhz1GZwCkP4UJnC

Ethereum:
0x71C7656EC7ab88b098defB751B7401B5f6d8976F

Tron:
TXYZopYRdj2D9XRtbG4uXyrFPRw6sM3pjN
```

<Note>
  Estas son direcciones de ejemplo para pruebas. En sandbox, cualquier dirección con formato válido funcionará.
</Note>

## Limitaciones del Sandbox

<Warning>
  Ten en cuenta estas diferencias entre sandbox y producción:
</Warning>

| Característica         | Sandbox        | Producción          |
| ---------------------- | -------------- | ------------------- |
| Dinero real            | ❌ No           | ✅ Sí                |
| Verificación KYC       | ❌ Simulada     | ✅ Verificación real |
| Procesamiento de pago  | ⚡ Instantáneo  | ⏱️ Tiempo real      |
| Límites de transacción | ♾️ Sin límites | ✅ Basado en KYC     |
| Webhooks               | ✅ Sí           | ✅ Sí                |
| Límites de tasa de API | 🔓 Relajados   | 🔒 Aplicados        |

## Depuración en Sandbox

### Habilitar Registro Detallado

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

async function makeRequest(endpoint, options) {
  if (DEBUG) {
    console.log('Solicitud:', endpoint, options);
  }
  
  const response = await fetch(endpoint, options);
  const data = await response.json();
  
  if (DEBUG) {
    console.log('Respuesta:', data);
  }
  
  return data;
}
```

### Monitorear Estado del 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(`Intento ${i + 1}: Estado = ${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 finalización del ramp');
}
```

## Cambiando a Producción

Cuando estés listo para ir en vivo:

<Steps>
  <Step title="Actualizar URL Base">
    Cambia de `teste-94u93qnn.uc.gateway.dev` a `killb.app`

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

  <Step title="Usar Credenciales de Producción">
    Reemplaza las credenciales del sandbox con las claves de API de producción
  </Step>

  <Step title="Eliminar Llamadas Faker">
    Elimina todas las llamadas a los endpoints `/api/v2/faker/*`
  </Step>

  <Step title="Implementar KYC Real">
    Maneja la verificación KYC real y las cargas de documentos
  </Step>

  <Step title="Agregar Manejo de Errores">
    Implementa manejo de errores y registro de nivel de producción
  </Step>

  <Step title="Habilitar Monitoreo">
    Configura el monitoreo y alertas para tu integración
  </Step>
</Steps>

## Lista de Verificación de Pruebas

Antes de ir a producción, prueba estos escenarios:

<AccordionGroup>
  <Accordion title="Camino Feliz" icon="check">
    * [ ] Creación de usuario y KYC
    * [ ] Creación de cuenta (banco y billetera)
    * [ ] Generación de cotización
    * [ ] Finalización de on-ramp
    * [ ] Finalización de off-ramp
    * [ ] Recepción de webhook
    * [ ] Generación de recibo
  </Accordion>

  <Accordion title="Escenarios de Error" icon="xmark">
    * [ ] Manejo de cotización expirada
    * [ ] Detalles de cuenta inválidos
    * [ ] Saldo insuficiente
    * [ ] Simulación de pago fallido
    * [ ] Errores de red
    * [ ] Expiración de token
    * [ ] Firmas de webhook inválidas
  </Accordion>

  <Accordion title="Casos Extremos" icon="flask">
    * [ ] Montos muy pequeños (\< \$1)
    * [ ] Montos muy grandes (> \$10,000)
    * [ ] Transacciones concurrentes
    * [ ] Limitación de tasa
    * [ ] Prevención de duplicados (externalId)
    * [ ] Múltiples cuentas por usuario
  </Accordion>
</AccordionGroup>

## ¿Necesitas Ayuda?

<CardGroup cols={1}>
  <Card title="Soporte por email" icon="envelope" href="mailto:tech@killb.com">
    Comunícate con nuestro equipo
  </Card>
</CardGroup>