Jobs API, structured logs and job.finished webhook
This release expands the API support for asynchronous jobs, making bulk operations easier to monitor from external integrations.
Jobs as an API resource
OpenTiendas now exposes jobs through the API.
A job represents an asynchronous background task created by OpenTiendas to process heavy API operations without blocking the original request or affecting store performance.
Jobs are commonly created by bulk operations, such as product or variant updates. When one of these operations is accepted, the API returns 202 Accepted together with a job_id.
This means the request has been accepted and queued, but it does not mean that all records have already been processed successfully. The final result is determined later, when the job is executed.
A new endpoint is available to retrieve the current status and summary of a job:
GET /api/v1/jobs/{id}
The response includes the job type, status, relevant timestamps, and a processing summary with the number of processed, successful, and failed records.
This allows external systems such as ERPs, PIMs or custom integrations to check the result of a bulk operation without relying on the shop backoffice.
Job logs
A second endpoint is available to retrieve the logs generated during job execution:
GET /api/v1/jobs/{id}/logs
Job logs are useful when an integration needs to understand which records failed, which warnings were generated, or which fields caused validation errors.
The endpoint returns paginated logs and supports filtering by severity, code and creation date. Logs can also be ordered by creation date.
Log entries now include structured information when available, such as:
- the log severity,
- a stable log code,
- a human-readable message,
- identifiers for the affected record,
- and affected fields.
For example, an integration can now detect that a specific variant identified by EAN failed because the supplier_stock field did not pass validation, without having to parse the full message manually.
Detailed response schemas, filters, log codes and examples are available in the API documentation.
New webhook event: job.finished
A new webhook event is available:
job.finished
This event is emitted when an asynchronous job reaches a final state.
It is triggered when a job finishes successfully, finishes with errors, or fails during processing. The event does not necessarily mean that the job completed successfully, so integrations should inspect the job status in the payload to determine the final result.
The webhook payload includes the job identifier, job type, final status, timestamps and processing summary.
Logs are not included in the webhook payload. Integrations that need the full detail can use the Jobs API and the Job Logs endpoint after receiving the webhook.
This allows external systems to avoid periodic polling and react automatically when a bulk operation has finished.
Clearer behavior for asynchronous bulk operations
The documentation for asynchronous bulk operations has also been clarified.
Bulk endpoints perform an initial validation before creating a job. This includes checks such as JSON format, payload structure, payload size, required top-level fields, match configuration, identifier fields and basic data types.
If this initial validation fails, no job is created and the API returns an error response.
If the request passes initial validation, the endpoint creates and queues a job, then returns 202 Accepted with a job_id. Record-level validations and write operations are performed later, during job processing.
This distinction is important: 202 Accepted confirms that the job has been created, not that every record has been created or updated successfully.
The documentation now also clarifies that, for partial updates, integrations only need to send the identifiers required by match_by and the fields that should be modified.
Summary
This release improves API observability for asynchronous operations by:
- exposing jobs as an API resource,
- adding a dedicated endpoint for job logs,
- exposing structured log information,
- adding the
job.finishedwebhook event, - and clarifying the behavior of
202 Acceptedresponses in bulk operations.
These changes provide a more reliable foundation for integrations that need to run large updates and track their final result programmatically.
What's next
Upcoming improvements will focus on:
- adding support for price lists and custom pricing rules through the API,
- expanding API coverage for more integration use cases,
- and continuing to evolve the API as a robust integration layer for ERPs, PIMs, CRMs and custom synchronization services.