Crear

Descripcion general

Este endpoint permite crear uno o varios registros patronales (IMSS) 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 fila debe enviar legal_entity_number, number, risk_class, risk_premium y premium_effective_from. Una solicitud exitosa devuelve 201 con los registros creados, incluyendo los campos generados por el servidor (employer_registration_number, created_at, updated_at).

En modo lote, si cualquier fila falla la validación, ningún registro se crea — la respuesta lista los problemas por fila para corregirlos en una sola pasada. Un lote puede mezclar registros de varias razones sociales: la unicidad se aplica por par (legal_entity_number, number), por lo que dos filas con el mismo number pero distinta legal_entity_number son válidas.

risk_premium se acepta como número JSON (0–1) en el cuerpo, pero se serializa como string decimal (Decimal(9,7), por ejemplo "0.0054355") en la respuesta para preservar la precisión.

Inicio del audit trail de prima. En cada creación exitosa se abre una fila inicial en premium_history con effective_from = premium_effective_from y effective_to = null. Este trail es la fuente para los archivos SUA, así que es append-only — nunca se edita. Los cambios posteriores de risk_class / risk_premium agregan nuevas filas vía PATCH.

Endpoint

{
  "legal_entity_number": 1,
  "number": "Y6712345678",
  "risk_class": 1,
  "risk_premium": 0.005,
  "premium_effective_from": "2026-01-01"
}

{
  "legal_entity_number": 1,
  "number": "Y6712345678",
  "label": "RP principal CDMX",
  "risk_class": 1,
  "risk_premium": 0.005,
  "premium_effective_from": "2026-01-01",
  "is_active": true
}

[
  {
    "legal_entity_number": 1,
    "number": "Y6712345678",
    "risk_class": 1,
    "risk_premium": 0.005,
    "premium_effective_from": "2026-01-01"
  },
  {
    "legal_entity_number": 2,
    "number": "Y8898765432",
    "risk_class": 3,
    "risk_premium": 0.02513,
    "premium_effective_from": "2026-01-01"
  }
]

Reglas de los campos

Forma de las respuestas

201 — solicitud única

Cuando el cuerpo es un objeto, la respuesta es el objeto del registro creado.

{
  "employer_registration_number": 5,
  "legal_entity_number": 1,
  "number": "Y6712345678",
  "label": "RP principal CDMX",
  "risk_class": 1,
  "risk_premium": "0.005",
  "premium_effective_from": "2026-01-01T00:00:00.000Z",
  "is_active": true,
  "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": [
    { "employer_registration_number": 6, "...": "..." },
    { "employer_registration_number": 7, "...": "..." }
  ]
}

Errores

400 — validación fallida (solicitud única)

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

{
  "message": "Validation failed.",
  "errors": { "risk_premium": ["La prima debe expresarse como fracción (0–1)."] }
}

400 — validación fallida (solicitud por lote)

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

{
  "message": "Validation failed for 1 employer registration(s). No registrations were created.",
  "summary": { "total": 2, "with_errors": 1 },
  "errors": [
    {
      "index": 0,
      "employer_registration": { "legal_entity_number": 99, "number": "Y6712345678" },
      "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.
• employer_registration.legal_entity_number / employer_registration.number — 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 — condición de carrera

Otra solicitud reclamó el par (legal_entity_id, number) 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 registro 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: