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

# Onboarding KYC/KYB/IDV de la organización

> Lleva tu organización del registro a la aprobación para tráfico en vivo: envía el formulario KYC, añade opcionalmente una sesión de verificación de identidad alojada, comprueba el estado, gestiona el rechazo y completa las últimas puertas previas a la publicación.

# Onboarding KYC/KYB/IDV de la organización

El paso 5 del [Quickstart](/quickstart#step-5-go-live) nombra dos puertas duras para el tráfico en vivo: un KYC de organización aprobado y un saldo financiado. El KYC de organización es una revisión única por workspace — verifica *el negocio en sí*, no sus números (los paquetes de documentos por número son un tema separado; compara al final).

Esta guía cubre el ciclo completo — envía, opcionalmente añade una sesión de verificación alojada, consulta el veredicto, reenvía en caso de rechazo — y luego las puertas restantes previas al lanzamiento.

***

## 1. Por qué el tráfico en vivo está bloqueado

Los envíos en vivo permanecen restringidos hasta que alguien del equipo de operaciones de Devotel ha revisado un perfil de negocio real. Hasta que llegue la aprobación:

* Comprar números sigue siendo posible, pero ningún SMS, WhatsApp ni voz saldrá de la plataforma.
* El panel muestra el estado en una pancarta; la misma página que esta guía abarca es accesible desde **Ajustes → KYC**.

Dos estados empujan la revisión adelante. `not_started` significa que el formulario nunca se ha enviado. `pending_review` significa que una cola de operadores tiene la solicitud (el webhook de confirmación de email lo pre-registra al registrarte; el formulario de abajo lo sustituye con detalle enriquecido). Tras la decisión obtienes `approved` o `rejected`.

## 2. Envía el formulario

POST hacia `/api/v1/organization/kyc/submit` con el perfil de negocio. El API valida: nombre de la empresa y país obligatorios, sitio web opcional, descripción de uso de diez caracteres mínimas, beneficiarios reales hasta un máx. de 20.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
    -H "X-API-Key: $ORBIT_TEST_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "company_name": "Acme Logistics Ltd.",
      "company_website": "https://acme-logistics.example",
      "country": "US",
      "industry": "Logística",
      "use_case": "Notificaciones de estado de entrega enviadas a clientes que optaron al pagar.",
      "estimated_monthly_volume": 45000,
      "registration_number": "DE-554433",
      "beneficial_owners": [
        { "name": "Maria Alvarez", "ownership_percentage": 100 }
      ]
    }'
  ```

  ```typescript Node.js theme={null}
  import { Devotel } from '@devotel-orbit/node';

  const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

  const result = await orbit.organization.kyc.submit({
    company_name: 'Acme Logistics Ltd.',
    company_website: 'https://acme-logistics.example',
    country: 'US',
    industry: 'Logística',
    use_case: 'Notificaciones de entrega a clientes con consentimiento.',
    estimated_monthly_volume: 45000,
  });
  console.log(result.data.status); // "pending_review"
  ```
</CodeGroup>

Una respuesta correcta marca `pending_review` y devuelve el registro guardado más el veredicto de screening — la revisión la realiza una persona, nada se aprueba ni se rechaza automáticamente.

**Respuesta (200):**

```json theme={null}
{
  "data": {
    "status": "pending_review",
    "kyc": {
      "status": "pending_review",
      "company_name": "Acme Logistics Ltd.",
      "country": "US",
      "submitted_at": "2026-09-04T09:12:33Z"
    },
    "kyb": {
      "status": "review",
      "matches": [],
      "legal_name": "Acme Logistics Ltd.",
      "country": "US",
      "screened_at": "2026-09-04T09:12:33Z"
    },
    "message": "Your KYC submission has been received and is awaiting review."
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-09-04T09:12:33Z" }
}
```

`data.kyb` es la señal de screening (`clear` si la entidad está limpia, `review` si un país sancionado o una parte denegada coincidió). Se revisa junto con el formulario — no bloquea la presentación y un veredicto `review` exige la misma validación humana. El campo falta cuando el screening no ha podido ejecutarse (entonces se notifica para revisión manual).

## 3. Revestimientos por mercado — lo que tu destino realmente exige

El formulario anterior se presenta una vez por organización, pero qué campos el revisor pondera más depende del destino. El `country` que envías fija el mercado — responde con el mercado de destino, no con la dirección de facturación; un emisor destinado a UK que declare `country: "US"` solo gana un reintento por corrección. Dos grupos de campos siempre llegan al revisor: el texto libre `use_case`, y los campos identitarios KYB (`registration_number`, `beneficial_owners`). Una organización que apunte a varios mercados bloqueados repite el patrón documental una vez por destino — agrupa las subidas por destino en la biblioteca documental en lugar de diluir un único formulario.

Los mercados abajo retienen los envíos hasta que se complete la pre-inscripción. Para cada uno: los campos del perfil a destacar, y los roles documentales que el regulador pide. Las subidas se realizan bajo **Cumplimiento → Documentos** y se citan por identificador entre registros; los roles visibles en revisión son `business_doc`, `address_proof`, `id_proof`, `authorization`. La [matriz de mercado de Sender-ID](/guides/sender-id-country-matrix) lleva el nivel `registration` vivo por país; el [guía documentos](/compliance/documents-kyc) cubre el flujo de subida.

### Alemania — BNetzA identidad de la entidad

BNetzA (Bundesnetzagentur) valida la identidad detrás de cada ruta alfanumérica y de cada registro de voz KYC. Destaca `registration_number` (inscripción en el registro mercantil local) y una denominación social correcta. Documentos: `business_doc` (extracto del registro mercantil).

### España — CNMC sender-id / itinierancia

La CNMC sanciona la venta de mensajes hasta que el remitente alfanumérico esté inscrito. Destaca `registration_number` y un `use_case` enfocado en el destinatario español. Documentos: `business_doc` (CIF/NIF de la entidad).

### Francia — ARCEP registro del remitente

ARCEP y los operadores registran la identidad que coloca el remitente alfanumérico; marcas no inscritas reciben rechazos de ruta SMS. Destaca `registration_number` (inscripción RCS) con un `use_case` cerrado en el tráfico Declarado. Documentos: `business_doc` (extrait Kbis o SIREN) más `authorization` cuando una agencia presenta para una marca.

### Turquía — BTK nombre del remitente

El BTK inscribe el nombre del remitente — no solo la route: presenta el nombre que tus clientes verán y menciónalo en `use_case`. Documentos: `business_doc` (documentos de la cámara de comercio).

### Mercados arábigos — ejemplo EAU TDRA

Algunos mercados arábigos (por ejemplo los EAU, TDRA + operadores e&/du) esperan una identidad de marca amparada por KYC junto al remitente — el revisor más propenso a rechazar una solicitud ligera. Destaca `company_name`, `company_website` y un `use_case` completo. Documentos: `business_doc` más `authorization` de marca.

En cada mercado la idea es la misma: decide lo que vas a escribir en `company_name`, `use_case` y `registration_number` **antes** de que un filtro de envío bloquee el tráfico con un `422`. [Send Gates](/compliance/send-gates) explica cómo un destino `required` bloquea los envíos no inscritos. Para la lectura en mercados históricamente en inglés (Reino Unido, Arabia Saudita, EAU, Brasil, India DLT, US 10DLC), consulta la [versión en inglés de esta guía](/guides/organization-kyc-onboarding).

## 4. Opcional: añade una sesión IDV alojada

Algunos operadores piden un documento de identidad estatal más un chequeo de liveness antes de firmar. POST `/api/v1/organization/kyc/idv/session` abre una sesión alojada en el proveedor provisionado; abre la URL entrega en un navegador o pásalo al firmante.

```bash cURL theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/idv/session \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://your-app.example/kyc/return" }'
```

**Respuesta (200):**

```json theme={null}
{
  "data": {
    "status": "pending",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:13:04Z"
  },
  "meta": { "request_id": "req_def456", "timestamp": "2026-09-04T09:13:04Z" }
}
```

Hasta que un operador provee de un proveedor, el endpoint responde `503`:

```json theme={null}
{ "error": { "code": "IDV_NOT_CONFIGURED", "message": "Identity verification is not available for this account", "status": 503 } }
```

Comprueba el veredicto del proveedor con `GET /api/v1/organization/kyc/idv/status`. Se auto-reconcilia: mientras la sesión almacenada es `pending`, cada GET pregunta al proveedor por el último resultado y escribe la transición terminal. Un `verified`, `declined` o `expired` terminal — con una `reason` cuando el proveedor lo da — se suma a la señal que el operador evalúa junto a la solicitud. **Nunca** es auto-aprobado: un `verified` no aprueba el KYC y un `declined` no lo rechaza.

```json theme={null}
{
  "data": {
    "status": "verified",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:44:12Z",
    "configured": true
  }
}
```

## 5. Consulta el veredicto de la organización

Haz poll a `GET /api/v1/organization/kyc/status` hasta que llegue el veredicto de la organización. Los estados posibles son `not_started`, `pending` (transitorio pre-envío), `pending_review`, `approved` y `rejected`; la respuesta también eco los campos empresariales enviados y `reviewed_at` una vez tomada una decisión.

```bash cURL theme={null}
curl https://api.orbit.devotel.io/api/v1/organization/kyc/status \
  -H "X-API-Key: $ORBIT_TEST_KEY"
```

**Respuesta (200):**

```json theme={null}
{
  "data": {
    "status": "pending_review",
    "company_name": "Acme Logistics Ltd.",
    "country": "US",
    "industry": "Logística",
    "submitted_at": "2026-09-04T09:12:33Z",
    "reviewed_at": null,
    "source": null
  },
  "meta": { "request_id": "req_ghi789", "timestamp": "2026-09-04T09:15:00Z" }
}
```

Los SDK antiguos y los códigos hechos a mano a veces leyeron el camino sencillo `GET /api/v1/organization/kyc`; sirve la misma forma de respuesta, así que apuntar a `/kyc/status` sigue siendo seguro y compatible.

El endpoint es seguro de consultar desde el panel o un servidor — degrada a una lectura neutra `not_started` en un blip de base de datos transitorio sin sacar un 503, y la siguiente consulta se corrige sola.

## 6. Reenvío y el guardia «ya verificado»

POST de nuevo el formulario es la acción correcta con un `rejected`: la escritura vuelve a marcar `pending_review`, sobrescribe el bloque del formulario y re-ejecuta el screening con las respuestas corregidas. También se admite un reenvío todavía `pending_review` — reemplaza el perfil en curso.

Reenviar una organización **approved** devuelve **409**:

```json theme={null}
{
  "error": {
    "code": "ALREADY_VERIFIED",
    "message": "KYC verification has already been approved",
    "status": 409
  }
}
```

La misma guarda se aplica a una sesión IDV una vez que la identidad `verified` — un POST al endpoint de sesión recibe entonces `409 ALREADY_VERIFIED`, y re-capturar solo tiene sentido cuando la organización fue rechazada y se está relanzando.

## 7. Qué significa un rechazo y qué hacer

Un rechazo es un veredicto humano — el operador deambula el **panel de operaciones Devotel**, lee tus campos más la señal de screening y IDV, y presiona aprobar o rechazar. La superficie de cliente nunca expone una razón mecánica; el email de decisión nombra la brecha y la corrección. Trata `rejected` como accionable:

1. Relee los campos enviados por exactitud (un nombre legal incorrecto o una descripción use-case ligera es el bloqueo más frecuente).
2. Corrige cualquier coincidencia `kyb` y cualquier resultado IDV `declined`.
3. Reenvía con los datos corregidos — el endpoint lo acepta y la cola se reordena.

Si el rechazo es claramente un error — por ejemplo un error en el panel del operador más que en tus datos — presenta por la [soporte](/troubleshooting/auth-and-api-keys) con el identificador de cuenta y el identificador `req_*` de la consulta de status; el dueño de la cola de revisión puede reabrir el caso y aprobarlo desde el lado del operador.

### Qué esta puerta NO es: documentos por número

El KYC de organización se sitúa junto a los paquetes de documentos que los operadores piden por número — estos últimos (registro de empresa, prueba de domicilio, identidad) cubren un número en concreto que posees y siguen un bucle de revisión distinto bajo **Cumplimiento → Documentos**. Aprobar la organización no zanja un paquete por número, y viceversa: ve la [guía documentos KYC por número](/compliance/documents-kyc) para ese registro separado.

## 8. Una vez aprobado — las últimas puertas del lanzamiento

La aprobación bascula el veredicto de la organización, entonces `GET /organization/kyc/status` devuelve `approved`. Completa las dos últimas puertas de la [checklist go-live](/guides/go-live-checklist):

* **Genera la clave viva.** Bajo **Ajustes → Claves API**, crea un secret con el prefijo `dv_live_sk_` y cambia la clave de sandbox `dv_test_sk_` — las formas de solicitud son idénticas, por lo que no hace falta reescribir código.
* **Financia el saldo.** Agrega fondos bajo **Ajustes → Facturación**; SMS, WhatsApp y voz restan todos de esa cartera, y los envíos vivos fallan con un error de facturación mientras el saldo esté vacío.
* **SMS US: añade 10DLC.** Si el destino incluye long-codes US, completa el [registro de marca + campaña 10DLC](/guides/10dlc-registration). La aprobación KYC por sí sola no sustituye la inscripción de la carrier; ambas puertas deben quedar en verde antes de que un send SMS US salga del sandbox.

Con las dos puertas duras y los registros de canal superados, el envío vivo se comporta idénticamente al sandbox — mismo endpoint, mismo envelope webhook, ninguna otra bucla de aprobación.

***

## Referencias asociadas

* [Checklist go-live](/guides/go-live-checklist) — las puertas previas al tráfico vivo.
* [Sender-ID Registration](/compliance/sender-id-registration) — registros por país apoyados por identificadores `doc_`.
* [Documentos KYC por número](/compliance/documents-kyc) — la biblioteca documental propietaria del tenant.