{ "openapi": "3.0.3", "info": { "title": "AMANA ERP API", "version": "2.0.0", "description": "# AMANA ERP REST API\n\nThe AMANA ERP API gives you programmatic access to all ERP data and operations.\nUse it to build custom integrations, automate workflows, or sync with third-party systems.\n\n## Authentication\n\nAll API requests require a Bearer token in the Authorization header:\n\n```\nAuthorization: Bearer {your_api_token}\n```\n\nGet your API token from **Settings → API & Integrations** in the AMANA dashboard.\n\n## Base URL\n\n```\nhttps://api.amana.io\n```\n\n## Rate Limits\n\n- Standard: 60 requests/minute per tenant\n- Burst: up to 30 requests/second\n- Returns `429 Too Many Requests` when exceeded\n\n## GCC Data Residency\n\nAMANA deploys in regional AWS cells. GCC Standard uses Bahrain (me-south-1);\nUAE in-country hosting uses me-central-1. Your tenant's assigned region is set at provision.", "contact": { "name": "AMANA Developer Support", "email": "api@amana.io", "url": "https://developers.amana.io" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.amana.io", "description": "Production" }, { "url": "https://sandbox.api.amana.io", "description": "Sandbox" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Get your token from Settings → API & Integrations" } }, "responses": { "Unauthorized": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "statusCode": { "type": "integer", "example": 401 } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Resource not found" }, "statusCode": { "type": "integer", "example": 404 } } } } } }, "RateLimited": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Too many requests" }, "statusCode": { "type": "integer", "example": 429 } } } } } } }, "schemas": { "Pagination": { "type": "object", "properties": { "items": { "type": "array" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Classic Polo Shirt" }, "brandId": { "type": "string", "format": "uuid", "nullable": true }, "brand": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "slug": { "type": "string", "example": "classic-polo-shirt" }, "status": { "type": "string", "enum": [ "active", "inactive", "discontinued" ] }, "hasVariants": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Fatima Al Mansouri" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "example": "+971501234567" }, "city": { "type": "string" }, "countryCode": { "type": "string", "example": "AE" }, "status": { "type": "string", "enum": [ "active", "inactive", "blocked" ] } } }, "SalesOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "soNumber": { "type": "string", "example": "SO-00001" }, "status": { "type": "string", "enum": [ "draft", "confirmed", "picking", "shipped", "delivered", "cancelled" ] }, "grandTotal": { "type": "number", "example": 525 }, "currencyCode": { "type": "string", "example": "AED" }, "createdAt": { "type": "string", "format": "date-time" } } }, "POSTransaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "receiptNumber": { "type": "string", "example": "RCP-DXB01-20250115-0001" }, "grandTotal": { "type": "number", "example": 157.5 }, "taxTotal": { "type": "number", "example": 7.5 }, "status": { "type": "string", "enum": [ "completed", "voided", "refunded" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "InventoryStock": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "outletId": { "type": "string", "format": "uuid" }, "quantityOnHand": { "type": "number" }, "reorderLevel": { "type": "number" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" } } } } }, "tags": [ { "name": "Products", "description": "Product and variant management" }, { "name": "Inventory", "description": "Stock levels and movements" }, { "name": "Customers", "description": "Customer records and segments" }, { "name": "Sales Orders", "description": "Order lifecycle management" }, { "name": "POS", "description": "Point of sale transactions" }, { "name": "Purchase Orders", "description": "Procurement workflow" }, { "name": "Finance", "description": "GL, AP, AR, and financial reports" }, { "name": "HR", "description": "Employees, payroll, and attendance" }, { "name": "CRM", "description": "Leads, pipeline, and interactions" }, { "name": "Webhooks", "description": "Event subscription management" }, { "name": "Marketplace", "description": "App marketplace — install and manage integrations" }, { "name": "Zapier", "description": "Zapier trigger and action endpoints" }, { "name": "Retail", "description": "Store grading and merchandising" }, { "name": "GRC", "description": "Governance, risk, and compliance" }, { "name": "MasterData", "description": "Master data governance and stewardship" }, { "name": "Loyalty", "description": "Loyalty programme, ledger, and rewards" } ], "paths": { "/products": { "get": { "tags": [ "Products" ], "summary": "List products", "description": "Returns a paginated list of all products for the authenticated tenant.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "categoryId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Paginated list of products", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Products" ], "summary": "Create product", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Classic Polo Shirt" }, "brandId": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "categoryId": { "type": "string", "format": "uuid" }, "unitOfMeasure": { "type": "string", "default": "piece" }, "hasVariants": { "type": "boolean", "default": false } } } } } }, "responses": { "201": { "description": "Product created" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get product", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Product details" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Products" ], "summary": "Update product", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "brandId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive", "discontinued" ] } } } } } }, "responses": { "200": { "description": "Product updated" } } } }, "/inventory/stock": { "get": { "tags": [ "Inventory" ], "summary": "Get stock levels", "description": "Returns current stock quantities across all outlets.", "parameters": [ { "name": "outletId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "variantId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "lowStock", "in": "query", "schema": { "type": "boolean" }, "description": "Filter items at or below reorder level" } ], "responses": { "200": { "description": "Stock levels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryStock" } } } } } } } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } ] } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "city": { "type": "string" }, "countryCode": { "type": "string", "default": "AE" } } } } } }, "responses": { "201": { "description": "Customer created" } } } }, "/sales-orders": { "get": { "tags": [ "Sales Orders" ], "summary": "List sales orders", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Sales order list" } } } }, "/pos/transactions": { "get": { "tags": [ "POS" ], "summary": "List POS transactions", "parameters": [ { "name": "outletId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Transaction list" } } } }, "/webhooks/endpoints": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "responses": { "200": { "description": "Webhook endpoints" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string", "example": "My integration" }, "url": { "type": "string", "format": "uri", "example": "https://myapp.com/webhooks/amana" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "order.created", "inventory.low_stock" ] } } } } } }, "responses": { "201": { "description": "Webhook endpoint created with signing secret" } } } }, "/marketplace/apps": { "get": { "tags": [ "Marketplace" ], "summary": "List marketplace apps", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of approved marketplace apps" } } } }, "/marketplace/apps/{id}/install": { "post": { "tags": [ "Marketplace" ], "summary": "Install an app", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "App installed" }, "409": { "description": "Already installed" } } }, "delete": { "tags": [ "Marketplace" ], "summary": "Uninstall an app", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "App uninstalled" } } } }, "/zapier/auth/test": { "get": { "tags": [ "Zapier" ], "summary": "Verify Zapier credentials", "responses": { "200": { "description": "Credentials valid, returns tenant info" } } } }, "/zapier/triggers/new-sale": { "get": { "tags": [ "Zapier" ], "summary": "Trigger: new POS sale", "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "List of recent completed sales" } } } }, "/zapier/triggers/new-customer": { "get": { "tags": [ "Zapier" ], "summary": "Trigger: new customer", "responses": { "200": { "description": "List of recently created customers" } } } }, "/zapier/triggers/low-stock": { "get": { "tags": [ "Zapier" ], "summary": "Trigger: low stock alert", "responses": { "200": { "description": "List of items at or below reorder level" } } } }, "/zapier/actions/create-customer": { "post": { "tags": [ "Zapier" ], "summary": "Action: create customer", "responses": { "201": { "description": "Customer created" } } } }, "/store-grading/policy": { "get": { "tags": [ "Retail" ], "summary": "Get store grading policy", "responses": { "200": { "description": "Grading weights, cutoffs, and auto-regrade settings" } } }, "put": { "tags": [ "Retail" ], "summary": "Update store grading policy", "responses": { "200": { "description": "Updated policy" } } } }, "/store-grading/definitions": { "get": { "tags": [ "Retail" ], "summary": "List grade definitions (A/B/C)", "responses": { "200": { "description": "Grade definition list" } } }, "put": { "tags": [ "Retail" ], "summary": "Upsert grade definitions", "responses": { "200": { "description": "Updated definitions" } } } }, "/store-grading/outlets": { "get": { "tags": [ "Retail" ], "summary": "List outlets with metrics and current grades", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "companyId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Outlet grade rows with performance metrics" } } } }, "/store-grading/recalculate": { "post": { "tags": [ "Retail" ], "summary": "Recalculate store grades", "responses": { "200": { "description": "Recalculation summary (processed, changed, skipped)" } } } }, "/store-grading/history": { "get": { "tags": [ "Retail" ], "summary": "Grade change history", "responses": { "200": { "description": "Paginated grade history" } } } }, "/grc/policies/summary": { "get": { "tags": [ "GRC" ], "summary": "Policy registry summary counts", "responses": { "200": { "description": "Counts by status and review due" } } } }, "/grc/policies": { "get": { "tags": [ "GRC" ], "summary": "List compliance policies", "responses": { "200": { "description": "Policy registry entries" } } }, "post": { "tags": [ "GRC" ], "summary": "Create compliance policy", "responses": { "201": { "description": "Created policy" } } } }, "/grc/policies/{id}": { "get": { "tags": [ "GRC" ], "summary": "Get compliance policy", "responses": { "200": { "description": "Policy detail" } } }, "patch": { "tags": [ "GRC" ], "summary": "Update compliance policy", "responses": { "200": { "description": "Updated policy" } } }, "delete": { "tags": [ "GRC" ], "summary": "Delete compliance policy", "responses": { "204": { "description": "Deleted" } } } }, "/compliance/consent/records": { "get": { "tags": [ "Compliance" ], "summary": "List recent consent records", "responses": { "200": { "description": "Consent record list for admin workspace" } } } }, "/grc/risks/summary": { "get": { "tags": [ "GRC" ], "summary": "Risk register summary counts", "responses": { "200": { "description": "Counts by status and high-inherent risks" } } } }, "/grc/risks": { "get": { "tags": [ "GRC" ], "summary": "List enterprise risks", "responses": { "200": { "description": "Risk register entries" } } }, "post": { "tags": [ "GRC" ], "summary": "Create enterprise risk", "responses": { "201": { "description": "Created risk" } } } }, "/grc/risks/heatmap/html": { "get": { "tags": [ "GRC" ], "summary": "Risk heat-map printable HTML", "responses": { "200": { "description": "5x5 likelihood×impact heat-map for PDF export" } } } }, "/master-data/duplicate-candidates/spawn-stewardship": { "post": { "tags": [ "MasterData" ], "summary": "Spawn stewardship merge request for duplicate group", "responses": { "200": { "description": "Existing request (idempotent)" }, "201": { "description": "Created request" } } } }, "/master-data/duplicate-candidates/spawn-stewardship/bulk": { "post": { "tags": [ "MasterData" ], "summary": "Bulk-spawn merge stewardship requests for all duplicate groups", "responses": { "200": { "description": "Bulk spawn summary" } } } }, "/grc/risks/{id}": { "get": { "tags": [ "GRC" ], "summary": "Get enterprise risk with history", "responses": { "200": { "description": "Risk detail" } } }, "patch": { "tags": [ "GRC" ], "summary": "Update enterprise risk", "responses": { "200": { "description": "Updated risk" } } }, "delete": { "tags": [ "GRC" ], "summary": "Delete enterprise risk", "responses": { "204": { "description": "Deleted" } } } }, "/master-data/stewardship/requests": { "get": { "tags": [ "MasterData" ], "summary": "List stewardship requests", "responses": { "200": { "description": "Stewardship workflow queue" } } }, "post": { "tags": [ "MasterData" ], "summary": "Create stewardship request", "responses": { "201": { "description": "Created request" } } } }, "/master-data/stewardship/requests/{id}": { "get": { "tags": [ "MasterData" ], "summary": "Get stewardship request", "responses": { "200": { "description": "Request detail" } } }, "patch": { "tags": [ "MasterData" ], "summary": "Update stewardship request status", "responses": { "200": { "description": "Updated request" } } } }, "/ai/purchase-invoice/parse": { "post": { "tags": [ "AI" ], "summary": "Parse pasted supplier invoice text", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Parsed invoice lines and header fields" } } } }, "/ai/document-intelligence/scan": { "post": { "tags": [ "AI" ], "summary": "AMANA Document Intelligence — generic document scan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "docType" ], "properties": { "docType": { "type": "string", "enum": [ "supplier_invoice", "trade_license", "vat_certificate", "emirates_id", "passport", "expense_receipt", "product_label", "supplier_catalog_page" ] }, "documentId": { "type": "string", "format": "uuid" }, "storageKey": { "type": "string" }, "context": { "type": "object" } } } } } }, "responses": { "200": { "description": "Structured extraction with jobId" } } } }, "/ai/document-intelligence/jobs/{id}": { "get": { "tags": [ "AI" ], "summary": "Get document intelligence scan job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scan job record" } } } }, "/ai/purchase-invoice/ocr": { "post": { "tags": [ "AI" ], "summary": "OCR a uploaded supplier invoice image or PDF", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "supplierId" ], "properties": { "supplierId": { "type": "string", "format": "uuid" }, "documentId": { "type": "string", "format": "uuid" }, "storageKey": { "type": "string" } } } } } }, "responses": { "200": { "description": "Structured invoice with extractionSource and line items" }, "403": { "description": "Supplier OCR import disabled" }, "503": { "description": "ANTHROPIC_API_KEY or storage not configured" } } } }, "/loyalty/dashboard": { "get": { "tags": [ "Loyalty" ], "summary": "Loyalty command center aggregate", "description": "Programme status, liability, tier distribution, member counts, and setup checklist.", "responses": { "200": { "description": "Dashboard payload" } } } }, "/loyalty/program": { "get": { "tags": [ "Loyalty" ], "summary": "Get default loyalty programme", "responses": { "200": { "description": "LoyaltyProgram" } } }, "put": { "tags": [ "Loyalty" ], "summary": "Update default loyalty programme", "responses": { "200": { "description": "Updated programme" } } } }, "/loyalty/ledger": { "get": { "tags": [ "Loyalty" ], "summary": "Org-wide points ledger", "parameters": [ { "name": "customerId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "txnType", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ledger rows" } } } }, "/loyalty/rewards": { "get": { "tags": [ "Loyalty" ], "summary": "List rewards catalog", "responses": { "200": { "description": "Reward items" } } }, "post": { "tags": [ "Loyalty" ], "summary": "Create catalog reward", "responses": { "201": { "description": "Created reward" } } } } } }