# CreateAccountPayableDocument

## Permission Scope

accountPayableDocument

## Overview

createAccountPayableDocument creates a DRAFT AP document with its payable control account, initial commercial lines, line-owned posting distributions, and optional payable due schedule lines. It validates partner, currency, payable control account, total amount, line gross totals, distribution totals, and any provided due schedule, but it does not create journal entries. Accounting event creation starts only when postAccountPayableDocument runs.

## Business Rules

- Creates the document in DRAFT status
- Requires an existing company, business partner, currency, and ACTIVE payable control account
- Requires at least one line
- Requires at least one distribution under each line
- Header total amount must be positive
- Every line net and gross amount must be positive
- Every distribution amount must be positive
- Sum of line gross amounts must equal totalAmount
- Sum of each line's distribution amounts must equal that line's gross amount
- Sum of all distribution amounts must equal totalAmount
- If due schedule lines are provided, each due amount must be positive and the due schedule total must equal totalAmount
- Every distribution must reference an existing ACTIVE posting account
- The payable control account is stored on the AP document header
- Lines are inserted with the new document
- Distributions are inserted under the new document lines
- Due schedule lines are inserted under the new document
- A line is either purchase-order sourced (sourceType PURCHASE_ORDER) carrying a purchase order line reference, positive quantity, positive unit price, and a unit of measure, or amount-only carrying none of them
- A purchase-order sourced line net amount must equal quantity times unit price

## Process Flow

```mermaid
flowchart TD
    A[Receive create AP document request] --> B{Company exists?}
    B -->|No| C[Return error: company not found]
    B -->|Yes| D{Business partner exists?}
    D -->|No| E[Return error: business partner not found]
    D -->|Yes| F{Currency exists?}
    F -->|No| G[Return error: currency not found]
    F -->|Yes| H{Amounts and lines valid?}
    H -->|No| I[Return validation error]
    H -->|Yes| N{Payable control account exists?}
    N -->|No| O[Return error: account not found]
    N -->|Yes| J[Create AP document in DRAFT]
    J --> K[Create AP document lines]
    K --> L[Create AP distribution lines]
    L --> P[Create AP due schedule lines when provided]
    P --> M[Return created AP document]
```

## External Dependencies

- [coa-management::ListAccounts](../../../coa-management/docs/query/ListAccounts.md) - Validates payable control and distribution GL accounts exist and are ACTIVE

## Error Scenarios

- **COMPANY_NOT_FOUND**: Referenced company does not exist
- **AP_BUSINESS_PARTNER_NOT_FOUND**: Referenced business partner does not exist
- **AP_CURRENCY_NOT_FOUND**: Referenced currency does not exist
- **AP_MINIMUM_LINES_NOT_MET**: AP document must have at least one line and one distribution
- **AP_INVALID_AMOUNT**: AP document or line amount must be positive
- **AP_LINE_TOTAL_MISMATCH**: AP line gross total or distribution total does not match the document total
- **AP_LINE_SOURCE_INCONSISTENT**: AP line source type, purchase order line, quantity, unit price, and unit are not consistent
- **AP_LINE_AMOUNT_MISMATCH**: AP line net amount does not equal quantity times unit price
- **AP_DUE_SCHEDULE_INVALID**: AP due schedule must have positive amounts and sum to the document total
- **ACCOUNT_NOT_FOUND**: Referenced payable control or distribution GL account does not exist
- **ACCOUNT_INACTIVE**: Referenced payable control or distribution GL account is not ACTIVE

## Test Cases

- creates DRAFT AP document with lines and distributions
- passes custom header and line fields through to inserts
- returns error when company does not exist
- returns error when business partner does not exist
- returns error when currency does not exist
- returns error when no lines are provided
- returns error when total amount is not positive
- returns error when line gross total does not match document total
- returns error when distribution total does not match document total
- creates DRAFT AP document with multiple due schedule lines
- returns error when due schedule total does not match document total
- returns error when a purchase-order sourced line omits the purchase order line reference
- returns error when a purchase-order sourced line is missing a unit
- returns error when a purchase-order sourced line net amount does not equal quantity times unit price
- returns error when distribution account does not exist
- returns error when distribution account is inactive
- returns error when payable control account does not exist
- returns error when payable control account is inactive
