API Quick Start Guide - ERP Integration

Version: 1.0.0
For: Third-Party ERP Systems

---

Quick Overview

This guide will help you get started with the Supply Chain Portal API in 5 minutes.

Base URL

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

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

---

Step 1: Authentication

Get Your Access Token

bash

POST /api/auth/login

Content-Type: application/json



{

  "email": "your_email@example.com",

  "password": "your_password"

}

Response:

json

{

  "success": true,

  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",

  "user": { ... }

}

Use the Token

Include the token in all API requests:



Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

---

Step 2: Core Operations

Create an Order

bash

POST /api/purchase-order/create

Authorization: Bearer {token}

Content-Type: application/json



{

  "supplier": {

    "name": "ABC Electronics",

    "email": "contact@abcelectronics.com"

  },

  "orderLines": [

    {

      "position": "10",

      "item": {

        "number": "ITEM-001",

        "name": "Laptop Computer",

        "unitPrice": 999.99

      },

      "quantity": 10,

      "prices": {

        "netPrice": 9999.90

      }

    }

  ],

  "priority": "p1"

}

Get All Orders

bash

GET /api/purchase-order/allOrders?page=1&limit=10&status=approved

Authorization: Bearer {token}

Update Order Status

bash

PUT /api/purchase-order/{orderId}/status

Authorization: Bearer {token}

Content-Type: application/json



{

  "status": "approved"

}

---

Step 3: Shipments

Create Shipment

bash

POST /api/shipment/purchase-orders/{orderId}/lines/{lineId}

Authorization: Bearer {token}

Content-Type: application/json



{

  "departureFrom": "Shanghai Port",

  "finalDestination": "Los Angeles Port",

  "type": "Ocean",

  "carrier": "Maersk Line",

  "scheduledDeliveryDate": "2024-02-15"

}

Get Shipments

bash

GET /api/shipment?status=in_transit&page=1&limit=10

Authorization: Bearer {token}

---

Step 4: Items

Get All Items

bash

GET /api/items?page=1&limit=10&search=laptop

Authorization: Bearer {token}

Create Item

bash

POST /api/items

Authorization: Bearer {token}

Content-Type: application/json



{

  "itemNumber": "ITEM-002",

  "name": "Desktop Computer",

  "category": "Electronics",

  "type": "Material"

}

---

Step 5: Tasks

Get All Tasks

bash

GET /api/task/allTasks?status=Open&priority=p1

Authorization: Bearer {token}

Accept/Reject Task

bash

PUT /api/task/{taskId}/decision

Authorization: Bearer {token}

Content-Type: application/json



{

  "decision": "accept",

  "comments": "Approved"

}

---

Common Patterns

Pagination

All list endpoints support pagination:



GET /api/purchase-order/allOrders?page=1&limit=20

Filtering

Filter by status, date, etc.:



GET /api/purchase-order/allOrders?status=approved&dateFrom=2024-01-01

Error Handling

Always check the success field:

json

{

  "success": false,

  "message": "Error description"

}

---

Status Values Reference

Order Status

draft - Order is in draft

pending - Pending approval

approved - Approved

rejected - Rejected

completed - Completed

Shipment Status

pending - Pending

in_transit - In transit

delivered - Delivered

cancelled - Cancelled

Task Status

Open - Open

In Progress - In progress

Completed - Completed

Rejected - Rejected

Priority Levels

p1 - High priority

p2 - Medium priority

p3 - Low priority

---

Next Steps

1. Read Full Documentation: https://docs.onescp.com
2. Quick Start (this guide): https://docs.onescp.com/quick-start
3. Test with Swagger UI: Visit your API server’s /api-docs endpoint for interactive testing
4. Contact Support: Email support@onescp.com for integration help

---

Sync/Delta APIs (available)

Get only changes since a timestamp: GET /api/purchase-order/sync?since=2025-01-01T00:00:00Z&page=1&limit=100 (same pattern for /api/shipment/sync, /api/items/sync, /api/task/sync). See full docs for response format and usage.

Webhooks (available)

Subscribe to events: POST /api/webhooks/subscriptions with

{ "url": "https://your-server.com/webhook", "events": ["order.created", "order.updated"], "secret": "your-secret-min-16-chars" }

. Verify requests using the X-Webhook-Signature header (HMAC-SHA256 of body with your secret). See full docs for all events and payload format.

Coming Soon

API Keys: Alternative authentication for ERP systems

---

Documentation: https://docs.onescp.com
Need Help? Contact support@supplychain.com