Onboarding KYC/KYB/IDV de la organización

El paso 5 del Quickstart 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.

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 }
    ]
  }'

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"

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):

{
  "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 lleva el nivel registration vivo por país; el guía documentos 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 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.

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.

cURL

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):

{
  "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:

{ "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.

{
  "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.

cURL

curl https://api.orbit.devotel.io/api/v1/organization/kyc/status \
  -H "X-API-Key: $ORBIT_TEST_KEY"

Respuesta (200):

{
  "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:

{
  "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:

Relee los campos enviados por exactitud (un nombre legal incorrecto o una descripción use-case ligera es el bloqueo más frecuente).
Corrige cualquier coincidencia kyb y cualquier resultado IDV declined.
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 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 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:

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. 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 — las puertas previas al tráfico vivo.
Sender-ID Registration — registros por país apoyados por identificadores doc_.
Documentos KYC por número — la biblioteca documental propietaria del tenant.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Onboarding KYC/KYB/IDV de la organización

Onboarding KYC/KYB/IDV de la organización

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

2. Envía el formulario

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

Alemania — BNetzA identidad de la entidad

España — CNMC sender-id / itinierancia

Francia — ARCEP registro del remitente

Turquía — BTK nombre del remitente

Mercados arábigos — ejemplo EAU TDRA

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

5. Consulta el veredicto de la organización

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

7. Qué significa un rechazo y qué hacer

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

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

Referencias asociadas

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

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

​2. Envía el formulario

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

​Alemania — BNetzA identidad de la entidad

​España — CNMC sender-id / itinierancia

​Francia — ARCEP registro del remitente

​Turquía — BTK nombre del remitente

​Mercados arábigos — ejemplo EAU TDRA

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

​5. Consulta el veredicto de la organización

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

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

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

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

​Referencias asociadas

Onboarding KYC/KYB/IDV de la organización

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

2. Envía el formulario

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

Alemania — BNetzA identidad de la entidad

España — CNMC sender-id / itinierancia

Francia — ARCEP registro del remitente

Turquía — BTK nombre del remitente

Mercados arábigos — ejemplo EAU TDRA

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

5. Consulta el veredicto de la organización

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

7. Qué significa un rechazo y qué hacer

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

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

Referencias asociadas