Bulk operations
Thousands of records in one request: set stock, write products, export orders. The result is NDJSON, one line per input line, downloaded in ranges.
Bulk operations
Objects
BulkOperation
idintegerrequiredID of the record, unique among records of its kind in the store.
app_idintegerrequiredID of the app that created the operation.
typestringrequiredOperation type: inventory.set — set stock levels; products.upsert — create or update products with variants; money_transactions.create — manual income and expenses; money_transactions.update — edit money transactions, for example assign categories; orders.export — export orders; libro_iva.export — the Libro IVA Digital books of a legal entity for a month; accountant_package.export — the accountant package of a legal entity for a month.
- Values:
inventory.setproducts.upsertmoney_transactions.createmoney_transactions.updateorders.exportlibro_iva.exportaccountant_package.export
statusstringrequiredpending — waiting to start; running — in progress; cancelling — stops after the current line; completed — the whole input was processed or the file was built; cancelled — cancelled; failed — stopped before the end of the input or did not build the file (error).
- Values:
pendingrunningcancellingcompletedcancelledfailed
inputobject or nullrequiredThe input of the operation: a chunked upload or an address. null for an export and a file — they have no input.
Fields · 5
sourcestringrequiredupload — a chunked upload (/v1/uploads); url — a file downloaded from an address.
- Values:
uploadurl
urlstring or nullrequiredAddress the input is downloaded from; null for an upload.
file_namestring or nullrequiredName of the uploaded file; null for an address.
bytesinteger or nullrequiredSize of the input in bytes, unpacked when it came in gzip; null while unknown.
processed_bytesintegerrequiredHow many bytes of the input are done: the share of bytes is the progress.
paramsobject or nullrequiredExport or file parameters as accepted on creation: for orders.export, the filters of the GET /v1/orders feed (updated_since, number); for libro_iva.export, legal_entity_id, period and books; for accountant_package.export, legal_entity_id and period. null for an operation with an input.
linesobjectrequiredInput lines: read (including blank ones), executed successfully and refused. A refused line does not stop the operation; its reason is in the result. For an export, the feed items written to the result: read and succeeded are equal, failed is 0. For a file, zeros: its outcome is status and its content is the archive.
Fields · 3
readintegerrequiredLines read.
succeededintegerrequiredLines done successfully.
failedintegerrequiredLines rejected.
errorobject or nullrequiredFor failed, why the operation did not reach the end of the input or did not build the file. For a running one, the last input download failure that is still being retried. Otherwise null.
Fields · 4
codestringrequiredinvalid_url, blocked_address, unreachable, too_large, access_denied, not_found, rate_limited, http_error — the input was not downloaded (source_status for an error response of its server); input_corrupt — the input cannot be read, for example broken gzip; app_unavailable — the app was deleted or lost access; scope_revoked — the app lost a scope the operation needs; capability_disabled — the store no longer has the tax ledger that holds the file data; locations_restricted — the app was limited to locations, and the file covers the whole legal entity; legal_entity_deleted — the legal entity was deleted after the operation was created; libro_iva_not_applicable — the legal entity does not keep Libro IVA Digital; libro_iva_incomplete — documents of the period cannot be written as book records (documents); processing_failed — an internal failure.
- Values:
invalid_urlblocked_addressunreachabletoo_largeaccess_deniednot_foundrate_limitedhttp_errorinput_corruptapp_unavailablescope_revokedprocessing_failedcapability_disabledlocations_restrictedlegal_entity_deletedlibro_iva_not_applicablelibro_iva_incomplete
messagestringrequiredThe reason in words, in the language of the request.
source_statusinteger or nullrequiredHTTP status the server of the input responded with, for access_denied, not_found, rate_limited and http_error; otherwise null.
documentsarray of object or nullrequiredFor libro_iva_incomplete, the documents of the period that cannot be written as book records; fix them in the store and create the operation again. Otherwise null.
Fields · 3
typestringrequiredfiscal_document — a fiscal document of the sales book; supplier_bill — a supplier bill of the purchase or import book.
- Values:
fiscal_documentsupplier_bill
idintegerrequiredID of the record, unique among records of its kind in the store.
reasonstringrequiredWhy the document cannot be written: missing_request, missing_number — the fiscal document has no ARCA request or number; unknown_document_type, other_ledger_file, broker_fields_required — the bill type is not for this book or broker details are needed; currency_code_unconfirmed, unsupported_currency, missing_exchange_rate — the currency has no ARCA code or no rate; invalid_vendor_tax_id — invalid seller CUIT; unknown_tax_rate — the rate cannot be split into alícuotas; missing_despacho, unknown_rate — a goods import has no clearance number or rate; missing_import_document_kind, missing_import_document_description, unsupported_service_rate, missing_import_tax_payment — a services import lacks the provider document, the rate or the tax payment.
- Values:
missing_requestmissing_numberunknown_document_typeother_ledger_filebroker_fields_requiredcurrency_code_unconfirmedunsupported_currencymissing_exchange_rateinvalid_vendor_tax_idunknown_tax_ratemissing_despachounknown_ratemissing_import_document_kindmissing_import_document_descriptionunsupported_service_ratemissing_import_tax_payment
result_urlstringrequiredThe result address: NDJSON, one line per input line in order, with the outcomes of the lines processed so far; for an export, one feed item per line; for a file, the ZIP of the completed operation. Can be resumed with ranges.
result_scopesarray of stringrequiredScopes the result needs: reading the data of the kind and the field scopes the operation was created with, such as customers:read for an export of orders with customer data. The set is fixed at creation; a scope taken away stops the operation (scope_revoked).
sync_cursorstring or nullrequiredFor a completed export — the sync cursor of the feed it was built from (GET /v1/orders with the same params): the feed returns from it what changed after the export. null otherwise.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
started_atstring (date-time) or nullrequiredWhen the operation started; null while pending.
finished_atstring (date-time) or nullrequiredWhen the operation finished; null until then.
Endpoints
List the app bulk operations changed since a given time: progress and outcomes
get/bulk-operations
Scope: bulk:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
typestringOnly operations of this kind.
- Values:
inventory.setproducts.upsertmoney_transactions.createmoney_transactions.updateorders.exportlibro_iva.exportaccountant_package.export
statusstringOnly operations in this status.
- Values:
pendingrunningcancellingcompletedcancelledfailed
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/bulk-operations" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"app_id": 0,
"type": "inventory.set",
"status": "pending",
"input": {
"source": "upload",
"url": "string",
"file_name": "string",
"bytes": 0,
"processed_bytes": 0
},
"params": {},
"lines": {
"read": 0,
"succeeded": 0,
"failed": 0
},
"error": {
"code": "invalid_url",
"message": "string",
"source_status": 0,
"documents": [
{
"type": "fiscal_document",
"id": 0,
"reason": "missing_request"
}
]
},
"result_url": "string",
"result_scopes": [
"string"
],
"sync_cursor": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"started_at": "2026-01-15T12:00:00Z",
"finished_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Start a bulk operation from an upload or an input address, a feed export or a file build
post/bulk-operations
Scope: bulk:write
Parameters
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
typestringrequiredOperation type: inventory.set — set stock levels; products.upsert — create or update products with variants; money_transactions.create — manual income and expenses; money_transactions.update — edit money transactions, for example assign categories; orders.export — export orders; libro_iva.export — the Libro IVA Digital books of a legal entity for a month; accountant_package.export — the accountant package of a legal entity for a month.
- Values:
inventory.setproducts.upsertmoney_transactions.createmoney_transactions.updateorders.exportlibro_iva.exportaccountant_package.export
inputobjectThe input of the operation: a chunked upload or an address. null for an export and a file — they have no input.
Fields · 2
upload_idintegerID of a complete chunked upload (/v1/uploads).
- Minimum:
- 1
urlstringAddress the input is downloaded from; null for an upload.
- Max length:
- 2048
paramsobjectExport or file parameters as accepted on creation: for orders.export, the filters of the GET /v1/orders feed (updated_since, number); for libro_iva.export, legal_entity_id, period and books; for accountant_package.export, legal_entity_id and period. null for an operation with an input.
Fields · 6
updated_sincestring (date-time)For orders.export — orders changed after this moment.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleanFor orders.export — also deleted orders.
numberstringFor orders.export — only the order with this number.
- Max length:
- 16
legal_entity_idintegerFor libro_iva.export and accountant_package.export — the legal entity whose file is built.
periodstringFor libro_iva.export and accountant_package.export — the month as YYYY-MM, not later than the current month of the store.
booksarray of stringFor libro_iva.export — the books: ventas (sales) and compras (purchases with the import files), one or both.
- Min items:
- 1
- Max items:
- 2
- No repeats
- Values:
ventascompras
Responses
202Accepted: the outcome is at the Location URL
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns BulkOperation
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 403
capability_disabledResource not available to this store - 409
bulk_operation_queue_fullThe app operation queue is full - 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/bulk-operations" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"type": "inventory.set",
"input": {
"upload_id": 1,
"url": "string"
},
"params": {
"updated_since": "2026-01-15T12:00:00Z",
"include_deleted": true,
"number": "string",
"legal_entity_id": 0,
"period": "string",
"books": [
"ventas"
]
}
}{
"id": 0,
"app_id": 0,
"type": "inventory.set",
"status": "pending",
"input": {
"source": "upload",
"url": "string",
"file_name": "string",
"bytes": 0,
"processed_bytes": 0
},
"params": {},
"lines": {
"read": 0,
"succeeded": 0,
"failed": 0
},
"error": {
"code": "invalid_url",
"message": "string",
"source_status": 0,
"documents": [
{
"type": "fiscal_document",
"id": 0,
"reason": "missing_request"
}
]
},
"result_url": "string",
"result_scopes": [
"string"
],
"sync_cursor": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"started_at": "2026-01-15T12:00:00Z",
"finished_at": "2026-01-15T12:00:00Z"
}Get a bulk operation
get/bulk-operations/{operation}
Scope: bulk:read
Parameters
Path
operationintegerrequiredID of the bulk operation.
Responses
200Success
application/json
Returns BulkOperation
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/bulk-operations/{operation}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"app_id": 0,
"type": "inventory.set",
"status": "pending",
"input": {
"source": "upload",
"url": "string",
"file_name": "string",
"bytes": 0,
"processed_bytes": 0
},
"params": {},
"lines": {
"read": 0,
"succeeded": 0,
"failed": 0
},
"error": {
"code": "invalid_url",
"message": "string",
"source_status": 0,
"documents": [
{
"type": "fiscal_document",
"id": 0,
"reason": "missing_request"
}
]
},
"result_url": "string",
"result_scopes": [
"string"
],
"sync_cursor": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"started_at": "2026-01-15T12:00:00Z",
"finished_at": "2026-01-15T12:00:00Z"
}Get the result of a bulk operation — NDJSON, a line per input line or per exported item, or the ZIP of a file operation; resume with Range
get/bulk-operations/{operation}/result
Scope: bulk:read
Parameters
Path
operationintegerrequiredID of the bulk operation.
Header
RangestringOne byte range to resume a download: bytes=<from>- or bytes=<from>-<to>. The result of a running operation only grows: continue with bytes=<downloaded>- without If-Range; 416 means no new lines yet. Several ranges get the whole result.
- Example:
bytes=1048576-
If-RangestringETag of the result from the previous response. The range is served only if nothing was appended since then; otherwise the whole result (200).
- Example:
"52428800"
Responses
200Success
Headers
Accept-Rangesstringbytes — the result is served in ranges. A compressed response (Content-Encoding: gzip) has no such header: it cannot be resumed.
- Values:
bytes
ETagstringrequiredTag of the result: it changes when the result grows. Send it in If-Range to resume the same version. A compressed response has a weak tag (W/) that does not work in If-Range.
- Example:
"52428800"
application/x-ndjson
object or Order
Variant 1: object
lineintegerrequiredNumber of the input line, from 1.
statusintegerrequiredHTTP status the line would get as a separate request.
bodyobjectrequiredResponse to the line: the record as its endpoint returns it, or a problem+json error.
application/zip
string (binary)
206Part of the result by Range
Headers
Accept-Rangesstringbytes — the result is served in ranges. A compressed response (Content-Encoding: gzip) has no such header: it cannot be resumed.
- Values:
bytes
ETagstringrequiredTag of the result: it changes when the result grows. Send it in If-Range to resume the same version. A compressed response has a weak tag (W/) that does not work in If-Range.
- Example:
"52428800"
Content-RangestringrequiredThe served range and the written length: bytes 0-1023/52428800; on 416 — bytes */52428800.
- Example:
bytes 1048576-52428799/52428800
application/x-ndjson
object or Order
Variant 1: object
lineintegerrequiredNumber of the input line, from 1.
statusintegerrequiredHTTP status the line would get as a separate request.
bodyobjectrequiredResponse to the line: the record as its endpoint returns it, or a problem+json error.
application/zip
string (binary)
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
416The range starts beyond the written result
Headers
Content-RangestringrequiredThe served range and the written length: bytes 0-1023/52428800; on 416 — bytes */52428800.
- Example:
bytes 1048576-52428799/52428800
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
bulk_operation_result_unavailableThere is no result file - 416
range_not_satisfiableThe range starts beyond the result
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/bulk-operations/{operation}/result" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"Cancel a bulk operation at a line boundary
post/bulk-operations/{operation}/cancel
Scope: bulk:write
Parameters
Path
operationintegerrequiredID of the bulk operation.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns BulkOperation
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
bulk_operation_finishedThe operation has already finished - 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/bulk-operations/{operation}/cancel" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"app_id": 0,
"type": "inventory.set",
"status": "pending",
"input": {
"source": "upload",
"url": "string",
"file_name": "string",
"bytes": 0,
"processed_bytes": 0
},
"params": {},
"lines": {
"read": 0,
"succeeded": 0,
"failed": 0
},
"error": {
"code": "invalid_url",
"message": "string",
"source_status": 0,
"documents": [
{
"type": "fiscal_document",
"id": 0,
"reason": "missing_request"
}
]
},
"result_url": "string",
"result_scopes": [
"string"
],
"sync_cursor": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"started_at": "2026-01-15T12:00:00Z",
"finished_at": "2026-01-15T12:00:00Z"
}