Asignar turnos

Si tu organización usa Asistencia en Crehana y la planificación de turnos vive en otro sistema, podés mandar las asignaciones por API en vez de cargarlas a mano. Una asignación hecha por API es igual a una hecha desde Crehana: a partir de esas fechas las marcas de la persona se comparan contra ese turno, la puntualidad se clasifica con sus tolerancias y la gestión diaria se recalcula.

POST /api/v5/rest/org/{organization_slug}/time/attendance/shift-assignments/

La referencia completa está en Assign Shift.

Antes de empezar

• Credenciales de administrador. Las credenciales de la API tienen que ser de una cuenta ADMIN de la organización. Con otras, la respuesta es 403.
• El turno ya existe en Crehana. Cada turno tiene un id (shift_id) y, si es rotativo, sus ciclos también tienen id (start_cycle_id). Si el turno lo creás por API con Crear turnos, la respuesta trae los dos ids: guardalos en tu sistema. Si el turno se creó desde Crehana, hoy la API no lo lista: pedile los ids a tu contacto de Crehana.
• El id de cada persona. user_ids lleva ids centralizados: el user.id de GET /org/{organization_slug}/users/user-organizations/. No es el id de learning (learning_user_id). Todas las personas tienen que pertenecer a la organización: si alguna no, la respuesta es 404 con los ids que fallaron y no se asigna a nadie.

Una asignación de punta a punta

curl -X POST "https://www.crehana.com/api/v5/rest/org/acme/time/attendance/shift-assignments/" \
  -H "Api-Key: $API_KEY" \
  -H "Secret-Access: $SECRET_ACCESS" \
  -H "Content-Type: application/json" \
  -d '{
    "shift_id": "4ed0f6c7-a2a7-4de7-90cd-ae8cf26aabb1",
    "user_ids": [97097, 97099],
    "start_date": "2026-10-13",
    "end_date": "2026-12-31"
  }'

{
  "success": true,
  "message": "Shift assigned.",
  "code": "attendance-003",
  "datetime": "2026-10-07T09:00:03.120394",
  "data": {
    "shift_id": "4ed0f6c7-a2a7-4de7-90cd-ae8cf26aabb1",
    "start_date": "2026-10-13",
    "end_date": "2026-12-31",
    "start_cycle_id": null,
    "assignments": [
      {
        "id": "94caeb90-fd35-4e8b-9e67-28c8377cdbfc",
        "user_id": 97097,
        "shift_id": "4ed0f6c7-a2a7-4de7-90cd-ae8cf26aabb1",
        "start_date": "2026-10-13",
        "end_date": "2026-12-31",
        "start_cycle_id": null,
        "is_active": true,
        "created_at": "2026-10-07T14:00:03"
      },
      { "id": "…", "user_id": 97099, "…": "…" }
    ],
    "already_assigned_user_ids": []
  }
}

El 201 confirma que las personas de assignments ya tienen el turno en esas fechas.

Los campos

shift_id

El id del turno, tal como existe en Asistencia. Tiene que ser de tu organización y estar activo; si no, la respuesta es 404.

user_ids

Entre 1 y 100 personas por llamada, sin repetir. Para más gente, hacé varias llamadas.

La llamada es todo o nada: si una sola persona no pertenece a la organización, o no puede tomar el turno (ver Si la persona ya tiene un turno), no se asigna a nadie y la respuesta dice quién falló. Para que una persona no frene al resto, mandá una llamada por persona.

start_date y end_date

Días calendario en formato YYYY-MM-DD, los dos inclusive. end_date es opcional: sin él, la asignación queda abierta hasta que se cambie desde Crehana o se asigne otro turno.

Una asignación puede empezar en el pasado. En ese caso Crehana vuelve a calcular la asistencia de esos días (hasta 30 días hacia atrás) contra el turno nuevo.

start_cycle_id

Solo para turnos rotativos: el id del ciclo con el que arranca la rotación el día start_date. Por ejemplo, en un turno “4 días de trabajo, 2 de descanso”, decide si la persona empieza trabajando o descansando.

• Turno rotativo sin start_cycle_id → 400.
• Turno fijo con start_cycle_id → 400.

Si la persona ya tiene un turno

Hoy una persona tiene un turno por día. Si ya tenía un turno que se solapa con el nuevo en esas fechas, la asignación anterior se desactiva completa (también los días que quedaban fuera del período nuevo) y el turno nuevo la reemplaza. Por eso, para mover a alguien de turno a partir de una fecha alcanza con mandar la asignación nueva desde esa fecha; y si querés conservar parte del turno anterior, mandá después una asignación con ese turno para los días que quedaron sin cubrir.

Un choque se informa con un detalle por persona:

{
  "detail": {
    "errors": ["The shift clashes with a shift that at least one of the people already has in that period; nothing was assigned."],
    "code": "SHIFT_ASSIGNMENT_BLOCKED",
    "conflicts": [
      {
        "user_id": 97099,
        "reason": "SHIFT_TIME_OVERLAP",
        "conflict_date": "2026-10-14",
        "resulting_shift_count": 2,
        "conflicting_shift_id": "331e54df-2597-4286-8ed3-8ca132cc91d3",
        "conflicting_shift_name": "Turno Tarde"
      }
    ]
  }
}

Ante un 409, resolvé el choque desde Crehana (quitando o acortando el turno anterior) y volvé a mandar la asignación.

Reintentos: mandar dos veces es seguro

Si se corta la conexión y no sabés si la asignación llegó, reenviala igual. Las personas que ya tenían exactamente ese turno en ese período no se duplican: vienen en already_assigned_user_ids y no en assignments. Si no había nada nuevo para nadie, la respuesta es 200 con code: attendance-004.

{
  "success": true,
  "message": "Everybody already had this shift in this period.",
  "code": "attendance-004",
  "data": { "assignments": [], "already_assigned_user_ids": [97097, 97099], "...": "..." }
}

Evitá reenviar en paralelo: si dos copias llegan exactamente a la vez, una se guarda y la otra puede responder 409 (INTEGRITY_ERROR).

Respuestas

Los textos de errors son para un log o para una persona: programá contra el status y, si hace falta, contra detail.code. Más en Errores.

Lo que la API no hace (todavía)

• No lista los turnos ni sus ciclos. Los ids te los da Crehana.
• No quita ni acorta asignaciones: eso se hace desde Crehana.
• No crea ni edita turnos.

Lista de verificación

• Las credenciales son de un ADMIN de la organización.
• Tenés el shift_id del turno y, si es rotativo, el start_cycle_id.
• Cada persona pertenece a la organización y tenés su user_id centralizado.
• Las fechas van en YYYY-MM-DD y end_date no es anterior a start_date.
• Si alguien ya tenía turno en esas fechas, sabés que el anterior se desactiva completo.
• Tu integración ya contempla el 409 por choque de turnos.
• Los 500 y los cortes de red se reintentan. Los 4xx se registran y no se reintentan.