Integración para portales de empleo asociados
Un punto de partida práctico para conectar un portal de empleo con Kit mediante la API, el feed y el flujo de candidaturas que ya utiliza el socio.
Empieza por la interfaz que ya tienes
Kit puede conectarse a un portal de empleo sin pedirle que adopte un protocolo específico de Kit. Si ya dispones de una API para socios, un importador de feeds XML, un flujo OAuth, un endpoint de taxonomías, un callback de moderación o un contrato de candidaturas externas, nos integraremos con eso.
Esta guía es una lista de descubrimiento, no una especificación impuesta a los socios. Su objetivo es acortar la primera conversación técnica: muestra qué puede ofrecer Kit hoy, qué decisiones suelen hacer falta y dónde podemos adaptarnos a tu proceso actual.
Important
El contrato de producción que utilizas sigue siendo la referencia. Adaptaremos Kit a los campos documentados, la autenticación, el ciclo de vida, las reglas de créditos y el flujo de candidatos del portal. Los ejemplos siguientes describen las funciones actuales de Kit; no presuponen que un portal concreto acepte estos formatos.
Formas de integración
La mayoría de las colaboraciones utiliza una o varias de estas formas:
| Forma | Cuándo conviene | Qué ofrece Kit |
|---|---|---|
| Envío a la API del portal | El portal ya tiene una API para empleadores o publicación múltiple | Creación, actualización, pausa o cierre y sincronización de estado mediante un adaptador específico |
| El portal consulta un feed | El portal ingiere feeds de tenants o ATS de forma periódica | Un feed XML público y almacenable en caché por empleador; añadimos el dialecto del portal conforme a su esquema oficial |
| Enlace de candidatura externa | El portal envía a los candidatos al ATS del empleador | Una URL estable de la oferta o una URL directa de candidatura con atribución de origen |
| Candidatura nativa hacia Kit | El portal recoge la candidatura y tiene autorización para reenviarla | Una API de servidor limitada al tenant, un flujo de carga de CV con firma previa, el esquema del formulario y un justificante de envío sin información personal |
Podemos empezar por la forma compatible más sencilla y añadir después una sincronización más completa de estados o candidaturas. Un feed consultado por el portal no obliga a implementar el modelo de envío de Kit, y una integración de envío no obliga a consumir ninguno de los dialectos de feed existentes en Kit.
Formatos que Kit ya ofrece
Feeds públicos XML y Atom
Cada portal de empleo alojado dispone de un feed por empleador con solo las ofertas que aceptan candidaturas en ese momento:
https://startupkit.app/careers/example/jobs.xml
https://startupkit.app/careers/example/jobs/atom
Los dominios personalizados de portales de empleo exponen los mismos feeds en /jobs.xml y /jobs/atom. Kit genera actualmente dialectos de Adzuna, Atom 1.0, Jooble, Jobrapido, Talent.com y Uitzendbureau. Estos formatos muestran los datos disponibles; no presuponemos que otro portal acepte alguno de ellos. Cuando un socio facilite su esquema y cargas de ejemplo, Kit puede generar un dialecto específico en una URL estable. Los empleadores que usan Talent.com pueden seguir Publicar ofertas en Talent.com.
Las entradas del feed utilizan un identificador público estable de la oferta y pueden incluir:
- título y descripción HTML;
- nombre del empleador, departamento o categoría, ubicación y modalidad remota;
- fechas de publicación y actualización;
- tipo de empleo;
- salario mínimo y máximo, moneda y periodo cuando se divulgan;
- URL pública de la oferta y URL directa de candidatura con atribución UTM específica del socio.
Al pausar o cerrar una oferta, esta desaparece del feed. Al reabrirla, vuelve a aparecer con el mismo identificador público y la fecha de actualización correspondiente.
API REST de ofertas públicas
La API de ofertas públicas ofrece JSON mediante HTTPS para integraciones de servidor o navegador:
GET /api/public/v1/jobs
GET /api/public/v1/jobs/:public_token
POST /api/public/v1/jobs/:public_token/applications
La lista solo devuelve ofertas publicadas. La respuesta de detalle añade la descripción HTML saneada y el esquema del formulario de candidatura del empleador. Cada empleador crea un par de claves limitado al tenant; las integraciones de servidor utilizan la clave secreta sk_…. Ninguna clave puede leer registros de candidatos.
El reenvío de candidaturas nativas se acuerda por separado porque el portal debe respetar las preguntas obligatorias, las restricciones del CV, la información de consentimiento, la protección frente a bots y el origen real del candidato. Si un portal ya admite una URL de ATS externo, redirigir al candidato a Kit suele ser la primera versión más rápida y limpia.
Datos estructurados JobPosting
Cada página pública de una oferta incluye JSON-LD de schema.org/JobPosting generado en el servidor. Contiene la descripción, las fechas, el empleador, la ubicación o los requisitos de trabajo remoto, el tipo de empleo, el salario si existe, el estado de candidatura directa y la URL canónica.
El JSON-LD resulta útil para descubrimiento y validación. No sustituye a una API de publicación, un esquema de feed, un estado de moderación o un callback de ciclo de vida acordados.
Webhooks firmados del ciclo de vida
Kit puede enviar webhooks firmados cuando una oferta se:
- publica:
job_posting.published - pausa:
job_posting.paused - cierra:
job_posting.closed - reabre:
job_posting.reopened
El evento identifica al tenant y a la oferta, e incluye su estado y URL pública actuales. El socio puede utilizarlo como señal de invalidación y volver a consultar la oferta canónica en el feed o la API acordados. Consulta Introducción a los webhooks y Seguridad y entrega de webhooks.
Datos canónicos de las ofertas
Las superficies de publicación actuales de Kit pueden proporcionar este contrato básico:
| Campo | Notas |
|---|---|
| ID estable de la oferta | El token público permanece estable tras ediciones, pausas y reaperturas |
| Título y descripción | Título en texto sin formato y descripción HTML saneada |
| Empleador | Nombre del tenant; el logotipo y el sitio web proceden del perfil del empleador |
| Departamento o categoría | Valor escrito por el empleador y adaptado a la taxonomía del portal cuando es necesario |
| Ubicación y trabajo remoto | Ubicación en texto libre; ciudad, región y código de país estructurados; indicador remoto, y los países donde pueden estar los candidatos en remoto |
| Empleo | Tipo de empleo; durante el mapeo pueden recopilarse valores contractuales específicos del socio |
| Retribución | Mínimo, máximo, moneda ISO y periodo por hora, día, mes o año cuando se divulga |
| Fechas | Marcas de tiempo de publicación y última actualización; las ofertas cerradas salen de los feeds activos |
| URL | URL canónica de la oferta y URL directa de candidatura |
| Formulario de candidatura | Campos obligatorios, preguntas de cribado, información de consentimiento y restricciones del CV |
Los portales suelen exigir otros datos controlados, como nivel, competencias, idiomas, ID de categoría, varias ubicaciones, taxonomías de contratos, avisos de privacidad u opciones de paquetes de pago. Mapeamos o recopilamos esos campos durante la revisión de la integración en vez de forzarlos a un valor genérico que pierda información.
Qué necesitamos del socio
Envíanos la documentación y el flujo de trabajo que ya utilizas. Esta lista ayuda a detectar pronto las carencias; no pasa nada si algunos puntos no se aplican.
- Contactos técnicos y comerciales
- Documentación de la API, feed o publicación múltiple, con peticiones y respuestas de ejemplo
- Credenciales de sandbox o una cuenta de prueba segura
- Autenticación, rotación de claves, ámbitos, límites de frecuencia y requisitos de IP
- Taxonomías de categoría, ubicación, nivel, competencias, contrato y salario
- Campos obligatorios y opcionales, además de sus reglas de validación
- Comportamiento al crear, editar, publicar, pausar o cerrar, reabrir y caducar
- Idempotencia, reintentos, prevención de duplicados y semántica de errores
- Estados de moderación y compatibilidad con consultas periódicas o callbacks
- Reglas para candidaturas externas o nativas, atribución del origen, privacidad y conservación
- Propiedad de paquetes, consumo de créditos, selección de marca y reglas para créditos de prueba
- Proceso de aprobación, certificación y soporte para producción
Tip
Un ejemplo que funciona vale más que un documento nuevo. Para empezar nos basta una colección de Postman, un archivo OpenAPI, un ejemplo XML o una guía de integración existentes. Adaptaremos Kit y documentaremos solo las decisiones específicas de nuestra conexión.
Seguridad y datos de candidatos
- Los feeds públicos y los endpoints de ofertas contienen datos de empleo, nunca información personal de candidatos.
- Las credenciales se limitan al tenant y los secretos del servidor no se exponen al navegador.
- Los webhooks están firmados. El receptor debe verificar la firma y la antigüedad de la solicitud para rechazar repeticiones.
- Los datos de candidaturas solo se aceptan mediante una entrada acordada o la página de candidatura de Kit del empleador.
- No creamos integraciones con socios rastreando endpoints privados o sin documentar.
Iniciar una colaboración
Escribe a [email protected] y adjunta tu guía de integración o indica quién es responsable de ella. Te responderemos con un mapeo conciso de campos y el piloto más pequeño que resulte útil para ambos equipos.
En resumen
- Elige entre API de envío, feed consultado por el portal, candidatura externa, candidatura nativa o una combinación
- Comparte el contrato existente del portal y una vía de sandbox
- Acordad el mapeo de campos y taxonomías, además del consumo de créditos
- Prueba las rutas de creación, edición, cierre, errores y moderación
- Verifica la atribución del origen y la privacidad de los candidatos
- Empieza con un pequeño piloto de pago y vigila después los estados y las candidaturas