Article

An Article represents a predefined product that can be added to quotes and orders. Articles can be stocked items or custom-made products. Articles may optionally be linked to a BriefElement that contains production specifications (dimensions, material, decorations, finishes), but can also exist independently without any BriefElement reference.

Main Purpose

• Catalog predefined products for quick quotation
• Link standardized products to production specifications (optional)
• Track inventory for stocked items
• Integrate with ERP systems for product synchronization
• Enable reusable product definitions across multiple quotes

Key Properties

Property	Type	Description
id	UUID	Unique identifier
name	string	Article name (required)
code	string	Reference code (required, unique)
description	string	Article description
price	number	Unit price (min: 0)
stocked	boolean	Is in stock (default: false)
quantity	number	Quantity in stock (min: 0)
unit	string	Unit of dimensions (e.g., “mm”, “cm”)
enabled	boolean	Is enabled for use
externalId	string	External ID for ERP synchronization
briefElementId	UUID	Linked brief element ID
currencyId	UUID	Currency ID
createdAt	Date	Creation timestamp
updatedAt	Date	Last update timestamp

Main Relationships

Relationship	Entity	Type	Description
company	Company	Many-to-One	Associated company (required)
briefElement	BriefElement	Many-to-One	Production specifications
currency	Currency	Many-to-One	Article currency
preview	File	One-to-One	Preview image
files	File	One-to-Many	Associated files (CAD, images, etc.)
customFields	CustomFieldValue	One-to-Many	Custom field values
quoteItems	QuoteItem	One-to-Many	Quote items using this article
orderItems	OrderItem	One-to-Many	Order items using this article
createdBy	User	Many-to-One	Creator user

Article Creation Scenarios

Scenario 1: Article Linked to BriefElement from Actual Brief

1. User configures packaging in configurator → creates Brief with BriefElement
2. Article created with reference to existing briefElementId from that Brief
3. Article inherits production specs from the actual BriefElement

API Call:

{
  "name": "Custom Box 20x20x10",
  "code": "BOX-001",
  "briefElementId": "uuid-from-existing-brief",
  "price": 2.50,
  "companyId": "uuid-company"
}

Result: Article links to a BriefElement from an actual Brief, providing complete production specifications.

Scenario 2: Article Created from ERP with Standalone BriefElement

1. Article created in ERP system without existing Brief
2. API import creates both Article and a new standalone BriefElement
3. System automatically links them together
4. The BriefElement exists independently (not part of any Brief)

API Call:

{
  "name": "Box from ERP",
  "code": "ERP-001",
  "externalId": "ERP-12345",
  "price": 10.0,
  "companyId": "uuid-company",
  "briefElement": {
    "productId": "uuid-product",
    "lengthDimension": 200,
    "widthDimension": 200,
    "heightDimension": 100
  }
}

Result: Article links to a standalone BriefElement (not attached to any Brief), providing basic production specifications.

Scenario 3: Article Without BriefElement

1. Article created without any BriefElement reference
2. No production specifications attached
3. Typically used for simple catalog items, accessories, or non-packaging products

Common Use Cases:

• Packaging accessories (tape, labels, strapping)
• Shipping materials (bubble wrap, fillers)
• Assembly components (glue, fasteners)
• Services (delivery, setup, consultation)
• Standard off-the-shelf items that don’t require production specifications

API Call:

{
  "name": "Packaging Tape Roll",
  "code": "TAPE-001",
  "externalId": "ERP-67890",
  "price": 5.0,
  "companyId": "uuid-company"
}

Result: Article exists independently without any BriefElement link. Ideal for non-packaging production items that are purchased or stocked rather than manufactured.

BriefElement Linking Summary

Articles can have three different relationships with BriefElements:

1. Linked to BriefElement from Actual Brief: Article references a BriefElement that belongs to an existing Brief (for packaging production items with full specs)
2. Linked to Standalone BriefElement: Article references a BriefElement created specifically for the article (for packaging items imported from ERP)
3. No BriefElement Link: Article exists independently without production specifications (for non-packaging items like tape, labels, accessories, or services that don’t require manufacturing specifications)

Article Types

Stocked Articles

• stocked: true
• quantity: Available stock quantity
• Immediate availability
• Typically used for standard products

Custom-Made Articles

• stocked: false
• Produced on demand
• Links to BriefElement for manufacturing specs
• Requires production lead time

Related Endpoints

• POST /articles - Create article
• GET /articles/:id - Get article details with all relations
• GET /articles - Get paginated articles list
• PATCH /articles/:id - Update article
• DELETE /articles/:id - Soft delete article
• GET /articles/:id/files - Get article files

Query Parameters

When listing articles (GET /articles):

• page - Page number
• limit - Items per page
• search - Search by name or code
• sort - Sort field and order
• companyId - Filter by company
• briefElementId - Filter by brief element
• enabled - Filter by enabled status

Key Features

• ERP Integration: External ID field for synchronization
• Custom Fields: Extensible with company-specific fields
• File Attachments: Support for CAD files, images, documents
• Inventory Tracking: Quantity management for stocked items
• Reusability: Single article can be used in multiple quotes
• Production Specs: Link to BriefElement for manufacturing details
• Preview Images: Visual representation for quick selection

Integration with Quotes

Articles can be added to quotes via QuoteItems:

1. Select article from catalog
2. Create QuoteItem with articleId reference
3. Set quantity and override price if needed
4. Article’s BriefElement provides production specifications

See Also

• QuoteItem - Line items that reference articles
• BriefElement - Production specifications
• Quote - Quotes containing articles
• Company - Article owner company