Domistra API Documentation

Overview

Base URL

/api

The Domistra API is a RESTful API that allows you to manage properties, tenants, invoices, and utilities.

Response Format

All responses follow this format:

{
  "success": true,
  "data": { /* response data */ }
}

// Error response
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

200 Success 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 409 Conflict 429 Rate Limited 500 Server Error

Authentication

JWT Token

Authentication uses JWT tokens stored in HttpOnly cookies. The token is automatically sent with each request.

CSRF Protection

All state-changing requests (POST, PUT, DELETE) require the X-CSRF-Token header.

Auth

POST /api/auth/login Login and get token ▼

Request Body

{
  "username": "string",
  "password": "string"
}

Response

{
  "success": true,
  "data": {
    "csrf_token": "string",
    "user": { "id": 1, "username": "admin", "full_name": "Admin User" }
  }
}

POST /api/auth/logout Logout and clear session ▼

Clears the authentication cookie.

GET /api/auth/me Get current user ▼

Response

{
  "success": true,
  "data": {
    "user": { "id": 1, "username": "admin", "full_name": "Admin" },
    "csrf_token": "fresh_token"
  }
}

POST /api/auth/change-password Change user password ▼

Request Body

{
  "current_password": "string",
  "new_password": "string"
}

Password Requirements: 8+ characters, uppercase, lowercase, digit

Tenants

GET /api/tenants List all tenants ▼

Query Parameters

Name	Type	Description
is_active	boolean	Filter by active status

GET /api/tenants/:id Get single tenant ▼

Returns tenant with utility percentages.

POST /api/tenants Create tenant ▼

Request Body

Name	Type	Description
name *	string	Tenant name
address *	string	Address
city *	string	City
county *	string	County
email	string	Email address
phone	string	Phone number
rent_amount_eur	number	Monthly rent (EUR)

PUT /api/tenants/:id Update tenant ▼

Same fields as create, all optional.

DELETE /api/tenants/:id Deactivate tenant ▼

Soft delete - sets is_active to false.

PUT /api/tenants/:id/percentages Update utility percentages ▼

Request Body

{
  "percentages": {
    "electricity": 25.5,
    "gas": 30,
    "water": 20
  }
}

Invoices (Issued)

GET /api/invoices List all invoices ▼

Query Parameters

Name	Type	Description
tenant_id	number	Filter by tenant
type	string	rent, utility, generic
paid	boolean	Filter by paid status

GET /api/invoices/next-number Get next invoice number ▼

Returns the next available invoice number based on prefix and sequence.

POST /api/invoices/rent Create rent invoice ▼

Request Body

{
  "tenant_id": 1,
  "invoice_date": "2025-01-15",
  "due_date": "2025-01-31",
  "period_month": 1,
  "period_year": 2025,
  "exchange_rate": 4.97,
  "additional_items": [
    { "description": "Parking", "unit_price": 50 }
  ]
}

POST /api/invoices/utility Create utility invoice ▼

Request Body

{
  "tenant_id": 1,
  "calculation_id": 5
}

POST /api/invoices/generic Create generic invoice ▼

Request Body

{
  "client_name": "ABC Company",
  "invoice_date": "2025-01-15",
  "due_date": "2025-01-31",
  "items": [
    {
      "description": "Service",
      "quantity": 1,
      "unit_price": 500,
      "vat_rate": 19
    }
  ]
}

GET /api/invoices/:id/pdf Download PDF ▼

Returns PDF file download.

POST /api/invoices/:id/mark-paid Mark as paid ▼

Request Body

{
  "paid_date": "2025-01-20"  // optional, defaults to today
}

DELETE /api/invoices/:id Delete invoice ▼

Only unpaid invoices can be deleted.

Received Invoices

GET /api/received-invoices List all ▼

Query Parameters

Name	Type	Description
provider_id	number	Filter by provider
type	string	Utility type
paid	boolean	Filter by paid status

GET /api/received-invoices/period/:year/:month Get by period ▼

Get invoices overlapping with a specific month.

POST /api/received-invoices Create ▼

Request Body

{
  "provider_id": 1,
  "invoice_number": "F-12345",
  "invoice_date": "2025-01-10",
  "due_date": "2025-01-25",
  "amount": 450.50,
  "utility_type": "electricity",
  "period_start": "2024-12-01",
  "period_end": "2024-12-31"
}

POST /api/received-invoices/:id/mark-paid Mark paid with date ▼

{ "paid_date": "2025-01-20" }

Meter Readings

GET /api/meter-readings List all ▼

Query Parameters

Name	Type	Description
meter_id	number	Filter by meter

GET /api/meter-readings/period/:year/:month Get by period ▼

Get all meter readings for a specific month.

POST /api/meter-readings Create reading ▼

Request Body

{
  "meter_id": 1,
  "reading_date": "2025-01-15",
  "reading_value": 12500,
  "period_month": 1,
  "period_year": 2025
}

Consumption is calculated automatically from previous reading.

POST /api/meter-readings/batch Create multiple ▼

Request Body

{
  "readings": [
    { "meter_id": 1, "reading_date": "2025-01-15", "reading_value": 12500, "period_month": 1, "period_year": 2025 },
    { "meter_id": 2, "reading_date": "2025-01-15", "reading_value": 8750, "period_month": 1, "period_year": 2025 }
  ]
}

Utility Calculations

GET /api/utility-calculations List all ▼

Returns all utility calculations with invoice count.

GET /api/utility-calculations/preview/:year/:month Preview calculation ▼

Preview utility shares without saving. Includes meter difference data.

POST /api/utility-calculations Create/save calculation ▼

Request Body

{
  "period_year": 2025,
  "period_month": 1,
  "overrides": {
    "1": { "electricity": 25, "gas": 30 },
    "2": { "electricity": 75, "gas": 70 }
  }
}

Overrides are keyed by tenant_id with utility percentages.

POST /api/utility-calculations/:id/finalize Finalize calculation ▼

Locks the calculation. Cannot be modified after finalization.

Meters

GET /api/meters List active meters ▼

Returns all active meters with tenant names.

POST /api/meters Create meter ▼

{
  "name": "Meter 1",
  "tenant_id": 1,
  "is_general": false
}

Utility Providers

GET /api/utility-providers List all ▼

Query Parameters

Name	Type	Description
type	string	electricity, gas, water, salubrity, internet, other
active	boolean	Filter by active status

POST /api/utility-providers Create provider ▼

{
  "name": "ENEL",
  "type": "electricity",
  "account_number": "123456789"
}

Company

GET /api/company Get company info ▼

Returns company details including balance.

PUT /api/company Update company ▼

{
  "name": "My Company SRL",
  "cui_cif": "RO12345678",
  "address": "Str. Example 123",
  "city": "Bucharest",
  "county": "Sector 1",
  "iban": "RO49AAAA1B31007593840000"
}

Profile

GET /api/profile Get profile ▼

Returns user profile with company data.

PUT /api/profile Update profile ▼

{
  "user": {
    "full_name": "John Doe",
    "email": "john@example.com"
  },
  "company": {
    "invoice_prefix": "INV"
  }
}

Dashboard

GET /api/dashboard/summary Get summary stats ▼

Returns key metrics: total revenue, pending invoices, active tenants, etc.

GET /api/dashboard/charts/revenue Revenue chart data ▼

Query: ?months=12

GET /api/dashboard/charts/cash-flow Cash flow chart ▼

Query: ?months=12

GET /api/dashboard/overdue-invoices Overdue invoices ▼

List of all overdue invoices.

GET /api/dashboard/reports/tenant-statement/:tenant_id Tenant statement ▼

Query: ?start_date=2025-01-01&end_date=2025-12-31

Exchange Rates

GET /api/exchange-rates/current Current EUR/RON rate ▼

Fetches current rate from BNR (National Bank of Romania).

GET /api/exchange-rates/:date Rate for date ▼

Date format: YYYY-MM-DD. Falls back to previous day if not available.

Activity Logs

GET /api/activity-logs List logs ▼

Query Parameters

Name	Type	Description
limit	number	Default: 50
offset	number	Pagination offset
entity_type	string	Filter by entity
action_type	string	create, update, delete, payment

GET /api/activity-logs/recent Recent activity ▼

Query: ?limit=10

Notifications

GET /api/notifications List notifications ▼

Query Parameters

Name	Type	Description
include_read	boolean	Include read notifications
limit	number	Default: 20

GET /api/notifications/count Unread count ▼

Returns count of unread notifications.

GET /api/notifications/check Check for new ▼

Creates notifications for due/overdue invoices.

PUT /api/notifications/read-all Mark all read ▼

Marks all notifications as read.

Invoice Templates

GET /api/templates List templates ▼

Returns all invoice templates.

POST /api/templates/:id/set-default Set default ▼

Sets the template as the default for new invoices.

Google Drive Backup

GET /api/google/auth-url Get OAuth URL ▼

Returns URL to redirect user for Google authorization.

GET /api/google/status Connection status ▼

Returns whether Google Drive is connected and account info.

POST /api/google/backup Create backup ▼

Creates database backup and uploads to Google Drive.

POST /api/google/restore/:id Restore backup ▼

Downloads and restores database from backup.

Search

GET /api/search Global search ▼

Query Parameters

Name	Type	Description
q *	string	Search query (min 2 chars)

Response

{
  "success": true,
  "data": {
    "tenants": [...],
    "invoices": [...],
    "providers": [...],
    "total_count": 15
  }
}