Orders Integration Guide

This guide explains how to integrate the Order system. An order represents a confirmed customer order containing line items (articles), delivery tracking, and billing information.

Quick Start

Essential Workflow

1. Create Order: POST /orders with company, project, and initial items
2. Add Items: POST /order-items to add articles to the order
3. Track Delivery: Update trackingId, expectedDeliveryDate, and actualDeliveryDate
4. Monitor Status: Track order state through status workflow (e.g., pending → processing → shipped → delivered)
5. Sync to ERP: Use externalId field for bidirectional synchronization with ERP systems

Key Endpoints

Endpoint	Returns	Use Case
POST /orders	Order	Create customer order
GET /orders/:id	Complete order + items	Get all order data
POST /order-items	OrderItem	Add line item to order
GET /orders	Order list	List orders with filtering
PATCH /orders/:id	Updated order	Update order details

---

Core Entities Overview

1. Order

Root entity representing a confirmed customer order with billing and delivery tracking.

Key Properties: id, externalId, billedAmount, trackingId, orderDate, expectedDeliveryDate, actualDeliveryDate

Status Tracking:

• Orders can have customizable statuses (e.g., pending, processing, shipped, delivered, cancelled)
• Status workflow managed via Status entity

Main Relationships:

• items → OrderItem[] (One-to-Many, required)
• company → Company, project → Project
• status → Status, currency → Currency
• shippingAddress → Address, createdBy → User
• files → File[], comments → Comment[], customFields → CustomFieldValue[]

📖 Full Order Entity Documentation

---

2. OrderItem

Line item within an order, typically references catalog articles.

What It Contains:

• Product Reference: Links to Article for product details
• Pricing: Unit price, quantity, total price
• Units: Measurement unit (kg, m, pcs, etc.)
• Hierarchy: Parent-child relationships for complex order structures

Item Types:

• Article: References a predefined catalog product (primary use case)
  • Article may be linked to a BriefElement for manufacturing specifications
  • Article may exist as standalone inventory item

Hierarchical Structure:

OrderItems can be structured hierarchically for complex orders:

• Parent OrderItem → Represents a grouped product or kit
• Children OrderItems → Individual components within the group

Example structure:

Order
  └── OrderItem (parent) → Product Bundle
        ├── OrderItem (child) → Component A
        ├── OrderItem (child) → Component B
        └── OrderItem (child) → Component C
  └── OrderItem → Standalone Product

Key Properties: id, orderId, articleId, quantity, unitPrice, totalPrice, unit, position

Main Relationships:

• order → Order (Many-to-One)
• article → Article (Many-to-One)
• parent/children → OrderItem (for hierarchical items)
• createdBy → User, comment → Comment

📖 Full OrderItem Entity Documentation

---

3. Article

Predefined product that can be added to orders, linked to production specifications.

What It Contains:

• Product Details: Name, code, description, pricing
• Inventory: Stock status and quantity
• Production Specs: Link to BriefElement for manufacturing details
• ERP Integration: External ID for synchronization

Key Properties: id, code, name, price, stocked, quantity, briefElementId, externalId

Main Relationships:

• company → Company (Many-to-One, required)
• briefElement → BriefElement (Many-to-One)
• orderItems → OrderItem[] (One-to-Many)
• quoteItems → QuoteItem[] (One-to-Many)
• files → File[] (preview, CAD files, documents)

📖 Full Article Entity Documentation

---

Entity Relationships

Company → Project → Order → OrderItem → Article → BriefElement

Key Relationships:

1. Order Structure: Company → Project → Order → OrderItems
2. Product Reference: OrderItem → Article → BriefElement (for manufacturing specs)
3. Hierarchical Orders: OrderItem → Parent/Children OrderItems
4. ERP Sync: Orders and Articles use externalId for external system integration

---

API Endpoints

Order Management

Create Order

POST /orders

Creates a new order with company, project, and billing information.

Request Example:

{
  "companyId": "uuid-company",
  "projectId": "uuid-project",
  "statusId": "uuid-status",
  "billedAmount": 1500.00,
  "currencyId": "uuid-currency",
  "orderDate": "2024-01-15T10:00:00Z",
  "expectedDeliveryDate": "2024-02-15T10:00:00Z",
  "shippingAddressId": "uuid-address",
  "externalId": "ERP-ORDER-12345"
}

Response: Order entity with id and timestamps

---

Get Order with Items

GET /orders/:id

Retrieves complete order information including all line items.

Response Example:

{
  "id": "uuid-order",
  "externalId": "ERP-ORDER-12345",
  "billedAmount": 1500.00,
  "trackingId": "TRACK-123456",
  "orderDate": "2024-01-15T10:00:00Z",
  "expectedDeliveryDate": "2024-02-15T10:00:00Z",
  "actualDeliveryDate": null,
  "company": { "id": "uuid", "name": "Acme Corp" },
  "project": { "id": "uuid", "name": "Q1 Production" },
  "status": { "id": "uuid", "internalLabel": "Processing" },
  "items": [
    {
      "id": "uuid-item-1",
      "articleId": "uuid-article",
      "quantity": 1000,
      "unitPrice": 1.50,
      "totalPrice": 1500.00,
      "unit": "pcs",
      "position": 1,
      "article": {
        "id": "uuid-article",
        "code": "ART-001",
        "name": "Custom Box"
      }
    }
  ]
}

---

OrderItem Management

Add Order Item

POST /order-items

Adds a new line item to an existing order.

Request Example:

{
  "orderId": "uuid-order",
  "articleId": "uuid-article",
  "quantity": 500,
  "unitPrice": 2.00,
  "totalPrice": 1000.00,
  "unit": "pcs",
  "position": 2
}

Response: Created OrderItem entity

---

Update Order Item

PATCH /order-items/:id

Updates an existing order item (quantity, pricing, etc.).

---

Order Queries

List Orders

GET /orders

Retrieves orders with filtering and pagination.

Query Parameters:

• page: Page number (default: 1)
• limit: Items per page (default: 10)
• companyId: Filter by company
• projectId: Filter by project
• statusId: Filter by status (comma-separated for multiple)
• externalId: Filter by ERP external ID
• orderDateStart, orderDateEnd: Filter by order date range
• expectedDeliveryDateStart, expectedDeliveryDateEnd: Filter by expected delivery
• actualDeliveryDateStart, actualDeliveryDateEnd: Filter by actual delivery
• sort: Sort field (e.g., orderDate, updatedAt)
• order: Sort direction (ASC or DESC)

Example Request:

GET /orders?companyId=uuid&statusId=uuid-processing,uuid-shipped&page=1&limit=50&sort=orderDate&order=DESC

---

Workflow Examples

Example 1: Create Order from Existing Articles

Scenario: Create an order for existing catalog products.

// 1. Create Order
POST /orders
{
  "companyId": "company-uuid",
  "projectId": "project-uuid",
  "billedAmount": 0,
  "orderDate": "2024-01-15T10:00:00Z",
  "expectedDeliveryDate": "2024-02-15T10:00:00Z"
}

// Response: { "id": "order-uuid", ... }

// 2. Add Order Items
POST /order-items
{
  "orderId": "order-uuid",
  "articleId": "article-1-uuid",
  "quantity": 1000,
  "unitPrice": 1.50,
  "totalPrice": 1500.00,
  "unit": "pcs"
}

POST /order-items
{
  "orderId": "order-uuid",
  "articleId": "article-2-uuid",
  "quantity": 500,
  "unitPrice": 2.00,
  "totalPrice": 1000.00,
  "unit": "pcs"
}

// 3. Update Order with Total Billed Amount
PATCH /orders/order-uuid
{
  "billedAmount": 2500.00
}

---

Example 2: ERP Synchronization

Scenario: Sync orders between ERP and Packitoo.

// 1. Create Order with ERP Reference
POST /orders
{
  "companyId": "company-uuid",
  "projectId": "project-uuid",
  "externalId": "ERP-ORDER-12345",
  "billedAmount": 3500.00,
  "orderDate": "2024-01-15T10:00:00Z"
}

// 2. Query Orders by ERP ID
GET /orders?externalId=ERP-ORDER-12345

// 3. Update Delivery Tracking from ERP
PATCH /orders/order-uuid
{
  "trackingId": "TRACK-987654",
  "actualDeliveryDate": "2024-02-14T14:30:00Z"
}

---

Example 3: Hierarchical Order Items

Scenario: Create an order with grouped items (e.g., product kits).

// 1. Create Order
POST /orders
{
  "companyId": "company-uuid",
  "projectId": "project-uuid",
  "billedAmount": 5000.00
}

// 2. Create Parent Item (Product Kit)
POST /order-items
{
  "orderId": "order-uuid",
  "articleId": "kit-article-uuid",
  "quantity": 100,
  "unitPrice": 50.00,
  "totalPrice": 5000.00,
  "unit": "kits"
}
// Response: { "id": "parent-item-uuid", ... }

// 3. Create Child Items (Kit Components)
POST /order-items
{
  "orderId": "order-uuid",
  "parentId": "parent-item-uuid",
  "articleId": "component-a-uuid",
  "quantity": 100,
  "position": 1
}

POST /order-items
{
  "orderId": "order-uuid",
  "parentId": "parent-item-uuid",
  "articleId": "component-b-uuid",
  "quantity": 200,
  "position": 2
}

---

Integration Best Practices

1. Status Management

• Configure custom statuses for your order workflow
• Common workflow: Pending → Processing → Shipped → Delivered
• Handle edge cases: Cancelled, On Hold, Backordered

2. ERP Synchronization

• Use externalId to maintain bidirectional sync with ERP systems
• Store ERP order ID in externalId field
• Query by externalId to avoid duplicate orders
• Sync delivery tracking and status updates

3. Delivery Tracking

• Set orderDate when order is placed
• Set expectedDeliveryDate based on production and shipping estimates
• Update trackingId when shipment is created
• Set actualDeliveryDate when delivery is confirmed

4. Pricing and Currency

• Set billedAmount to match total of all order items
• Use currencyId to specify billing currency
• Ensure OrderItem.totalPrice = quantity * unitPrice

5. Address Management

• Link shippingAddressId for delivery tracking
• Ensure address is valid and complete before order creation
• Consider storing address snapshot to preserve historical data

---

Related Resources

• Brief Integration Guide - Creating product configurations
• Quote Integration Guide - Converting quotes to orders
• Article Entity - Product catalog management
• Company Entity - Customer management
• Project Entity - Project organization