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

1. Asynchronous Processing: Batch operations run in the background and may take time to complete
2. Status Tracking: Regular status checks are recommended to monitor progress
3. Error Handling: Failed operations within a batch are tracked individually
4. Completion States: Processes can end in completed, failed, or partial completion states
5. 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

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));

Python

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

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));

Python

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)

Best Practices for Batch Processing

1. 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

2. 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

3. 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

4. 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