Batch Operations API

The Batch Operations API allows you to monitor and track the status of asynchronous batch processes in the Nilo platform. When you perform bulk operations (like updating multiple products, prices, or promotions), these processes run asynchronously, and you can use these endpoints to track their progress and results.

Understanding Batch Processes

Batch processes in Nilo represent large-scale operations that are processed asynchronously:

Process Structure
- Each batch process has a unique UUID identifier
- Processes contain multiple individual operations
- Operations are tracked with detailed status and results
- Progress can be monitored in real-time

Important Considerations

Asynchronous Processing: Batch operations run in the background and may take time to complete
Status Tracking: Regular status checks are recommended to monitor progress
Error Handling: Failed operations within a batch are tracked individually
Completion States: Processes can end in completed, failed, or partial completion states
Detailed Logging: Each operation within a batch maintains its own status and error messages

Batch Operations

Get Batch Process Details

GET/batch/{uuid}/detail

Retrieves detailed information about a specific batch process, including the status of individual operations within the batch.

Path Parameters

Parameter	Type	Required	Description
uuid	string	Yes	Batch process identification code

Response Parameters

Parameter	Type	Description
uuid	string	Unique identifier of the batch process
detail	array	Array of individual operations in the batch

Each detail item contains:

Field	Type	Description
code	string	Unique identifier for the operation
endpoint	string	API endpoint used for the operation
action	string	Type of action performed
batchItem	string	JSON data of the processed item
status	string	Current status (processing/completed/failed)
message	string	System message or error description
finishedAt	string	Completion timestamp (ISO 8601 format)
createdAt	string	Creation timestamp (ISO 8601 format)

Response Example

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "detail": [
    {
      "code": "550e8400-e29b-41d4-a716-446655440000",
      "endpoint": "batch/product/22222.1",
      "action": "availability",
      "batchItem": "{\"product\": \"22222.1\", \"store\": 2134, \"available\": true, \"units\": 1}",
      "status": "completed",
      "message": "Product processed successfully",
      "finishedAt": "2025-12-03T10:15:30Z",
      "createdAt": "2025-12-03T10:15:30Z"
    }
  ]
}

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/detail",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/detail"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Get Batch Process Status

GET/batch/{uuid}/status

Retrieves a summary of the batch process status, including progress statistics and completion state.

Path Parameters

Parameter	Type	Required	Description
uuid	string	Yes	Batch process identification code

Response Parameters

Parameter	Type	Description
uuid	string	Unique identifier of the batch process
status	string	Overall status (processing/completed/failed)
createdAt	string	Creation timestamp (ISO 8601 format)
finishedAt	string	Completion timestamp (ISO 8601 format)
summary	object	Statistical summary of the batch process

Summary object contains:

Field	Type	Description
total	integer	Total number of operations in the batch
processed	integer	Number of operations processed
failed	integer	Number of failed operations
completed	integer	Number of successfully completed operations

Response Example

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "createdAt": "2025-12-03T10:15:30Z",
  "finishedAt": "2025-12-03T10:15:30Z",
  "summary": {
    "total": 100,
    "processed": 50,
    "failed": 10,
    "completed": 40
  }
}

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/status",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/status"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Get Failed Batch Process Details

GET/batch/{uuid}/detail/failed

Retrieves only the failed operations from a specific batch process. This is useful for identifying and retrying operations that did not complete successfully without having to filter through the entire batch detail.

Path Parameters

Parameter	Type	Required	Description
uuid	string	Yes	Batch process identification code

Response Parameters

Parameter	Type	Description
uuid	string	Unique identifier of the batch process
detail	array	Array of failed operations only from the batch

Each detail item contains:

Field	Type	Description
code	string	Unique identifier for the operation
endpoint	string	API endpoint used for the operation
action	string	Type of action performed
batchItem	string	JSON data of the processed item
status	string	Status (always "failed" for this endpoint)
message	string	Error description
finishedAt	string	Completion timestamp (ISO 8601 format)
createdAt	string	Creation timestamp (ISO 8601 format)

Response Example

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "detail": [
    {
      "code": "550e8400-e29b-41d4-a716-446655440001",
      "endpoint": "batch/product/99999",
      "action": "availability",
      "batchItem": "{\"product\": \"99999\", \"store\": 2134, \"available\": true, \"units\": 1}",
      "status": "failed",
      "message": "Product code not found",
      "finishedAt": "2025-12-03T10:15:30Z",
      "createdAt": "2025-12-03T10:15:28Z"
    }
  ]
}

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/detail/failed",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/detail/failed"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Get Failed Items by Date

GET/batch/failed-items

Returns failed items for the authenticated supplier on a given date. Use the optional filters to narrow the retry queue.

Query parameter	Type	Required	Description
`date`	string	Yes	Date in `YYYY-MM-DD` format.
`entity`	string	No	Entity to filter. See allowed values below.
`page`	integer	No	Page number.
`pageSize`	integer	No	Number of items per page.

Allowed entity values: STOCK, PRODUCT, STORE, PROMOTION, GROUPERS, PRICELIST, ORDER, BRAND, CATEGORY, SALES_REP, COMMERCIAL_ROUTE, and LOYALTY.

curl -G "https://api.nilo.com/batch/failed-items" \
  -H "Authorization: YOUR_AUTH_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date=2026-05-19" \
  --data-urlencode "entity=PRODUCT" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=50"

Best Practices for Batch Processing

Status Monitoring
- Regularly check batch status for long-running processes
- Implement exponential backoff for status checks
- Monitor both overall status and individual operation details
- Keep track of failed operations for retry strategies
Error Handling
- Review detailed error messages for failed operations
- Implement retry logic for failed items
- Keep track of partially completed batches
- Log all error responses for troubleshooting
Performance Optimization
- Group related operations in single batches
- Monitor batch sizes for optimal performance
- Schedule large batches during off-peak hours
- Implement parallel processing when possible
Data Management
- Maintain records of batch process IDs
- Archive completed batch details for auditing
- Track success rates across different operation types
- Monitor patterns in failed operations

Security

Authentication

All endpoints require two types of authentication:

API Key in header: x-api-key
Authorization token in header: Authorization

Required Permissions

For batch operation endpoints, the following permissions are required:

For reading batch details: supplier/batch.read
For reading batch status: supplier/bulk.read
For reading failed items: supplier/batch.read

Understanding Batch Processes​

Important Considerations​

Batch Operations​

Get Batch Process Details​

Path Parameters​

Response Parameters​

Response Example​

Example Usage​

Get Batch Process Status​

Path Parameters​

Response Parameters​

Response Example​

Example Usage​

Get Failed Batch Process Details​

Path Parameters​

Response Parameters​

Response Example​

Example Usage​

Get Failed Items by Date​

Best Practices for Batch Processing​

Security​

Authentication​

Required Permissions​

Tana

Understanding Batch Processes

Important Considerations

Batch Operations

Get Batch Process Details

Path Parameters

Response Parameters

Response Example

Example Usage

Get Batch Process Status

Path Parameters

Response Parameters

Response Example

Example Usage

Get Failed Batch Process Details

Path Parameters

Response Parameters

Response Example

Example Usage

Get Failed Items by Date

Best Practices for Batch Processing

Security

Authentication

Required Permissions