En empresas medianas y grandes, el sistema de gestión de RRHH ya existe. Puede ser un ATS internacional (Greenhouse, Lever, BambooHR, SAP SuccessFactors, Workday) o una solución local construida sobre hoja de cálculo y correos. La verificación de antecedentes no debería existir en paralelo — debería estar embebida en el flujo que el equipo ya usa.
Este artículo es para líderes de RRHH y equipos de IT que están evaluando cómo integrar StatusEC con su stack actual. Cubre arquitectura, endpoints, webhooks, autenticación y los patrones de integración más comunes.
Arquitectura de alto nivel
Una integración típica tiene cuatro componentes:
| Componente | Responsabilidad |
|---|---|
| Su ATS / HRIS | Fuente de verdad del candidato/empleado. Guarda etapa del proceso, datos del titular, resultado de verificación. |
| Trigger | Evento que dispara la verificación (cambio de etapa, nuevo empleado, scan mensual programado). |
| API StatusEC | Recibe el pedido, ejecuta verificación de 12 fuentes, notifica vía webhook. |
| Webhook receptor | Endpoint suyo que recibe el resultado y lo guarda en el ATS. |
Los endpoints principales
La API StatusEC tiene endpoints claros. Los más usados:
POST /v1/verificaciones — crear nueva
POST https://api.statusec.com/v1/verificaciones
Authorization: Bearer sk_live_[your_key]
Content-Type: application/json
{
"cedula": "1712345678",
"titular_id_externo": "cand_8472",
"metadata": {
"ats_candidate_id": "cand_8472",
"position": "Cajero Sucursal Norte",
"department": "Operaciones"
},
"webhook_url": "https://su-empresa.com/webhooks/statusec",
"consentimiento_id": "cons_abc123"
}Campos notables: titular_id_externo permite cruzar de vuelta a su ATS. metadata es libre y aparece en el reporte. consentimiento_id referencia un consentimiento LOPDP ya capturado.
GET /v1/verificaciones/:id — consultar estado
Retorna estado actual (FETCHING_APIS, WAITING_DATA, GENERATING, COMPLETED, FAILED) y progreso por fuente. Útil para mostrar estado en su UI.
GET /v1/verificaciones/:id/pdf — descargar reporte
Retorna el PDF binario del reporte generado. Puede guardarse directamente en el storage de su ATS.
POST /v1/webhooks — configurar notificaciones
Registra un endpoint para recibir eventos: verificación completada, falla crítica, cambio mensual detectado. El payload incluye firma HMAC para verificar autenticidad.
Tres patrones de integración comunes
Patrón 1: Disparo por cambio de etapa del candidato
Cuando el candidato en su ATS cambia de "Entrevista Final" a "Oferta Pendiente", un trigger dispara la verificación. Este es el patrón más común.
Implementación:
- Hook en el ATS que escucha el evento stage_change.
- Cuando la etapa destino es "Oferta Pendiente", llama
POST /v1/verificaciones. - Webhook receptor espera el resultado. Cuando llega, actualiza un campo custom en el ATS con el score y adjunta el PDF.
- RRHH ve el resultado directamente en la ficha del candidato sin cambiar de sistema.
Patrón 2: Verificación masiva programada
Para el monitoreo continuo, un cron interno de su sistema lista los empleados activos cada mes y los manda a verificación en batch.
Implementación:
- Cron job mensual en su HRIS: extrae lista de empleados activos.
- Llama al endpoint batch
POST /v1/batchescon la lista de cédulas. - StatusEC procesa en paralelo, notifica vía webhook por cada reporte completado.
- Su sistema guarda cada PDF y marca el empleado con su score mensual.
Patrón 3: Dashboard embedido
Para empresas que quieren que el equipo de RRHH trabaje sin salir del ATS, se puede embeber el dashboard StatusEC como iframe o consumir la API de dashboards para construir widgets nativos en su UI.
¿Cuál patrón aplica a su empresa?
La elección depende del ATS actual y de cuánto control tiene IT sobre extensiones. En una demo técnica revisamos su stack y recomendamos el patrón apropiado.
Agendar demo técnicaAutenticación y seguridad
- Autenticación: API key por cliente. Keys separadas para sandbox y producción.
- Rate limiting: por plan. Planes empresariales típicos: 100 requests/minuto, hasta 10,000/día.
- Firma HMAC en webhooks: cada evento enviado a su endpoint incluye un header
X-StatusEC-Signatureque permite verificar que proviene efectivamente de StatusEC. - TLS 1.2+ obligatorio para todos los endpoints.
- IP allowlisting disponible en planes enterprise — solo IPs registradas del cliente pueden usar su API key.
Cómo maneja la integración el consentimiento LOPDP
El consentimiento es el punto más delicado. Dos opciones:
- Su sistema captura el consentimiento: el formulario de aplicación del candidato incluye el consentimiento LOPDP. Su sistema lo archiva y lo referencia por
consentimiento_idal disparar la verificación. - StatusEC captura el consentimiento: su sistema llama
POST /v1/consentimientoscon los datos del titular, StatusEC envía un link al candidato para firma digital, y cuando firma dispara la verificación automáticamente.
La opción 1 es mejor cuando el ATS ya tiene flujo de consentimiento robusto. La opción 2 es mejor cuando el flujo legal del cliente está subdesarrollado.
El proceso de onboarding técnico
Para un cliente que activa integración API, el onboarding típico:
- Semana 1: entrega de credenciales sandbox, documentación técnica, ambiente de pruebas.
- Semana 2: integración en sandbox por parte del cliente. Soporte StatusEC disponible para dudas.
- Semana 3: pruebas end-to-end con datos reales (cédulas propias de IT). Ajustes.
- Semana 4: go-live con monitoreo conjunto las primeras 48 horas. Transición a soporte estándar.
Patrón específico para el ecosistema ecuatoriano
Muchas empresas ecuatorianas medianas no usan ATS internacional — usan soluciones locales construidas sobre hoja de cálculo, Google Drive, o sistemas ERP con módulo de RRHH (Dolibarr, SAP Business One, Odoo). Para este ecosistema, el patrón de integración es distinto:
- Si usa Google Sheets como registro de candidatos: un script de Apps Script puede llamar a la API StatusEC cuando se cambia el estado de un candidato en una columna. Tiempo de implementación: 1-2 días por un desarrollador con experiencia en Apps Script.
- Si usa un ERP con módulo RRHH: la integración típica es un middleware entre el ERP y StatusEC. Se dispara por cambio de estado del registro de candidato/empleado. 1-2 semanas de implementación.
- Si no hay sistema formal: el portal StatusEC + módulo de consentimiento digital es el equivalente a tener un ATS básico. RRHH registra candidatos en el portal y la verificación queda asociada al perfil.
La API es estándar REST — no exige que el cliente tenga infraestructura sofisticada. Lo que sí exige es un desarrollador que entienda HTTP, autenticación por API key, y manejo de webhooks con HMAC.
Preguntas frecuentes
¿Tienen SDKs en Node.js o Python?
Sí. SDKs oficiales en Node.js y Python se entregan al activar el plan con API habilitada. Incluyen tipos, manejo de errores y helpers para webhooks.
¿Qué formato tienen los webhooks?
JSON con firma HMAC. Eventos principales: verificacion.completed, verificacion.failed, monitoreo.delta_detected. Payload incluye datos del titular (ofuscados según plan) y link al reporte.
¿Puedo hacer verificaciones de prueba sin consumir créditos reales?
En sandbox sí. Se usan cédulas de prueba predefinidas que simulan distintos escenarios (BAJO, MEDIO, ALTO, fuente caída, datos ambiguos). En producción todas las verificaciones consumen crédito real.
¿Cómo manejo errores transientes de la API?
Los endpoints responden códigos HTTP estándar. 429 para rate limit (respete el header Retry-After), 500/502/503 para errores temporales (reintente con exponential backoff). Los SDKs implementan esto por default.
¿Hay integración pre-construida con Greenhouse / BambooHR?
Integraciones certificadas con los ATS más populares del mercado están en roadmap. Actualmente, integración custom vía API es el camino. Consulte en la demo si su ATS ya tiene conector parcial.
Conclusión
La integración API convierte la verificación de antecedentes de un trámite externo en parte nativa del flujo de RRHH. Para equipos de IT, es una API REST estándar con webhooks, HMAC, rate limiting y SDKs. Para equipos de RRHH, es ver el score y el PDF directamente en la ficha del candidato sin cambiar de sistema.
Para una demo técnica con su equipo de IT, agende aquí. El onboarding típico toma 4 semanas para integraciones estándar.