Crear

Descripcion general

Este endpoint permite crear uno o varios empleados dentro de tu organización. Acepta tanto un objeto como un arreglo de hasta 100 objetos, y la respuesta refleja la forma del cuerpo enviado. Cada empleado se crea vinculado a la legal_entity_number enviada. Una solicitud exitosa devuelve 201 con los empleados creados como un objeto plano que incluye los datos personales, los de su empleo (estatus, fechas, asignaciones y compensación) y los campos generados por el servidor (employee_number, created_at, updated_at).

Estatus y alta de nómina. Si omites activate, el empleado solo se crea con estatus active cuando está listo para nómina, es decir, cuando la fila incluye legal_entity_number, rfc, curp, postal_code (o home_postal_code si fiscal_address_same_as_home es true), work_center_state_code, daily_base_salary, regimen_fiscal, work_shift_type, payroll_calendar_number, contract_number, y además imss_number, imss_worker_type e imss_work_schedule si contributes_to_imss es true. Si falta alguno, se crea como pending (Sin alta en nómina). Con activate: true, un empleado que no está listo se rechaza con 400 ACTIVATION_INCOMPLETE y la lista de datos faltantes; envía activate: false para forzar pending. Si el alta cae en periodos de nómina ya cerrados, la llamada se rechaza con 409 RETRO_CONFIRMATION_REQUIRED (con retro_periods); reenvíala con confirm_retro: true y cada periodo se paga con un ajuste retroactivo en la siguiente nómina. Cuando capturas daily_base_salary, se registra automáticamente la primera fila del historial de sueldos.

En modo lote, si cualquier fila falla la validación, ningún empleado se crea — la respuesta lista los problemas por fila para corregirlos en una sola pasada.

Si envías termination_date en una fila, el empleado se crea dado de baja, útil al cargar el historial de alguien que ya se fue. La fecha no puede ser posterior a hoy ni anterior a hire_date, y la fila no puede traer activate: true (sino, 400). Un empleado creado dado de baja nunca pide confirm_retro ni genera ajustes retroactivos. Si contributes_to_imss es true, employer_registration se vuelve obligatorio en la misma fila (sino, 400).

Movimientos IMSS. Cada empleado creado que aporta al IMSS genera su alta en Movimientos IMSS, y su baja si la fila trae termination_date. Envía already_registered_with_imss: true cuando el alta ya se presentó ante el IMSS fuera de la plataforma, por ejemplo al migrar desde otro sistema: queda registrada como ya presentada, sin fecha límite y sin SBC calculado. Por defecto es false y queda pendiente de presentar. La baja sigue termination_already_registered_with_imss; si lo omites, toma la misma respuesta que el alta.

Tipo de trabajador. worker_type dice qué es la persona para efectos estatutarios: subordinate (por defecto), asimilado u honorarios. No se infiere del tipo de contrato SAT. Un asimilado o un trabajador por honorarios recibe sueldo e ISR sin subsidio, sin IMSS, sin SBC ni prestaciones de ley, así que contributes_to_imss debe ser false para ellos (sino, 400). Por la misma razón no llevan imss_number, employer_registration ni seniority_date: enviar cualquiera de ellos con un worker_type distinto de subordinate responde 400 en ese campo.

Horario de trabajo. El horario se asigna al empleado, no a su contrato: dos personas con el mismo contrato pueden tener horarios distintos. Envía work_schedule_number para un horario semanal fijo o work_schedule_bundle_number para una rotación — nunca ambos (400). Con una rotación puedes indicar work_schedule_bundle_start_step para escalonar al empleado dentro del ciclo (una cuadrilla en matutino mientras otra va en nocturno); si lo omites, arranca en el primer paso de la rotación, que es lo que lo mantiene sincronizado con ella. Un work_schedule_bundle_start_step sin rotación en el mismo cuerpo se rechaza con 400. Si no envías ninguno de los dos, el empleado sigue el horario predeterminado de la organización.

Nota sobre los números de horario: los horarios y las rotaciones aún no se exponen como endpoint propio en la API; utiliza el número visible en Configuración → Tiempo y Acceso → Horarios.

Campos personalizados. Los valores de campos personalizados se envían como claves planas en la raíz del cuerpo del empleado, junto a first_name, rfc, etc. La clave es el key de la definición (gestionada en Campos personalizados → Empleados) y el valor debe ser compatible con el type de la definición. Cualquier definición activa marcada con is_required_for_create: true debe enviarse en cada fila — si falta, la fila falla con CUSTOM_FIELD_REQUIRED.

Endpoint

{
  "first_name": "María",
  "paternal_last_name": "González",
  "rfc": "GOPM900101AB1",
  "curp": "GOPM900101MDFNRR07",
  "legal_entity_number": 1,
  "hire_date": "2026-01-15",
  "work_center_state_code": "CMX"
}

{
  "first_name": "María",
  "paternal_last_name": "González",
  "maternal_last_name": "Pérez",
  "rfc": "GOPM900101AB1",
  "curp": "GOPM900101MDFNRR07",
  "legal_entity_number": 1,
  "hire_date": "2026-01-15",
  "work_center_state_code": "CMX",
  "postal_code": "06000",
  "department_code": "VEN",
  "job_position_code": "GER-VEN",
  "branch_code": "CDMX",
  "cost_center_code": "CC01",
  "contributes_to_imss": true,
  "already_registered_with_imss": false,
  "employer_registration": "Y6712345678",
  "imss_number": "12345678903",
  "daily_base_salary": 500,
  "regimen_fiscal": "02",
  "work_shift_type": "01",
  "payroll_calendar_number": 2,
  "contract_number": 5,
  "work_schedule_number": 3,
  "work_schedule_bundle_number": null,
  "work_schedule_bundle_start_step": null,
  "organizational_units": [10],
  "shirt_size": "M",
  "fit_for_duty": true,
  "years_experience": 7
}

[
  {
    "first_name": "María",
    "paternal_last_name": "González",
    "rfc": "GOPM900101AB1",
    "curp": "GOPM900101MDFNRR07",
    "legal_entity_number": 1,
    "hire_date": "2026-01-15",
    "work_center_state_code": "CMX"
  },
  {
    "first_name": "Juan",
    "paternal_last_name": "Pérez",
    "rfc": "PEXJ850715XY2",
    "curp": "PEXJ850715HDFRRN09",
    "legal_entity_number": 1,
    "hire_date": "2026-01-15",
    "work_center_state_code": "CMX"
  }
]

Campos obligatorios

Campos opcionales — datos personales del empleado

Campos opcionales — datos laborales del empleado

Campos opcionales — valores de campos personalizados

Los valores de campos personalizados se envían como claves planas en la raíz del cuerpo del empleado, no dentro de un objeto envoltorio. La clave es el key de la definición y el valor debe ser compatible con el type declarado:

Si una definición activa tiene is_required_for_create: true, su key debe enviarse en cada fila. Las definiciones opcionales pueden omitirse.

Forma de las respuestas

201 — solicitud única

Cuando el cuerpo es un objeto, la respuesta es el objeto plano del empleado creado: datos personales + los de su empleo actual. El status es active solo si el empleado quedó listo para nómina; de lo contrario, pending.

{
  "employee_number": 5,
  "internal_number": null,
  "first_name": "María",
  "middle_name": null,
  "paternal_last_name": "González",
  "maternal_last_name": null,
  "gender": null,
  "birth_date": null,
  "birth_country": null,
  "birth_state": null,
  "birth_state_code": null,
  "birth_municipality_code": null,
  "birth_city": null,
  "birth_place": null,
  "nationality": null,
  "phone_number": null,
  "secondary_phone_number": null,
  "rfc": "GOPM900101AB1",
  "curp": "GOPM900101MDFNRR07",
  "postal_code": null,
  "work_center_state_code": "CMX",
  "home_street": null,
  "home_exterior_number": null,
  "home_interior_number": null,
  "home_neighborhood": null,
  "home_municipality_code": null,
  "home_city": null,
  "home_state_code": null,
  "home_postal_code": null,
  "fiscal_address_same_as_home": false,
  "domicile_state_code": null,
  "fiscal_street": null,
  "fiscal_exterior_number": null,
  "fiscal_interior_number": null,
  "fiscal_neighborhood": null,
  "fiscal_municipality_code": null,
  "fiscal_city": null,
  "bank": null,
  "clabe": null,
  "account_number": null,
  "card_number": null,
  "notes": null,
  "legal_entity_number": 1,
  "status": "pending",
  "hire_date": "2026-01-15T00:00:00.000Z",
  "seniority_date": null,
  "termination_date": null,
  "job_position_code": null,
  "branch_code": null,
  "department_code": null,
  "cost_center_code": null,
  "employer_registration": null,
  "imss_number": null,
  "contributes_to_imss": false,
  "worker_type": "subordinate",
  "minimum_wage_zone": "general",
  "imss_worker_type": null,
  "imss_work_schedule": null,
  "salary_type": null,
  "is_unionized": false,
  "receives_annual_isr_adjustment": true,
  "opts_into_annual_isr_adjustment": false,
  "is_included_in_payroll_calculations": true,
  "daily_base_salary": null,
  "regimen_fiscal": null,
  "work_shift_type": null,
  "payroll_calendar_number": null,
  "contract_number": null,
  "work_schedule_number": null,
  "work_schedule_bundle_number": null,
  "work_schedule_bundle_start_step": null,
  "organizational_units": [],
  "created_at": "2026-05-25T10:00:00.000Z",
  "updated_at": "2026-05-25T10:00:00.000Z"
}

201 — solicitud por lote

Cuando el cuerpo es un arreglo, la respuesta envuelve los resultados en summary + created[].

{
  "summary": { "total": 2, "created": 2 },
  "created": [
    { "employee_number": 6, "...": "..." },
    { "employee_number": 7, "...": "..." }
  ]
}

Errores

400 — validación fallida (solicitud única)

Lista plana de problemas para el único empleado:

{
  "message": "Validation failed.",
  "errors": [
    {
      "field": "rfc",
      "code": "DUPLICATE_RFC",
      "message": "An employee with this 'rfc' already exists in this organization."
    }
  ]
}

Para fallas de validación de esquema (campo faltante, tipo incorrecto), errors es un objeto indexado por campo:

{
  "message": "Validation failed.",
  "errors": {
    "rfc": ["Ingresa el RFC."],
    "hire_date": ["Ingresa la fecha de ingreso."]
  }
}

400 — validación fallida (solicitud por lote)

Reporte por fila. Ningún empleado del lote fue creado.

{
  "message": "Validation failed for 1 employee(s). No employees were created.",
  "summary": { "total": 2, "with_errors": 1 },
  "errors": [
    {
      "index": 0,
      "employee": { "first_name": "María", "paternal_last_name": "González" },
      "issues": [
        {
          "field": "legal_entity_number",
          "code": "LEGAL_ENTITY_NOT_FOUND",
          "message": "No legal entity with number '99' in this organization."
        }
      ]
    }
  ]
}

• index — posición 0-based de la fila que falló dentro del arreglo enviado.
• employee.first_name / employee.paternal_last_name — extraídos de tu entrada para que identifiques la fila sin contar.
• issues[] — todos los problemas de esa fila listados juntos para corregirlos antes de reintentar.

409: alta en periodos cerrados, número interno duplicado o condición de carrera

Si un empleado se da de alta con una fecha de ingreso dentro de periodos ya cerrados y no enviaste confirm_retro: true, la respuesta es 409 con errors[].code RETRO_CONFIRMATION_REQUIRED y retro_periods. En modo lote, el error llega en la fila correspondiente y ningún empleado es creado.

Si otro empleado de la organización ya tiene el internal_number que enviaste (sin distinguir mayúsculas), la respuesta es 409 con errors[].code DUPLICATE_INTERNAL_NUMBER. En modo lote, dos filas con el mismo número también lo producen, y ningún empleado es creado.

Otra solicitud concurrente reclamó un RFC o CURP entre el momento en que validamos el tuyo y el momento en que escribimos. En modo lote, la transacción completa hace rollback — ningún empleado es creado. Reintenta la misma solicitud.

Vocabulario de códigos de error

Estos códigos aparecen dentro de issues[].code (o como code en el cuerpo de error en single) y son estables — tu cliente puede ramificar lógica con base en ellos: