# Crear (/docs/developers/api-reference/legal-entities/create)

## Descripcion general [#descripcion-general]

Este endpoint permite crear una o varias razones sociales 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. Una solicitud exitosa devuelve `201` con la(s) razón(es) social(es) creada(s), incluyendo los campos generados por el servidor (`legal_entity_number`, `created_at`, `updated_at`).

`legal_entity_number` lo asigna el servidor: **no lo envíes**. En modo lote, si **cualquier** fila falla la validación, **ninguna** razón social se crea — la respuesta lista los problemas por fila para corregirlos en una sola pasada.

**Preparación para nómina.** Al crear cada razón social se le vinculan automáticamente los **valores de nómina compartidos** de la organización: el catálogo de conceptos estándar y el contrato base, que se crea con las prestaciones mínimas de ley (aguinaldo de 15 días, prima vacacional de 25 % y vacaciones según la tabla de ley), de modo que queda lista para nómina de inmediato. La operación es idempotente: en modo lote nunca se duplican.

## Endpoint [#endpoint]

`POST https://app.integranom.com/api/v1/legal-entities`

## Solicitud unica — minima [#solicitud-unica--minima]

***

`name` es el único campo requerido. `is_active` toma el valor `true` por defecto.

```json
{ "name": "Acme S.A. de C.V." }
```

**cURL**

```bash
curl -X POST "https://app.integranom.com/api/v1/legal-entities" \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme S.A. de C.V." }'
```

**Respuesta**

```json
{
"legal_entity_number": 7,
"name": "Acme S.A. de C.V.",
"is_active": true,
"created_at": "2026-05-25T10:00:00.000Z",
"updated_at": null
}
```

## Solicitud unica — inactiva al crear [#solicitud-unica--inactiva-al-crear]

***

Puedes crear una razón social inactiva pasando `is_active: false`. Aparecerá en `GET` (salvo que filtres por `active=true`) y podrá activarse después con `PATCH`.

```json
{ "name": "Acme S.A. de C.V.", "is_active": false }
```

**cURL**

```bash
curl -X POST "https://app.integranom.com/api/v1/legal-entities" \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme S.A. de C.V.", "is_active": false }'
```

**Respuesta**

```json
{
"legal_entity_number": 7,
"name": "Acme S.A. de C.V.",
"is_active": false,
"created_at": "2026-05-25T10:00:00.000Z",
"updated_at": null
}
```

## Solicitud por lote (1–100 razones sociales) [#solicitud-por-lote-1100-razones-sociales]

***

Envía un **arreglo** de hasta 100 razones sociales en el mismo endpoint. Si **cualquier** fila falla la validación, **ninguna** razón social se crea y la respuesta lista los problemas por fila.

```json
[
  { "name": "Acme S.A. de C.V." },
  { "name": "Beta S.A. de C.V." }
]
```

**cURL**

```bash
curl -X POST "https://app.integranom.com/api/v1/legal-entities" \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json" \
-d '[
  { "name": "Acme S.A. de C.V." },
  { "name": "Beta S.A. de C.V." }
]'
```

**Respuesta**

```json
{
"summary": { "total": 2, "created": 2 },
"created": [
  {
    "legal_entity_number": 7,
    "name": "Acme S.A. de C.V.",
    "is_active": true,
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": null
  },
  {
    "legal_entity_number": 8,
    "name": "Beta S.A. de C.V.",
    "is_active": true,
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": null
  }
]
}
```

## Reglas de los campos [#reglas-de-los-campos]

| Campo       | Tipo    | Requerido | Notas                            |
| ----------- | ------- | --------- | -------------------------------- |
| `name`      | string  | Sí        | No vacío tras recortar espacios. |
| `is_active` | boolean | No        | Por defecto `true`.              |

## Forma de las respuestas [#forma-de-las-respuestas]

### `201` — solicitud única [#201--solicitud-única]

Cuando el cuerpo es **un objeto**, la respuesta es el objeto de la razón social creada.

```json
{
  "legal_entity_number": 7,
  "name": "Acme S.A. de C.V.",
  "is_active": true,
  "created_at": "2026-05-25T10:00:00.000Z",
  "updated_at": null
}
```

### `201` — solicitud por lote [#201--solicitud-por-lote]

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

```json
{
  "summary": { "total": 2, "created": 2 },
  "created": [
    { "legal_entity_number": 7, "name": "Acme S.A. de C.V.", "...": "..." },
    { "legal_entity_number": 8, "name": "Beta S.A. de C.V.", "...": "..." }
  ]
}
```

## Errores [#errores]

### `400` — JSON inválido [#400--json-inválido]

```json
{ "message": "Invalid JSON body." }
```

### `400` — validación fallida (solicitud única) [#400--validación-fallida-solicitud-única]

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

```json
{
  "message": "Validation failed.",
  "errors": { "name": ["Ingresa el nombre."] }
}
```

### `400` — validación fallida (solicitud por lote) [#400--validación-fallida-solicitud-por-lote]

Reporte por fila. **Ninguna** razón social del lote fue creada.

```json
{
  "message": "Validation failed for 1 legal entity(ies). No legal entities were created.",
  "summary": { "total": 2, "with_errors": 1 },
  "errors": [
    {
      "index": 0,
      "legal_entity": { "name": "" },
      "issues": [
        {
          "field": "name",
          "code": "INVALID_INPUT",
          "message": "Ingresa el nombre."
        }
      ]
    }
  ]
}
```

* `index` — posición 0-based de la fila que falló dentro del arreglo enviado.
* `legal_entity.name` — extraído de tu entrada para que identifiques la fila sin contar.
* `issues[]` — todos los problemas de esa fila listados juntos para corregirlos antes de reintentar.

Si la falla es a nivel del arreglo (por ejemplo más de 100 elementos), la respuesta cae al formato plano indexado por campo: `{ "message": "Validation failed.", "errors": { ... } }`.

### `500` [#500]

```json
{ "message": "Internal Server Error" }
```

## Vocabulario de códigos de error [#vocabulario-de-códigos-de-error]

| Codigo          | Significado                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `INVALID_INPUT` | Falla genérica de validación de esquema (campo faltante, tipo incorrecto, `name` vacío tras recortar). |