Core API Reference

The Core API provides endpoints for managing orders, channels, places, storage locations, and other entities in the Unified Order Service.

API Endpoints Overview

System Endpoints

Endpoint	Method	Description
`/v1/health`	GET	Health check endpoint
`/v1/version`	GET	Get current API version information

Orders Endpoints

Endpoint	Method	Description
`/v1/orders`	POST	Create a new order
`/v1/orders`	GET	List orders with pagination and filtering
`/v1/orders/{orderId}`	GET	Get order details by ID
`/v1/orders/{orderId}`	PUT	Update an existing order
`/v1/orders/{orderId}/status`	PATCH	Update order status
`/v1/orders/{orderId}/items`	GET	Get items in an order
`/v1/orders/{orderId}/history`	GET	Get complete version history with metadata
`/v1/orders/{orderId}/versions/{version}`	GET	Get specific order version details
`/v1/orders/{orderId}/status-history`	GET	Get chronological history of status changes

Channels Endpoints

Endpoint	Method	Description
`/v1/channels`	POST	Create a new channel
`/v1/channels`	GET	List channels with pagination
`/v1/channels/{channelId}`	GET	Get channel details by ID
`/v1/channels/{channelId}`	PUT	Update channel configuration
`/v1/channels/{channelId}/health-check`	POST	Trigger a health check for a channel
`/v1/channels/{channelId}/order-schema`	GET	Get JSON schema for creating orders in this channel
`/v1/channels/{channelId}/inventory`	GET	Get inventory for a channel
`/v1/channels/{channelId}/inventory/sync`	POST	Trigger inventory sync for a channel
`/v1/channels/base-schema`	GET	Get base order schema
`/v1/channels/types`	GET	List all available channel types
`/v1/channels/types`	POST	Add a new channel type

Places Endpoints

Endpoint	Method	Description
`/v1/places`	POST	Create a new place
`/v1/places`	GET	List places with pagination
`/v1/places/{placeId}`	GET	Get place details by ID
`/v1/places/{placeId}`	PUT	Update an existing place
`/v1/places/{placeId}`	PATCH	Partially update a place
`/v1/places/{placeId}/channels/{channelId}`	POST	Add a place to a channel
`/v1/places/{placeId}/channels/{channelId}`	DELETE	Remove a place from a channel
`/v1/places/{placeId}/inventory`	GET	Get inventory for a place

Storage Locations Endpoints

Endpoint	Method	Description
`/v1/places/{placeId}/storage-location`	GET	List all storage locations for a place
`/v1/places/{placeId}/storage-location`	POST	Create a new storage location for a place
`/v1/places/{placeId}/storage-location/{id}`	GET	Get storage location details by ID
`/v1/places/{placeId}/storage-location/{id}`	PATCH	Update an existing storage location
`/v1/places/{placeId}/storage-location/{id}`	DELETE	Delete a storage location
`/v1/places/{placeId}/storage-location/{id}/temperature`	GET	Get current temperature for a storage location
`/v1/places/{placeId}/storage-location/{id}/temperature/history`	GET	Get temperature history for a storage location

Subscriptions Endpoints

Endpoint	Method	Description
`/dts/places/{placeId}/subscriptions`	PUT	Store or update device subscription for push notifications
`/dts/places/{placeId}/subscriptions`	DELETE	Remove device subscription

FCM Notifications

FCM notifications are automatically sent by the system when order events occur. See the FCM Notifications API Reference for payload formats and event specifications.

Payload Structure: All FCM notifications use a default.data wrapper structure for compatibility with mobile apps.

Event Types:

event_order_created - Order creation notifications
event_order_status_changed - Order status change notifications
event_timeslot_started - Timeslot monitoring notifications
event_unpicked_orders_reminder - Reminder notifications for unpicked orders

Webhooks Endpoints

Endpoint	Method	Description
`/v1/channels/{channelId}/webhook`	PUT	Update webhook configuration for a channel
`/v1/channels/{channelId}/webhook`	GET	Get webhook configuration for a channel
`/v1/channels/{channelId}/webhook/test`	POST	Test webhook configuration for a channel
`/v1/channels/{channelId}/webhook/events`	GET	List available webhook events for a channel
`/v1/webhooks/logs`	GET	Get recent webhook delivery logs

API Keys Endpoints

Endpoint	Method	Description
`/v1/api-keys`	POST	Create a new API key
`/v1/api-keys`	GET	List API keys
`/v1/api-keys/{keyId}`	GET	Get API key details
`/v1/api-keys/{keyId}`	PUT	Update API key configuration
`/v1/api-keys/{keyId}`	DELETE	Deactivate an API key
`/v1/api-keys/{keyId}/permissions`	GET	Get permissions for an API key
`/v1/api-keys/{keyId}/permissions`	PUT	Update permissions for an API key

Authentication

All endpoints require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

For more details on authentication, see the Authentication Guide.

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request. Error responses include a message field with more details about the error.

Common Error Codes

400 Bad Request: The request was malformed or missing required parameters
401 Unauthorized: Authentication failed or is missing
403 Forbidden: The API key doesn't have the required permissions
404 Not Found: The requested resource doesn't exist
409 Conflict: Resource conflict (e.g., duplicate name)
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: An unexpected error occurred on the server