Audit Logs
Track all changes and actions in your VasBox account for compliance and security.
Audit logs provide a complete, immutable record of all actions taken in your VasBox account. Use them for compliance reporting, security monitoring, and troubleshooting.
Audit logs are required by ZIMRA regulations and cannot be deleted or modified.
Log Structure
Each audit log entry contains detailed information about the action performed:
Audit Log Entry
{
"id": "log_abc123",
"type": "invoice.submitted",
"actor": {
"type": "user",
"id": "user_xyz789",
"email": "admin@company.com"
},
"resource": {
"type": "invoice",
"id": "inv_def456"
},
"changes": {
"status": {
"from": "draft",
"to": "submitted"
},
"fiscal_code": {
"from": null,
"to": "ZW-2024-ABC123"
}
},
"metadata": {
"ip_address": "192.168.1.100",
"user_agent": "VasBox-PHP/1.0"
},
"created_at": "2024-01-15T10:30:00Z"
}
Log Fields
| Field | Description |
|---|---|
| id | Unique identifier for the log entry |
| type | Event type (e.g., invoice.created, user.login) |
| actor | Who performed the action (user, API key, or system) |
| resource | The resource that was affected |
| changes | What changed (before and after values) |
| metadata | Additional context (IP address, user agent) |
| created_at | When the action occurred |
Event Types
| Category | Events |
|---|---|
| Invoices | invoice.created, invoice.updated, invoice.submitted, invoice.voided |
| Receipts | receipt.created, receipt.voided |
| Users | user.login, user.logout, user.created, user.updated |
| API Keys | api_key.created, api_key.revoked, api_key.used |
| Settings | settings.updated, webhook.created, webhook.deleted |
Querying Logs
Search and filter audit logs using the API:
Bash
curl -G https://api.vasbox.co.zw/v1/audit-logs \
-H "Authorization: Bearer YOUR_API_KEY" \
-d "resource_type=invoice" \
-d "resource_id=inv_def456" \
-d "from=2024-01-01" \
-d "to=2024-01-31"
Query Parameters
| Parameter | Description |
|---|---|
| type | Filter by event type |
| resource_type | Filter by resource type (invoice, receipt, user) |
| resource_id | Filter by specific resource ID |
| actor_type | Filter by actor type (user, api_key, system) |
| actor_id | Filter by specific actor ID |
| from | Start date (ISO 8601) |
| to | End date (ISO 8601) |
Response
JSON
{
"data": [
{
"id": "log_001",
"type": "invoice.created",
"actor": { "type": "api_key", "id": "key_abc" },
"created_at": "2024-01-15T10:00:00Z"
},
{
"id": "log_002",
"type": "invoice.updated",
"actor": { "type": "user", "id": "user_xyz" },
"created_at": "2024-01-15T10:15:00Z"
},
{
"id": "log_003",
"type": "invoice.submitted",
"actor": { "type": "user", "id": "user_xyz" },
"created_at": "2024-01-15T10:30:00Z"
}
],
"meta": {
"current_page": 1,
"per_page": 20,
"total": 3
}
}
Data Retention
Audit logs are retained according to your plan and regulatory requirements:
| Plan | Retention Period | Export Options |
|---|---|---|
| Free | 30 days | CSV |
| Starter | 1 year | CSV, JSON |
| Professional | 5 years | CSV, JSON, API |
| Enterprise | 7+ years | All formats + custom |
Regulatory Compliance
ZIMRA requires businesses to retain transaction records for at least 6 years. Ensure your plan meets this requirement.
Exporting Logs
Export audit logs for external storage or compliance reporting:
- Dashboard - Download CSV/JSON from the Audit Logs page
- API - Programmatically export logs in bulk
- Scheduled Exports - Set up automatic daily/weekly exports (Enterprise)
Previous Fiscal Devices
NextPHP SDK