Skip to Content
API ReferenceAPI Reference

API Reference

Arkan ERP provides a RESTful API for all platform operations, plus WebSocket support for real-time events.

Base URL

https://your-api-host/api/v1

Authentication

All requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "X-Company-Id: COMPANY_UUID" \
     https://your-api-host/api/v1/projects

Get a Token

POST /api/v1/auth/login
Content-Type: application/json
 
{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}

Refresh a Token

POST /api/v1/auth/refresh
Content-Type: application/json
 
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without re-authenticating.

Company Context

Set the X-Company-Id header to scope requests to a specific company. This header is required for all endpoints except /auth and /companies.

X-Company-Id: 550e8400-e29b-41d4-a716-446655440000

See Multi-Company for details on company isolation.

Pagination

All list endpoints support cursor-based pagination:

ParameterTypeDefaultDescription
limitnumber25Items per page (max 100)
cursorstring—Cursor from previous response
sortstringcreatedAtSort field
orderstringdescSort direction (asc or desc)

Response includes pagination metadata:

{
  "data": [ ... ],
  "meta": {
    "total": 142,
    "limit": 25,
    "cursor": "eyJpZCI6IjEyMyJ9",
    "hasMore": true
  }
}

Rate Limiting

API requests are rate-limited per tenant:

PlanRequests/minuteBurst
Free6010
Starter12020
Professional30050
Business600100
Enterprise1200200

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1713024060

Accounting

Chart of Accounts

MethodPathDescription
GET/accounting/accountsList chart of accounts
POST/accounting/accountsCreate an account
GET/accounting/accounts/:idGet account details
PATCH/accounting/accounts/:idUpdate an account

Journal Entries

MethodPathDescription
POST/accounting/journal-entriesCreate a journal entry
GET/accounting/journal-entriesList journal entries
GET/accounting/journal-entries/:idGet entry details
POST/accounting/journal-entries/:id/postPost a draft entry

Invoices & Bills

MethodPathDescription
GET/accounting/invoicesList invoices
POST/accounting/invoicesCreate an invoice
POST/accounting/invoices/:id/postPost a draft invoice
POST/accounting/invoices/:id/cancelCancel with credit note

Payments

MethodPathDescription
GET/accounting/paymentsList payments
POST/accounting/paymentsRecord a payment
POST/accounting/payments/:id/postPost a draft payment
POST/accounting/payments/:id/allocateAllocate to invoices

Batch Payment Export

MethodPathDescription
GET/accounting/batch-payment/exportableList payments eligible for export
POST/accounting/batch-payment/export/uaeftsExport as UAEFTS file (UAE bank transfer)
POST/accounting/batch-payment/export/csvExport as CSV file
POST/accounting/batch-payment/export/wpsExport as WPS/SIF file (salary payments)
PUT/accounting/batch-payment/bank-details/:partnerIdSave partner bank details
GET/accounting/batch-payment/bank-details/:partnerIdGet partner bank details

Invoice Margin

MethodPathDescription
GET/accounting/invoice-margin/:invoiceIdGet margin for a single invoice
GET/accounting/invoice-margin/reportMargin report for a date range

Financial Reports

MethodPathDescription
GET/accounting/reports/profit-lossProfit & Loss statement
GET/accounting/reports/balance-sheetBalance Sheet
GET/accounting/reports/cash-flowCash Flow statement
GET/accounting/reports/aged-receivablesAged receivables
GET/accounting/reports/aged-payablesAged payables
GET/accounting/reports/revenue-by-clientRevenue by client
GET/accounting/reports/revenue-by-projectRevenue by project
GET/accounting/reports/budget-vs-actualBudget vs actual
GET/accounting/reports/taxTax report

Bank Reconciliation

MethodPathDescription
POST/accounting/bank-reconciliation/statementsImport a bank statement
GET/accounting/bank-reconciliation/statementsList bank statements
POST/accounting/bank-reconciliation/matchMatch statement line to entry
POST/accounting/bank-reconciliation/write-offWrite off small difference

Fixed Assets

MethodPathDescription
POST/accounting/assetsCreate an asset
GET/accounting/assetsList assets
POST/accounting/assets/:id/depreciateRun depreciation
POST/accounting/assets/:id/disposeDispose an asset

Sales

Orders

MethodPathDescription
GET/sales/ordersList sales orders
POST/sales/ordersCreate an order
GET/sales/orders/:idGet order details
PATCH/sales/orders/:idUpdate an order
POST/sales/orders/:id/confirmConfirm an order
POST/sales/orders/:id/cancelCancel an order

Quotes

MethodPathDescription
GET/sales/quotesList quotes
POST/sales/quotesCreate a quote
POST/sales/quotes/:id/sendSend quote to client
POST/sales/quotes/:id/acceptAccept a quote
POST/sales/quotes/:id/convert-to-orderConvert to sales order

Billing & Down Payments

MethodPathDescription
POST/sales/billing/invoice/:orderIdCreate invoice from order
POST/sales/billing/down-payment/:orderIdCreate deposit invoice
POST/sales/billing/credit-note/:invoiceIdCreate credit note
GET/sales/billing/summary/:orderIdBilling summary for order
POST/sales/billing/cogs/:deliveryIdCreate COGS entry

Deliveries

MethodPathDescription
POST/sales/deliveries/from-order/:orderIdCreate delivery from order
GET/sales/deliveriesList deliveries
POST/sales/deliveries/:id/confirmConfirm delivery
POST/sales/deliveries/:id/deliverMark as delivered
GET/sales/deliveries/atp/:productIdAvailable-to-promise

Returns

MethodPathDescription
POST/sales/returnsCreate a return
POST/sales/returns/:id/receiveReceive returned goods
POST/sales/returns/:id/refundProcess refund

Pricing & Discounts

MethodPathDescription
GET/sales/pricing/resolveResolve product price
POST/sales/pricing/listsCreate price list
POST/sales/discounts/evaluateEvaluate applicable discounts
GET/sales/discounts/validate-promoValidate promo code

Commissions

MethodPathDescription
POST/sales/commissions/rulesCreate commission rule
GET/sales/commissions/rulesList commission rules
GET/sales/commissions/calculateCalculate commissions for period
GET/sales/commissions/summaryCommission summary per salesperson

Suggestions (Upsell / Cross-sell)

MethodPathDescription
GET/sales/suggestions?product_ids=x,yGet product suggestions

Returns three types: frequently_bought_together, upsell, category_companions.

Warnings

MethodPathDescription
GET/sales/warnings?entity_type=client&entity_id=xGet warnings for entity
GET/sales/warnings/check-order?client_id=x&product_ids=a,bCheck all warnings for order
POST/sales/warningsCreate manual warning
DELETE/sales/warnings/:idRemove a warning

Incoterms

MethodPathDescription
GET/sales/incotermsList all Incoterms 2020 codes

Subscriptions

MethodPathDescription
POST/sales/subscriptionsCreate subscription
POST/sales/subscriptions/:id/activateActivate
POST/sales/subscriptions/:id/pausePause
POST/sales/subscriptions/generate-invoicesGenerate due invoices

Inventory & Warehousing

Products

MethodPathDescription
GET/inventory/productsList products with stock levels
POST/inventory/productsCreate a product
GET/inventory/products/:idGet product details
GET/inventory/products/:id/stockGet stock by location

Stock Operations

MethodPathDescription
POST/inventory/movesCreate a stock move
POST/inventory/moves/transferTransfer between locations
POST/inventory/adjustmentsCreate inventory adjustment
POST/inventory/cycle-countsStart a cycle count session
POST/inventory/barcode/quick-moveQuick move via barcode

Scrap Management

MethodPathDescription
POST/inventory/scrapCreate a scrap order
GET/inventory/scrapList scrap entries
GET/inventory/scrap/reasonsGet available scrap reasons

Putaway Strategies

MethodPathDescription
POST/inventory/putaway/rulesCreate putaway rule
GET/inventory/putaway/rulesList putaway rules
DELETE/inventory/putaway/rules/:idDelete a rule
GET/inventory/putaway/resolve?warehouse_id=x&product_id=yResolve location for product

Routing Rules

MethodPathDescription
POST/inventory/routingCreate warehouse route
GET/inventory/routingList routes
GET/inventory/routing/:idGet route details
PATCH/inventory/routing/:idUpdate route
DELETE/inventory/routing/:idDelete route
GET/inventory/routing/resolve/:warehouseId/:typeResolve route for operation

Purchasing

MethodPathDescription
POST/inventory/purchase-ordersCreate PO
GET/inventory/purchase-ordersList POs
POST/inventory/purchase-orders/:id/approveApprove PO
POST/inventory/purchase-orders/:id/confirmConfirm PO
POST/inventory/purchase-orders/:id/receiveReceive goods
POST/inventory/rfqsCreate RFQ
GET/inventory/rfqs/:id/compareCompare vendor quotes
POST/inventory/blanket-ordersCreate blanket order
POST/inventory/blanket-orders/:id/call-offCreate call-off PO

Purchase Agreements (Tenders)

MethodPathDescription
POST/inventory/purchase-agreementsCreate a tender
GET/inventory/purchase-agreementsList tenders
POST/inventory/purchase-agreements/:id/openOpen for bidding
POST/inventory/purchase-agreements/:id/bidsSubmit a bid
POST/inventory/purchase-agreements/:id/evaluateStart evaluation
POST/inventory/purchase-agreements/:id/awardAward to vendor
GET/inventory/purchase-agreements/:id/compareBid comparison table

Vendor Rating

MethodPathDescription
GET/inventory/vendor-rating/rankingVendor ranking by score
GET/inventory/vendor-rating/:vendorIdVendor scorecard

Valuation & Costing

MethodPathDescription
GET/inventory/valuationInventory valuation report
GET/inventory/valuation/by-categoryValuation by category
GET/inventory/standard-cost/variancesCost variance report
POST/inventory/landed-costsCreate landed cost

Reports

MethodPathDescription
GET/inventory/reports/turnoverInventory turnover
GET/inventory/reports/abcABC classification
GET/inventory/reports/agingInventory aging
GET/inventory/reports/dead-stockDead stock analysis
GET/inventory/reports/forecastDemand forecast

CRM

MethodPathDescription
GET/crm/leadsList leads
POST/crm/leadsCreate a lead
POST/crm/leads/:id/convertConvert lead to deal
GET/crm/dealsList deals
PATCH/crm/deals/:idUpdate a deal
GET/crm/clientsList clients
POST/crm/clientsCreate a client
GET/crm/contactsList contacts

HR & Payroll

MethodPathDescription
GET/hr/employeesList employees
POST/hr/employeesCreate an employee
GET/hr/payroll/runsList payroll runs
POST/hr/payroll/runsCreate a payroll run
POST/hr/payroll/runs/:id/postPost payroll to GL
GET/hr/leave/requestsList leave requests
POST/hr/leave/requestsSubmit a leave request
GET/hr/attendanceList attendance records

Projects

MethodPathDescription
GET/projectsList projects
POST/projectsCreate a project
GET/projects/:idGet project details
GET/projects/:id/work-itemsList work items
POST/projects/:id/work-itemsCreate a work item
GET/projects/:id/sprintsList sprints
POST/projects/:id/sprintsCreate a sprint

Odoo Data Import

Full migration toolkit for importing data from Odoo instances. See Import Tool for detailed documentation.

Sessions

MethodPathDescription
POST/import/sessionsCreate import session
GET/import/sessionsList sessions
GET/import/sessions/:idGet session details
GET/import/sessions/:id/errorsGet import errors
GET/import/sessions/:id/mappingsGet Odoo→Arkan ID mappings
POST/import/sessions/:id/completeMark session complete

CSV Import

MethodPathDescription
POST/import/analyzeAnalyze CSV (detect model, preview data)
POST/import/validateValidate CSV against model rules
POST/import/sessions/:id/import/accountsImport chart of accounts
POST/import/sessions/:id/import/journalsImport journals
POST/import/sessions/:id/import/taxesImport taxes
POST/import/sessions/:id/import/categoriesImport product categories
POST/import/sessions/:id/import/uomImport units of measure
POST/import/sessions/:id/import/partnersImport clients & vendors
POST/import/sessions/:id/import/productsImport products
POST/import/sessions/:id/import/warehousesImport warehouses
POST/import/sessions/:id/import/locationsImport locations
POST/import/sessions/:id/import/opening-stockImport opening stock
POST/import/sessions/:id/import/journal-entriesImport journal entries
POST/import/sessions/:id/import/paymentsImport payments
POST/import/sessions/:id/import/sales-ordersImport sales orders
POST/import/sessions/:id/import/purchase-ordersImport purchase orders
POST/import/sessions/:id/import/opening-balanceGenerate opening balance entry

Odoo Live Connector

MethodPathDescription
POST/import/odoo/connectTest connection to Odoo
POST/import/odoo/summaryGet record counts from Odoo
POST/import/odoo/fieldsList model fields
POST/import/odoo/extractExtract records as JSON + CSV
POST/import/odoo/extract-and-importExtract and import in one step

Post-Import Validation

MethodPathDescription
POST/import/sessions/:id/validateRun validation (trial balance, record counts, FK integrity)

Customer Portal

Token-based self-service portal for customers. Tokens are generated by admin users and shared with clients.

Admin Endpoints (JWT required)

MethodPathDescription
POST/customer-portal/tokensGenerate portal token for client
GET/customer-portal/tokensList active tokens
DELETE/customer-portal/tokens/:idRevoke a token

Public Endpoints (token-based)

MethodPathDescription
GET/customer-portal/view/:token/dashboardCustomer dashboard
GET/customer-portal/view/:token/quotesList quotes
POST/customer-portal/view/:token/quotes/:id/acceptAccept a quote
POST/customer-portal/view/:token/quotes/:id/declineDecline a quote
GET/customer-portal/view/:token/ordersList orders
GET/customer-portal/view/:token/orders/:idOrder details with deliveries
GET/customer-portal/view/:token/invoicesList invoices
GET/customer-portal/view/:token/paymentsPayment history
GET/customer-portal/view/:token/deliveriesDelivery tracking

Vendor Portal

Token-based self-service portal for vendors (suppliers). See Vendor Portal for details.

Admin Endpoints (JWT required)

MethodPathDescription
POST/vendor-portal/tokensGenerate token for vendor
GET/vendor-portal/tokensList active tokens
DELETE/vendor-portal/tokens/:idRevoke a token

Public Endpoints (token-based)

MethodPathDescription
GET/vendor-portal/view/:token/dashboardVendor dashboard
GET/vendor-portal/view/:token/purchase-ordersList POs
GET/vendor-portal/view/:token/purchase-orders/:idPO detail
POST/vendor-portal/view/:token/purchase-orders/:id/acknowledgeAcknowledge PO
POST/vendor-portal/view/:token/purchase-orders/:id/shippingUpdate shipping info
POST/vendor-portal/view/:token/invoicesSubmit vendor invoice
GET/vendor-portal/view/:token/invoicesView submitted invoices
GET/vendor-portal/view/:token/paymentsView payment status
GET/vendor-portal/view/:token/rfqsView RFQs
POST/vendor-portal/view/:token/rfqs/:id/submitSubmit quote response

WebSocket Events

Connect to the WebSocket endpoint for real-time updates:

wss://your-api-host/ws?token=YOUR_TOKEN

Module Cache Invalidation

Join a module room to receive real-time data change notifications:

{ "event": "join_module", "data": { "moduleKey": "accounting" } }

The server emits module.invalidate when data changes, triggering client-side refetch.

Event Types

EventPayloadDescription
module.invalidate{ moduleKey, eventName }Data changed in a module
notificationNotification objectNew notification for user
user_joined{ userId, fullName, state }User came online
user_left{ userId }User went offline
dm:messageMessage objectDirect message received
dm:typing{ userId, userName }User is typing

Error Responses

All errors follow a consistent format:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "field": "email", "message": "must be a valid email address" }
  ]
}
Status CodeMeaning
400Bad Request — validation error
401Unauthorized — invalid or expired token
403Forbidden — insufficient permissions
404Not Found — resource does not exist
409Conflict — duplicate or state conflict
429Too Many Requests — rate limit exceeded
500Internal Server Error
Last updated on
PermissionsImport Tool