Inserción por lotes (batch)

tecsas3 batch run ejecuta una secuencia de operaciones contra la API TecsaS3 desde un archivo JSON. Es la vía oficial para ingestar datos en masa (migraciones, cargas iniciales, sincronización con sistemas legados) sin escribir un script de bash que concatene llamadas. Internamente cada item se enruta a una operación del CLI (<recurso>.<acción>, ver cli/src/tecsas3_cli/resources/batch.py:141-201).

Formatos aceptados

_parse_batch() (batch.py:106-138) acepta tres variantes:

JSON array — un array de objetos, uno por operación.
JSON Lines (JSONL) — un objeto JSON por línea.
JSON object con clave operations — el resto del objeto se ignora.

El primer formato es el recomendado para tecsas3 por su legibilidad en git diffs. Los otros dos son útiles cuando la fuente de datos ya emite JSONL (logs, exports de otros sistemas).

Esquema de cada item

Cada operación es un objeto JSON con esta forma mínima:

{
  "op": "recurso.accion",
  "payload": { ... }
}

op también acepta la clave alternativa "operation". El payload se pasa tal cual al endpoint HTTP subyacente. Las operaciones soportadas hoy (batch.py:151-161) son:

Operación	Endpoint	Notas
`paciente.create`	`POST /paciente/paciente/`	FK `persona` y `familia` como enteros.
`paciente.update`	`PATCH /paciente/paciente/{id}/`	Requiere `id` o `paciente_id`.
`paciente.get`	`GET /paciente/paciente/{id}/`	Devuelve la ficha plana.
`examen.create`	`POST /lab/api/examen/`	Payload crudo.
`examen.list`	`GET /lab/api/examen/`	Filtra por `paciente` (ID entero).
`agente.create`	`POST /agente/api/agente/`	Alta de agente de campo.
`agente.get`	`GET /agente/api/agente/{id}/`	Devuelve la ficha del agente.

Ejemplo: 3 pacientes en un archivo

Guarda el siguiente contenido como pacientes.json:

[
  {
    "op": "paciente.create",
    "payload": {
      "persona": 101,
      "familia": 12,
      "nivel_riesgo": "verde",
      "codigo_eapb": {"codigo": "FAMISANAR", "nombre": "FAMISANAR"},
      "zona_residencia": "rural",
      "esta_activo": true
    }
  },
  {
    "op": "paciente.create",
    "payload": {
      "persona": 102,
      "familia": 12,
      "nivel_riesgo": "amarillo",
      "codigo_eapb": {"codigo": "NUEVA_EPS", "nombre": "NUEVA EPS"},
      "zona_residencia": "urbano",
      "esta_activo": true
    }
  },
  {
    "op": "paciente.get",
    "payload": {"paciente_id": 42}
  }
]

Ejecución

# Modo por defecto: se detiene en el primer error
tecsas3 --json --no-input batch run pacientes.json --stop-on-error

# Continuar aun con errores, registrando todos los fallos al final
tecsas3 --json --no-input batch run pacientes.json --continue-on-error

# Dry-run conceptual: ejecuta pero solo imprime conteos (no hay flag --dry-run todavía)
tecsas3 --json --no-input batch run pacientes.json 2>&1 | jq '.total, .ok, .errors'

Salida

La respuesta de batch run es siempre un objeto JSON con esta estructura (batch.py:88-97):

{
  "total": 3,
  "executed": 3,
  "ok": 3,
  "errors": 0,
  "stopped": false,
  "results": [
    {"index": 1, "op": "paciente.create", "status": "ok", "result": {"id": 501, "nivel_riesgo": "verde"}},
    {"index": 2, "op": "paciente.create", "status": "ok", "result": {"id": 502, "nivel_riesgo": "amarillo"}},
    {"index": 3, "op": "paciente.get", "status": "ok", "result": {"id": 42, "nombre_completo": "..."}}
  ],
  "failures": []
}

Si --stop-on-error está activo y se produce un fallo:

{
  "total": 3,
  "executed": 2,
  "ok": 1,
  "errors": 1,
  "stopped": true,
  "results": [{"index": 1, "op": "paciente.create", "status": "ok", "result": {"id": 501}}],
  "failures": [
    {
      "index": 2,
      "op": "paciente.create",
      "status": "error",
      "error": {"code": "VALIDATION_ERROR", "message": "familia: ... no existe"}
    }
  ]
}

Cada item del batch se ejecuta con el mismo token, el mismo tenant y la misma configuración que la invocación principal. Eso tiene dos consecuencias operativas: un fallo de autenticación (token expirado, 401) o de tenant (403 tenant_context_required) aborta todo el batch, porque el orquestador no puede re-autenticarse a mitad de un lote. Antes de lanzar un batch grande, valida el contexto con tecsas3 auth whoami y comprueba que la membresía siga activa.

Flags y comportamiento

Flag	Default	Efecto
`--stop-on-error`	`True`	Detiene en el primer error y reporta `stopped: true`.
`--continue-on-error`	`False`	Procesa todos los items; el resumen incluye todos los fallos.

El exit_code del proceso es 0 si todos los items se ejecutaron sin error. Si hubo al menos un fallo, se eleva TecsaError(code="BATCH_FAILED") con details.first_error apuntando al primer fallo — útil para cortar pipelines en CI.

Patrones de uso

Carga inicial con conteo de progreso

tecsas3 --json --no-input batch run pacientes.json --continue-on-error \
  | tee batch.log \
  | jq -c '{ok: .ok, errors: .errors, stopped: .stopped}'

Idempotencia con `paciente.get` previo

Cuando un batch es re-ejecutable, valida primero con un paciente.get por ID antes de intentar paciente.create. Esto convierte la operación en idempotente:

[
  {"op": "paciente.get", "payload": {"paciente_id": 501}},
  {"op": "paciente.create", "payload": {"persona": 101, "familia": 12, "...": "..."}}
]

Batch + Pipeline

Combina batch run con pipe run para ingestar en un tenant y disparar notificaciones en otro. El placeholder ${batch_run.results[0].result.id} propaga el ID creado.

Errores frecuentes

Código	Causa
`BATCH_EMPTY`	El archivo está vacío o solo tiene espacios/saltos.
`BATCH_FORMAT_INVALID`	Ni JSON array, ni JSONL, ni `{operations: [...]}`.
`BATCH_INVALID_OP`	`op` no tiene la forma `recurso.accion` (falta el punto).
`BATCH_RESOURCE_UNSUPPORTED`	El recurso no está en la lista actual (`paciente`/`examen`/`agente`).
`BATCH_ACTION_UNSUPPORTED`	La acción no existe para ese recurso.
`BATCH_MISSING_ID`	`paciente.update` sin `id` ni `paciente_id` en el payload.
`BATCH_FAILED`	Al menos un item falló (resumen en `details.first_error`).

Próximos pasos

Para workflows con dependencias entre steps (output de A alimenta a B), usa pipe run en su lugar.
Versiona los archivos batch en git y valida el formato en CI con jq . pacientes.json.
Para datasets grandes (>1k items), divide en chunks de 100 y usa --continue-on-error con checkpoints por índice.

Referencias

cli/src/tecsas3_cli/resources/batch.py:26-103 — batch_run (loop principal)
cli/src/tecsas3_cli/resources/batch.py:106-138 — _parse_batch() (formatos aceptados)
cli/src/tecsas3_cli/resources/batch.py:141-201 — _execute_op() (mapa recurso.acción)
cli/src/tecsas3_cli/resources/paciente.py:260-312 — paciente create (esquema del payload)

Empezar

Conceptos

Guías

Soporte

Inserción por lotes (batch)

Formatos aceptados

Esquema de cada item

Ejemplo: 3 pacientes en un archivo

Ejecución

Salida

Flags y comportamiento

Patrones de uso

Carga inicial con conteo de progreso

Idempotencia con `paciente.get` previo

Batch + Pipeline

Errores frecuentes

Próximos pasos

Referencias

​Formatos aceptados

​Esquema de cada item

​Ejemplo: 3 pacientes en un archivo

​Ejecución

​Salida

​Flags y comportamiento

​Patrones de uso

​Carga inicial con conteo de progreso

​Idempotencia con paciente.get previo

​Batch + Pipeline

​Errores frecuentes

​Próximos pasos

​Referencias

Formatos aceptados

Esquema de cada item

Ejemplo: 3 pacientes en un archivo

Ejecución

Salida

Flags y comportamiento

Patrones de uso

Carga inicial con conteo de progreso

Idempotencia con `paciente.get` previo

Batch + Pipeline

Errores frecuentes

Próximos pasos

Referencias