Operations Module - Document Management

Overview

The Operations module provides document management capabilities for product lifecycle, inventory, and supply chain operations. This guide covers document handling for three key Operations entities: Products, Suppliers, and Purchase Orders.

Operations Document Capabilities:

Product images, manuals, and specifications
Supplier contracts and compliance documents
Purchase order receipts and delivery notes
Public product catalogs and galleries
Private supplier agreements and audits
Compliance and certification tracking

Supported Entities

The Operations module supports document management for these entities:

Entity	Purpose	Common Document Types	Max File Size
Product	Product catalog and documentation	Images, manuals, specifications, datasheets	10 MB
Supplier	Vendor management	Contracts, certifications, tax documents	50 MB
Purchase Order	Procurement documentation	PO documents, receipts, delivery notes	20 MB

Product Documents

Overview

Product documents include product images (thumbnails, galleries), technical specifications, user manuals, certificates, datasheets, warranty documents, and marketing materials. These documents support e-commerce, product catalogs, and customer service.

Endpoint: /api/v1/operations/products/{productId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`thumbnail`	Product thumbnail images	Primary catalog image
`gallery`	Product gallery images	Additional product photos
`primary`	Primary/featured image	Main product image
`specification`	Technical specifications	Product spec sheets
`manual`	User manuals	Product user guides
`certificate`	Certificates	Quality certificates, ISO certs
`datasheet`	Technical datasheets	Detailed technical docs
`warranty`	Warranty documents	Warranty information
`compliance`	Compliance documents	Safety, regulatory compliance
`safety`	Safety documentation	Safety data sheets (SDS)
`marketing`	Marketing materials	Product brochures, flyers

Common Scenarios

Scenario 1: Product Catalog Images

Set up product images for e-commerce catalog:

bash

# Upload thumbnail (primary catalog image)
curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@thumbnail.jpg" \
  -F "type=image" \
  -F "tags[]=thumbnail" \
  -F "tags[]=primary" \
  -F "name=Product Thumbnail - Widget XL-2000" \
  -F "is_public=true" \
  -F "metadata[display_order]=1" \
  -F "metadata[width]=800" \
  -F "metadata[height]=800"

# Upload gallery images
curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@angle1.jpg" \
  -F "type=image" \
  -F "tags[]=gallery" \
  -F "name=Product Image - Front View" \
  -F "is_public=true" \
  -F "metadata[display_order]=2"

curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@angle2.jpg" \
  -F "type=image" \
  -F "tags[]=gallery" \
  -F "name=Product Image - Side View" \
  -F "is_public=true" \
  -F "metadata[display_order]=3"

# Retrieve all product images ordered by display_order
curl -X GET "https://api.crm.test/api/v1/operations/products/50001/documents?type=image&tags=gallery,thumbnail" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Scenario 2: Product Documentation

Upload technical documentation:

bash

# Upload user manual (public for customers)
curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@user_manual.pdf" \
  -F "type=manual" \
  -F "tags[]=manual" \
  -F "name=User Manual - Widget XL-2000" \
  -F "description=Complete user guide and installation instructions" \
  -F "is_public=true"

# Upload technical specifications (private for internal use)
curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@technical_specs.pdf" \
  -F "type=specification" \
  -F "tags[]=specification" \
  -F "tags[]=datasheet" \
  -F "name=Technical Specifications - Internal" \
  -F "is_public=false"

# Upload safety documentation
curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@safety_datasheet.pdf" \
  -F "type=technical" \
  -F "tags[]=safety" \
  -F "name=Safety Data Sheet (SDS)" \
  -F "is_public=true"

Scenario 3: Compliance and Certifications

Manage product certifications and compliance documents:

bash

# Upload quality certificate
curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@iso_certificate.pdf" \
  -F "type=certificate" \
  -F "tags[]=certificate" \
  -F "tags[]=compliance" \
  -F "name=ISO 9001 Quality Certificate" \
  -F "is_public=false" \
  -F "is_sensitive=true" \
  -F "expires_at=2026-12-31T23:59:59Z"

# Upload compliance documentation
curl -X POST https://api.crm.test/api/v1/operations/products/50001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@ce_marking.pdf" \
  -F "type=certificate" \
  -F "tags[]=compliance" \
  -F "name=CE Marking Certificate" \
  -F "description=European Conformity certification" \
  -F "is_public=false"

# List all compliance documents
curl -X GET "https://api.crm.test/api/v1/operations/products/50001/documents?tags=compliance,certificate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Metadata Usage

Product documents support custom metadata for enhanced organization:

Image Metadata:

json

{
  "metadata": {
    "display_order": 1,
    "width": 1920,
    "height": 1080,
    "alt_text": "Product front view"
  }
}

Document Metadata:

json

{
  "metadata": {
    "version": "2.5",
    "language": "en",
    "revision_date": "2025-01-15"
  }
}

Validation Rules

File Requirements:

Maximum size: 10 MB
Allowed formats: Images (JPEG, PNG, GIF, WebP), PDFs, Word documents

Required Fields:

file - The document file
type - Document type

Optional Fields:

tags - Array of tags (validated against allowed list)
name, description
is_public - Default: false (recommended true for product images/manuals)
is_sensitive - For internal specs, certifications
metadata - Custom fields including display_order, dimensions

Supplier Documents

Overview

Supplier documents include contracts, certifications, tax documents, compliance documents, insurance certificates, audit reports, agreements, and NDAs. These documents are critical for vendor management, compliance, and procurement.

Endpoint: /api/v1/operations/suppliers/{supplierId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`contract`	Supplier contracts	Vendor agreements
`certificate`	Certificates	Quality certifications
`tax_document`	Tax-related documents	W-9, tax ID documents
`compliance`	Compliance documents	Regulatory compliance
`insurance`	Insurance certificates	Liability insurance
`audit`	Audit reports	Supplier audits
`agreement`	General agreements	Service agreements
`nda`	Non-Disclosure Agreement	Confidentiality agreements

Common Scenarios

Scenario 1: Supplier Onboarding

Complete supplier documentation for onboarding:

bash

# Upload supplier contract
curl -X POST https://api.crm.test/api/v1/operations/suppliers/60001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@supplier_contract.pdf" \
  -F "type=contract" \
  -F "tags[]=contract" \
  -F "tags[]=agreement" \
  -F "name=Supplier Agreement 2025" \
  -F "description=Master purchase agreement" \
  -F "is_public=false" \
  -F "is_sensitive=true" \
  -F "expires_at=2025-12-31T23:59:59Z"

# Upload tax documentation
curl -X POST https://api.crm.test/api/v1/operations/suppliers/60001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@w9_form.pdf" \
  -F "type=form" \
  -F "tags[]=tax_document" \
  -F "name=W-9 Tax Form" \
  -F "is_public=false" \
  -F "is_sensitive=true"

# Upload insurance certificate
curl -X POST https://api.crm.test/api/v1/operations/suppliers/60001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@insurance_cert.pdf" \
  -F "type=certificate" \
  -F "tags[]=insurance" \
  -F "name=Liability Insurance Certificate" \
  -F "is_public=false" \
  -F "is_sensitive=true" \
  -F "expires_at=2026-06-30T23:59:59Z"

# Upload NDA
curl -X POST https://api.crm.test/api/v1/operations/suppliers/60001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@nda_signed.pdf" \
  -F "type=legal" \
  -F "tags[]=nda" \
  -F "name=Non-Disclosure Agreement - Signed" \
  -F "is_public=false" \
  -F "is_sensitive=true"

Scenario 2: Supplier Compliance Management

Manage compliance certifications and audits:

bash

# Upload quality certification
curl -X POST https://api.crm.test/api/v1/operations/suppliers/60001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@iso_cert.pdf" \
  -F "type=certificate" \
  -F "tags[]=certificate" \
  -F "tags[]=compliance" \
  -F "name=ISO 9001:2015 Certificate" \
  -F "description=Quality management certification" \
  -F "is_public=false" \
  -F "expires_at=2027-03-15T23:59:59Z"

# Upload audit report
curl -X POST https://api.crm.test/api/v1/operations/suppliers/60001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@audit_report_2024.pdf" \
  -F "type=report" \
  -F "tags[]=audit" \
  -F "tags[]=compliance" \
  -F "name=Annual Supplier Audit 2024" \
  -F "description=Third-party audit results" \
  -F "is_public=false" \
  -F "is_sensitive=true"

# List all compliance documents
curl -X GET "https://api.crm.test/api/v1/operations/suppliers/60001/documents?tags=compliance" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Scenario 3: Document Expiration Tracking

Track and renew expiring supplier documents:

bash

# Find expiring documents (filter client-side by expires_at)
curl -X GET "https://api.crm.test/api/v1/operations/suppliers/60001/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Upload renewed insurance certificate
curl -X POST https://api.crm.test/api/v1/operations/suppliers/60001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@insurance_cert_renewed.pdf" \
  -F "type=certificate" \
  -F "tags[]=insurance" \
  -F "name=Liability Insurance Certificate 2026" \
  -F "description=Renewed certificate" \
  -F "is_public=false" \
  -F "is_sensitive=true" \
  -F "expires_at=2027-06-30T23:59:59Z"
# Note: Old certificate automatically archived

Validation Rules

File Requirements:

Maximum size: 50 MB
All file types accepted

Required Fields:

file, type

Optional Fields:

tags, name, description
is_public - Default: false (recommended for all supplier documents)
is_sensitive - Recommended: true for contracts, financial documents
expires_at - Important for certifications, insurance, contracts

Purchase Order Documents

Overview

Purchase Order documents include PO confirmations, supplier invoices, delivery notes, packing slips, and receipts. These documents support the procurement workflow and goods receiving process.

Endpoint: /api/v1/operations/purchase-orders/{purchaseOrderId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`purchase_order`	PO documents	Generated purchase orders
`receipt`	Receipt documents	Goods receipt documents
`invoice`	Supplier invoices	Purchase invoices
`delivery_note`	Delivery notes	Shipping delivery notes
`packing_slip`	Packing slips	Shipment packing lists
`confirmation`	Order confirmations	Supplier confirmations

Common Scenarios

Scenario 1: Purchase Order Workflow

Document complete PO lifecycle:

bash

# Upload generated PO document
curl -X POST https://api.crm.test/api/v1/operations/purchase-orders/70001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@po_70001.pdf" \
  -F "type=invoice" \
  -F "tags[]=purchase_order" \
  -F "name=Purchase Order PO-70001" \
  -F "description=Purchase order sent to supplier" \
  -F "is_public=false"

# Upload supplier confirmation
curl -X POST https://api.crm.test/api/v1/operations/purchase-orders/70001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@supplier_confirmation.pdf" \
  -F "type=receipt" \
  -F "tags[]=confirmation" \
  -F "name=Supplier Order Confirmation" \
  -F "description=Confirmation received from supplier" \
  -F "is_public=false"

Scenario 2: Goods Receiving Documentation

Document receipt of goods:

bash

# Upload delivery note from supplier
curl -X POST https://api.crm.test/api/v1/operations/purchase-orders/70001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@delivery_note.pdf" \
  -F "type=receipt" \
  -F "tags[]=delivery_note" \
  -F "name=Delivery Note - Shipment #12345" \
  -F "is_public=false"

# Upload packing slip
curl -X POST https://api.crm.test/api/v1/operations/purchase-orders/70001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@packing_slip.pdf" \
  -F "type=receipt" \
  -F "tags[]=packing_slip" \
  -F "name=Packing Slip" \
  -F "is_public=false"

# Upload goods receipt document
curl -X POST https://api.crm.test/api/v1/operations/purchase-orders/70001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@goods_receipt.pdf" \
  -F "type=receipt" \
  -F "tags[]=receipt" \
  -F "name=Goods Receipt - PO-70001" \
  -F "description=Internal goods receipt confirmation" \
  -F "is_public=false"

Scenario 3: Invoice Matching

Link supplier invoices to purchase orders:

bash

# Upload supplier invoice
curl -X POST https://api.crm.test/api/v1/operations/purchase-orders/70001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@supplier_invoice.pdf" \
  -F "type=invoice" \
  -F "tags[]=invoice" \
  -F "name=Supplier Invoice #INV-54321" \
  -F "description=Invoice for PO-70001" \
  -F "is_public=false"

# Retrieve all PO documents for 3-way match
curl -X GET "https://api.crm.test/api/v1/operations/purchase-orders/70001/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Should return: PO, delivery note, invoice for matching

Validation Rules

File Requirements:

Maximum size: 20 MB
All file types accepted (typically PDFs)

Required Fields:

file, type

Optional Fields:

tags, name, description
is_public - Default: false (all PO documents should be private)

Cross-Entity Workflows

Product-Supplier Relationship

Link supplier certifications to products:

bash

# Get supplier quality certificate
GET /api/v1/operations/suppliers/60001/documents?tags=certificate

# Reference certificate ID in product metadata or custom fields
# (Documents remain attached to supplier, referenced from product)

Purchase Order to Inventory

Document goods receipt workflow:

bash

# 1. Upload delivery documents to PO
POST /api/v1/operations/purchase-orders/70001/documents
{
  "file": <delivery_note.pdf>,
  "tags": ["delivery_note", "receipt"]
}

# 2. Create inventory transaction (goods received)
POST /api/v1/operations/inventory/transactions

# 3. Link documents via metadata or notes field

Best Practices

1. Product Documentation

Public Product Content:

Make product images, manuals, and marketing materials public
Optimize images for web (use WebP format when possible)
Use descriptive file names for SEO
Include alt text in metadata

Private Technical Specs:

Keep internal specifications private
Mark cost data and supplier info as sensitive
Use expiration dates for time-limited certifications

Image Organization:

Use display_order metadata for gallery sequence
Tag primary image with both thumbnail and primary
Store multiple angles/views with consistent naming

2. Supplier Management

Document All Suppliers:

Require contracts, insurance, tax documents at onboarding
Set expiration dates for all time-limited documents
Review expiring documents monthly
Maintain audit trail of all supplier documentation

Compliance Tracking:

Tag all compliance documents consistently
Track certification expiration dates
Upload renewed documents before expiration
Archive old versions for audit purposes

Security:

Mark all supplier documents as private and sensitive
Restrict access to procurement and finance teams
Implement approval workflows for contract changes

3. Purchase Order Documentation

Complete Documentation:

Upload PO document at creation
Attach supplier confirmation when received
Upload all receiving documents (delivery note, packing slip)
Link supplier invoice for 3-way matching

Naming Conventions:

Include PO number in document name
Reference shipment numbers in descriptions
Use consistent tag combinations

Audit Trail:

Never hard-delete PO documents
Maintain complete history for financial audits
Include dates in document names and descriptions

4. Performance Optimization

Image Optimization:

Compress images before upload (target 200-500 KB)
Use appropriate dimensions (800x800px for thumbnails)
Leverage public storage and CDN for product images
Generate responsive image sizes client-side if needed

File Organization:

Batch upload multiple product images together
Use metadata to organize instead of creating duplicate tags
Clean up draft/test documents periodically

Troubleshooting

Common Issues

Problem: Product images not displaying in catalog

Solution:

Verify images are marked as is_public: true
Check storage link is created (php artisan storage:link)
Confirm image URLs are correct in response
Verify CDN/storage configuration

Problem: Expired supplier certificates not flagged

Solution:

Ensure expires_at date is set on upload
Query documents and filter by expiration client-side
Implement scheduled job to check expirations
Send renewal reminders 30-60 days before expiration

Problem: PO document upload fails with "Invalid tag"

Solution:

Check tags against allowed list for purchase orders
Use underscore format: purchase_order, not purchase-order
Tags are case-sensitive (use lowercase)

Main Document Management Guide - System-wide documentation
Product Lifecycle Guide - Complete product management
Inventory Management - Inventory operations
Purchase Order Workflow - Complete PO documentation

API Reference

For complete API specifications:

OpenAPI Specification: /docs/openapi.yaml
Interactive Documentation: Scribe-generated API docs
Endpoint Group: Operations Module → Document Management

Operations Module - Document Management ​

Overview ​

Supported Entities ​

Product Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Product Catalog Images ​

Scenario 2: Product Documentation ​

Scenario 3: Compliance and Certifications ​

Metadata Usage ​

Validation Rules ​

Supplier Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Supplier Onboarding ​

Scenario 2: Supplier Compliance Management ​

Scenario 3: Document Expiration Tracking ​

Validation Rules ​

Purchase Order Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Purchase Order Workflow ​

Scenario 2: Goods Receiving Documentation ​

Scenario 3: Invoice Matching ​

Validation Rules ​

Cross-Entity Workflows ​

Product-Supplier Relationship ​

Purchase Order to Inventory ​

Best Practices ​

1. Product Documentation ​

2. Supplier Management ​

3. Purchase Order Documentation ​

4. Performance Optimization ​

Troubleshooting ​

Common Issues ​

Related Documentation ​

API Reference ​

Operations Module - Document Management

Overview

Supported Entities

Product Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Product Catalog Images

Scenario 2: Product Documentation

Scenario 3: Compliance and Certifications

Metadata Usage

Validation Rules

Supplier Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Supplier Onboarding

Scenario 2: Supplier Compliance Management

Scenario 3: Document Expiration Tracking

Validation Rules

Purchase Order Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Purchase Order Workflow

Scenario 2: Goods Receiving Documentation

Scenario 3: Invoice Matching

Validation Rules

Cross-Entity Workflows

Product-Supplier Relationship

Purchase Order to Inventory

Best Practices

1. Product Documentation

2. Supplier Management

3. Purchase Order Documentation

4. Performance Optimization

Troubleshooting

Common Issues

Related Documentation

API Reference