> ## 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.

# Integrar Órdenes de Trabajo

> Guía paso a paso para crear, sincronizar y gestionar Órdenes de Trabajo (OTs) via la API de Terceros de SIMA

## Resumen

Las Órdenes de Trabajo (OTs) son la entidad central de SIMA. Representan operaciones de campo — aplicaciones, labores, scouting y más. Los sistemas de terceros pueden crear, leer, actualizar y eliminar OTs de forma bidireccional.

<Warning>
  Antes de crear una OT, debés tener la **estructura jerárquica** (Establecimientos, Campañas, Lotes) y los **datos maestros** (Formulados, Máquinas, Aplicadores) ya configurados en SIMA. Si aún no los tenés, empezá con la guía de [Configuración de Jerarquía](/guides/hierarchy-setup).
</Warning>

***

## Estructura de una OT

Cada Orden de Trabajo tiene tres secciones:

| Sección    | Descripción                                                              |
| ---------- | ------------------------------------------------------------------------ |
| `header`   | Información general: nombre, fecha, estado, empresa, tipo de comprobante |
| `supplies` | Aplicaciones de agroquímicos — formulado, área y cantidad por cultivo    |
| `labours`  | Labores — aplicadores, contratistas, máquinas por cultivo                |

Cada línea de supply o labour está vinculada a un **cultivo** (`cultivation.local_id`), que asocia la operación a una combinación específica de lote + campaña + cultivo.

***

## Checklist de prerequisitos

Antes de crear una OT, confirmá que tenés IDs para:

<Steps>
  <Step title="Empresa">
    El contexto de sociedad. Obtenelo de la respuesta del login (`society.id`) o via `GET /api/v3/third_party/companies`.
  </Step>

  <Step title="Cultivo">
    La combinación de lote + campaña + cultivo que es objetivo de la operación. Obtenelo via `GET /api/v3/third_party/cultivations`. Cada línea de supply y labour necesita un `cultivation_id`.
  </Step>

  <Step title="Formulados (para supplies)">
    El producto agroquímico. Obtenés los IDs de `GET /api/v3/third_party/formulateds`.
  </Step>

  <Step title="Aplicadores / Contratistas / Máquinas (para labours)">
    Opcional pero frecuente. Obtenelos de sus respectivos endpoints de datos maestros.
  </Step>
</Steps>

***

## Endpoints

### Listar Órdenes de Trabajo

```
GET /api/v3/third_party/work_orders
```

**Filtros principales:**

| Parámetro         | Tipo     | Descripción                                     |
| ----------------- | -------- | ----------------------------------------------- |
| `updated_at_from` | datetime | Detectar cambios desde la última sincronización |
| `updated_at_to`   | datetime | Límite superior para detección de cambios       |
| `state`           | string   | `confirmed` o `pending`                         |
| `cultivation_id`  | int      | Filtrar por cultivo                             |
| `formulated_id`   | int      | Filtrar por formulado utilizado                 |
| `page` / `size`   | int      | Paginación (tamaño por defecto: 10)             |

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.qa.sima.ag/api/v3/third_party/work_orders?updated_at_from=2024-01-01T00:00:00-03:00&page=1" \
    -H "Authorization: Bearer TU_TOKEN" \
    -H "X-SIMA-SYSTEM-ID: 8" \
    -H "Accept: application/json"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.qa.sima.ag/api/v3/third_party/work_orders",
      headers={"Authorization": f"Bearer {token}", "X-SIMA-SYSTEM-ID": "8"},
      params={"updated_at_from": "2024-01-01T00:00:00-03:00", "page": 1},
  )
  ```
</CodeGroup>

***

### Crear una Orden de Trabajo

```
POST /integration/api/v1/workOrders
```

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.qa.sima.ag/integration/api/v1/workOrders \
    -H "Authorization: Bearer TU_TOKEN" \
    -H "X-SIMA-SYSTEM-ID: 8" \
    -H "Content-Type: application/json" \
    -d '{
      "header": {
        "system_id": "third_party",
        "name": "Aplicación Herbicida - Lote L1",
        "date": "2024-07-04T17:03:14-03:00",
        "voucher_date": "2024-07-04T00:00:00-03:00",
        "state": { "pending": true, "executed": false, "confirmed": false },
        "extra_fields": {
          "company": { "local_id": 32 },
          "voucher_type": { "local_id": 7 }
        }
      },
      "supplies": [
        {
          "cultivation": { "local_id": 243405 },
          "date": "2024-07-04T17:03:14-03:00",
          "area_applied": 37,
          "formulated": { "local_id": 8844 },
          "total_applied": 59.999,
          "state": { "pending": true, "executed": false, "confirmed": false },
          "extra_fields": { "voucher_type": { "local_id": 7 } }
        }
      ],
      "labours": [
        {
          "cultivation": { "local_id": 243405 },
          "date": "2024-07-04T00:00:00-03:00",
          "area_applied": 37,
          "contractors": [{ "local_id": 3056 }],
          "machines": [{ "local_id": 4419 }],
          "state": { "pending": true, "executed": false, "confirmed": false },
          "extra_fields": { "voucher_type": { "local_id": 7 } }
        }
      ]
    }'
  ```
</CodeGroup>

Una respuesta exitosa devuelve la OT creada con el `local_id` asignado por SIMA en el header. **Guardá este ID** para vincular futuras actualizaciones o eliminaciones.

***

### Actualizar una OT

```
PATCH /integration/api/v1/workOrders/{localId}
```

Enviá la estructura completa de la OT (igual que en la creación) con los campos modificados. SIMA reemplaza los supplies y labours existentes con lo que enviás.

***

### Eliminar una OT

```
DELETE /integration/api/v1/workOrders/{localId}
```

Devuelve `HTTP 204 No Content` si fue exitoso.

**Eliminación masiva** (múltiples IDs a la vez):

```
DELETE /integration/api/v1/workOrdersGroup
```

```json theme={null}
{ "data": [473229, 473228] }
```

***

### Agregar información adicional a una OT

Usá esto para adjuntar metadata personalizada de tu sistema a una OT existente:

```
POST /api/v3/third_party/{wo_id}/additional_info
```

```json theme={null}
{
  "origin_system": "nombre-de-tu-erp",
  "data": { "referencia_erp": "OT-2024-0042", "centro_costo": "CAMPO-01" }
}
```

***

## Estados de una OT

| Estado            | Significado                              |
| ----------------- | ---------------------------------------- |
| `pending: true`   | Creada pero aún no ejecutada en el campo |
| `executed: true`  | Operación de campo completada            |
| `confirmed: true` | Revisada y confirmada en SIMA            |

<Info>
  Las OTs con `is_read_only: true` no pueden modificarse. Verificá este campo antes de intentar una actualización.
</Info>

***

## Mapeo de IDs entre sistemas

Cada entidad en SIMA tiene un `local_id` (ID de SIMA) y un `external_id` (ID de tu sistema). Al crear una OT desde tu sistema, podés pasar tu propio ID como `external_id` para usarlo en búsquedas futuras:

```json theme={null}
"header": {
  "system_id": "third_party",
  "local_id": null,
  "external_id": "tu-id-de-erp-aqui"
}
```

***

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Configurar la Jerarquía" icon="sitemap" href="/guides/hierarchy-setup">
    Configurá Establecimientos, Campañas y Lotes antes de crear OTs
  </Card>

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

  <Card title="Estrategia de Sincronización" icon="arrows-rotate" href="/guides/sync-strategy">
    Cómo detectar y traer cambios eficientemente
  </Card>
</CardGroup>