Desarrollador: claves de API y API REST

Qué hace

La API REST de Certivant permite a sus propios sistemas crear solicitudes de verificación, subir documentos y consultar el estado sin pasar por el panel. Dos casos de uso principales:

1. Integrar la verificación en su propio flujo de alta. Su formulario de registro envía los datos a su backend, su backend llama a Certivant y el solicitante recibe un enlace al flujo alojado de Certivant.
2. Sincronizar el estado de la verificación con su almacén de datos o su CRM. Combínela con los webhooks para que sus sistemas se actualicen con cada cambio de estado.

La autenticación de la API se realiza mediante claves de API que emite desde el panel. La documentación completa de los endpoints está en /app/{su-org}/kyc/developer; esta página cubre la gestión de claves y la visión general conceptual.

Dónde está

KYC → Desarrollador en la barra lateral izquierda. (Antes, las claves de API estaban en los ajustes de KYC/B; ahora tienen su propio espacio en Desarrollador.)

El portal para desarrolladores es un único centro con un menú a la izquierda:

• Resumen e inicio rápido: su URL base, la autenticación y una petición lista para copiar en 8 lenguajes (cURL, JavaScript, TypeScript, Python, PHP, Go, Java, C#). Los fragmentos vienen rellenados con su host real y un marcador para su clave.
• Claves de API: lista, crea y revoca sus claves.
• Referencia de endpoints: cada endpoint de la integración (/v1) con su método, ruta, ámbitos y parámetros, además de un enlace al Playground interactivo de la API.
• Manejadores de webhooks: manejadores listos para usar que verifican la firma, en 6 lenguajes (consulte también Webhooks).
• Límite de peticiones: el límite efectivo por minuto de su organización, en modo de solo lectura.
• Preguntas frecuentes: las preguntas que más hacen los integradores.

Emitir una clave de API

Usar la clave

Envíela en la cabecera Authorization:

Authorization: Bearer ck_live_a3f...

Las claves creadas antes del formato ck_live_ / ck_test_ (que empiezan por kyk_) siguen funcionando sin cambios.

La forma más rápida de tener una integración funcionando:

curl https://api.certivant.com/api/v1/kyc/requests \
  -H "Authorization: Bearer $CV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "applicant": {
      "fullName": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

Atribución a socios y subinquilinos

Si realiza verificaciones en nombre de muchos clientes finales desde una sola organización (el patrón clásico de socio o revendedor, por ejemplo, una plataforma de firma electrónica que verifica a los firmantes de cientos de empresas), no necesita una organización por cliente. Etiquete cada solicitud con dos campos opcionales al crearla mediante la API:

• subTenantName: el nombre visible del cliente final (por ejemplo, «Acme Corp»).
• subTenantExternalId: su propio identificador interno de ese cliente (por ejemplo, cust_8842).

Una vez etiquetadas, puede:

• Filtrar el endpoint de listado por subTenantExternalId (GET /api/v1/kyc/requests?subTenantExternalId=cust_8842).
• Enrutar los webhooks: ambos campos se repiten en cada sobre de evento, de modo que su manejador sabe a qué cliente pertenece un resultado sin necesidad de una consulta adicional.
• Filtrar los paneles: Uso de KYC/B, Registro de auditoría, Monitorización, Informes y Analíticas incorporan un filtro de Subinquilino en cuanto alguna solicitud lleva las etiquetas, y las listas de KYC/KYB pueden mostrar las columnas Subinquilino e ID externo (ocultas por defecto; actívelas desde el menú de columnas).

Consulte la referencia de la API para ver la forma exacta de la petición: Solicitudes KYC → Crear una solicitud.

Límites de peticiones

Su límite de peticiones por minuto de la API lo define su plan (valores típicos: 60/min en Launch, 300/min en Pro/Scale, 600/min en Enterprise). El límite exacto de su organización aparece en modo de solo lectura en la página Desarrollador, y cada respuesta de la API lo incluye en la cabecera X-RateLimit-Limit. Cada clave se mide de forma independiente dentro de ese límite.

Si lo supera, las peticiones devuelven HTTP 429 Too Many Requests con X-RateLimit-Reset (segundos hasta que se reinicia la ventana). Espere y reintente.

¿Necesita un límite mayor? Su superadministrador lo establece: puede subir su límite por cliente hasta el máximo de su plan desde Administración → Clientes → (su organización) → Editar organización (un límite mayor implica pasar a un plan superior). El límite lo controla el operador: los inquilinos pueden verlo, pero no modificarlo. Consulte la referencia para desarrolladores con el funcionamiento completo: Límites de peticiones.

Buenas prácticas de seguridad

• Guarde las claves en variables de entorno o en un gestor de secretos. Nunca las suba a git ni las comparta en un chat. Las claves subidas a repositorios públicos son escaneadas y robadas en cuestión de minutos.
• Una clave por entorno. No comparta una clave ck_live_... entre preproducción y producción: rotar una no debe afectar a la otra.
• Use claves con ámbitos. Una clave de solo lectura para monitorización y una clave de escritura para el servicio de alta es más segura que una única clave omnipotente en todas partes.
• Restrinja las claves a sus servidores. Añada la lista de IP permitidas para las claves que se usan solo desde direcciones fijas.
• Rote las claves trimestralmente. Use Rotar (más abajo): la clave antigua sigue funcionando durante el solapamiento que elija, de modo que puede desplegar la nueva sin interrupción. El registro de auditoría registra el cambio.
• Vigile el uso no autorizado. La lista de claves muestra cuándo y desde qué dirección se usó por última vez cada clave, y el registro de auditoría registra la creación, las ediciones, las rotaciones y las revocaciones. Investigue cualquier dirección que no reconozca.

Rotar una clave

Desarrollador → Claves de API → Rotar crea un reemplazo con la misma etiqueta, los mismos permisos, restricciones, lista de IP permitidas y caducidad, y muestra la nueva clave una sola vez.

• Solapamiento (de 0 a 168 horas, por defecto 24). La clave antigua sigue funcionando durante ese tiempo y después devuelve 401 api_key_rotated. Establezca 0 para revocar la clave antigua de inmediato.
• La lista marca la clave antigua como «Rotada: la clave antigua funciona hasta …» y la nueva como «Reemplaza una clave rotada». Una clave que ya ha sido rotada no puede volver a rotarse: rote su reemplazo.
• También puede editar o revocar la clave antigua durante el solapamiento si necesita cortarla antes.

Revocar una clave

Cuando una clave está comprometida, filtrada o ya no se necesita:

• Desarrollador → Claves de API → menú de tres puntos → Revocar.
• Surte efecto de inmediato. Cualquier petición en curso que use la clave recibirá un 401 en la siguiente llamada.
• No puede deshacerse: no hay botón de «anular la revocación». Emita una clave nueva si se arrepiente.

La revocación queda registrada en el registro de auditoría, junto con el usuario que la realizó.

Producción frente a pruebas

Cada clave es de una de estas dos clases:

• Prueba (ck_test_...): pensada para desarrollo y CI.
• Producción (ck_live_...): pensada para producción.

El entorno etiqueta el uso: cada respuesta incluye X-Certivant-Environment: test o live, y el panel muestra el distintivo junto a la clave, de modo que puede distinguir el tráfico de prueba del de producción en sus registros.

Solución de problemas

401 Unauthorized

El campo error.reason del cuerpo de la respuesta indica el motivo:

403 Forbidden

error.reason:

429 Too Many Requests

Tiene un límite de peticiones. Consulte la cabecera Retry-After (segundos) y espere en consecuencia. Si necesita un volumen sostenido, solicite un límite mayor.

«He perdido el valor de la clave»

Las claves se muestran una sola vez. No hay forma de recuperarlas. Revoque la clave antigua y emita una nueva: su equipo tendrá que actualizar el nuevo valor allí donde estaba desplegado el antiguo.

Relacionado

• Webhooks: combínelos con la API para una integración completa.
• Lista y detalle de KYC: vista desde el panel de las solicitudes creadas por API.
• Registro de auditoría: cada llamada a la API aparece aquí.