API Documentation: Invoice, Stock & Stock Adjustment

Guide:

Base URL for these resources: https://shopdesk.xstak.com/api/<resource>

JWT token:

First, open the ShopDesk Web App, open the Developer Tools, and navigate to Application → Local Storage. Copy the value of xstak_studio_token.

Include this token in your API request headers as:

Authorization: Bearer <token>

1. Invoice — `/api/invoice`

1.1 GET `/api/invoice`

Purpose: List invoices for the authenticated user’s brand, with optional filters and pagination. Used to see which invoices have not yet been synced to SAP and to drive sync workflows.

Query parameters:

What to expect:

• Success: {status: 200, message, data } — data is an array of invoice objects (invoice_number, dates, totals, status, store, products, customer_info, etc.).
• 400: Validation failed (error object with field messages).
• 401: Missing or invalid token.
• 403: brandId or storeId not allowed for this user.
• 429: Rate limit exceeded (generalLimiter).
• 500: Server error.

Example cURL:

curl --location 'https://shopdesk.xstak.com/api/invoice?page=1&limit=100' \
--header 'Authorization: Bearer <token>' \
--header 'X-API-Key: {{token}}'

1.2 PUT `/api/invoice/sync`

Purpose: Sync selected invoices to SAP. You send a list of invoice IDs; the API fetches those invoices (with products and store prices), maps them to a SAP-compatible format, and returns that data. Downstream SAP sync is intended to use this payload.

Request body:

json

{
"ids":[
2727,
2729,
2731
]
}

What to expect:

• Success: { message, data } where data is the list of invoices in SAP-compatible format (with products and store prices).
• Error: Non-2xx or message: "NOT OK" on failure.

2. Stock — `/api/stock`

Stock routes are mounted at /api/stock.

2.1 PUT `/api/stock/return`

Purpose: Sync selected stock returns to SAP. You send stock return IDs; the API fetches those records (with products) and returns them for downstream SAP sync.

Request body:

json

{
"ids": [
2727,
2731
]
}

What to expect:

• Success: { message: "ok", data } — data is the list of stock returns (with products).
• Error: message: "NOT OK" or non-2xx on failure.

2.2 GET `/api/stock/return`

Purpose: Get out-of-sync stock returns for a store, paginated. Used to see which stock returns are pending SAP sync.

Headers:

Query parameters:

What to expect:

• Success: { status: 200, message, stock_returns: { page: { pageNumber, numberOfElements, totalElements, totalPages }, data } } — data is array of stock returns (id, show_id, name, supplier, date, products with sku, quantity, price).
• 500: Server error.

2.3 PUT `/api/stock/adjustment`

Purpose: Sync selected stock adjustments to SAP. You send adjustment IDs; the API fetches those records (with products) and returns them for downstream SAP sync.

Request body:

json

{
"ids": [
2727,
2731
]
}

What to expect:

• Success: { message: "ok", data } — data is the list of stock adjustments with products.
• Error: message: "NOT OK" or non-2xx on failure.

2.4 GET `/api/stock/adjustment`

Purpose: Get out-of-sync stock adjustments for a store, paginated. Used to see which adjustments are pending SAP sync.

Headers:

Query parameters:

What to expect:

• Success: { status: 200, message, stock_adjustment: { page: { pageNumber, numberOfElements, totalElements, totalPages }, data } } — data is array of adjustments (date, message, unique, created_at, products with sku, name, description, quantity, type).
• 500: Server error.

2.5 POST `/api/stock/adjustment`

Purpose: Used by SAP (or an integration) to create stock adjustments. Accepts an array of adjustments; each has a type (ADD, SUBTRACT, REPLACE), message, and products (sku + adjustment_quantity). Creates stock adjustment records and updates product store quantities accordingly.

[
{
"call_source": "SAP",
"message": "Physical count correction",
"type": "ADD",
"products": [
{
"sku": "ABC-123",
"adjustment_quantity": 10
},
{
"sku": "XYZ-456",
"adjustment_quantity": -2
}
]
}
]

What to expect:

• Success: { message: "OK" } (HTTP 200).
• Error: { message: "NOT OK" } or 4xx/5xx; validation errors if body does not match schema.

2.6 POST `/api/stock/return`

Purpose: Create stock return(s) for the authenticated user’s brand/store. Used to record returns (e.g. from supplier) with name, date, and line items (sku, quantity, price). Increases or records stock return data and can drive stock updates.

Headers:

Request body (array):

json

[
{
"name": "Stock return 1",
"date": "2023-03-31T04:53:22.000Z",
"products": [
{
"sku": "ABC-1234",
"quantity": 2,
"price": 800
},
{
"sku": "AUC-1234",
"quantity": 4,
"price": 600
}
]
}
]

What to expect:

• Success: { status: true, message: "Return Created Successfully" } (200).
• 400: Validation failed — error and optionally expectedPayload / expectedHeaders.
• 401: Missing or invalid token.
• 403: Brand/store not allowed for this user.
• 404: User not found.
• 500: Server error.