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

# Usuarios

> Comprendiendo la gestión de usuarios y KYC en KillB

## ¿Qué es un Usuario?

Un **Usuario** en KillB representa un individuo o entidad empresarial que puede realizar transacciones ramp. Los usuarios están obligados a completar la verificación Know Your Customer (KYC) o Know Your Business (KYB) antes de transaccionar.

<Info>
  Toda transacción en KillB debe estar asociada a un usuario verificado para cumplir con requisitos regulatorios.
</Info>

## Tipos de Usuario

<Tabs>
  <Tab title="PERSON">
    Usuarios individuales (personas físicas)

    **Información Requerida:**

    * Nombre completo (primero, medio, último)
    * Fecha de nacimiento
    * Email y teléfono
    * Dirección física
    * ID emitido por el gobierno
    * Nacionalidad y ciudadanía

    **Casos de Uso:**

    * Remesas personales
    * Inversiones individuales
    * Compras de cripto personales

    **Ejemplo:**

    ```json theme={null}
    {
      "type": "PERSON",
      "data": {
        "firstName": "Juan",
        "lastName": "García",
        "dateOfBirth": "1990-05-15",
        "email": "juan@example.com",
        "phone": "+573001234567",
        "document": {
          "type": "NUIP",
          "number": "1234567890",
          "issuedCountryCode": "CO"
        }
      }
    }
    ```
  </Tab>

  <Tab title="COMPANY">
    Entidades empresariales y corporaciones

    **Información Requerida:**

    * Nombre de la empresa y nombre comercial
    * Número de registro
    * Estructura legal
    * Dirección comercial
    * ID fiscal (NIT, EIN, RFC, etc.)
    * Información del propietario

    **Casos de Uso:**

    * Pagos empresariales
    * Tesorería corporativa
    * Transacciones B2B
    * Servicios de nómina

    **Ejemplo:**

    ```json theme={null}
    {
      "type": "COMPANY",
      "data": {
        "companyName": "Acme Corp SAS",
        "tradeName": "Acme",
        "registeredNumber": "900123456",
        "legalStructure": "LLC",
        "email": "business@acme.com",
        "document": {
          "type": "NIT",
          "number": "900123456-1",
          "issuedCountryCode": "CO"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Estado del Usuario

Los usuarios pueden tener diferentes estados:

| Estado     | Descripción                   | ¿Puede Transaccionar? |
| ---------- | ----------------------------- | --------------------- |
| `ACTIVE`   | Usuario verificado y aprobado | ✅ Sí                  |
| `PENDING`  | Documentos KYC bajo revisión  | ❌ No                  |
| `REJECTED` | Verificación KYC falló        | ❌ No                  |

<Tip>
  Controla las operaciones con `status === ACTIVE`. Si un usuario está `PENDING`, envíalo a `complianceUrl` para completar la verificación.
</Tip>

## Documentos Requeridos

### Documentos de Persona

<Tabs>
  <Tab title="Colombia">
    * **NUIP** (Número Único de Identificación Personal)
    * **Cédula de Ciudadanía** (CC)
    * **Pasaporte**
    * **Licencia de Conducir**
  </Tab>

  <Tab title="México">
    * **INE** (Instituto Nacional Electoral)
    * **IFE** (versión antigua del INE)
    * **Pasaporte**
    * **RFC** (Tax ID)
    * **CURP** (ID del Registro de Población)
  </Tab>

  <Tab title="Estados Unidos">
    * **Pasaporte**
    * **Licencia de Conducir**
    * **SSN** (Número de Seguro Social)
  </Tab>

  <Tab title="Otros Países">
    * **Pasaporte** (Universalmente aceptado)
    * **Tarjeta de Identidad Nacional**
    * **DNI** (Documento Nacional de Identidad)
  </Tab>
</Tabs>

## ID Externo

El campo `externalId` te permite vincular usuarios de KillB con tu propio sistema de usuarios:

```json theme={null}
{
  "type": "PERSON",
  "externalId": "user_abc123_de_mi_sistema",
  "data": { ... }
}
```

**Beneficios:**

* Mapear usuarios de KillB a tu base de datos
* Evitar creación de usuario duplicado
* Simplificar búsquedas de usuario
* Mantener integridad referencial

<Tip>
  Usa tu ID de usuario interno como `externalId` para fácil mapeo entre sistemas.
</Tip>

## Gestionando Usuarios

### Crear un Usuario

```bash theme={null}
POST /api/v2/users
```

Ve la [Guía de Creación de Usuario](/es/guides/users/create-user) para ejemplos detallados.

### Consultar Usuarios

```bash theme={null}
GET /api/v2/users?type=PERSON&email=usuario@example.com
```

**Opciones de Filtro:**

* `type` - PERSON o COMPANY
* `firstName`, `lastName`, `email`
* `externalId` - Tu ID de sistema
* `customerId` - Filtrar por cliente

### Actualizar Usuario

```bash theme={null}
PATCH /api/v2/users/{userId}
```

Actualiza información del usuario, sube documentos adicionales o modifica datos de perfil.

### Eliminar Usuario

```bash theme={null}
DELETE /api/v2/users/{userId}
```

<Warning>
  La eliminación de usuario es una eliminación suave. Los datos del usuario se retienen para compliance pero se marcan como inactivos.
</Warning>

## Mejores Prácticas

<AccordionGroup>
  <Accordion title="Recopilar Información Precisa" icon="clipboard-check">
    * Valida formatos de datos antes del envío
    * Asegura que los nombres coincidan exactamente con los IDs del gobierno
    * Usa formato correcto de número de teléfono (+\[código de país]\[número])
    * Verifica direcciones de email
    * Confirma que las direcciones estén completas y precisas
  </Accordion>

  <Accordion title="Usar IDs Externos" icon="link">
    * Siempre proporciona un `externalId`
    * Usa tu ID de usuario interno
    * Permite búsquedas y reconciliación fáciles
    * Previene creación de usuario duplicado
  </Accordion>

  <Accordion title="Manejar Estados KYC" icon="hourglass">
    * Verifica `status` antes de permitir transacciones
    * Muestra a los usuarios su `accessLevel` y límites
    * Guía a los usuarios al siguiente paso de verificación
    * Monitorea `complianceUrl` para actualizaciones KYC
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crea Tu Primer Usuario" icon="user-plus" href="/es/guides/users/create-user">
    Sigue la guía paso a paso para crear usuarios
  </Card>

  <Card title="Comprendiendo Cuentas" icon="wallet" href="/es/concepts/accounts">
    Aprende sobre cuentas bancarias y billeteras
  </Card>

  <Card title="Referencia API" icon="code" href="/api-reference/endpoint/users-create">
    Ve la documentación completa de la API de Usuarios
  </Card>
</CardGroup>