Casos de uso

Sincronizar usuarios

Mantener tu nómina reflejada en Crehana desde tu propio sistema.

El caso más común de integración: tu sistema de RRHH es la fuente de verdad y Crehana tiene que reflejar altas, bajas y cambios.

El flujo

1

Resolvé primero la estructura

Áreas, cargos y categorías de cargo tienen que existir antes que los usuarios: crear un usuario los exige. Listá lo que ya hay y creá lo que falte.

2

Traé el estado actual

GET /org/{slug}/users/user-organizations/ te da los usuarios que Crehana ya conoce. Recorrelo con limit y offset — ver Paginación.

3

Compará contra tu nómina

Usá el correo como clave de correlación. Es el único identificador que existe en los dos sistemas antes de la primera sincronización.

4

Aplicá las diferencias

Altas con POST /users/, cambios con POST /users/update_user/, bajas con POST /users/{id}/deactivate/.

5

Completá lo que va después

Jefe y campos personalizados sí se asignan una vez que el usuario existe.

Primero: la estructura organizacional

Área, cargo y categoría de cargo son obligatorios para crear un usuario, así que tienen que existir antes. Se crean una sola vez y después se reutilizan:

GET  /org/{slug}/organizations/areas/
GET  /org/{slug}/organizations/positions/
GET  /org/{slug}/organizations/position-categories/

Listá primero lo que ya existe para no duplicar; si falta algo, se crea con el POST de la misma ruta. Guardá los ids: son los que vas a mandar en cada alta.

Altas

POST /users/ exige seis campos: los tres de identidad más los tres de estructura.

$curl -X POST https://www.crehana.com/api/v5/rest/org/acme/users/ \
>  -H "Api-Key: $API_KEY" -H "Secret-Access: $SECRET_ACCESS" \
>  -H "Content-Type: application/json" \
>  -d '{
>        "first_name": "Ana",
>        "last_name": "Pérez",
>        "email": "ana@acme.com",
>        "area_level_1_id": 12,
>        "position_id": 34,
>        "position_category_id": 5
>      }'

Hay más campos opcionales —sede, jefe por correo, documento, fechas de ingreso y baja, teléfono— que podés mandar en el mismo request. Están todos en la API Reference.

Si el correo ya existe en la organización vas a recibir un 409. Eso no es un fallo de tu integración: es la respuesta correcta a un alta duplicada. Tratalo como “ya estaba” y seguí.

Bajas: desactivar, no borrar

La desactivación es reversible: POST /users/reactivate-user/ devuelve al usuario a estado activo conservando su historial de aprendizaje.

Para bajas masivas está POST /users/deactivate/, que recibe varios usuarios en una sola llamada — es lo que conviene si sincronizás por lotes.

DELETE /users/{id}/ también desactiva al usuario: internamente usa la misma familia de mutaciones que deactivate. Si tu intención es dar de baja, usá los endpoints de deactivate, que dicen en el nombre lo que hacen.

Jefe

El jefe se asigna aparte, después del alta, con POST /users/{centralized_user_id}/boss/. Para quitarlo, DELETE sobre la misma ruta.

Campos personalizados

Para lo que no entra en el modelo estándar —legajo, centro de costo, país de facturación— están los campos personalizados. Se definen a nivel organización y después se les asigna valor por usuario:

$curl -X POST https://www.crehana.com/api/v5/rest/org/acme/users/123/custom-fields/ \
>  -H "Api-Key: $API_KEY" -H "Secret-Access: $SECRET_ACCESS" \
>  -H "Content-Type: application/json" \
>  -d '{"custom_fields": [{"id": 7, "value": "L-4821"}]}'

Los campos que no incluyas en el request conservan su valor. No hace falta mandar todos cada vez.

Recomendaciones

  • Sincronizá por diferencias, no por reemplazo. Traer el estado y aplicar solo lo que cambió es más barato y no toca usuarios que no se modificaron.
  • Guardá el id de Crehana en tu sistema después del alta. Correlacionar por correo funciona, pero si alguien cambia de correo perdés el vínculo.
  • Empezá por QA. El mismo flujo contra qa.creha.co te deja probar una sincronización completa sin tocar datos reales.