Complete API Reference

This document provides comprehensive reference information needed to build complete frontend applications using the ERPax API.

Query Syntax (Ransack)
Field Validation Rules
Response Formats
Business Rules & Constraints
Batch Operations
Member Actions
Nested Resources
File Uploads
CSRF Token Handling

Query Syntax (Ransack)

ERPax uses Ransack for advanced filtering. All list endpoints support Ransack query parameters.

Basic Syntax

GET /admin/resource.json?q[field_predicate]=value

Common Predicates

Predicate	Description	Example
`eq`	Equals	`q[invoice_type_eq]=invoice`
`not_eq`	Not equals	`q[confirmed_not_eq]=true`
`cont`	Contains (case-insensitive)	`q[number_cont]=INV-2024`
`not_cont`	Does not contain	`q[name_not_cont]=Test`
`start`	Starts with	`q[code_start]=CUST`
`end`	Ends with	`q[code_end]=001`
`gt`	Greater than	`q[total_amount_cents_gt]=100000`
`gteq`	Greater than or equal	`q[date_gteq]=2024-01-01`
`lt`	Less than	`q[total_amount_cents_lt]=500000`
`lteq`	Less than or equal	`q[date_lteq]=2024-12-31`
`present`	Field is present (not null/blank)	`q[number_present]=1`
`blank`	Field is blank (null or empty)	`q[number_blank]=1`
`null`	Field is null	`q[cancelled_at_null]=1`
`not_null`	Field is not null	`q[number_not_null]=1`
`in`	Value in array	`q[invoice_type_in][]=invoice&q[invoice_type_in][]=quotation`
`not_in`	Value not in array	`q[status_not_in][]=cancelled`
`matches`	Regex match	`q[code_matches]=^[A-Z]+-\d+$`
`does_not_match`	Regex does not match	`q[email_does_not_match]=@example\.com$`

Association Filters

Filter by associated resource fields:

# Filter invoices by seller code
GET /admin/invoices.json?q[seller_code_cont]=CUST
# Filter invoices by buyer name
GET /admin/invoices.json?q[buyer_name_cont]=Supplier
# Filter items by address company
GET /admin/items.json?q[address_company_cont]=Acme

Combining Conditions

Multiple conditions are combined with AND:

GET /admin/invoices.json?q[invoice_type_eq]=invoice&q[confirmed_eq]=true&q[total_amount_cents_gteq]=100000

OR Conditions

Use _or to combine predicates with OR:

GET /admin/invoices.json?q[invoice_type_eq]=invoice&q[invoice_type_or_quotation_eq]=quotation

Sorting

Sort results using s parameter:

# Sort by date descending
GET /admin/invoices.json?s=date_desc
# Sort by total amount ascending
GET /admin/invoices.json?s=total_amount_cents_asc
# Multiple sort fields
GET /admin/invoices.json?s[]=date_desc&s[]=total_amount_cents_asc

Quick Search

Many resources support quick search across multiple fields:

# Search invoices by number, buyer name, etc.
GET /admin/invoices.json?q[search_cont]=INV-2024
# Search items by code, name, barcode
GET /admin/items.json?q[search_cont]=Widget

Field Validation Rules

Invoice Fields

Required Fields:

invoice_type - Must be one of: cart, request, quotation, proforma_invoice, invoice, credit_note, debit_note, purchase_order, protocol, bill, subscription, lease
date - Required for confirmed invoices
seller_id or buyer_id - At least one address required (depends on namespace) Validation Rules:
number - Unique per seller and invoice_type (when present)
protocol_number - Unique per buyer and invoice_type (when present)
billing_period - Must be valid period value if present
currency_code - ISO 4217 currency code (e.g., USD, EUR, GBP)
total_amount_cents - Integer (amount in cents)
exchange_rate - Decimal (precision 10, scale 5) Business Rules:
Once confirmed=true, most fields become read-only
number is auto-generated on confirmation for certain invoice types
Cannot delete confirmed invoices (unless specific permissions)

Address Fields

Required Fields:

None (but at least name or company recommended) Validation Rules:
code - Unique per host, case-insensitive, max 128 chars, no spaces
email - Valid email format (if present)
tax_code - VAT ID format: [Country Code][Number] (e.g., BG123456789)
currency_code - ISO 4217 currency code
tax_rate - Decimal (0.0 to 100.0)
postal_code - Max 20 chars Business Rules:
Cannot delete address with associated invoices
Hierarchical relationships via ancestry field

Item Fields

Required Fields:

seller_id (address_id) - Address that owns the item Validation Rules:
code - Unique per host (if present)
barcode - Unique per host (if present)
price_cents, cost_cents, vendor_price_cents - Integers (amounts in cents)
tax_rate - Decimal (0.0 to 100.0)
inventory_quantity - Integer
currency_code - ISO 4217 currency code Business Rules:
Cannot delete item with associated invoice lines
Inventory tracking requires inventory_policy to be set

Payment Fields

Required Fields:

invoice_id - Associated invoice
amount_cents - Payment amount
date - Payment date Validation Rules:
amount_cents - Integer, must be positive
currency_code - ISO 4217 currency code
sender_id, receiver_id - Address IDs Business Rules:
Payment amount cannot exceed invoice total due
Cannot delete payment if invoice is confirmed

Response Formats

Standard List Response

json

{
  "resource_name": [
    {
      "id": 1,
      "field1": "value1",
      "field2": "value2",
      "nested_resource": {
        "id": 10,
        "name": "Nested Name"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 5,
    "total_count": 123
  }
}

Standard Show Response

json

{
  "resource_name": {
    "id": 1,
    "field1": "value1",
    "field2": "value2",
    "nested_resources": [
      {
        "id": 10,
        "name": "Nested Name"
      }
    ]
  }
}

Standard Create/Update Response

json

{
  "resource_name": {
    "id": 123,
    "field1": "value1",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Error Response (422 Validation)

json

{
  "errors": {
    "field_name": ["Error message 1", "Error message 2"],
    "another_field": ["Another error"]
  }
}

Error Response (Other)

json

{
  "error": "Error message"
}

Money Fields

All money fields are returned in two formats:

field_cents - Integer (amount in cents)
field - String (formatted amount, e.g., "1000.00")
formatted_field - String (formatted with currency, e.g., "$1,000.00") Examples:
total_amount_cents: 100000
total_amount: "1000.00"
formatted_amount: "$1,000.00"

Date/Time Fields

Dates: "2024-01-15" (ISO 8601 date format)
Timestamps: "2024-01-15T10:30:00Z" (ISO 8601 datetime format, UTC)

Business Rules & Constraints

Invoice Lifecycle

Draft State:

All fields editable
No invoice number assigned
Can be deleted Confirmed State:
Most fields read-only
Invoice number assigned (if applicable)
Cannot be deleted (unless specific permissions)
Accounting entries generated automatically
Can only edit: confirmed, cancelled_at, cancel_reason, delivered_at (with permissions) Document Transitions:
cart → request → quotation → proforma_invoice → invoice
purchase_order → protocol → bill
Automatic transitions on confirmation

Namespace-Specific Rules

Admin Namespace:

seller_id defaults to domain.address_id if omitted
Full access to all resources Sales Namespace:
seller_id automatically set to host.address_id
supplier_id defaults to domain.address_id
Limited to sales operations Client Namespace:
buyer_id automatically set to user.address_id
seller_id must be from host.addresses
Limited to self-service operations

Multi-Tenancy

All resources automatically scoped to current domain
Cannot access resources from other domains
host_id field ensures tenant isolation

Batch Operations

Batch Action Request

javascript

POST /admin/resource/batch_action.json
Content-Type: application/json
{
  "batch_action": "action_name",
  "collection_selection": [1, 2, 3, 4, 5]
}

Batch Action Response

json

{
  "message": "Batch action completed",
  "affected_count": 5
}

Available Batch Actions

Invoices:

filter - Filter collection to selected records
update - Update selected records
renew - Renew renewable invoices
cancel - Cancel selected invoices
confirm - Confirm selected invoices
account - Create accounting entries Items:
update - Update selected items Addresses:
(varies by resource)

Member Actions

Member Action Request

javascript

POST /admin/resource/:id/action_name.json
Content-Type: application/json
{
  // Action-specific parameters
}

Common Member Actions

Invoices:

POST /admin/invoices/:id/email - Send invoice via email
POST /admin/invoices/:id/print - Generate printable version
POST /admin/invoices/:id/duplicate - Create duplicate
POST /admin/invoices/:id/renew - Renew recurring invoice
POST /admin/invoices/:id/backorder - Create backorder
POST /admin/invoices/:id/create_payment - Create payment
POST /admin/invoices/:id/create_credit_note - Create credit note
POST /admin/invoices/:id/create_debit_note - Create debit note
POST /admin/invoices/:id/create_protocol - Create protocol Domains:
POST /admin/domains/:id/activate - Activate domain
POST /admin/domains/:id/suspend - Suspend domain
POST /admin/domains/:id/enable_ssl - Enable SSL
POST /admin/domains/:id/disable_ssl - Disable SSL

Nested Resources

Accessing Nested Resources

GET /admin/parent_resource/:id/nested_resource.json

Creating Nested Resources

javascript

POST /admin/parent_resource/:id/nested_resource.json
Content-Type: application/json
{
  "nested_resource": {
    "field1": "value1",
    "field2": "value2"
  }
}

Common Nested Resources

Invoices:

/admin/invoices/:id/invoice_lines - Line items
/admin/invoices/:id/payments - Payments
/admin/invoices/:id/accounting_equations - Accounting entries
/admin/invoices/:id/packing_lines - Packing/shipping Addresses:
/admin/addresses/:id/contacts - Contacts
/admin/addresses/:id/payment_methods - Payment methods
/admin/addresses/:id/items - Items
/admin/addresses/:id/daily_sales - Sales reports
/admin/addresses/:id/accounting_transactions - Accounting transactions Users:
/admin/users/:id/user_logs - Activity logs

File Uploads

Upload Request

javascript

POST /admin/resource.json
Content-Type: multipart/form-data
{
  "resource": {
    "name": "Resource Name",
    "attachment": <file>
  }
}

Supported File Types

Images: image/jpeg, image/png, image/gif, image/webp
Documents: application/pdf, application/msword, etc.
Maximum file size: Configured per resource (typically 10MB)

Upload Response

json

{
  "resource": {
    "id": 123,
    "attachment_url": "https://example.com/path/to/file.jpg",
    "attachment_filename": "file.jpg",
    "attachment_content_type": "image/jpeg",
    "attachment_size": 12345
  }
}

CSRF Token Handling

Getting CSRF Token

For session-based authentication, include CSRF token in requests:

javascript

// Get token from meta tag
function getCSRFToken() {
  const meta = document.querySelector('meta[name="csrf-token"]');
  return meta ? meta.content : null;
}
// Or from cookie
function getCSRFTokenFromCookie() {
  const name = 'XSRF-TOKEN';
  const value = `; ${document.cookie}`;
  const parts = value.split(`; ${name}=`);
  if (parts.length === 2) return parts.pop().split(';').shift();
  return null;
}

Including CSRF Token

javascript

fetch('/admin/invoices.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': getCSRFToken(),
    'Accept': 'application/json'
  },
  body: JSON.stringify({ invoice: {...} })
});

CSRF Token in Cookies

The API sets XSRF-TOKEN cookie automatically. Use this for Angular and other frameworks that read from cookies.

Frontend Development Guide - Complete frontend development guide
Getting Started - Authentication and first API calls
API Routes - All available endpoints
Examples - Complete working examples

This reference covers all technical details needed to build complete frontend applications using only the ERPax API.

Complete API Reference ​

Table of Contents ​

Query Syntax (Ransack) ​

Basic Syntax ​

Common Predicates ​

Association Filters ​

Combining Conditions ​

OR Conditions ​

Sorting ​

Quick Search ​

Field Validation Rules ​

Invoice Fields ​

Address Fields ​

Item Fields ​

Payment Fields ​

Response Formats ​

Standard List Response ​

Standard Show Response ​

Standard Create/Update Response ​

Error Response (422 Validation) ​

Error Response (Other) ​

Money Fields ​

Date/Time Fields ​

Business Rules & Constraints ​

Invoice Lifecycle ​

Namespace-Specific Rules ​

Multi-Tenancy ​

Batch Operations ​

Batch Action Request ​

Batch Action Response ​

Available Batch Actions ​

Member Actions ​

Member Action Request ​

Common Member Actions ​

Nested Resources ​

Accessing Nested Resources ​

Creating Nested Resources ​

Common Nested Resources ​

File Uploads ​

Upload Request ​

Supported File Types ​

Upload Response ​

CSRF Token Handling ​

Getting CSRF Token ​

Including CSRF Token ​

CSRF Token in Cookies ​

Related Documentation ​

Complete API Reference

Table of Contents

Query Syntax (Ransack)

Basic Syntax

Common Predicates

Association Filters

Combining Conditions

OR Conditions

Sorting

Quick Search

Field Validation Rules

Invoice Fields

Address Fields

Item Fields

Payment Fields

Response Formats

Standard List Response

Standard Show Response

Standard Create/Update Response

Error Response (422 Validation)

Error Response (Other)

Money Fields

Date/Time Fields

Business Rules & Constraints

Invoice Lifecycle

Namespace-Specific Rules

Multi-Tenancy

Batch Operations

Batch Action Request

Batch Action Response

Available Batch Actions

Member Actions

Member Action Request

Common Member Actions

Nested Resources

Accessing Nested Resources

Creating Nested Resources

Common Nested Resources

File Uploads

Upload Request

Supported File Types

Upload Response

CSRF Token Handling

Getting CSRF Token

Including CSRF Token

CSRF Token in Cookies

Related Documentation