Create purchase order

Creates a new purchase order to track purchase commitments before invoices are received. This endpoint handles three types of purchase orders with comprehensive validation and automatic folio generation.

Purchase Order Types

1. Against Invoice

Single invoice purchase order with exactly one item at 100%.

Use case: Simple purchases with a single invoice expected.

Example: Purchasing office equipment for $10,000 CLP.

2. By Milestone

Multiple named deliverables with individual percentages.

Use case: Projects with defined stages and separate invoicing for each stage.

Example: Software project with Design (30%), Development (50%), Testing (20%).

3. By Percentage

Multiple payment stages with percentages (no names required).

Use case: Service contracts with payment schedule.

Example: Consulting service with 30% advance, 50% mid-project, 20% final payment.

Prerequisites

Before creating a purchase order, you need:

1. Business Partner: The vendor/supplier for this purchase

   • Must be pre-registered and approved
   • Find partners: GET /v1/erp/payouts/business_partners

2. Company: The company making the purchase

   • User must be a member with appropriate role
   • Required roles: admin, owner, or member

Validation Rules

General Rules (All Types)

• amount_cents: Must be positive integer (in cents)
• description: Required field for purchase reference
• currency: Must be one of: CLP, UF, USD
• items: Must have at least one item
• percentages: Item percentages must sum to exactly 100%

Type-Specific Rules

AgainstInvoice:

• Must have exactly 1 item
• Item percentage must be 100%
• Item name is optional (not required)

ByMilestone:

• Must have at least 1 item
• Each item must have a name
• Item percentages must sum to 100%

ByPercentage:

• Must have at least 2 items
• Item names are optional (not required)
• Item percentages must sum to 100%

Automatic Features

Folio Generation

System automatically generates a folio: a per-company sequential integer (1, 2, 3, ...), unique within the company. It is not a formatted string.

Item Amount Calculation

System automatically calculates item amounts based on percentages:

• Formula: item.amount_cents = (total_amount_cents × percentage / 100).round
• Automatically recalculated when total amount changes

Creator Tracking

System automatically assigns current authenticated user as creator (user_id).

Workflow

1. Purchase order is created with status draft
2. Admin/creator assigns reviewers to items (if approval required)
3. Reviewers approve or reject items independently
4. When fiscal invoice arrives, it's linked to approved items
5. Linked items can be paid via bank transactions
6. When all items are paid, purchase order is considered complete

Important Notes

• Regular users can only create purchase orders for companies they are members of
• All amounts are in the smallest currency unit (cents for CLP)
• Item amounts are automatically calculated from percentages
• Full audit trail is maintained for all changes

{
  "purchase_order": {
    "type": "Erp::Payouts::PurchaseOrders::AgainstInvoice",
    "business_partner_id": "8e668a4e-8485-4248-86cc-a7a2201cf8c3",
    "description": "Office equipment - 5 laptops",
    "amount_cents": 10000000,
    "currency": "CLP",
    "items_attributes": [
      {
        "number": 1,
        "name": "Design and Requirements Analysis",
        "percentage": 100
      }
    ]
  }
}