Operaciones masivas

Una operación masiva procesa miles de registros en una solicitud: la entrada es un archivo NDJSON, y el resultado dice qué pasó con cada línea.

Cargando el índice de búsqueda…

Operaciones masivas

Tipos de operación

typeUna línea de la entradaScope
inventory.setEl cuerpo de fijar stock.inventory:write
products.upsertEl cuerpo de escribir un producto por ID externo, más external_id y, si querés que se verifique la versión, version.catalog:write
money_transactions.createEl cuerpo de registrar un ingreso o egreso manual.finance:write
money_transactions.updateEl cuerpo de editar un movimiento de dinero, más el id del movimiento y, si querés que se verifique la versión, version. Así se categoriza el libro en lote.finance:write
orders.exportSin entrada: la operación exporta los pedidos según los filtros de params.orders:read
libro_iva.exportSin entrada: la operación genera los libros del Libro IVA Digital de una razón social para un mes; en params van legal_entity_id, period (YYYY-MM) y books (ventas, compras o ambos).fiscal:read
accountant_package.exportSin entrada: la operación genera el paquete del contador de una razón social para un mes; en params van legal_entity_id y period.fiscal:read

Iniciar una operación necesita bulk:write además del scope de su tipo. Cada línea pasa por las mismas verificaciones que el endpoint individual y recibe la misma respuesta, así que una línea que falla no frena a las demás.

Prepará la entrada

NDJSON es un objeto JSON por línea. Un archivo de stock:

NDJSON
{"variant_id": 1042, "location_id": 3, "on_hand": "24", "expected_on_hand": "20"}
{"variant_id": 1043, "location_id": 3, "on_hand": "0", "expected_on_hand": "5"}
{"variant_id": 2210, "location_id": 3, "on_hand": "12.5", "expected_on_hand": "12.5"}

El archivo puede pesar hasta 256 MB, y una línea hasta 1 MB; un archivo comprimido con gzip se descomprime al entrar. Subilo por partes, o pasale a la operación la url del archivo y la tienda lo descarga sola.

Subí por partes

Iniciá una carga con el nombre y el tamaño del archivo. La respuesta indica el tamaño de una parte, chunk_bytes, hasta 1 MB:

Solicitud
curl -X POST "https://api.saleya.app/v1/uploads" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 3c2b1a09-8f7e-4d6c-b5a4-938271605f4e' \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "stock-2026-11-11.ndjson",
  "size": 3407872
}'
Respuesta
HTTP/1.1 201 Created

{
  "id": 55,
  "file_name": "stock-2026-11-11.ndjson",
  "size": 3407872,
  "received": 0,
  "complete": false,
  "chunk_bytes": 1048576,
  "expires_at": "2026-11-12T14:30:00Z",
  "created_at": "2026-11-11T14:30:00Z"
}

Enviá el archivo en orden, una parte por solicitud: los bytes crudos como cuerpo y el byte donde empieza la parte en offset. Cuando received llega al tamaño, la carga está complete.

Solicitud
curl -X POST "https://api.saleya.app/v1/uploads/55/chunks?offset=1048576" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 7e6d5c4b-3a29-4180-9f8e-7d6c5b4a3928' \
  -H "Content-Type: application/octet-stream" \
  --data-binary '@stock.part-01'

Si se corta la conexión, leé la carga y seguí desde received. Una parte con otro desplazamiento recibe 409 upload_offset_mismatch, y la respuesta indica el correcto.

Iniciá la operación

Solicitud
curl -X POST "https://api.saleya.app/v1/bulk-operations" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 2b1a0f9e-8d7c-4b6a-9594-837261504f3e' \
  -H "Content-Type: application/json" \
  -d '{
  "type": "inventory.set",
  "input": {
    "upload_id": 55
  }
}'

La respuesta es 202 con la operación y su dirección en Location. Las operaciones de una aplicación corren de a una, en el orden en que se crearon; pueden esperar o correr hasta 5 a la vez, y una más recibe 409 bulk_operation_queue_full.

Seguila con GET /bulk-operations/{operation} — status y los contadores de lines — o esperá el webhook bulk_operation.finished. Cancelarla la detiene entre dos líneas: lo escrito queda.

Leé el resultado

El resultado también es NDJSON: una línea por cada línea de entrada con su número, el estado que recibiría como solicitud aparte y la respuesta — el registro o el rechazo.

NDJSON
{"line": 1, "status": 200, "body": {"status": "applied", "inventory_level": {"variant_id": 1042, "location_id": 3, "on_hand": "24", "reserved": "2", "available": "22", "updated_at": "2026-11-11T14:31:02Z"}}}
{"line": 2, "status": 409, "body": {"type": "stock_on_hand_changed", "title": "On-hand quantity changed", "status": 409, "detail": "The on-hand quantity is 4, not 5: stock moved after it was read. Read the level again and repeat the request with the new expected_on_hand.", "current": {"on_hand": "4"}}}
{"line": 3, "status": 200, "body": {"status": "unchanged", "inventory_level": {"variant_id": 2210, "location_id": 3, "on_hand": "12.5", "reserved": "0", "available": "12.5", "updated_at": "2026-11-10T09:12:44Z"}}}

El resultado se puede leer mientras la operación corre: solo crece. Retomá una descarga con Range: bytes=<descargado>-. El resultado de orders.export son los pedidos mismos, y la exportación terminada da un sync_cursor para seguir el listado de pedidos.

En libro_iva.export y accountant_package.export el resultado no es NDJSON sino un ZIP con los mismos archivos que exporta el panel de la tienda. Aparece completo cuando la operación queda completed; antes de eso, y si la operación falló, el resultado responde 409. Si el libro no se puede generar por comprobantes del período, la operación termina failed y error.documents nombra cada comprobante y el motivo.

La operación y sus archivos se guardan durante 7 días después de terminar.

Siguiente guíaWebhooks