Getting Started

Welcome to ERPax! This guide will help you get started integrating with the ERPax API and building frontend applications.

Choose Your Path

For Business Users

New to ERPax? Start here:

1. Platform Overview - Comprehensive introduction to ERPax
2. Understand the Value - Learn why ERPax is different
3. Explore Features - See what ERPax can do
4. Business Guide - Business-focused resources
5. API Reference - Learn the interface

For Frontend Developers

Building a frontend application? Start here:

1. Frontend Development Guide - COMPLETE GUIDE - Everything needed to build detached frontends
2. API Authentication - Get authenticated
3. First API Call - Make your first request
4. API Reference - Complete API documentation (44 routes)

For API Integrators

Integrating external systems? Start here:

1. API Authentication - Authentication methods
2. Integration Guide - External system integration
3. API Reference - Complete API documentation
4. Webhooks - Event notifications

Quick Start (API Integration)

Quick Setup

This guide assumes you have access to an ERPax instance. If you need an account, contact your ERPax administrator.

Prerequisites

• API Access: Valid ERPax account with API access
• API Endpoint: Your ERPax instance URL (e.g., https://your-company.erpax.com)
• Development Tools:
  • Browser with developer tools
  • cURL or Postman for API testing
  • JavaScript/TypeScript for frontend development

API Authentication

ERPax uses session-based authentication for browser applications and supports token-based authentication for API integrations. Session-Based Authentication (Browser):

// Login via API
const response = await fetch('https://your-company.erpax.com/users/sign_in.json', {
  method: 'POST',
  credentials: 'include', // Important: include cookies
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    user: {
      email: '[email protected]',
      password: 'your-password'
    }
  })
});
if (response.ok) {
  // Session cookie is now set
  // Subsequent requests will be authenticated
}

Token-Based Authentication (API):

# Get authentication token
curl -X POST https://your-company.erpax.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'
# Use token in subsequent requests
curl -X GET https://your-company.erpax.com/admin/invoices.json \
  -H "Authorization: Bearer YOUR_TOKEN"

For detailed authentication examples, see API Integration Basics.

First API Call

Once authenticated, make your first API call: List Invoices:

// Get list of invoices
const response = await fetch('https://your-company.erpax.com/admin/invoices.json', {
  credentials: 'include',
  headers: {
    'Accept': 'application/json'
  }
});
if (response.ok) {
  const data = await response.json();
  console.log('Invoices:', data.invoices);
} else {
  console.error('Error:', response.status, response.statusText);
}

Create an Invoice:

// Create a new invoice
const response = await fetch('https://your-company.erpax.com/admin/invoices.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'X-CSRF-Token': getCSRFToken() // Get from meta tag
  },
  body: JSON.stringify({
    invoice: {
      invoice_type: 'invoice',
      seller_id: 1,
      buyer_id: 2,
      date: '2025-01-15',
      currency_code: 'USD',
      invoice_lines_attributes: [
        {
          seller_item_id: 10,
          quantity: 5,
          unit_price_cents: 10000
        }
      ]
    }
  })
});
if (response.ok) {
  const invoice = await response.json();
  console.log('Created invoice:', invoice.invoice);
}

Frontend Development Setup

JavaScript/Stimulus Setup

If you're building a frontend application that integrates with ERPax:

1. Include ERPax JavaScript:

   <script type="module">
     import { Application } from '@hotwired/stimulus';
     const application = Application.start();
   </script>

2. Create API Client:

   class ERPaxClient {
     constructor(baseURL) {
       this.baseURL = baseURL;
     }
     
     async getInvoices(filters = {}) {
       const params = new URLSearchParams();
       Object.entries(filters).forEach(([key, value]) => {
         params.append(`q[${key}]`, value);
       });
       
       const response = await fetch(`${this.baseURL}/admin/invoices.json?${params}`, {
         credentials: 'include',
         headers: { 'Accept': 'application/json' }
       });
       
       return response.json();
     }
   }
   
   const client = new ERPaxClient('https://your-company.erpax.com');

3. Create Stimulus Controller:

   // app/javascript/controllers/invoice_controller.js
   import { Controller } from '@hotwired/stimulus';
   
   export default class extends Controller {
     static targets = ['list', 'form'];
     
     async loadInvoices() {
       const response = await fetch('/admin/invoices.json', {
         credentials: 'include'
       });
       const data = await response.json();
       this.listTarget.innerHTML = this.renderInvoices(data.invoices);
     }
     
     renderInvoices(invoices) {
       return invoices.map(inv => `
         <div class="invoice">
           <h3>${inv.number}</h3>
           <p>${inv.formatted_amount}</p>
         </div>
       `).join('');
     }
   }

For complete Stimulus examples, see Stimulus Controllers Guide.

First Steps

1. Get Your Account Information

Before making API calls, you need:

• API Endpoint: Your ERPax instance URL
• Credentials: Email and password for authentication
• Domain: Your tenant domain (if multi-tenant)

2. Authenticate

Use the authentication methods above to get a session or token.

3. Explore the API

Start with simple read operations:

// Get current domain
const domain = await fetch('/admin/domains/current.json', {
  credentials: 'include'
}).then(r => r.json());
// Get addresses
const addresses = await fetch('/admin/addresses.json', {
  credentials: 'include'
}).then(r => r.json());
// Get invoices
const invoices = await fetch('/admin/invoices.json', {
  credentials: 'include'
}).then(r => r.json());

4. Understand Domain Address

Each domain has an associated address that represents your business entity. This address is automatically used as the default seller when creating invoices. See Invoices and Addresses documentation for relationship details.Get Domain and Address:

// Get current domain (includes address)
const response = await fetch('/admin/domains/current.json', {
  credentials: 'include'
});
const { domain } = await response.json();
console.log('Domain:', domain.name);
console.log('Domain Address:', domain.address); // Address object with id, name, email, etc.
// Or get address directly
if (domain.address_id) {
  const addressResponse = await fetch(`/admin/addresses/${domain.address_id}.json`, {
    credentials: 'include'
  });
  const { address } = await addressResponse.json();
  console.log('Business Address:', address);
}

Domain Address as Default Seller: When creating invoices via API, if you don't specify a seller_id, the system automatically uses your domain's address as the seller:

// Create invoice without seller_id - domain.address is used automatically
const invoice = await fetch('/admin/invoices.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': getCSRFToken()
  },
  body: JSON.stringify({
    invoice: {
      invoice_type: 'invoice',
      buyer_id: 2, // Customer address
      // seller_id omitted - domain.address used automatically
      date: '2025-01-15',
      currency_code: 'USD'
    }
  })
});

Namespace-Specific Behavior:

• Admin namespace: Domain address is default seller
• Sales namespace: Host address is fixed seller, domain address is supplier
• Client namespace: User address is buyer, seller must be from host addresses See Domain Model and Invoice Model for detailed address relationships.

5. Create Your First Resource

Create an address:

const response = await fetch('/admin/addresses.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': getCSRFToken()
  },
  body: JSON.stringify({
    address: {
      code: 'CUST-001',
      name: 'Customer Name',
      email: '[email protected]',
      currency_code: 'USD'
    }
  })
});

6. Build Your Integration

Now you're ready to build your integration:

• API Integration Basics - Complete integration guide
• Integration Guide - External system integration
• API Reference - Complete API documentation (337+ endpoints)
• Frontend Examples - Complete working examples

Understanding ERPax Features

Unified Document Model

ERPax uses a single Invoice model for all document types (invoices, purchase orders, quotations, etc.). This means:

• Single API: One endpoint for all document types
• Consistent Structure: Same data model across document types
• Type Field: Use invoice_type to differentiate types

// Create different document types
const invoice = { invoice_type: 'invoice', ... };
const quotation = { invoice_type: 'quotation', ... };
const purchaseOrder = { invoice_type: 'purchase_order', ... };

Automatic Accounting

When you confirm an invoice, ERPax automatically:

• Generates accounting entries - Double-entry accounting for both seller and buyer
• Creates accounting equations - Balanced debit/credit entries
• Tracks payments - Payment dates and due dates
• Calculates totals - All financial calculations are automatic

Multi-Tenancy

ERPax is multi-tenant by design:

• Automatic Scoping: All API requests are automatically scoped to your tenant
• Data Isolation: Complete isolation between tenants
• Domain-Based: Tenant determined by request hostname

// Tenant context is automatic
// tenant1.erpax.com → tenant1's data
// tenant2.erpax.com → tenant2's data

Next Steps

Now that you're set up, explore ERPax further:

• Platform Overview - Comprehensive overview of ERPax architecture and features
• Explore Features - See all capabilities in detail
• For Developers - Technical documentation and integration guides
• API Reference - Complete API documentation (337+ endpoints)
• Architecture - System architecture and design principles (see API endpoints for system design)

---

Ready to begin? Start with the Platform Overview for a comprehensive introduction, or explore Features and Philosophy to understand ERPax better.