Briefs Integration Guide

This guide explains how to integrate the Brief (packaging request) system. A brief represents a client’s packaging request containing one or more configured products with complete specifications.

Quick Start

Essential Workflow

1. Create Brief: POST /briefs with BriefElements containing product specs
2. Monitor Status: Poll GET /briefs/:id until predictionStatus: COMPLETED and hasPrice: true
3. Get Complete Data: GET /briefs/:id/details for all pricing and logistics
4. Analyze Elements: GET /briefs/:id/process/:elementIndex for manufacturing details per element (0-indexed)
5. Cost Analysis: GET /briefs/:id/value-analysis for comprehensive cost breakdown

Key Endpoints

Endpoint	Returns	Use Case
POST /briefs	Brief with prediction	Create packaging request
GET /briefs/:id/details	Complete brief + pricing	Get all data after processing
GET /briefs/:id/process/0	Manufacturing for element 0	Detailed process for first product
GET /briefs/:id/value-analysis	Cost breakdown	Analyze pricing and optimization

---

Core Entities Overview

1. Brief

Root entity representing a packaging request/quote.

Key Properties: id, code, name, predictionStatus, hasPrice, packingType, palletType

Property Groups: Core identifiers, Packing configuration, Pallet configuration, CAD Status, Prediction tracking

Main Relationships:

• briefElements → BriefElement[] (One-to-Many, required)
• briefComputed → BriefComputed (One-to-One)
• predictionRequest → BriefPrice (One-to-One)
• project → Project, company → Company
• deliveryAddress → Address (Many-to-One)

📖 Full Brief Entity Documentation

---

2. BriefElement

Configured product within a brief with complete specifications.

What It Contains:

• Dimensions: Length, width, height, layout configurations
• Materials: Material types, grammage, corrugated compositions
• Decoration: Printing details, colors, decoration quantities
• Finishes: Lamination, varnish, hot stamping, embossing
• Quantity: Production quantities per decoration variant

Key Properties: id, briefId, position (for retrieving computed data), productId, decorationsCount (required)

Main Relationships:

• brief → Brief (Many-to-One)
• briefElementPrice → BriefElementPrice (One-to-One)

📖 Full BriefElement Entity Documentation

---

3. BriefComputed

Computed product formulas and CAD design results. Does NOT include pricing.

What It Contains:

• Computed product formulas and CAD design results
• Logistics calculations (packing, pallets, delivery)
• Standard formula execution for CAD-based products

Key Properties: Packing/pallet types, delivery costs, logistic costs

Main Relationships:

• brief → Brief (One-to-One)
• briefElements → BriefElementComputed[] (One-to-Many)

📖 Full BriefComputed Entity Documentation

---

4. BriefElementComputed

Computed data for individual brief elements.

What It Contains:

• Computed dimensions (flat pack surface, CAD measurements)
• CAD integration data (design keys, project keys)
• Decoration summary and finishing data
• Production data and overhead rates

Key Properties: position (matches BriefElement position), computed dimensions, CAD keys

Main Relationships:

• briefComputed → BriefComputed (Many-to-One)

Note: Use position to link with BriefElement: briefComputed.briefElements[position] matches brief.briefElements[position]

📖 Full BriefElementComputed Entity Documentation

---

5. BriefPrice (PredictionRequest)

Pricing and prediction data for a brief.

What It Contains:

• Total price, product cost, tooling cost, delivery cost
• Detailed cost breakdown by category
• Production time and process count
• Manufacturing process (PredictionRequestComputed)

Key Properties: totalPrice, productCost, toolingCost, deliveryCost, costBreakdown, productionTime

Main Relationships:

• brief → Brief (One-to-One)
• predictionRequestComputed → PredictionRequestComputed[] (One-to-Many)

📖 Full BriefPrice Entity Documentation

---

6. PredictionRequestComputed

Computed manufacturing process data for individual brief elements.

What It Contains:

• Manufacturing process sequences and operations
• Machine operation rates and provider services
• Detailed cost breakdowns by operation category
• Sheet layout calculations and production metrics
• Optimization recommendations

Key Properties: id, position (matches BriefElement position), unitPrice, productionTime, costBreakdown, costSummary

Main Relationships:

• predictionRequest → BriefPrice (Many-to-One)
• predictionMachineOperationRates → PredictionMachineOperationRate[] (One-to-Many)
• predictionOperationSequence → PredictionOperation[] (One-to-Many)

Note: Retrieved via GET /briefs/:id/process/:position endpoint using the element’s position (0-indexed)

📖 Full PredictionRequestComputed Entity Documentation

---

7. BriefElementPrice

Simple pricing data for individual brief elements.

What It Contains: Unit price and quantity for element-level costs

Key Properties: unitPrice, quantity

📖 Full BriefElementPrice Entity Documentation

---

8. Project

Groups briefs and quotes for a business opportunity.

Key Properties: id, code, name, companyId, statusId

Main Relationships: briefs → Brief[], company → Company

📖 Full Project Entity Documentation

---

9. Company

Client organization.

Key Properties: id, code, name

Main Relationships:

• projects → Project[] (One-to-Many)
• briefs → Brief[] (One-to-Many, direct when project is null)

📖 Full Company Entity Documentation

---

Entity Relationships Diagram

Company
  ├─── Projects (optional)
  │      ├─── Briefs
  │      │      ├─── BriefElements
  │      │      │      └─── BriefElementPrice
  │      │      ├─── BriefComputed
  │      │      │      └─── BriefElementComputed (one per element)
  │      │      └─── BriefPrice (PredictionRequest)
  │      │             └─── PredictionRequestComputed (one per element)
  │      │                    └─── PredictionOperation (sequence)
  │      │
  │      └─── Quotes & more
  │
  └─── Briefs (direct, especially when project feature is not enabled) & more

---

Workflow Examples

1. Create and Process a Brief

# Step 1: Create brief
POST /briefs
{
  "name": "Custom Folding Carton",
  "projectId": "uuid",
  "companyId": "uuid",
  "briefElements": [{
    "position": 0,
    "productId": "uuid",
    "lengthDimension": 200,
    "widthDimension": 150,
    "heightDimension": 80,
    "decorationsCount": [{"quantity": 5000, "decorationIndex": 0}],
    ...
  }]
}

# Step 2: Monitor status
GET /briefs/:id
# Wait until predictionStatus: COMPLETED and hasPrice: true

# Step 3: Get complete data
GET /briefs/:id/details

# Step 4: Get manufacturing details for first element
GET /briefs/:id/process/0

# Step 5: Get cost breakdown
GET /briefs/:id/value-analysis

2. Multiple Products in One Brief

POST /briefs
{
  "briefElements": [
    { "position": 0, "productId": "uuid-carton", ... },
    { "position": 1, "productId": "uuid-box", ... }
  ]
}

# Access each element's manufacturing:
GET /briefs/:id/process/0  # First product
GET /briefs/:id/process/1  # Second product

3. ERP Sync

# Incremental sync
GET /briefs?lastupdate=2024-01-15T10:30:00Z&order=+updatedAt&limit=100

# Filter by company
GET /briefs?companyId=uuid-of-company

# Filter by status
GET /briefs?status=uuid-status-1,uuid-status-2

---

Key Integration Points

Position Property

The position property in BriefElement is critical for data retrieval:

// Link BriefElement with BriefElementComputed
const element = brief.briefElements[0];  // position: 0
const computed = brief.briefComputed.briefElements[0];  // Matches position: 0

// Access manufacturing process
GET /briefs/:id/process/0  // Uses element position

Pricing vs Computed Data

• BriefComputed: Product formulas, CAD results, logistics (NO pricing)
• BriefPrice: All pricing information, cost breakdowns, margins

Required Fields

• briefElements array is required (min: 1 element)
• decorationsCount is required for each BriefElement
• position must be unique within each brief (0-indexed)

---

API Endpoints Summary

Endpoint	Purpose
POST /briefs	Create brief (synchronous)
POST /briefs/async	Create brief (soon: asynchronous)
GET /briefs	Get paginated briefs
GET /briefs/:id	Get basic brief data
GET /briefs/:id/details	Get complete brief with all relations
GET /briefs/:id/process/:elementIndex	Get manufacturing for specific element
GET /briefs/:id/value-analysis	Get cost breakdown and optimization
GET /briefs/:id/prediction-panel	Get prediction display data
PUT /briefs/:id	Update brief
DELETE /briefs/:id	Soft delete brief

---

Additional Resources

• Brief Entity Reference - Complete Brief entity documentation
• Quote System Guide - Quote management
• Webhook Guide - Real-time event integration
• API Reference - Complete API documentation
• Create Access Token - Authentication setup

---

For detailed property lists, schemas, and advanced use cases, refer to the individual entity documentation pages linked above.