Integrar Órdenes de Trabajo

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.

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.

Las OTs usan dos rutas de API: lectura en v3 (/api/v3/third_party/work_orders) y escritura en v1 (/integration/api/v1/workOrders). Ver Versiones de la API para el detalle.

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:

Empresa

El contexto de sociedad. Obtenelo de la respuesta del login (society.id) o via GET /api/v3/third_party/companies.

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.

Formulados (para supplies)

El producto agroquímico. Obtenés los IDs de GET /api/v3/third_party/formulateds.

Aplicadores / Contratistas / Máquinas (para labours)

Opcional pero frecuente. Obtenelos de sus respectivos endpoints de datos maestros.

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)

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"

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},
)

Respuesta exitosa (HTTP 200):

{
  "items": [
    {
      "id": 473229,
      "name": "Aplicación Herbicida - Lote L1",
      "date": "2024-07-04T17:03:14-03:00",
      "state": { "pending": true, "executed": false, "confirmed": false },
      "is_read_only": false,
      "cultivation_id": 243405,
      "company_id": 32,
      "updated_at": "2024-07-04T17:03:14-03:00",
      "created_at": "2024-07-04T17:03:14-03:00"
    }
  ],
  "current_page": 1,
  "next_page": null,
  "total_pages": 1,
  "total_items": 1
}

Crear una Orden de Trabajo

POST /integration/api/v1/workOrders

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 } }
      }
    ]
  }'

Respuesta exitosa (HTTP 200):

{
  "header": {
    "local_id": 473229,
    "external_id": null,
    "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": [
    {
      "local_id": 891234,
      "cultivation": { "local_id": 243405 },
      "formulated": { "local_id": 8844 },
      "area_applied": 37,
      "total_applied": 59.999
    }
  ],
  "labours": [
    {
      "local_id": 891235,
      "cultivation": { "local_id": 243405 },
      "area_applied": 37,
      "contractors": [{ "local_id": 3056 }],
      "machines": [{ "local_id": 4419 }]
    }
  ]
}

Guardá el local_id del header (473229 en este ejemplo) 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.

Siempre hacé un GET antes de un PATCH. Obtené la OT actual con GET /api/v3/third_party/work_orders, construí el payload a partir de esa respuesta, aplicá tus cambios y enviá la estructura completa. Ver Schemas de Entidades.

Respuesta exitosa (HTTP 200): devuelve la OT actualizada con la misma estructura que el POST.

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

{ "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/work_orders/{wo_id}/additional_info

{
  "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

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

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:

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

Próximos pasos

Configurar la Jerarquía

Configurá Establecimientos, Campañas y Lotes antes de crear OTs

Datos Maestros

Sincronizá Formulados, Máquinas y Aplicadores

Estrategia de Sincronización

Cómo detectar y traer cambios eficientemente

Empezar

Guías de Integración

Resumen

Estructura de una OT

Checklist de prerequisitos

Endpoints

Listar Órdenes de Trabajo

Crear una Orden de Trabajo

Actualizar una OT

Eliminar una OT

Agregar información adicional a una OT

Estados de una OT

Mapeo de IDs entre sistemas

Próximos pasos

Configurar la Jerarquía

Datos Maestros

Estrategia de Sincronización

​Resumen

​Estructura de una OT

​Checklist de prerequisitos

​Endpoints

​Listar Órdenes de Trabajo

​Crear una Orden de Trabajo

​Actualizar una OT

​Eliminar una OT

​Agregar información adicional a una OT

​Estados de una OT

​Mapeo de IDs entre sistemas

​Próximos pasos

Configurar la Jerarquía

Datos Maestros

Estrategia de Sincronización

Resumen

Estructura de una OT

Checklist de prerequisitos

Endpoints

Listar Órdenes de Trabajo

Crear una Orden de Trabajo

Actualizar una OT

Eliminar una OT

Agregar información adicional a una OT

Estados de una OT

Mapeo de IDs entre sistemas

Próximos pasos