Tipos de operación
type | Una línea de la entrada | Scope |
|---|---|---|
inventory.set | El cuerpo de fijar stock. | inventory:write |
products.upsert | El 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.create | El cuerpo de registrar un ingreso o egreso manual. | finance:write |
money_transactions.update | El 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.export | Sin entrada: la operación exporta los pedidos según los filtros de params. | orders:read |
libro_iva.export | Sin 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.export | Sin 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:
{"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:
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
}'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.
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
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.
{"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.