メインコンテンツまでスキップ
バージョン: 🚧 Canary

🛒 Order Service

Testing Status

The Order Service provides a complete REST API for managing order entities with CRUD operations. It's built using the Nodeblocks functional composition approach and integrates seamlessly with MongoDB.

🚀 Quickstart​

import express from 'express';
import {middlewares, services, drivers} from '@nodeblocks/backend-sdk';

const {nodeBlocksErrorMiddleware} = middlewares;
const {orderService} = services;
const {withMongo} = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

express()
  .use(
    orderService(
      {
        ...(await connectToDatabase('orders')),
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('organizations')), // Required for org-scoped order lists
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        authMode: 'bearer', // or 'cookie'
        identity: {
          typeIds: {
            admin: '100',
            guest: '000',
            regular: '001',
          },
        },
        organization: {
          roles: {
            admin: 'admin',
            member: 'member',
            owner: 'owner',
          },
        },
      },
    ),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 Endpoint Summary​

Order Operations​

MethodPathDescriptionAuth Required
POST/ordersCreate a new order✅ Required
GET/orders/:orderIdRetrieve an order by ID✅ Required
GET/ordersList/filter orders (non-admin must pass own identityId)✅ Required
GET/orders/organizations/:organizationIdList orders for organization✅ Required
PATCH/orders/:orderIdUpdate an order✅ Required
DELETE/orders/:orderIdDelete an order✅ Required

🗄️ Entity Schema​

The order entity combines base fields (auto-generated) with complex order-specific data including items array and pricing:

{
  "items": [
    {
      "productId": "string (uuid)",
      "quantity": "number",
      "price": "number"
    }
  ],
  "total": "number",
  "subtotal": "number",
  "tax": "number",
  "currency": "string",
  "status": "string",
  "identityId": "string (uuid)",
  "organizationId": "string (uuid)",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

Field Details​

FieldTypeAuto-GeneratedRequiredDescription
itemsarray❌✅Array of order items with product details
totalnumber❌✅Total order amount (minimum 0)
subtotalnumber❌❌Subtotal before tax (minimum 0)
taxnumber❌❌Tax amount (minimum 0)
currencystring❌❌Currency code (e.g., "USD", "EUR")
statusstring❌❌Order status (e.g., "pending", "completed")
identityIdstring (uuid)❌✅Identity who placed the order
organizationIdstring (uuid)❌❌Organization associated with the order
createdAtdatetime✅✅Creation timestamp
idstring✅✅Unique identifier (UUID)
updatedAtdatetime✅✅Last modification timestamp

Items Array Schema​

Each item in the items array must contain:

FieldTypeRequiredValidationDescription
productIdstring (uuid)✅UUID formatProduct identifier
quantitynumber✅Minimum 1Quantity ordered
pricenumber✅Minimum 0Price per unit

📝 Note: The schema enforces additionalProperties: false, meaning only defined fields are allowed. Auto-generated fields are set by the service and should not be included in create/update requests.

🔐 Authentication Headers​

For all endpoints, include the following authentication details:

Authorization: Bearer <access_token>   // bearer mode (default)
x-nb-fingerprint: <device_fingerprint>

If the service is configured with authMode: 'cookie', the access token is read from the accessToken cookie instead of the Authorization header.

⚠️ Important: The x-nb-fingerprint header is required for all authenticated requests if fingerprint was specified during authorization. Without it, requests will return 401 Unauthorized.

🔧 API Endpoints​

1. Create Order​

Creates a new order with the provided information including items array and pricing details.

Request:

  • Method: POST
  • Path: /orders
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token> in bearer mode, or the accessToken cookie in cookie mode
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearer token required in bearer mode, or cookie-based auth when authMode: 'cookie'

Request Body:

FieldTypeRequiredDescription
itemsarray✅Array of order items (see Items Schema)
totalnumber✅Total order amount
identityIdstring (uuid)✅Identity who placed the order
subtotalnumber❌Subtotal before tax
taxnumber❌Tax amount
currencystring❌Currency code
statusstring❌Order status
organizationIdstring (uuid)❌Organization associated with order

Response Body:

FieldTypeDescription
itemsarrayArray of order items with product details
items[].productIdstringProduct identifier
items[].quantitynumberQuantity ordered
items[].pricenumberPrice per unit
totalnumberTotal order amount
subtotalnumberSubtotal before tax
taxnumberTax amount
currencystringCurrency code
statusstringOrder status
identityIdstringIdentity who placed the order
organizationIdstringOrganization associated with order
createdAtstringCreation timestamp
idstringUnique order identifier
updatedAtstringLast update timestamp

Validation:

  • Schema Validation: Enforced automatically (items, total, identityId required)
  • Route Validators:
    • Require authenticated request (bearer token in bearer mode, or cookie-based auth when authMode: 'cookie')
    • Require admin role or self (order owner)

Error Responses:

When the request body is missing:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Request body is required"
  }
}

When the insert operation does not return an inserted ID:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Failed to create order"
  }
}

When an unexpected server error occurs during creation:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Unknown error creating order"
  }
}

Authorization Note: When creating an order, non-admin callers must set identityId in the request body to match the identityId on their access token. Platform admin users may create orders for any identityId (validator: some(checkIdentityType(['admin']), isSelf(...))).

Example Request:

curl -X POST http://localhost:8089/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "identityId": "30000000-0000-4000-a000-000000000001",
    "items": [
      {
        "productId": "10000000-0000-4000-a000-000000000001",
        "quantity": 2,
        "price": 50
      },
      {
        "productId": "10000000-0000-4000-a000-000000000002",
        "quantity": 1,
        "price": 25
      }
    ],
    "subtotal": 125,
    "tax": 12.5,
    "total": 137.5,
    "currency": "USD",
    "status": "pending",
    "organizationId": "20000000-0000-4000-a000-000000000001"
  }'

Success Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "currency": "USD",
  "items": [
    {
      "productId": "10000000-0000-4000-a000-000000000001",
      "quantity": 2,
      "price": 50
    },
    {
      "productId": "10000000-0000-4000-a000-000000000002",
      "quantity": 1,
      "price": 25
    }
  ],
  "organizationId": "20000000-0000-4000-a000-000000000001",
  "identityId": "30000000-0000-4000-a000-000000000001",
  "subtotal": 125,
  "tax": 12.5,
  "total": 137.5,
  "status": "pending",
  "createdAt": "2025-07-04T01:59:20.084Z",
  "id": "10283907-d41a-4647-a235-18ec63f3369a",
  "updatedAt": "2025-07-04T01:59:20.084Z"
}

Error Responses:

When request body is missing required fields:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'identityId'",
      "request body must have required property 'items'",
      "request body must have required property 'total'"
    ]
  }
}

When authentication fails:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "token could not be verified"
  }
}

When authorization fails:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Identity ID does not match"
  }
}

2. Get Order by ID​

Retrieves a specific order by its unique ID.

Request:

  • Method: GET
  • Path: /orders/:orderId
  • Headers:
    • Authorization: Bearer <token> in bearer mode, or the accessToken cookie in cookie mode
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearer token required in bearer mode, or cookie-based auth when authMode: 'cookie'

URL Parameters:

ParameterTypeRequiredDescription
orderIdstring✅Unique order identifier

Response Body:

FieldTypeDescription
itemsarrayArray of order items with product details
items[].productIdstringProduct identifier
items[].quantitynumberQuantity ordered
items[].pricenumberPrice per unit
totalnumberTotal order amount
subtotalnumberSubtotal before tax
taxnumberTax amount
currencystringCurrency code
statusstringOrder status
identityIdstringIdentity who placed the order
organizationIdstringOrganization associated with order
createdAtstringCreation timestamp
idstringUnique order identifier
updatedAtstringLast update timestamp

Validation:

  • Schema Validation: Enforced automatically (path/query parameters as defined by the route schema)
  • Route Validators:
    • Require authenticated request (bearer token in bearer mode, or cookie-based auth when authMode: 'cookie')
    • Require admin role or order ownership

Example Request:

curl http://localhost:8089/orders/10283907-d41a-4647-a235-18ec63f3369a \
  -H "Authorization: Bearer <access_token>"

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "currency": "USD",
  "items": [
    {
      "productId": "10000000-0000-4000-a000-000000000001",
      "quantity": 2,
      "price": 50
    },
    {
      "productId": "10000000-0000-4000-a000-000000000002",
      "quantity": 1,
      "price": 25
    }
  ],
  "organizationId": "20000000-0000-4000-a000-000000000001",
  "identityId": "30000000-0000-4000-a000-000000000001",
  "subtotal": 125,
  "tax": 12.5,
  "total": 137.5,
  "status": "completed",
  "createdAt": "2025-07-04T01:59:20.084Z",
  "id": "10283907-d41a-4647-a235-18ec63f3369a",
  "updatedAt": "2025-07-07T08:11:16.176Z"
}

Error Responses:

When the order ID is missing:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Order ID is required"
  }
}

When an unexpected server error occurs during retrieval:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to get order"
  }
}

When no order exists with the provided ID:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Order not found"
  }
}

3. List Orders​

Retrieves a list of orders with optional filtering and pagination.

Request:

  • Method: GET
  • Path: /orders
  • Headers:
    • Authorization: Bearer <token> in bearer mode, or the accessToken cookie in cookie mode
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearer token required in bearer mode, or cookie-based auth when authMode: 'cookie'

Query Parameters:

ParameterTypeRequiredDescription
currencystring❌Filter by currency
organizationIdstring❌Filter by organization
statusstring❌Filter by status
subtotalnumber❌Filter by subtotal amount (minimum 0)
taxnumber❌Filter by tax amount (minimum 0)
totalnumber❌Filter by total amount (minimum 0)
identityIdstring❌*Filter by identityId (*required for non-admin; must match the token subject)
pagenumber❌Page number for pagination (1-1000)
limitnumber❌Number of items per page (1-50)

Response Body: Paginated response with orders array and metadata.

Response Structure:

{
  "data": [
    {
      "id": "string",
      "items": [
        {
          "productId": "string",
          "quantity": number,
          "price": number
        }
      ],
      "total": number,
      "subtotal": number,
      "tax": number,
      "currency": "string",
      "status": "string",
      "identityId": "string",
      "organizationId": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

Validation:

  • Schema Validation: Enforced automatically (path/query parameters as defined by the route schema)
  • Route Validators:
    • Require authenticated request (bearer token in bearer mode, or cookie-based auth when authMode: 'cookie')
    • Require admin role or self via query identityId (isSelf on requestQuery.identityId)

Non-admin callers must include ?identityId=<their-identity-id>. Listing without identityId is admin-only.

Example Requests:

List all orders (admin):

curl http://localhost:8089/orders \
  -H "Authorization: Bearer <admin_access_token>"

List own orders (non-admin):

curl "http://localhost:8089/orders?identityId=30000000-0000-4000-a000-000000000001" \
  -H "Authorization: Bearer <access_token>"

Filter by status:

curl "http://localhost:8089/orders?status=completed&identityId=30000000-0000-4000-a000-000000000001" \
  -H "Authorization: Bearer <access_token>"

Filter by currency:

curl "http://localhost:8089/orders?currency=USD&identityId=30000000-0000-4000-a000-000000000001" \
  -H "Authorization: Bearer <access_token>"

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "currency": "USD",
      "items": [
        {
          "productId": "10000000-0000-4000-a000-000000000001",
          "quantity": 2,
          "price": 50
        },
        {
          "productId": "10000000-0000-4000-a000-000000000002",
          "quantity": 1,
          "price": 25
        }
      ],
      "organizationId": "20000000-0000-4000-a000-000000000001",
      "identityId": "30000000-0000-4000-a000-000000000001",
      "subtotal": 125,
      "tax": 12.5,
      "total": 137.5,
      "status": "completed",
      "createdAt": "2025-07-04T01:59:20.084Z",
      "id": "10283907-d41a-4647-a235-18ec63f3369a",
      "updatedAt": "2025-07-07T08:11:16.176Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

Example Request with Pagination:

curl "http://localhost:8089/orders?page=1&limit=10" \
  -H "Authorization: Bearer <access_token>"

4. Update Order​

Updates an existing order with partial data.

Request:

  • Method: PATCH
  • Path: /orders/:orderId
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token> in bearer mode, or the accessToken cookie in cookie mode
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearer token required in bearer mode, or cookie-based auth when authMode: 'cookie'

URL Parameters:

ParameterTypeRequiredDescription
orderIdstring✅Unique order identifier

Request Body (all fields optional):

FieldTypeRequiredDescription
itemsarray❌Array of order items
totalnumber❌Total order amount
subtotalnumber❌Subtotal before tax
taxnumber❌Tax amount
currencystring❌Currency code
statusstring❌Order status
identityIdstring (uuid)❌Identity who placed the order
organizationIdstring (uuid)❌Organization associated with order

Response Body:

FieldTypeDescription
itemsarrayArray of order items with product details
items[].productIdstringProduct identifier
items[].quantitynumberQuantity ordered
items[].pricenumberPrice per unit
totalnumberUpdated total order amount
subtotalnumberUpdated subtotal before tax
taxnumberUpdated tax amount
currencystringUpdated currency code
statusstringUpdated order status
identityIdstringIdentity who placed the order
organizationIdstringUpdated organization associated with order
createdAtstringCreation timestamp
idstringUnique order identifier
updatedAtstringLast update timestamp

Validation:

  • Schema Validation: Enforced automatically (partial updates, all fields optional)
  • Route Validators:
    • Require authenticated request (bearer token in bearer mode, or cookie-based auth when authMode: 'cookie')
    • Require admin role or order ownership

Example Request:

curl -X PATCH http://localhost:8089/orders/10283907-d41a-4647-a235-18ec63f3369a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"status": "completed"}'

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "currency": "USD",
  "items": [
    {
      "productId": "10000000-0000-4000-a000-000000000001",
      "quantity": 2,
      "price": 50
    },
    {
      "productId": "10000000-0000-4000-a000-000000000002",
      "quantity": 1,
      "price": 25
    }
  ],
  "organizationId": "20000000-0000-4000-a000-000000000001",
  "identityId": "30000000-0000-4000-a000-000000000001",
  "subtotal": 125,
  "tax": 12.5,
  "total": 137.5,
  "status": "completed",
  "createdAt": "2025-07-04T01:59:20.084Z",
  "id": "10283907-d41a-4647-a235-18ec63f3369a",
  "updatedAt": "2025-07-07T08:11:16.176Z"
}

Error Responses:

When the order ID is missing:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Order ID is required"
  }
}

When the request body is missing:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Request body is required"
  }
}

When the update operation does not modify any data:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Failed to update order"
  }
}

When an unexpected server error occurs during update:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to update order"
  }
}

When no order exists with the provided ID:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Order not found"
  }
}

5. Delete Order​

Permanently deletes an order from the system.

Request:

  • Method: DELETE
  • Path: /orders/:orderId
  • Headers:
    • Authorization: Bearer <token> in bearer mode, or the accessToken cookie in cookie mode
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearer token required in bearer mode, or cookie-based auth when authMode: 'cookie'

URL Parameters:

ParameterTypeRequiredDescription
orderIdstring✅Unique order identifier

Response Body:

FieldTypeDescription
No response body-Delete endpoint returns no response body on success

Validation:

  • Route Validators:
    • Require authenticated request (bearer token in bearer mode, or cookie-based auth when authMode: 'cookie')
    • Require admin role or order ownership

Example Request:

curl -X DELETE http://localhost:8089/orders/10283907-d41a-4647-a235-18ec63f3369a \
  -H "Authorization: Bearer <access_token>"

Success Response:

HTTP/1.1 204 No Content

Error Responses:

When the order ID is missing:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Order ID is required"
  }
}

When an unexpected server error occurs during deletion:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to delete order"
  }
}

When no order exists with the provided ID:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Order not found"
  }
}

6. List Orders by Organization ID​

Retrieves a paginated list of orders scoped to a specific organization, with automatic access control based on organization membership and role permissions.

Request:

  • Method: GET
  • Path: /orders/organizations/:organizationId
  • Headers:
    • Authorization: Bearer <token> in bearer mode, or the accessToken cookie in cookie mode
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearer token required in bearer mode, or cookie-based auth when authMode: 'cookie' (organization member with owner/admin/member role)

URL Parameters:

ParameterTypeRequiredDescription
organizationIdstring✅Unique identifier of the organization to retrieve orders for

Query Parameters:

ParameterTypeRequiredDescription
pagenumber❌Page number for pagination (1-1000)
limitnumber❌Number of items per page (1-50)

Response Body: Paginated response with orders array and metadata.

Response Structure:

{
  "data": [
    {
      "id": "string",
      "items": [
        {
          "productId": "string",
          "quantity": number,
          "price": number
        }
      ],
      "total": number,
      "subtotal": number,
      "tax": number,
      "currency": "string",
      "status": "string",
      "identityId": "string",
      "organizationId": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

Validation:

  • Schema Validation: Organization ID path parameter and pagination query parameters
  • Route Validators:
    • Require authenticated request (bearer token in bearer mode, or cookie-based auth when authMode: 'cookie')
    • Require organization membership with owner, admin, or member role

Example Request:

curl "http://localhost:8089/orders/organizations/org-123?page=1&limit=10" \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "order-456",
      "organizationId": "org-123",
      "currency": "USD",
      "status": "confirmed",
      "items": [
        {
          "productId": "prod-789",
          "quantity": 2,
          "price": 29.99
        }
      ],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

Error Responses:

Unauthorized (401):

{
  "error": {
    "message": "token could not be verified"
  }
}

Bad Request (400):

{
  "error": {
    "message": "Invalid organization ID"
  }
}

Forbidden (403):

{
  "error": {
    "message": "Identity is not a member of the organization"
  }
}

Forbidden (403):

{
  "error": {
    "message": "Identity is not authorized to access this organization"
  }
}

Internal Server Error (500):

{
  "error": {
    "message": "db.organizations is not set"
  }
}

Internal Server Error (500):

{
  "error": {
    "message": "configuration.organization.roles is not set"
  }
}

Internal Server Error (500):

{
  "error": {
    "message": "Failed to fetch organization"
  }
}

Internal Server Error (500):

{
  "error": {
    "message": "Failed to find orders"
  }
}

Use Cases:

  • Organization administrators viewing all orders for their organization
  • Financial reporting and analytics for organization-specific order data
  • Customer service teams accessing order history within their organization
  • Compliance and audit requirements for organization-scoped data access

⚙️ Configuration Options​

Datastore​

CollectionRequiredDescription
orders✅Order documents
identities✅Identity lookups / auth context
organizations❌Required for /orders/organizations/:organizationId

The organization-scoped endpoint also requires configuration.organization.roles; its keys must include owner, admin, and member.

Service Configuration​

interface OrderServiceConfiguration {
  authSecrets: {
    authEncSecret: string; // JWT encryption secret
    authSignSecret: string; // JWT signing secret
  };
  authMode?: 'bearer' | 'cookie'; // Default: bearer behavior when unset
  identity?: {
    typeIds?: {
      admin: string; // Admin user type identifier
      guest: string; // Guest user type identifier
      regular: string; // Regular user type identifier
    };
  };
  organization?: {
    roles?: {
      admin: string;
      member: string;
      owner: string;
    };
  };
}

Configuration Details​

The order service configuration is organized into logical groups for security and user type management.

🔐 Security Settings​

authSecrets - JWT token security secrets

  • Type: { authEncSecret: string; authSignSecret: string }
  • Description: Secret keys for JWT encryption and signing (used for token validation)
  • Required: Yes (for production)
  • Child Properties:
    • authEncSecret: Secret key for JWT payload encryption
    • authSignSecret: Secret key for JWT signature verification

👥 User Type Settings​

identity.typeIds - User type identifier configuration

  • Type: { admin?: string; guest?: string; regular?: string }
  • Description: Custom user type identifiers for role-based access control
  • Default: undefined (uses default type validation)
  • Child Properties:
    • admin: Admin user type identifier
      • Type: string
      • Description: Custom identifier for admin users
      • Use Case: Role-based access control for administrative operations
      • Example: "admin", "administrator", "superuser"
    • guest: Guest user type identifier
      • Type: string
      • Description: Custom identifier for guest users
      • Use Case: Limited access for unauthenticated or temporary users
      • Example: "guest", "visitor", "anonymous"
    • regular: Regular user type identifier
      • Type: string
      • Description: Custom identifier for regular users
      • Use Case: Standard user access permissions
      • Example: "regular", "member", "customer"

Example Configuration​

const orderConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret',
  },
  identity: {
    typeIds: {
      admin: 'administrator',
      guest: 'visitor',
      regular: 'member',
    },
  },
  organization: {
    roles: {
      admin: 'admin',
      member: 'member',
      owner: 'owner',
    },
  },
};

🚨 Error Handling​

All order service errors return JSON format with appropriate HTTP status codes:

Common Error Codes​

StatusError MessageDescription
400Validation ErrorInvalid request body format or missing required fields
400request body must have required property 'identityId'Missing identityId field in request body
400request body must have required property 'items'Missing items array in request body
400request body must have required property 'total'Missing total field in request body
400request body must NOT have additional propertiesRequest contains unsupported fields
400Failed to create orderDatabase insert operation failed to return an inserted ID
400Failed to update orderUpdate operation doesn't modify any data (no changes detected)
400Failed to delete orderDatabase deletion operation failed
401token could not be verifiedMissing or invalid authorization token
401Authentication failedMissing or invalid authentication token
401Token fails security checkToken security validation failed
403Identity is not authorized to access this resourceIdentity lacks required type permissions (admin access)
403Identity is not authorized to access this organizationIdentity lacks a permitted organization role
403Identity ID does not matchRequested identityId does not match the authenticated identity
403Identity is not the owner of the resourceIdentity does not own the requested order
404Order not foundOrder doesn't exist for the requested operation
500Unknown error creating orderDatabase connection issues or unexpected failures during creation
500Failed to get orderDatabase connection issues or unexpected failures during retrieval
500Failed to find ordersDatabase connection issues, invalid filter syntax, or unexpected failures during listing
500Failed to update orderDatabase connection issues or unexpected failures during update
500Failed to delete orderDatabase connection issues or unexpected failures during deletion

Error Response Format​

{
  "error": {
    "message": "Error message description",
    "data": ["Additional error details"]
  }
}

Validation Errors include additional details:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'identityId'",
      "request body must have required property 'items'",
      "request body must have required property 'total'"
    ]
  }
}

🔗 Related Documentation​