API Overview
Learn the fundamentals of the VasBox REST API, including request/response formats, pagination, and versioning.
The VasBox API is a RESTful API that uses standard HTTP methods and returns JSON responses. All API access is over HTTPS, and all data is sent and received as JSON.
Base URL
All API requests should be made to the following base URLs:
| Environment | Base URL |
|---|---|
| Production | https://api.vasbox.co.zw/v1 |
| Sandbox | https://sandbox.api.vasbox.co.zw/v1 |
Request Format
All requests must include the following headers:
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer YOUR_API_KEY | Yes |
| Content-Type | application/json | For POST/PATCH/PUT |
| Accept | application/json | Recommended |
Example Request
curl -X POST https://api.vasbox.co.zw/v1/invoices \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"customer_id": "cust_123",
"items": [...]
}'
Response Format
All responses are returned in JSON format. Successful responses include the requested resource, while error responses include an error object with details.
Success Response
{
"id": "inv_abc123",
"object": "invoice",
"status": "draft",
"total": 1500.00,
"created_at": "2024-01-15T10:30:00Z"
}
Error Response
{
"error": {
"code": "validation_error",
"message": "The given data was invalid.",
"details": {
"customer_id": ["The customer_id field is required."],
"items": ["The items field must have at least 1 item."]
}
}
}
HTTP Status Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Invalid or missing API key |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource not found |
| 422 | Unprocessable Entity | Validation failed |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error |
Pagination
List endpoints return paginated results. Use the page and per_page query parameters to navigate through results.
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Page number to retrieve |
| per_page | 20 | Items per page (max 100) |
Paginated Response
{
"data": [
{ "id": "inv_001", ... },
{ "id": "inv_002", ... }
],
"meta": {
"current_page": 1,
"per_page": 20,
"total": 150,
"last_page": 8
},
"links": {
"first": "https://api.vasbox.co.zw/v1/invoices?page=1",
"last": "https://api.vasbox.co.zw/v1/invoices?page=8",
"prev": null,
"next": "https://api.vasbox.co.zw/v1/invoices?page=2"
}
}
Versioning
The API is versioned via the URL path. The current version is v1. When we make breaking changes, we'll release a new version while maintaining support for previous versions.