Overview
This document provides comprehensive API documentation for the Zhatva accounting/billing system, specifically designed for UI/UX developers to build outstanding user experiences.
Base Information
- Base URL: /api/v1
- Authentication: JWT Bearer Token (except for auth endpoints and some firm endpoints)
- Content Type: application/json
- Date Format: YYYY-MM-DD (ISO 8601)
- Timestamp Format: YYYY-MM-DDTHH:mm:ssZ (RFC 3339)
- Currency Format: Decimal string (e.g., "150.00")
Authentication
Login
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "
[email protected]",
"password": "password123"
}
Response (200 OK):
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "user-uuid",
"email": "
[email protected]",
"name": "John Doe"
}
}
Logout
POST /api/v1/auth/logout
Authorization: Bearer {token}
Response (200 OK):
{
"message": "Successfully logged out"
}
Firm Management
Create Firm
POST /api/v1/firms
Content-Type: application/json
{
"name": "Acme Consulting Ltd",
"default_currency": "USD"
}
Response (201 Created):
{
"id": "firm-uuid",
"name": "Acme Consulting Ltd",
"default_currency": "USD"
}
Other Endpoints
- GET /api/v1/firms/{id} - Get Firm
- PUT /api/v1/firms/{id} - Update Firm
User Management
Create User
POST /api/v1/users
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "Jane Developer",
"email": "
[email protected]",
"password": "secure123",
"billing_rate": {
"amount": "150.00",
"currency": "USD"
}
}
Response (201 Created):
{
"id": "user-uuid",
"name": "Jane Developer",
"email": "
[email protected]",
"firm_id": "firm-uuid",
"billing_rate": {
"amount": "150.00",
"currency": "USD"
},
"is_active": true
}
Other Endpoints
- GET /api/v1/users/{id} - Get User
- PUT /api/v1/users/{id} - Update User
Client Management
Create Client
POST /api/v1/clients
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "TechCorp Inc",
"default_currency": "USD"
}
Response (201 Created):
{
"id": "client-uuid",
"name": "TechCorp Inc",
"firm_id": "firm-uuid",
"default_currency": "USD"
}
List Clients
GET /api/v1/clients
Authorization: Bearer {token}
Response (200 OK):
[
{
"id": "client-uuid-1",
"name": "TechCorp Inc",
"firm_id": "firm-uuid",
"default_currency": "USD"
},
{
"id": "client-uuid-2",
"name": "DesignCo Ltd",
"firm_id": "firm-uuid",
"default_currency": "EUR"
}
]
Other Endpoints
- GET /api/v1/clients/{id} - Get Client
- PUT /api/v1/clients/{id} - Update Client
Project Management
Create Project
POST /api/v1/projects
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "Website Redesign",
"client_id": "client-uuid",
"project_type": "TIME_AND_MATERIALS",
"currency": "USD"
}
Project Types:
- NON_BILLABLE - Internal projects, no billing
- FIXED_PRICE - Fixed price projects with milestones
- TIME_AND_MATERIALS - Billable hourly work
Response (201 Created):
{
"id": "project-uuid",
"name": "Website Redesign",
"client_id": "client-uuid",
"currency": "USD",
"project_type": "TIME_AND_MATERIALS"
}
Activities
Activities represent work subdivisions within a project (e.g., "development", "testing", "project management").
POST /api/v1/activities
Authorization: Bearer {token}
Content-Type: application/json
{
"project_id": "project-uuid",
"name": "Development",
"description": "Software development work",
"estimated_hours": "40.0"
}
Activity Statuses:
- NOT_STARTED - Activity not yet begun
- IN_PROGRESS - Work is underway
- COMPLETED - Activity finished
- ON_HOLD - Temporarily paused
Time Tracking
Create Time Entry
POST /api/v1/time-entries
Authorization: Bearer {token}
Content-Type: application/json
{
"user_id": "user-uuid",
"project_id": "project-uuid",
"hours": "8.0",
"description": "Implemented user authentication",
"work_date": "2025-01-15"
}
Response (201 Created):
{
"id": "timeentry-uuid",
"user_id": "user-uuid",
"project_id": "project-uuid",
"hours": "8.0",
"description": "Implemented user authentication",
"work_date": "2025-01-15",
"status": "DRAFT"
}
Time Entry Workflow
- GET /api/v1/time-entries - List Time Entries
- GET /api/v1/time-entries/{id} - Get Time Entry
- PUT /api/v1/time-entries/{id}/submit - Submit Time Entry
- PUT /api/v1/time-entries/{id}/approve - Approve Time Entry
Time Entry Statuses:
- DRAFT - Initial state, can be edited
- SUBMITTED - Submitted for approval
- APPROVED - Approved by manager
- REJECTED - Rejected, back to draft
- CLOSED - Locked for period close
- INVOICED - Included in an invoice
Expense Management
Create Expense
POST /api/v1/expenses
Authorization: Bearer {token}
Content-Type: application/json
{
"user_id": "user-uuid",
"project_id": "project-uuid",
"amount": "125.50",
"currency": "USD",
"category": "Travel",
"description": "Client meeting travel costs",
"expense_date": "2025-01-15"
}
Expense Statuses:
- DRAFT - Initial state
- PARSED - OCR processing completed
- PENDING_APPROVAL - Waiting for approval
- APPROVED - Approved by manager
- REJECTED - Rejected, back to draft
- CLOSED - Locked for period close
- INVOICED - Included in an invoice
Invoice Management
Generate Invoice
POST /api/v1/invoices/generate
Content-Type: application/json
{
"client_id": "client-uuid",
"from_date": "2025-01-01",
"to_date": "2025-01-31"
}
Response (201 Created):
{
"id": "invoice-uuid",
"invoice_number": "INV-2025-001",
"client_id": "client-uuid",
"subtotal": "4500.00",
"total": "4950.00",
"currency": "USD",
"line_items_count": 12,
"issue_date": "2025-02-01",
"due_date": "2025-02-31",
"status": "DRAFT"
}
Invoice Statuses
- DRAFT - Can be edited
- ISSUED - Sent to client, partially editable with audit trail
- PARTIALLY_PAID - Some payment received
- PAID - Fully paid (terminal state, cannot be edited)
- OVERDUE - Past due date
- CANCELLED - Cancelled (terminal state, cannot be edited)
Invoice Operations
- POST /invoices/{id}/update-draft - Update draft invoice fields
- POST /invoices/{id}/update-due-date - Update due date (ISSUED invoices)
- POST /invoices/{id}/apply-discount - Apply discount (ISSUED invoices)
- POST /invoices/{id}/change-currency - Change currency (DRAFT only)
- POST /invoices/{id}/unbilled-items - Add unbilled items to draft
- POST /invoices/{id}/manual-item - Add manual line item
- DELETE /invoices/{id}/line-items/{lineItemID} - Remove line item
- DELETE /invoices/{id} - Delete draft invoice
- GET /invoices/{id}/audit-history - Get audit history
Error Handling
All endpoints return consistent error responses:
400 Bad Request
{
"error": "validation_failed",
"message": "name cannot be empty"
}
401 Unauthorized
{
"error": "unauthorized",
"message": "authorization header required"
}
404 Not Found
{
"error": "not_found",
"message": "resource not found"
}
500 Internal Server Error
{
"error": "internal_error",
"message": "an unexpected error occurred"
}
Additional Resources
- Health Check: GET /health - Returns "OK" (200)
- FX Rates: GET /api/v1/fx-rates - List exchange rates
- Period Management: PUT /api/v1/periods/{id}/close - Close period
Back to Home