API Basics
What type of API does eveXso provide?
eveXso provides a RESTful API with 72+ endpoints. All requests and responses use JSON format. The API follows REST best practices with standard HTTP methods (GET, POST, PUT, DELETE) and status codes.
Is there an API specification available?
Yes, we provide: OpenAPI 3.0 specification (downloadable), Postman collection with all 72+ endpoints, interactive API Playground for testing, comprehensive Quick Start Guide, and code examples for common scenarios.
What programming languages can I use?
Any language that supports HTTP requests can integrate with eveXso. Popular choices include: Python (requests library), JavaScript/Node.js (axios, fetch), C# (.NET HttpClient), Java (HttpURLConnection, OkHttp), PHP (cURL, Guzzle), and Ruby (Net::HTTP, HTTParty).
Do you provide SDKs or client libraries?
Currently, we don't provide official SDKs. However, our REST API is straightforward to use with standard HTTP libraries. Many customers generate client libraries from our OpenAPI specification using tools like Swagger Codegen or OpenAPI Generator.
How do I authenticate API requests?
Authentication uses OAuth 2.0 client credentials flow: 1) POST to /oauth/token with client_id and client_secret, 2) Receive an access_token (valid for 24 hours), 3) Include token in Authorization header: 'Bearer {access_token}', 4) Refresh token before expiry.
Getting Started
How do I get API credentials?
API credentials are provided during eveXso onboarding. You'll receive: client_id and client_secret for test environment, client_id and client_secret for production environment, and API base URLs for both environments. Contact support if you need credentials.
Where do I start with the API?
Follow these steps: 1) Read the Quick Start Guide (/developers/quick-start), 2) Get your API credentials, 3) Try the API Playground to test endpoints interactively, 4) Download the Postman collection for your language, 5) Implement authentication, 6) Start with simple endpoints (inventory/check, customer/check), 7) Build out your integration incrementally.
Is there a sandbox environment?
Yes, every eveXso account includes a test environment. The test environment: mirrors production functionality, includes sample data for testing, allows unlimited API calls, can be reset if needed, and has separate API credentials from production.
How long does it take to make the first API call?
Most developers make their first successful API call within 30 minutes using our Quick Start Guide and API Playground. A complete basic integration (inventory and orders) typically takes 1-2 weeks.
API Endpoints
What entities can I access via the API?
The API provides access to 12 entity types: Inventory (items, stocking factors, warehouse info), Sales Orders (orders, line items, shipments), Purchase Orders (orders, receipts), Customers (customer details, supply locations), Suppliers (supplier details, supply locations), Warehouse Locations (warehouses, areas, zones, bins), Couriers (courier services, tracking), Production (production orders, BOMs), ERP Updates (outgoing/incoming consignments, move attempts), Comparisons (inventory reconciliation), Dangerous Goods (UN numbers, classifications), and Custom Scripts (event-driven automation).
What are the most commonly used endpoints?
The most common endpoints are: inventory/add - import inventory items, inventory/check - validate inventory data, sales_order/add - import sales orders, customer/add - import customers, supplier/add - import suppliers, erp_update/outgoing_consignment - get shipment updates, erp_update/incoming_consignment - get receipt updates, warehouse/check - get warehouse structure, and courier_service/check - get available couriers.
How do I discover available endpoints?
Multiple ways to explore endpoints: Use the API Playground (interactive testing), download the Postman collection (all 72+ endpoints), view the OpenAPI specification, read the Quick Start Guide (organized by workflow), or check the API documentation page.
Are there bulk import endpoints?
Yes, most endpoints support bulk operations. For example: inventory/add accepts arrays of items (up to 1000 per request), customer/add accepts arrays of customers, sales_order/add can import multiple orders. For very large imports (10,000+ records), batch them into chunks of 1000.
Data Formats
What date format should I use?
Use ISO 8601 format: 'YYYY-MM-DDTHH:MM:SS' (e.g., '2025-12-20T14:30:00'). Dates are stored in UTC. If you send a date without timezone, it will be interpreted as UTC. For date-only fields, use 'YYYY-MM-DD'.
How do I handle decimal numbers?
Send decimal numbers as numbers (not strings): quantity: 10.5, price: 99.99. Use appropriate precision: quantities (2 decimal places), prices (2 decimal places), weights (3 decimal places). The API will round to appropriate precision.
What character encoding should I use?
Always use UTF-8 encoding for all API requests and responses. Include the Content-Type header: 'Content-Type: application/json; charset=utf-8'. This ensures proper handling of international characters.
How do I handle special characters in item codes?
Item codes and other identifiers should: use URL-safe characters (A-Z, a-z, 0-9, -, _), avoid spaces (use hyphens or underscores), be case-sensitive, and have a maximum length of 50 characters. If your ERP uses special characters, encode them or create a mapping.
Error Handling
What HTTP status codes does the API return?
Standard HTTP status codes: 200 OK (success), 201 Created (resource created), 400 Bad Request (validation error), 401 Unauthorized (invalid/expired token), 403 Forbidden (insufficient permissions), 404 Not Found (resource doesn't exist), 429 Too Many Requests (rate limit exceeded), 500 Internal Server Error (server error).
How do I handle validation errors?
Validation errors (400 status) include detailed error messages: { "error": "Validation failed", "details": [ { "field": "item_code", "message": "Required field" }, { "field": "quantity", "message": "Must be positive" } ] }. Use the check endpoints to validate data before committing.
What should I do if I get a 429 rate limit error?
If you hit rate limits: implement exponential backoff (wait 1s, 2s, 4s, 8s), reduce request frequency, use bulk endpoints instead of individual requests, and contact support if you need higher limits for specific use cases.
How do I debug API errors?
Debugging steps: 1) Check the HTTP status code, 2) Read the error message in the response body, 3) Verify your request format matches the API spec, 4) Use the API Playground to test the same request, 5) Check the audit log in eveXso, 6) Enable verbose logging in your code, 7) Contact support with request/response examples.
Best Practices
How often should I poll for updates?
Recommended polling intervals: ERP updates (shipments, receipts): every 5-15 minutes, inventory changes: every 15-60 minutes, order status: every 15-30 minutes. For real-time updates, use webhooks instead of polling.
Should I use webhooks or polling?
Webhooks are recommended for: real-time order updates, shipment notifications, inventory changes, and receipt confirmations. Polling is suitable for: batch imports, scheduled synchronization, and systems that don't support webhooks. Webhooks reduce API calls by 90%+.
How do I handle idempotency?
For idempotent operations: inventory/add updates existing items by item_code, customer/add updates existing customers by customer_code. For non-idempotent operations: sales_order/add rejects duplicate order_number, use check endpoints to verify before creating. Include a unique request_id for critical operations.
What's the best way to handle large data imports?
For large imports: batch records into chunks of 1000, implement parallel processing (multiple concurrent requests), use bulk endpoints (not individual), add retry logic with exponential backoff, log all successes and failures, and validate with check endpoints first.
How do I secure my API credentials?
Security best practices: never commit credentials to source control, use environment variables or secure vaults, rotate credentials periodically, use separate credentials for test/production, implement IP whitelisting if possible, and log all API access for audit purposes.
Advanced Topics
Can I extend the API with custom logic?
Yes, eveXso supports event-driven scripts (JavaScript) that execute during API operations. You can: validate custom business rules, transform data before saving, trigger external webhooks, generate custom reports, and implement complex workflows. Scripts are configured in the eveXso admin panel.
How do I handle multi-warehouse scenarios?
Multi-warehouse support: each warehouse has a unique warehouse_code, specify warehouse_code in inventory/add for item locations, orders can be assigned to specific warehouses, use warehouse/check to get warehouse structure, and inter-warehouse transfers are supported via move_attempt endpoints.
Can I access historical data via the API?
Yes, most endpoints support date range filters: erp_update endpoints include from_date and to_date parameters, audit logs are available for 90 days, historical inventory movements can be queried, and shipment history is retained indefinitely. For bulk historical exports, contact support.
How do I test my integration?
Testing strategy: 1) Use the test environment for all development, 2) Test with the API Playground first, 3) Implement automated tests for critical workflows, 4) Test error scenarios (invalid data, missing fields), 5) Load test with realistic data volumes, 6) Perform end-to-end testing with your ERP, 7) Validate in production with a pilot group.
Ready to Build Your Integration?
Start with our interactive API Playground and comprehensive documentation.