ONESCP Portal - API Documentation for ERP Integration

Version: 1.0.0
Last Updated: March 19, 2025
Documentation: https://docs.onescp.com

Base URL for API calls

• Base URL http://api.onescp.com — use this base URL for API requests.

---

Table of Contents

1. Overview
2. Authentication
3. Core APIs
- Orders
- Shipments
- Items
- Tasks
4. Supporting APIs
- Suppliers
- Carriers
5. Webhooks
6. Sync/Delta APIs
7. Sync from ERP to Portal
8. ERP Integration Checklist
9. Error Handling
10. Rate Limiting
11. Best Practices
12. Support
13. Infrastructure & Requirements

---

Overview

This API documentation is designed for third-party ERP systems to integrate with the ONESCP Portal. The API provides endpoints for managing Orders, Shipments, Items, and Tasks with full CRUD operations, filtering, pagination, and document management.

Key Features

• RESTful API - Standard HTTP methods (GET, POST, PUT, PATCH, DELETE)


• JWT Authentication - Secure token-based authentication


• Comprehensive CRUD - Create, Read, Update, Delete operations for all entities


• Filtering & Search - Advanced filtering and search capabilities


• Pagination - Efficient data retrieval with pagination


• Document Management - Upload, download, and manage documents


• Real-time Updates - Webhooks support


• Sync APIs - Delta/sync endpoints for efficient data synchronization

API Versioning

Currently, the API is at version 1.0.0. All endpoints are under /api/ prefix.

Response Format

All API responses follow a consistent format:

Success Response:


{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

Error Response:


{
  "success": false,
  "message": "Error description",
  "error": "Detailed error information"
}

---

Authentication

All API endpoints (except authentication endpoints) require a valid JWT token in the Authorization header.

Getting an Access Token

Endpoint: POST /api/auth/login

Request:


{
  "email": "user@example.com",
  "password": "your_password"
}

Response:


{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "_id": "user_id",
    "name": "John Doe",
    "email": "user@example.com",
    "role": "buyer",
    "companyId": "company_id"
  }
}

Using the Token

Include the token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration

• Tokens expire after 24 hours


• Refresh token endpoint: POST /api/auth/refresh (if implemented)

API Key Authentication (Coming Soon)

For ERP integrations, API key authentication will be available as an alternative to user-based JWT tokens.

---

Core APIs

Orders

Orders represent purchase orders in the supply chain system. Each order contains line items, supplier information, delivery schedules, and documents.

#### Base Endpoint
/api/purchase-order

#### Get All Orders

Endpoint: GET /api/purchase-order/allOrders

Headers:


Authorization: Bearer {token}

Query Parameters:


• page (optional): Page number (default: 1)


• limit (optional): Items per page (default: 10)


• status (optional): Filter by status (draft, pending, approved, rejected, completed)


• supplier (optional): Filter by supplier ID


• dateFrom (optional): Filter orders from date (ISO 8601)


• dateTo (optional): Filter orders until date (ISO 8601)

Response:


{
  "success": true,
  "orders": [
    {
      "_id": "order_id",
      "purchaseOrderNumber": "PO-2024-001",
      "supplier": {
        "name": "ABC Electronics",
        "email": "contact@abcelectronics.com"
      },
      "status": "approved",
      "priority": "p1",
      "orderLines": [
        {
          "_id": "line_id",
          "position": "10",
          "item": {
            "number": "ITEM-001",
            "name": "Laptop Computer",
            "unitPrice": 999.99
          },
          "quantity": 10,
          "prices": {
            "netPrice": 9999.90
          }
        }
      ],
      "totalAmount": 9999.90,
      "deliveryDate": "2024-12-31",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "pages": 3
  }
}

#### Get Order by ID

Endpoint: GET /api/purchase-order/{id}

Response:


{
  "success": true,
  "order": {
    "_id": "order_id",
    "purchaseOrderNumber": "PO-2024-001",
    "supplier": { ... },
    "orderLines": [ ... ],
    "documents": [ ... ],
    "status": "approved",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

#### Create Order

Endpoint: POST /api/purchase-order/create

Request Body:


{
  "supplier": {
    "name": "ABC Electronics",
    "email": "contact@abcelectronics.com",
    "address": "123 Supplier St, City, Country"
  },
  "orderLines": [
    {
      "position": "10",
      "item": {
        "number": "ITEM-001",
        "name": "Laptop Computer",
        "unitPrice": 999.99,
        "purchaseUnitOfMeasureIso": "EA"
      },
      "quantity": 10,
      "prices": {
        "netPrice": 9999.90
      },
      "description": "High-performance laptop"
    }
  ],
  "deliveryDate": "2024-12-31",
  "priority": "p1",
  "notes": "Urgent delivery required"
}

Response:


{
  "success": true,
  "message": "Purchase order created successfully",
  "order": {
    "_id": "new_order_id",
    "purchaseOrderNumber": "PO-2024-002",
    ...
  }
}

#### Update Order

Endpoint: PUT /api/purchase-order/{id}

Request Body:


{
  "deliveryDate": "2025-01-15",
  "notes": "Updated delivery notes",
  "priority": "p2"
}

#### Update Order Status

Endpoint: PUT /api/purchase-order/{id}/status

Request Body:


{
  "status": "approved",
  "notes": "Approved by manager"
}

Status Values:


• draft - Order is in draft state


• pending - Order is pending approval


• approved - Order is approved


• rejected - Order is rejected


• completed - Order is completed

#### Delete Order

Endpoint: DELETE /api/purchase-order/{id}

Response:


{
  "success": true,
  "message": "Purchase order deleted successfully"
}

#### Order Line Management

Add Order Line:
POST /api/purchase-order/{id}/lines

Update Order Line:
PUT /api/purchase-order/{id}/lines/{lineId}

Delete Order Line:
DELETE /api/purchase-order/{id}/lines/{lineId}

#### Order Documents

Add Document:
POST /api/purchase-order/{id}/documents

Content-Type: multipart/form-data

Form Data:


• document: File to upload


• type: Document type (Invoice, Shipping, Contract, General, Custom Clearance)


• name: Document name (optional)


• description: Document description (optional)

Get Documents:
GET /api/purchase-order/{id}/documents

Delete Document:
DELETE /api/purchase-order/{id}/documents/{documentId}

---

Shipments

Shipments represent the transportation of goods from origin to destination. Each shipment is linked to purchase order lines and can contain multiple containers.

#### Base Endpoint
/api/shipment

#### Get All Shipments

Endpoint: GET /api/shipment

Query Parameters:


• page (optional): Page number


• limit (optional): Items per page


• status (optional): Filter by status (pending, in_transit, delivered, cancelled)


• carrier (optional): Filter by carrier name

Response:


{
  "success": true,
  "shipments": [
    {
      "_id": "shipment_id",
      "shipmentNumber": "SH-2024-001",
      "purchaseOrder": "order_id",
      "status": "in_transit",
      "type": "Ocean",
      "departureFrom": "Shanghai Port",
      "finalDestination": "Los Angeles Port",
      "carrier": "Maersk Line",
      "containers": [
        {
          "_id": "container_id",
          "containerNumber": "MSKU1234567",
          "containerType": "40ft",
          "status": "In Transit",
          "eta": "2024-02-15T14:30:00Z"
        }
      ],
      "scheduledDeliveryDate": "2024-02-15",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": { ... }
}

#### Get Shipment by ID

Endpoint: GET /api/shipment/{id}

#### Create Shipment

Endpoint: POST /api/shipment/purchase-orders/{purchaseOrderId}/lines/{lineId}

Request Body:


{
  "departureFrom": "Shanghai Port",
  "departureCity": "Shanghai",
  "departureCountryISO2": "CN",
  "finalDestination": "Los Angeles Port",
  "finalDestinationCity": "Los Angeles",
  "finalDestinationCountryISO2": "US",
  "type": "Ocean",
  "carrier": "Maersk Line",
  "scheduledDeliveryDate": "2024-02-15",
  "containers": [
    {
      "containerNumber": "MSKU1234567",
      "containerType": "40ft",
      "sealNumber": "SEAL123456",
      "weight": 25000,
      "volume": 67.7
    }
  ]
}

#### Update Shipment

Endpoint: PATCH /api/shipment/{id}

Request Body:


{
  "status": "in_transit",
  "carrier": "CMA CGM",
  "scheduledDeliveryDate": "2024-02-20"
}

#### Update Shipment Status

Endpoint: PATCH /api/shipment/{id}/status

Request Body:


{
  "status": "delivered"
}

Status Values:


• pending - Shipment is pending


• in_transit - Shipment is in transit


• delivered - Shipment is delivered


• cancelled - Shipment is cancelled

#### Container Management

Add Container:
POST /api/shipment/{id}/containers

Update Container:
PATCH /api/shipment/{id}/containers/{containerId}

Delete Container:
DELETE /api/shipment/{id}/containers/{containerId}

#### Shipment Documents

Add Document:
POST /api/shipment/{id}/documents

Get Documents:
GET /api/shipment/{id}/documents

Delete Document:
DELETE /api/shipment/{id}/documents/{documentId}

---

Items

Items represent products or materials in the inventory system. Items can be of different types: Material, Supplier, or Attributes.

#### Base Endpoint
/api/items

#### Get All Items

Endpoint: GET /api/items

Query Parameters:


• page (optional): Page number


• limit (optional): Items per page


• search (optional): Search by name or description


• category (optional): Filter by category


• itemStatus (optional): Filter by status (Pending, Under Approval, Processed)

Response:


{
  "success": true,
  "items": [
    {
      "_id": "item_id",
      "itemNumber": "ITEM-001",
      "name": "Laptop Computer",
      "description": "High-performance laptop",
      "category": "Electronics",
      "type": "Material",
      "itemStatus": "Processed",
      "material": {
        "MATNR": "000000000000015330",
        "LAEDA": "10/29/2024",
        "MTART": "120404"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": { ... }
}

#### Get Item by ID

Endpoint: GET /api/items/{id}

#### Create Item

Endpoint: POST /api/items

Request Body:


{
  "itemNumber": "ITEM-002",
  "name": "Desktop Computer",
  "description": "High-performance desktop",
  "category": "Electronics",
  "type": "Material",
  "material": {
    "MATNR": "000000000000015331",
    "LAEDA": "10/29/2024",
    "MTART": "120404"
  }
}

#### Update Item

Endpoint: PUT /api/items/{id}

#### Delete Item

Endpoint: DELETE /api/items/{id}

#### Bulk Import Items

Endpoint: POST /api/items/bulk-import

Content-Type: multipart/form-data

Form Data:


• file: CSV or Excel file containing items


• updateExisting: Boolean (default: false)

Response:


{
  "success": true,
  "message": "Items imported successfully",
  "imported": 25,
  "updated": 5,
  "errors": []
}

#### Export Items

Endpoint: GET /api/items/export

Query Parameters:


• format (optional): Export format (csv, excel)

---

Tasks

Tasks represent workflow items that require action, such as order approvals, shipment confirmations, etc.

#### Base Endpoint
/api/task

#### Get All Tasks

Endpoint: GET /api/task/allTasks

Query Parameters:


• page (optional): Page number


• limit (optional): Items per page


• status (optional): Filter by status (Open, In Progress, Completed, Rejected)


• priority (optional): Filter by priority (p1, p2, p3)

Response:


{
  "success": true,
  "tasks": [
    {
      "_id": "task_id",
      "title": "Review Purchase Order",
      "description": "Review and approve purchase order PO-001",
      "status": "Open",
      "priority": "p1",
      "assignedTo": {
        "_id": "user_id",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "relatedOrder": {
        "_id": "order_id",
        "purchaseOrderNumber": "PO-2024-001"
      },
      "dueDate": "2024-12-31T23:59:59Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": { ... }
}

#### Get Task by ID

Endpoint: GET /api/task/taskid/{id}

#### Create Task

Endpoint: POST /api/task/{orderId}

Request Body:


{
  "title": "Review Purchase Order",
  "description": "Review and approve purchase order",
  "assignedTo": "user_id",
  "priority": "p1",
  "dueDate": "2024-12-31T23:59:59Z"
}

#### Update Task

Endpoint: PUT /api/task/taskid/{id}

#### Accept or Reject Task

Endpoint: PUT /api/task/{id}/decision

Request Body:


{
  "decision": "accept",
  "comments": "Approved after review"
}

Decision Values:


• accept - Accept the task


• reject - Reject the task

#### Update Task Status

Endpoint: PUT /api/task/taskid/{id}

Request Body:


{
  "status": "In Progress"
}

Status Values:


• Open - Task is open


• In Progress - Task is in progress


• Completed - Task is completed


• Rejected - Task is rejected

---

Supporting APIs

Suppliers

Suppliers represent vendor companies in the system. These endpoints are read-only for reference purposes.

#### Base Endpoint
/api/suppliers

#### Get All Suppliers

Endpoint: GET /api/suppliers

Response:


{
  "success": true,
  "suppliers": [
    {
      "_id": "supplier_id",
      "name": "ABC Electronics",
      "email": "contact@abcelectronics.com",
      "address": "123 Supplier St",
      "phone": "+1234567890"
    }
  ]
}

---

Carriers

Carriers represent shipping companies. These endpoints are read-only for reference purposes.

#### Base Endpoint
/api/carriers

#### Get All Carriers

Endpoint: GET /api/carriers

Response:


{
  "success": true,
  "carriers": [
    {
      "_id": "carrier_id",
      "name": "Maersk Line",
      "code": "MAEU",
      "type": "Ocean"
    }
  ]
}

---

Webhooks

Webhooks send HTTP POST requests to your URL when data changes, so your ERP can stay in sync in real time.

Endpoints (all require Authorization: Bearer {token})

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/webhooks/subscriptions | Create a subscription |
| GET | /api/webhooks/subscriptions | List your company’s subscriptions |
| GET | /api/webhooks/subscriptions/:id | Get one subscription |
| DELETE | /api/webhooks/subscriptions/:id | Delete a subscription |

Create subscription

POST /api/webhooks/subscriptions

Body:


• url (string, required): Your endpoint URL (e.g. https://your-erp.com/webhooks/onescp).


• events (array of strings, required): Events to subscribe to (see list below).


• description (string, optional): Label for this subscription.


• secret (string, optional): Min 16 characters; used to sign payloads. If omitted, a secret is generated.

Response: { "success": true, "subscription": { "_id", "url", "events", "status", ... } } (secret is not returned after creation).

Events

| Event | When it is sent |
|-------|------------------|
| order.created | New order created |
| order.updated | Order updated |
| order.deleted | Order soft-deleted (after approval) |
| order.status_changed | Order status updated |
| shipment.created | New shipment created |
| shipment.updated | Shipment updated |
| shipment.deleted | Shipment soft-deleted (after approval) |
| shipment.status_changed | Shipment status updated |
| item.created | New item created |
| item.updated | Item updated |
| item.deleted | Item deleted or soft-deleted |
| task.created | New task created |
| task.updated | Task updated |
| task.completed | Task accepted/completed |
| task.rejected | Task rejected |

Payload and headers

Each delivery is a POST to your url with:

Headers:


• Content-Type: application/json


• X-Webhook-Signature: sha256= — verify with your secret


• X-Webhook-Event:


• X-Webhook-Delivery-Id:

Body:


{
  "event": "order.updated",
  "timestamp": "2025-01-26T12:00:00.000Z",
  "data": { "_id": "...", "purchaseOrderNumber": "PO-2024-001", "status": "approved", ... }
}

Verifying the signature

Compute HMAC-SHA256(secret, rawRequestBody) and compare to the X-Webhook-Signature value (without the sha256= prefix). If they match, the payload is from ONESCP.

Scoping

Subscriptions are per company. You only receive events for data your company can access (e.g. orders where your company is buyer or supplier). Item events are sent to all subscribers (items are not company-scoped).

Delivery and failures

Deliveries are logged (success/failure, status code, duration). Your endpoint should return 2xx quickly; process the payload asynchronously if needed. Failed deliveries are logged for debugging.

---

Sync/Delta APIs

Sync/Delta APIs return only records that changed since a given timestamp, for efficient incremental sync with ERPs.

Endpoints

All require Authorization: Bearer {token}.

| Entity | Method | Endpoint |
|----------|--------|----------|
| Orders | GET | /api/purchase-order/sync |
| Shipments| GET | /api/shipment/sync |
| Items | GET | /api/items/sync |
| Tasks | GET | /api/task/sync |

Query Parameters

• since (required): ISO 8601 timestamp (e.g. 2025-01-01T00:00:00Z). Only records with updatedAt (or deletedAt for soft-deletes) after this time are returned. Use a very old date or omit for initial full sync.


• page (optional): Page number, default 1.


• limit (optional): Items per page, default 100, max 500.

Example: GET /api/purchase-order/sync?since=2025-01-25T00:00:00Z&page=1&limit=100

Response Format

{
  "success": true,
  "created": [ { "_id": "...", "purchaseOrderNumber": "PO-2024-002", "createdAt": "...", ... } ],
  "updated": [ { "_id": "...", "purchaseOrderNumber": "PO-2024-001", "status": "approved", "updatedAt": "...", ... } ],
  "deleted": [ { "_id": "...", "deletedAt": "2024-01-16T12:00:00Z" } ],
  "lastSyncTimestamp": "2024-01-16T12:00:00Z",
  "hasMore": false,
  "pagination": { "page": 1, "limit": 100, "total": 42 }
}

• created: Records created after since.


• updated: Records updated after since (and created before or at since).


• deleted: Soft-deleted records with deletedAt after since (IDs only plus deletedAt).


• lastSyncTimestamp: Use this as the next since value for the next sync.


• hasMore: If true, call again with the same since and next page.

Scoping

• Orders: Same as list APIs (buyer or supplier company; super_admin sees all).


• Shipments: Same as list APIs (shipments for orders where user’s company is buyer or supplier).


• Items: No company filter; all items visible to the app.


• Tasks: Only tasks where assignedTo is the current user.

Usage Flow

1. Initial sync: Call with since=1970-01-01T00:00:00Z (or omit) and page through until hasMore is false.
2. Incremental sync: Store lastSyncTimestamp from the last response; use it as since on the next run.
3. Conflict resolution: Use updatedAt (and deletedAt) to order and deduplicate on the client.

---

Sync from ERP to Portal

These endpoints let SAP or any ERP push data into the portal (ERP → portal). Use the same Authorization: Bearer {token} (e.g. a dedicated integration user). Upserts are idempotent: use erpId or business keys so the same payload does not create duplicates.

| Entity | Method | Endpoint |
|-----------|--------|----------|
| Orders | POST | /api/purchase-order/sync-from-erp |
| Shipments | POST | /api/shipment/sync-from-erp |
| Items | POST | /api/items/sync-from-erp |

Request body

• Orders: { "orders": [ { "erpId": "SAP-PO-123", "purchaseOrderNumber": "PO-001", "buyerCompany": "", "supplierCompany": "", "supplierId": "", "createdBy": "", ... } ] }

Match: by erpId, or by purchaseOrderNumber + buyerCompany. New orders require purchaseOrderNumber, supplierCompany, supplierId, and createdBy (or the authenticated user is used as createdBy).

• Shipments: { "shipments": [ { "erpId": "SAP-SHP-456", "shipmentNumber": "SHP-001", "purchaseOrder": "", "lineIds": [ "" ], ... } ] }

Match: by erpId, or by shipmentNumber + purchaseOrder. New shipments require purchaseOrder and lineIds.

• Items: { "items": [ { "itemNumber": "MAT-001", "name": "...", "type": "Material", ... } ] }

Match: by itemNumber (unique). New items require itemNumber.

Response

{
  "success": true,
  "created": [ { "_id": "...", ... } ],
  "updated": [ { "_id": "...", ... } ],
  "errors": [ { "payload": { ... }, "message": "..." } ]
}

• created / updated: Documents created or updated in the portal.


• errors: Per-item validation or DB errors (invalid payload, missing required fields, etc.).

---

ERP Integration Checklist

Use this checklist before sending Purchase Orders (and related data) from SAP/any ERP to ONESCP to avoid common 400 Bad Request validation errors.

ID mapping (SAP vendor code → ONESCP IDs)

• Do not send SAP vendor codes (e.g. "1001") in fields that expect ONESCP IDs.


• supplierCompany must be the ONESCP Company _id (MongoDB ObjectId).


• supplierId must be the ONESCP User _id (MongoDB ObjectId) for the supplier contact user.


• Maintain a mapping table in the integration layer (or agree on a master-data sync) from:

- SAP vendorNumber → ONESCP supplierCompany _id (+ optionally ONESCP supplierId).

Purchase Order required fields (minimum)

• purchaseOrderNumber (string)


• supplierCompany (ONESCP Company _id)


• supplierId (ONESCP User _id)


• supplierAccountNumber (string)


• destination (object): delivery address (at minimum country/city/postal code/address lines)


• contactEmail (string): buyer contact email (must not be empty)


• lines (array): order lines (note: use lines, not orderLines)

Common payload shape reminders

• Use lines, not orderLines.


• Do not send empty strings for required string fields (e.g. contactEmail: "").


• If you are using Sync from ERP to Portal endpoints, include erpId where possible for idempotent upserts.

---

Error Handling

HTTP Status Codes

• 200 OK - Request successful


• 201 Created - Resource created successfully


• 400 Bad Request - Invalid request parameters


• 401 Unauthorized - Authentication required or invalid token


• 403 Forbidden - Insufficient permissions


• 404 Not Found - Resource not found


• 409 Conflict - Resource conflict (e.g., duplicate entry)


• 422 Unprocessable Entity - Validation error


• 500 Internal Server Error - Server error

Error Response Format

{
  "success": false,
  "message": "Error description",
  "error": {
    "code": "ERROR_CODE",
    "details": "Detailed error information",
    "field": "field_name" // If validation error
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

• AUTH_REQUIRED - Authentication token required


• AUTH_INVALID - Invalid or expired token


• VALIDATION_ERROR - Request validation failed


• NOT_FOUND - Resource not found


• DUPLICATE_ENTRY - Duplicate resource


• PERMISSION_DENIED - Insufficient permissions


• SERVER_ERROR - Internal server error

---

Rate Limiting

Rate limiting is implemented to ensure fair usage and system stability.

Current Limits

• Authentication Endpoints: 10 requests per minute per IP


• General API Endpoints: 100 requests per minute per token


• Bulk Operations: 10 requests per minute per token

Rate Limit Headers

Response headers include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

Rate Limit Exceeded

When rate limit is exceeded, the API returns:

Status Code: 429 Too Many Requests

Response:


{
  "success": false,
  "message": "Rate limit exceeded",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "retryAfter": 60
  }
}

---

Best Practices

1. Authentication

• Store tokens securely


• Implement token refresh before expiration


• Never expose tokens in client-side code or logs

2. Error Handling

• Always check the success field in responses


• Implement retry logic for transient errors (5xx status codes)


• Handle rate limiting gracefully with exponential backoff

3. Pagination

• Always use pagination for list endpoints


• Default page size: 10-50 items


• Maximum page size: 100 items

4. Data Synchronization

• Use timestamps (createdAt, updatedAt) for change tracking


• Implement idempotency for create/update operations


• Store last sync timestamp for efficient incremental syncs

5. Webhooks (When Available)

• Verify webhook signatures


• Implement idempotent webhook handlers


• Return 200 OK quickly and process asynchronously


• Implement retry logic for failed webhook deliveries

6. Performance

• Use filtering and search parameters to reduce data transfer


• Cache reference data (suppliers, carriers) locally


• Implement request batching where possible

---

Support

API Documentation

• Full documentation: https://docs.onescp.com


• Quick start guide: https://docs.onescp.com/quick-start


• Swagger UI (interactive): Available at your API server’s /api-docs endpoint (e.g. https://api.onescp.com/api-docs).

*For deployment: point the domain docs.onescp.com at the docs server and map / to the full doc and /quick-start to the quick start page (e.g. proxy to backend /docs and /docs/quick-start).*

Contact

• Email: support@onescp.com


• API Support: For integration issues and questions

Changelog

Version 1.0.0 (January 2025)


• Initial API release


• Core CRUD operations for Orders, Shipments, Items, Tasks


• Authentication and authorization


• Document management


• Filtering, search, and pagination


• Sync/Delta APIs for incremental sync (orders, shipments, items, tasks)


• Webhooks for real-time notifications (subscribe, HMAC-signed payloads, delivery logging)

Upcoming


• API key authentication for ERP systems


• Bulk update operations

---

Appendix

Date Formats

All dates are in ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ

Example: 2024-01-15T10:30:00Z

Timezone

All timestamps are in UTC (Coordinated Universal Time).

Field Naming

• API uses camelCase for field names


• Database IDs use MongoDB ObjectId format


• Enum values use lowercase (e.g., p1, p2, p3)

Pagination

Pagination is 1-indexed (first page is page 1).

---

Infrastructure & Requirements

This section describes deployment options and technical requirements for running ONESCP on a dedicated secured server (physical or VPS) or in the cloud. Use it when a customer wants to self-host or when you need hardware and license guidance.

Supported deployment options

| Option | Description |
|--------|--------------|
| Option 1 | Physical server or VPS — Windows Server (on-premises or hosted VPS) |
| Option 2 | Physical server or VPS — Linux (recommended for on-prem / VPS) |
| Option 3 | Amazon Web Services (AWS) — cloud-hosted (EC2 + managed or self-managed database) |

---

Option 1 — Windows Server (on-prem or VPS)

• OS: Windows Server 2019 or 2022 (customer-provided license).


• Application stack: Node.js LTS (e.g. v20), Nginx or IIS as reverse proxy, MongoDB.


• Database: MongoDB Community Edition (self-managed on same server or separate DB server); no additional license cost beyond OS.


• Minimum hardware (single-company / pilot):

- 4 vCPUs
- 8–16 GB RAM
- 200–300 GB SSD storage

---

Option 2 — Linux (on-prem or VPS, recommended)

• OS: Ubuntu Server 22.04 LTS or similar (no OS license fee).


• Application stack: Node.js LTS, Nginx, MongoDB, Redis (for queues/caching).


• Database: MongoDB Community Edition (self-managed).


• Minimum hardware (single-company / pilot):

- 4 vCPUs
- 8–16 GB RAM
- 200–300 GB SSD storage

---

Option 3 — Amazon Web Services (AWS)

• Compute: EC2 instance for the application (e.g. t3.medium or t3.large: 2–4 vCPUs, 8–16 GB RAM, 200–300 GB gp3 SSD).


• Database: Self-managed MongoDB on EC2, or managed MongoDB (e.g. MongoDB Atlas) or Amazon DocumentDB, depending on preference.


• Optional: Amazon ElastiCache (Redis) for queues and caching; S3 for file/document storage.

---

Software stack summary

| Component | Purpose |
|----------|---------|
| Node.js (LTS, e.g. v20) | Application runtime |
| Nginx or IIS (Windows) | Reverse proxy / HTTPS |
| MongoDB | Primary database |
| Redis | Email queue and caching (recommended on Linux; optional on Windows) |

---

License and responsibility summary

• Windows Server: License is the customer’s responsibility when using Option 1.


• MongoDB Community: No license fee; customer or partner manages installation and updates.


• Managed services (e.g. MongoDB Atlas, AWS DocumentDB, ElastiCache): Billed by the provider; customer or partner is responsible for subscription and configuration.

---

Sizing guidance (reference)

| Environment | vCPUs | RAM | Storage | Use case |
|-------------|-------|-----|---------|----------|
| Small / pilot | 4 | 8–16 GB | 200–300 GB SSD | Single company, low volume |
| Medium | 4–8 | 16–32 GB | 300–500 GB SSD | Multiple companies or higher volume |
| Large | 8+ | 32 GB+ | 500 GB+ SSD / scaled DB | High volume, separate DB server recommended |

For production, backups, monitoring, and security hardening (firewall, SSL, OS updates) are the responsibility of the party operating the server (customer or partner).

---

Document Version: 1.0.0
Last Updated: March 19, 2025
For: Third-Party ERP Integration