Sales Module - Document Management

Overview

The Sales module provides document management capabilities for the order-to-cash cycle. This guide covers document handling for three key Sales entities: Orders, Invoices, and Payments.

Sales Document Capabilities:

Order confirmations and shipping documents
Invoice PDFs and credit notes
Payment receipts and transaction proofs
Delivery tracking and customs documentation
Tax documents and financial records
Refund and chargeback documentation

Supported Entities

The Sales module supports document management for these entities:

Entity	Purpose	Common Document Types	Max File Size
Order	Sales order documentation	Confirmations, delivery notes, packing slips	20 MB
Invoice	Invoice and billing documents	Invoice PDFs, receipts, tax documents	10 MB
Payment	Payment transaction records	Receipts, bank statements, transaction proofs	10 MB

Order Documents

Overview

Order documents include order confirmations, delivery notes, packing slips, shipping labels, customs documentation, invoices, and receipts. These documents support order fulfillment, shipping, and customer communication.

Endpoint: /api/v1/sales/orders/{orderId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`confirmation`	Order confirmations	Order confirmation emails/PDFs
`delivery_note`	Delivery notes	Shipment delivery documentation
`packing_slip`	Packing slips	Shipment packing lists
`shipping_label`	Shipping labels	Carrier shipping labels
`customs`	Customs documentation	International shipping customs forms
`invoice`	Order invoices	Sales invoices attached to orders
`receipt`	Payment receipts	Payment confirmations

Common Scenarios

Scenario 1: Order Fulfillment Documentation

Document complete order fulfillment process:

bash

# Upload order confirmation (sent to customer)
curl -X POST https://api.crm.test/api/v1/sales/orders/80001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@order_confirmation.pdf" \
  -F "type=receipt" \
  -F "tags[]=confirmation" \
  -F "name=Order Confirmation #ORD-80001" \
  -F "description=Order confirmation sent to customer" \
  -F "is_public=false"

# Upload packing slip (warehouse)
curl -X POST https://api.crm.test/api/v1/sales/orders/80001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@packing_slip.pdf" \
  -F "type=receipt" \
  -F "tags[]=packing_slip" \
  -F "name=Packing Slip - Shipment #SHP-12345" \
  -F "is_public=false"

# Upload shipping label
curl -X POST https://api.crm.test/api/v1/sales/orders/80001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@shipping_label.pdf" \
  -F "type=receipt" \
  -F "tags[]=shipping_label" \
  -F "name=Shipping Label - FedEx Tracking #123456789" \
  -F "is_public=false"

# Upload delivery note
curl -X POST https://api.crm.test/api/v1/sales/orders/80001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@delivery_note.pdf" \
  -F "type=receipt" \
  -F "tags[]=delivery_note" \
  -F "name=Delivery Note - Signed" \
  -F "description=Customer signature confirmation" \
  -F "is_public=false"

Scenario 2: International Shipping with Customs

Handle international orders with customs documentation:

bash

# Upload customs declaration
curl -X POST https://api.crm.test/api/v1/sales/orders/80002/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@customs_declaration.pdf" \
  -F "type=form" \
  -F "tags[]=customs" \
  -F "name=Customs Declaration - EU Export" \
  -F "description=Commercial invoice and customs forms" \
  -F "is_public=false"

# Upload commercial invoice
curl -X POST https://api.crm.test/api/v1/sales/orders/80002/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@commercial_invoice.pdf" \
  -F "type=invoice" \
  -F "tags[]=invoice" \
  -F "tags[]=customs" \
  -F "name=Commercial Invoice - International Shipment" \
  -F "is_public=false"

Scenario 3: Order-Invoice Linking

Link invoice documents to orders:

bash

# Upload invoice PDF to order
curl -X POST https://api.crm.test/api/v1/sales/orders/80001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@invoice_80001.pdf" \
  -F "type=invoice" \
  -F "tags[]=invoice" \
  -F "name=Invoice #INV-80001" \
  -F "is_public=false"

# Upload payment receipt to order
curl -X POST https://api.crm.test/api/v1/sales/orders/80001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@payment_receipt.pdf" \
  -F "type=receipt" \
  -F "tags[]=receipt" \
  -F "name=Payment Receipt - Card Payment" \
  -F "is_public=false"

# Retrieve all order documents for customer service
curl -X GET "https://api.crm.test/api/v1/sales/orders/80001/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Validation Rules

File Requirements:

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

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 (all order documents should be private)

Invoice Documents

Overview

Invoice documents include generated invoice PDFs, payment receipts, proof of payment, credit notes, tax documents, proforma invoices, and commercial invoices. These documents support billing, accounting, and tax compliance.

Endpoint: /api/v1/sales/invoices/{invoiceId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`invoice_pdf`	Generated invoice PDFs	Official invoice documents
`receipt`	Payment receipts	Payment confirmations
`proof_of_payment`	Payment proof documents	Bank transfers, wire confirmations
`credit_note`	Credit note documents	Credit memos, refunds
`tax_document`	Tax-related documents	Tax invoices, VAT documents
`proforma`	Proforma invoices	Preliminary invoices, quotes
`commercial_invoice`	Commercial invoices	International trade invoices

Common Scenarios

Scenario 1: Invoice Generation and Payment

Complete invoice lifecycle documentation:

bash

# Upload generated invoice PDF
curl -X POST https://api.crm.test/api/v1/sales/invoices/90001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@invoice_90001.pdf" \
  -F "type=invoice" \
  -F "tags[]=invoice_pdf" \
  -F "name=Invoice #INV-90001" \
  -F "description=Official invoice document" \
  -F "is_public=false"

# Upload payment receipt after payment received
curl -X POST https://api.crm.test/api/v1/sales/invoices/90001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@payment_receipt.pdf" \
  -F "type=receipt" \
  -F "tags[]=receipt" \
  -F "tags[]=proof_of_payment" \
  -F "name=Payment Receipt - Stripe Payment" \
  -F "description=Stripe payment confirmation" \
  -F "is_public=false"

Scenario 2: Proforma to Final Invoice

Handle proforma invoice conversion:

bash

# Upload proforma invoice (preliminary)
curl -X POST https://api.crm.test/api/v1/sales/invoices/90002/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@proforma_invoice.pdf" \
  -F "type=quote" \
  -F "tags[]=proforma" \
  -F "name=Proforma Invoice #PI-90002" \
  -F "description=Preliminary invoice for customs" \
  -F "is_public=false"

# Upload final commercial invoice (after payment)
curl -X POST https://api.crm.test/api/v1/sales/invoices/90002/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@commercial_invoice.pdf" \
  -F "type=invoice" \
  -F "tags[]=invoice_pdf" \
  -F "tags[]=commercial_invoice" \
  -F "name=Commercial Invoice #INV-90002" \
  -F "description=Final invoice after payment confirmation" \
  -F "is_public=false"

Scenario 3: Credit Notes and Refunds

Document credit memos and refunds:

bash

# Upload credit note
curl -X POST https://api.crm.test/api/v1/sales/invoices/90003/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@credit_note.pdf" \
  -F "type=invoice" \
  -F "tags[]=credit_note" \
  -F "name=Credit Note #CN-90003" \
  -F "description=Partial refund for returned items" \
  -F "is_public=false"

# Upload refund receipt
curl -X POST https://api.crm.test/api/v1/sales/invoices/90003/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@refund_receipt.pdf" \
  -F "type=receipt" \
  -F "tags[]=receipt" \
  -F "name=Refund Receipt" \
  -F "description=Refund processed to original payment method" \
  -F "is_public=false"

Scenario 4: Tax Documentation

Handle tax-specific invoice documents:

bash

# Upload tax invoice (VAT-compliant)
curl -X POST https://api.crm.test/api/v1/sales/invoices/90004/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@tax_invoice.pdf" \
  -F "type=invoice" \
  -F "tags[]=invoice_pdf" \
  -F "tags[]=tax_document" \
  -F "name=Tax Invoice #INV-90004 (VAT)" \
  -F "description=VAT-compliant invoice for EU customer" \
  -F "is_public=false"

Validation Rules

File Requirements:

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

Required Fields:

file, type

Optional Fields:

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

Payment Documents

Overview

Payment documents include payment receipts, transaction proofs, bank statements, authorization documents, refund receipts, and chargeback documentation. These documents provide proof of payment, support reconciliation, and handle disputes.

Endpoint: /api/v1/sales/payments/{paymentId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`receipt`	Payment receipts	Payment confirmations
`transaction_proof`	Transaction proof	Wire transfer confirmations
`bank_statement`	Bank statements	Bank transfer statements
`authorization`	Payment authorizations	Credit card authorizations
`refund_receipt`	Refund receipts	Refund confirmations
`chargeback`	Chargeback documentation	Dispute documentation

Common Scenarios

Scenario 1: Credit Card Payment

Document credit card transaction:

bash

# Upload payment authorization
curl -X POST https://api.crm.test/api/v1/sales/payments/95001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@auth_code.pdf" \
  -F "type=receipt" \
  -F "tags[]=authorization" \
  -F "name=Payment Authorization - Card Transaction" \
  -F "description=Credit card authorization code" \
  -F "is_public=false"

# Upload payment receipt
curl -X POST https://api.crm.test/api/v1/sales/payments/95001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@payment_receipt.pdf" \
  -F "type=receipt" \
  -F "tags[]=receipt" \
  -F "name=Payment Receipt - Card #****1234" \
  -F "is_public=false"

Scenario 2: Wire Transfer Payment

Document wire transfer with bank proof:

bash

# Upload bank transfer proof
curl -X POST https://api.crm.test/api/v1/sales/payments/95002/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@wire_confirmation.pdf" \
  -F "type=financial" \
  -F "tags[]=transaction_proof" \
  -F "tags[]=bank_statement" \
  -F "name=Wire Transfer Confirmation" \
  -F "description=Bank wire transfer confirmation" \
  -F "is_public=false"

# Upload transaction receipt
curl -X POST https://api.crm.test/api/v1/sales/payments/95002/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@transaction_receipt.pdf" \
  -F "type=receipt" \
  -F "tags[]=receipt" \
  -F "tags[]=transaction_proof" \
  -F "name=Transaction Receipt" \
  -F "is_public=false"

Scenario 3: Refund Processing

Document refund transactions:

bash

# Upload refund receipt
curl -X POST https://api.crm.test/api/v1/sales/payments/95003/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@refund_receipt.pdf" \
  -F "type=receipt" \
  -F "tags[]=refund_receipt" \
  -F "name=Refund Receipt - $150.00" \
  -F "description=Refund processed to original card" \
  -F "is_public=false"

# Upload refund authorization
curl -X POST https://api.crm.test/api/v1/sales/payments/95003/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@refund_auth.pdf" \
  -F "type=receipt" \
  -F "tags[]=authorization" \
  -F "tags[]=refund_receipt" \
  -F "name=Refund Authorization" \
  -F "description=Manager approval for refund" \
  -F "is_public=false"

Scenario 4: Chargeback Dispute

Document chargeback and dispute resolution:

bash

# Upload chargeback notice
curl -X POST https://api.crm.test/api/v1/sales/payments/95004/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@chargeback_notice.pdf" \
  -F "type=legal" \
  -F "tags[]=chargeback" \
  -F "name=Chargeback Notice - Case #CB12345" \
  -F "description=Customer initiated chargeback" \
  -F "is_public=false"

# Upload dispute evidence
curl -X POST https://api.crm.test/api/v1/sales/payments/95004/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@dispute_evidence.pdf" \
  -F "type=legal" \
  -F "tags[]=chargeback" \
  -F "name=Chargeback Evidence Package" \
  -F "description=Evidence submitted to payment processor" \
  -F "is_public=false"

Validation Rules

File Requirements:

Maximum size: 10 MB
All file types accepted (typically PDFs, images for screenshots)

Required Fields:

file, type

Optional Fields:

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

Cross-Entity Workflows

Order-to-Invoice-to-Payment Flow

Complete order-to-cash documentation:

bash

# 1. Order created - upload confirmation
POST /api/v1/sales/orders/80001/documents
{
  "file": <confirmation.pdf>,
  "tags": ["confirmation"]
}

# 2. Invoice generated - upload invoice PDF
POST /api/v1/sales/invoices/90001/documents
{
  "file": <invoice.pdf>,
  "tags": ["invoice_pdf"]
}

# 3. Invoice reference can be added to order
POST /api/v1/sales/orders/80001/documents
{
  "file": <invoice.pdf>,
  "tags": ["invoice"]
}

# 4. Payment received - upload receipt to both
POST /api/v1/sales/payments/95001/documents
{
  "file": <receipt.pdf>,
  "tags": ["receipt"]
}

POST /api/v1/sales/invoices/90001/documents
{
  "file": <receipt.pdf>,
  "tags": ["receipt", "proof_of_payment"]
}

Shipping Integration

Link shipping documents across workflow:

bash

# Upload to order (fulfillment perspective)
POST /api/v1/sales/orders/80001/documents
{
  "file": <shipping_label.pdf>,
  "tags": ["shipping_label"]
}

# Same document could reference invoice for commercial shipping
# Documents attached at appropriate entity level

Best Practices

1. Order Documentation

Complete Order Records:

Upload confirmation immediately after order creation
Add shipping documents during fulfillment
Link invoice and payment documents
Maintain complete audit trail for customer service

Naming Conventions:

Include order number in document names
Reference tracking numbers in descriptions
Use consistent tag combinations

International Orders:

Always upload customs documentation
Include commercial invoices
Store shipping manifests
Keep copies of all export documents

2. Invoice Management

Invoice Generation:

Upload official invoice PDF immediately after generation
Use invoice_pdf tag consistently
Store tax-compliant versions separately if needed
Version invoices if corrections needed

Payment Tracking:

Link payment receipts to invoices immediately
Upload proof of payment for wire transfers
Document all partial payments separately
Maintain clear payment history

Tax Compliance:

Tag all tax invoices with tax_document
Store VAT-compliant versions separately
Keep records for required retention period
Include all required tax information

3. Payment Documentation

Transaction Records:

Upload payment receipts for every transaction
Document authorization codes for card payments
Store bank confirmations for wire transfers
Maintain proof of payment for all methods

Refund Management:

Document refund authorizations
Upload refund receipts
Link to original payment for reference
Track partial vs full refunds

Dispute Handling:

Upload chargeback notices immediately
Organize evidence documents systematically
Tag all dispute-related documents consistently
Maintain timeline of dispute resolution

4. Security and Compliance

Data Protection:

Mark all sales documents as private
Restrict access to finance and sales teams
Never expose payment details publicly
Comply with PCI-DSS for card data

Audit Trail:

Never hard-delete financial documents
Maintain complete transaction history
Document all refunds and chargebacks
Keep records per regulatory requirements

Document Retention:

Retain invoices per tax law requirements (typically 7 years)
Keep payment records for accounting periods
Store customs documents per trade regulations
Archive vs delete based on compliance needs

Troubleshooting

Common Issues

Problem: Invoice PDF not uploading

Solution:

Check file size is under 10 MB
Verify PDF is not corrupted
Ensure proper MIME type
Try re-generating PDF if issue persists

Problem: Payment receipt not linked to invoice

Solution:

Upload receipt to both payment and invoice entities
Use consistent tags (receipt, proof_of_payment)
Cross-reference document IDs in descriptions
Query both entities to verify upload

Problem: Cannot find order shipping documents

Solution:

Verify tags used during upload (shipping_label, delivery_note)
Check filters in query parameters
Search by document name or description
Use include_archived=true if documents were replaced

Problem: Chargeback evidence upload fails

Solution:

Combine multiple evidence files into single PDF
Check file size limit (10 MB)
Verify file type is supported
Upload supplementary evidence as separate documents

Main Document Management Guide - System-wide documentation
Order Management - Complete order management
Invoice Generation - Invoice workflows
Payment Processing - Payment handling
Order-to-Cash Workflow - Complete workflow documentation

API Reference

For complete API specifications:

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

Sales Module - Document Management ​

Overview ​

Supported Entities ​

Order Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Order Fulfillment Documentation ​

Scenario 2: International Shipping with Customs ​

Scenario 3: Order-Invoice Linking ​

Validation Rules ​

Invoice Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Invoice Generation and Payment ​

Scenario 2: Proforma to Final Invoice ​

Scenario 3: Credit Notes and Refunds ​

Scenario 4: Tax Documentation ​

Validation Rules ​

Payment Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Credit Card Payment ​

Scenario 2: Wire Transfer Payment ​

Scenario 3: Refund Processing ​

Scenario 4: Chargeback Dispute ​

Validation Rules ​

Cross-Entity Workflows ​

Order-to-Invoice-to-Payment Flow ​

Shipping Integration ​

Best Practices ​

1. Order Documentation ​

2. Invoice Management ​

3. Payment Documentation ​

4. Security and Compliance ​

Troubleshooting ​

Common Issues ​

Related Documentation ​

API Reference ​

Sales Module - Document Management

Overview

Supported Entities

Order Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Order Fulfillment Documentation

Scenario 2: International Shipping with Customs

Scenario 3: Order-Invoice Linking

Validation Rules

Invoice Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Invoice Generation and Payment

Scenario 2: Proforma to Final Invoice

Scenario 3: Credit Notes and Refunds

Scenario 4: Tax Documentation

Validation Rules

Payment Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Credit Card Payment

Scenario 2: Wire Transfer Payment

Scenario 3: Refund Processing

Scenario 4: Chargeback Dispute

Validation Rules

Cross-Entity Workflows

Order-to-Invoice-to-Payment Flow

Shipping Integration

Best Practices

1. Order Documentation

2. Invoice Management

3. Payment Documentation

4. Security and Compliance

Troubleshooting

Common Issues

Related Documentation

API Reference