API de contratación: un patrón REST + token portador para integraciones de reclutamiento

Por qué necesitas una API REST

La mayoría de plataformas ATS modernas exponen datos solo a través de webhooks y una interfaz nativa. Eso funciona si tienes 20 personas y un proceso único. Pero en el momento en que quieres:

• Sincronizar candidaturas a tu sistema de HR (BambooHR, Workday) que no tiene una integración pre-construida
• Extraer informes a tu almacén de datos para análisis personalizados
• Importación masiva de candidaturas desde un sistema antiguo
• Construir un panel personalizado que tu equipo prefiera sobre la interfaz nativa
• Automatizar tareas con Zapier o Make.com sin escribir código

...necesitas una API REST pública.

Una API REST es la lingua franca de integración SaaS. Cualquier herramienta que hable HTTP puede hablar con ella. Zapier, Make, n8n, Pipedream, scripts de Python personalizados, aplicaciones móviles, tus propios paneles —todos pueden leer y escribir datos con un simple token de autenticación.

El patrón de token portador

El patrón de API más seguro es tokens portadores: emites cada usuario una clave API, la incluyen en el encabezado Authorization: Bearer YOUR_KEY, y cada solicitud se autentica contra esa clave.

Así es como Stripe, GitHub, Slack, y la mayoría de APIs modernas funcionan. Es fácil de revocar (elimina la clave), fácil de rotar (genera una nueva), y fácil de alcanzar (emite diferentes claves con diferentes permisos).

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  https://api.clarityhire.com/v1/candidates?job_id=j_engineering_2026

Compara eso con nombre de usuario/contraseña u OAuth: los tokens portadores son sin estado (sin base de datos de sesión), pueden ser invalidados instantáneamente, y te dejan auditar qué clave hizo qué solicitud.

Alcances y permisos

Una mejor práctica de seguridad: no emitas tokens con acceso completo de lectura-escritura a todo. En su lugar, usa alcances.

candidates:read       # Puede listar y ver candidaturas
candidates:write      # Puede mover candidaturas, agregar notas
tests:read            # Puede ver resultados de pruebas
tests:write           # Puede crear y editar pruebas
jobs:read             # Puede listar trabajos
webhooks:manage       # Puede crear/eliminar webhooks

Cuando un desarrollador de terceros solicita acceso API (digamos, un proveedor de HRIS integrándose con tu plataforma), emites un token con solo candidates:read y candidates:write. No pueden ver tus datos de facturación o modificar preguntas de entrevista.

Los alcances también protegen contra daño accidental. Si un script de integración tiene un error y comienza a eliminar candidaturas, lo detectas más rápido si el script solo debería tener candidates:read.

Webhooks vs. encuesta

Dos patrones para mantener datos sincronizados:

Webhooks (impulsado por eventos):

POST https://your-system.com/webhook/clarityhire
{
  "event": "candidate.stage_changed",
  "data": {
    "candidate_id": "c_123",
    "old_stage": "screening",
    "new_stage": "assessment",
    "timestamp": "2026-05-21T14:30:00Z"
  }
}

Cuando algo sucede en ClarityHire, publica a tu punto final. Lo procesas inmediatamente. Rápido, eficiente, sin gastos generales de encuesta.

Encuesta (basado en extracción):

GET https://api.clarityhire.com/v1/candidates?job_id=j_123&updated_since=2026-05-21T00:00:00Z

Periódicamente (cada 5 minutos, cada hora) pregunta a ClarityHire "¿qué cambió?" y procesa la respuesta. Más simple de implementar si tu sistema no expone un punto final HTTP, pero más lento y más ruidoso.

Mejor práctica: webhooks para tiempo real (cambios de etapa, nuevas solicitudes), encuesta para sincronizaciones periódicas (exportación diaria de todas las candidaturas para tu almacén de datos).

Ambos patrones deberían soportar lógica de reintento. Los webhooks pueden fallar (interrupción de red, tu punto final inactivo). La API debería reintentar con retroceso exponencial y dejar que veas intentos fallidos en un panel de "registros de webhook".

Límites de tasa e idempotencia

Cuando expones una API, necesitas salvaguardias contra abuso y duplicados accidentales.

Límites de tasa: "Puedes hacer 1,000 solicitudes por hora por clave API." Si alguien lo excede, obtiene una respuesta 429 con un encabezado Retry-After. Zapier y otras plataformas de integración respetan estos límites automáticamente.

Idempotencia: Si una entrega de webhook falla, la reintentamos. Pero ¿y si la solicitud realmente tuvo éxito, pero la respuesta se agotó? Sin idempotencia, crearíamos una candidatura duplicada o moveríamos la candidatura dos veces.

Solución: requiere un encabezado Idempotency-Key en solicitudes de escritura.

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  -H "Idempotency-Key: zap_12345_attempt_1" \
  -X POST https://api.clarityhire.com/v1/candidates \
  -d '{"email": "[email protected]", "job_id": "j_eng"}'

La API almacena la clave y la respuesta. Si se usa la misma clave nuevamente, devuelve la respuesta almacenada. Sin duplicados.

Documentación y SDKs

Una API es inútil sin documentos. Necesitas:

1. Referencia de punto final: cada ruta, cada parámetro, cada formato de respuesta
2. Códigos de error: ¿qué significa un 400? ¿un 403?
3. Tipos de eventos de webhook: lista completa de eventos que emites, con cargas útiles de ejemplo
4. Ejemplos de código: fragmentos de curl, Python, JavaScript para tareas comunes
5. Autenticación: cómo generar y rotar claves

Bonificación: publica SDKs para lenguajes populares (Python, JavaScript, Go). Zapier viene con un SDK integrado, pero integraciones personalizadas se benefician de una biblioteca de cliente nativa que maneja paginación, reintentos, y manejo de errores.

Integración de Zapier: ventaja de próximo nivel

Zapier conecta cientos de aplicaciones sin código. Una vez que expones una API REST, escribir una integración de Zapier se convierte en un proyecto de 1-2 semanas en lugar de 4 semanas de construcción personalizada.

Ejemplo Zap:

• Desencadenante: "Nueva candidatura en trabajo de ClarityHire 'Ingeniero Backend Sénior'"
• Acción 1: "Agregar fila a Google Sheets"
• Acción 2: "Enviar mensaje Slack a #hiring"
• Acción 3: "Crear contacto en Pipedrive"

Un usuario de Zapier configura esto sin código. Otros usuarios de Zapier lo descubren en el mercado de Zapier y lo adoptan. Has construido un ecosistema de 100 integraciones sin escribir 100 integraciones.

Cómo ClarityHire expone su API

ClarityHire ofrece /api/v1/* con autenticación de token portador, permisos alcanzados, y soporte de webhook. Los documentos de referencia viven en api.clarityhire.com/docs. Límite de tasa: 1,000 solicitudes/hora por clave. Escrituras idempotentes con encabezado Idempotency-Key.

Puntos finales de ejemplo:

• GET /api/v1/candidates — listar candidaturas (soporta filtrado, paginación)
• GET /api/v1/candidates/{id} — candidatura única
• POST /api/v1/candidates/{id}/move-stage — transición de etapa
• GET /api/v1/webhooks — listar tus webhooks activos
• POST /api/v1/webhooks — registrar un nuevo webhook

Los webhooks pueden ser filtrados por tipo de evento, job_id, u organización. El sistema reintenta entregas fallidas 10 veces en 24 horas con retroceso exponencial.

TL;DR

Una API REST pública con tokens portadores desbloquea integraciones. Alcances de permisos por caso de uso. Prefiere webhooks para sincronización en tiempo real, encuesta para exportaciones por lotes. Impone idempotencia en escrituras para prevenir duplicados. Documenta completamente, incluyendo códigos de error y ejemplos. La integración de Zapier es el multiplicador: una API permite mil casos de uso sin que tu equipo los codifique.

La inversión en diseño de API paga dividendos en flexibilidad y adopción.