> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tp.sima.ag/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración de Jerarquía

> Cómo configurar la jerarquía de entidades en SIMA — Sociedades, Establecimientos, Campañas, Lotes y Cultivos — requerida antes de crear Órdenes de Trabajo

## Resumen

SIMA organiza los datos agropecuarios en una jerarquía estricta. Cada OT se vincula en última instancia a un **cultivo**, que es la combinación de un lote, una campaña y un cultivo. Debés configurar esta jerarquía antes de poder registrar operaciones de campo.

```
Sociedad (Productor)
  └── Establecimiento
        └── Lote
              └── Campaña Madre → Campaña
                    └── Cultivo (Lote + Campaña + Especie)
                          └── Orden de Trabajo
```

<Info>
  Si tu sistema ya tiene establecimientos y lotes, creálos en SIMA y vinculálos usando el campo `external_code` para mapear entre tus IDs y el `local_id` de SIMA.
</Info>

***

## Orden de configuración

El orden importa — cada nivel depende del anterior.

<Steps>
  <Step title="Verificar tu Sociedad (Productor)">
    El contexto de tu sociedad se devuelve en la respuesta del login como `society.id`. Es la raíz de todos tus datos. Las sociedades no se crean via API — son aprovisionadas por SIMA durante el onboarding.
  </Step>

  <Step title="Crear Establecimientos">
    Un establecimiento es un campo o grupo de campos perteneciente a un productor. Requiere un `farmer_id`.
  </Step>

  <Step title="Crear Lotes">
    Un lote es una parcela específica dentro de un establecimiento. Requiere un `establishment_id`.
  </Step>

  <Step title="Crear Campañas Madre y Campañas">
    Una campaña madre es una temporada agrícola (ej: "2024/25"). Una campaña es el cultivo específico dentro de esa temporada en un conjunto de lotes.
  </Step>

  <Step title="Crear Cultivos">
    Un cultivo vincula un lote a una campaña y una especie. Esta es la entidad referenciada en cada línea de OT.
  </Step>
</Steps>

***

## Establecimientos

### Crear

```
POST /api/v3/third_party/establishments
```

```json theme={null}
{
  "farmer_id": 13873,
  "name": "La Correntina",
  "observations": "Sector norte, bajo riego"
}
```

**Respuesta:**

```json theme={null}
{
  "id": 118422,
  "farmer_id": 13873,
  "name": "La Correntina",
  "observations": "Sector norte, bajo riego",
  "location": null,
  "created_at": "2024-08-30T18:03:13-03:00",
  "active": true
}
```

Guardá el `id` devuelto — lo vas a necesitar para crear lotes.

### Actualizar

```
PATCH /api/v3/third_party/establishments/{id}
```

### Eliminar

```
DELETE /api/v3/third_party/establishments/{id}
```

### Listar

```
GET /api/v3/third_party/establishments
```

**Filtros principales:**

| Parámetro         | Tipo     | Descripción                                    |
| ----------------- | -------- | ---------------------------------------------- |
| `farmer_id`       | int      | Filtrar por productor                          |
| `updated_at_from` | datetime | Detectar establecimientos nuevos o modificados |
| `page` / `size`   | int      | Paginación                                     |

***

## Lotes

### Crear

```
POST /api/v3/third_party/plots
```

```json theme={null}
{
  "establishment_id": 118422,
  "name": "Lote 1 Norte",
  "area": 150.5
}
```

### Listar

```
GET /api/v3/third_party/plots
```

Los lotes se pueden filtrar por `establishment_id` y `updated_at_from` para detección de cambios.

***

## Campañas Madre y Campañas

Una **Campaña Madre** representa una temporada agrícola (ej: "2024/25 Finos"). Una **Campaña** es el cultivo específico + período vinculado a un conjunto de lotes dentro de esa temporada.

### Listar Campañas Madre

```
GET /api/v3/third_party/master_campaigns
```

### Listar Campañas

```
GET /api/v3/third_party/campaigns
```

**Filtros principales:**

| Parámetro          | Descripción                           |
| ------------------ | ------------------------------------- |
| `establishment_id` | Campañas dentro de un establecimiento |
| `updated_at_from`  | Detección de cambios                  |
| `active`           | Solo campañas activas                 |

***

## Cultivos

Un cultivo vincula un **lote + campaña + especie**. Cada línea de supply y labour en una OT referencia un `cultivation_id`.

### Listar Cultivos

```
GET /api/v3/third_party/cultivations
```

Es el endpoint que vas a consultar con más frecuencia — devuelve los IDs que necesitás para crear OTs.

**Consulta típica para obtener cultivos de un establecimiento:**

```bash theme={null}
GET /api/v3/third_party/cultivations?establishment_id=118422&active=true
```

***

## Vincular tus IDs con los IDs de SIMA

Cuando tu sistema tiene sus propios identificadores, usá `external_code` para crear un mapeo persistente:

```json theme={null}
{
  "farmer_id": 13873,
  "name": "La Correntina",
  "external_code": "TU-ERP-ESTAB-001"
}
```

Luego podés buscar la entidad por tu propio código: `GET /api/v3/third_party/establishments?external_code=TU-ERP-ESTAB-001`

***

## Manejo de entidades existentes

Si tu cliente ya tiene establecimientos y lotes configurados en SIMA (ej: cargados manualmente via la app web), no los recreés. En su lugar:

1. Listá los establecimientos existentes: `GET /api/v3/third_party/establishments`
2. Hacé el match por nombre o ubicación con tus propios registros
3. Guardá el `local_id` de SIMA mapeado a tu propio ID
4. Usá `external_code` en creaciones/actualizaciones futuras para mantener el vínculo

***

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Datos Maestros" icon="database" href="/guides/master-data">
    Sincronizá Formulados, Aplicadores y Máquinas
  </Card>

  <Card title="Órdenes de Trabajo" icon="clipboard-list" href="/guides/work-orders">
    Creá tu primera Orden de Trabajo
  </Card>
</CardGroup>