Estrategia de Sincronización

Resumen

La API de Terceros de SIMA está diseñada para sincronización incremental. Cada endpoint de listado soporta filtros de auditoría (updated_at_from, deleted_at_from, active) que te permiten traer solo lo que cambió desde tu última sincronización, en lugar de descargar el dataset completo en cada ejecución.

Patrón de filtros de auditoría

Todos los endpoints de listado v3 (y la mayoría de v2) comparten el mismo set de parámetros de auditoría:

Parámetro	Tipo	Descripción
`updated_at_from`	datetime (ISO8601)	Registros modificados en o después de este timestamp
`updated_at_to`	datetime (ISO8601)	Registros modificados antes de este timestamp
`created_at_from`	datetime (ISO8601)	Registros creados en o después de este timestamp
`created_at_to`	datetime (ISO8601)	Registros creados antes de este timestamp
`deleted_at_from`	datetime (ISO8601)	Registros eliminados lógicamente en o después de este timestamp
`deleted_at_to`	datetime (ISO8601)	Registros eliminados lógicamente antes de este timestamp
`active`	bool	Filtrar por flag activo (`true` / `false`)

Formato de datetime: 2024-01-01T00:00:00-03:00 (ISO8601 con offset de timezone)

Los nombres de parámetros difieren entre v2 y v3. v3 usa updated_at_from; algunos endpoints v2 usan updated_from. Siempre verificá el endpoint específico en la referencia de API o consultá la guía de versiones.

Comportamiento por defecto de soft-delete

Por defecto, cuando no pasás ningún parámetro deleted_at_*, la API excluye automáticamente los registros eliminados lógicamente. Obtenés solo filas activas (no eliminadas).

# Devuelve solo establecimientos no eliminados
GET /api/v3/third_party/establishments?page=1

Para incluir registros eliminados (ej. para detectar borrados), pasá un rango con deleted_at_from:

# Devuelve establecimientos eliminados después del 1 de enero de 2024
GET /api/v3/third_party/establishments?deleted_at_from=2024-01-01T00:00:00-03:00

Flujo de sincronización recomendado

Sincronización inicial (primera vez)

Descargá el dataset completo de cada entidad. Paginá por todas las páginas.

page = 1
while True:
    response = requests.get(
        f"{BASE_URL}/api/v3/third_party/formulateds",
        headers=headers,
        params={"page": page, "size": 100, "active": "true"},
    )
    data = response.json()
    store_locally(data["items"])

    if data["next_page"] is None:
        break
    page += 1

save_sync_timestamp(datetime.now())

Sincronización incremental (ejecuciones posteriores)

Usá updated_at_from con el timestamp de tu última sincronización. Solo vuelven los registros que cambiaron.

last_sync = load_last_sync_timestamp()  # ej. "2024-06-01T00:00:00-03:00"

response = requests.get(
    f"{BASE_URL}/api/v3/third_party/formulateds",
    headers=headers,
    params={"updated_at_from": last_sync, "page": 1, "size": 100},
)
# Procesar y hacer upsert de los registros cambiados
save_sync_timestamp(datetime.now())

Detectar eliminaciones

Ejecutá una consulta separada con deleted_at_from para encontrar registros eliminados lógicamente y marcarlos como inactivos en tu sistema:

response = requests.get(
    f"{BASE_URL}/api/v3/third_party/establishments",
    headers=headers,
    params={"deleted_at_from": last_sync},
)
for item in response.json()["items"]:
    mark_as_deleted_locally(item["id"])

Frecuencia por entidad

No todas las entidades cambian al mismo ritmo. Adaptá la cadencia de sincronización:

Entidad	Frecuencia de cambio	Sync recomendado
Órdenes de Trabajo	Alta — se crean/actualizan constantemente	Cada 15–30 min o bajo demanda
Establecimientos / Lotes	Media — cambian cuando el cliente modifica la estructura	Diario
Campañas / Cultivos	Media — cambian al inicio/fin de campaña	Diario
Aplicadores / Máquinas	Baja — se agregan con nuevos contratistas	Diario o semanal
Formulados	Muy baja — catálogo global	Semanal
Unidades / Tipos de labor	Rara vez cambian	Semanal o al iniciar

Paginación

Todos los endpoints de listado están paginados. Usá los parámetros page y size:

GET /api/v3/third_party/work_orders?page=1&size=50

La respuesta incluye:

{
  "items": [ ... ],
  "current_page": 1,
  "next_page": 2,
  "total_pages": 19,
  "total_items": 57
}

Cuando next_page es null, llegaste a la última página.

El size por defecto es 10 en la mayoría de endpoints. Para sincronizaciones iniciales masivas, aumentá a 100 para reducir la cantidad de requests.

Mapeo de IDs

Cada entidad en SIMA tiene un local_id (ID interno de SIMA) y un external_code o external_id opcional (ID de tu sistema). Mantené una tabla de mapeo en tu base de datos:

tu_tabla_productos:
  erp_id         → tu ID interno de producto
  sima_local_id  → local_id de SIMA para el mismo producto
  last_synced    → timestamp de última sync de este registro

Usá external_code al crear o actualizar registros en SIMA para almacenar tu ID:

{
  "name": "Juan Rodríguez",
  "external_code": "ERP-APLICADOR-0042"
}

Errores comunes

Error	Enfoque correcto
Pasar `deleted_at_from=null` para obtener activos	Omití `deleted_at_*` por completo — los activos son el default
Usar `active=true` para filtrar soft-deletes	`active` y `deleted_at` son flags separados — usá ambos si hace falta
Re-descargar el catálogo completo en cada ejecución	Guardá un timestamp `last_sync` y usá `updated_at_from`
Usar nombres de parámetros v3 en endpoints v2	Verificá cada endpoint — v2 puede usar `updated_from` en lugar de `updated_at_from`

Empezar

Guías de Integración

Resumen

Patrón de filtros de auditoría

Comportamiento por defecto de soft-delete

Flujo de sincronización recomendado

Sincronización inicial (primera vez)

Sincronización incremental (ejecuciones posteriores)

Detectar eliminaciones

Frecuencia por entidad

Paginación

Mapeo de IDs

Errores comunes

Próximos pasos

Órdenes de Trabajo

Scouting

​Resumen

​Patrón de filtros de auditoría

​Comportamiento por defecto de soft-delete

​Flujo de sincronización recomendado

​Sincronización inicial (primera vez)

​Sincronización incremental (ejecuciones posteriores)

​Detectar eliminaciones

​Frecuencia por entidad

​Paginación

​Mapeo de IDs

​Errores comunes

​Próximos pasos

Órdenes de Trabajo

Scouting

Resumen

Patrón de filtros de auditoría

Comportamiento por defecto de soft-delete

Flujo de sincronización recomendado

Sincronización inicial (primera vez)

Sincronización incremental (ejecuciones posteriores)

Detectar eliminaciones

Frecuencia por entidad

Paginación

Mapeo de IDs

Errores comunes

Próximos pasos