# RegisterAccountPayableDocument

## Permission Scope

accountPayableDocument

## Overview

registerAccountPayableDocument accepts a DRAFT AP document for accounting review and posting. Registration locks the AP header, lines, distributions, and due schedule but does not create a journal entry. The journal is created and posted by postAccountPayableDocument. Registration reconciles purchase-order matching holds so that variances are surfaced as early as possible, snapshots the order price each purchase-order sourced line was matched against, and re-derives the system-owned accrual/invoice price variance distribution split against that price so an order repriced since creation cannot leave a stale split behind.

## Business Rules

- Only DRAFT AP documents can be registered
- The document must have at least one line
- Line total must match the document total
- The document must have at least one due schedule line
- Due schedule amounts must sum to the document total
- Registration sets registeredAt
- Registration does not create JournalEntry or JournalLine rows
- Registration reconciles SYSTEM payment holds from purchase-order matching, comparing invoiced quantity against the ordered and received quantity projections on the purchase-order line, for purchase-order sourced lines
- Registration applies invoice tolerance by supplier: an InvoiceToleranceConfig row for the AP document company and supplier relaxes unit price and quantity variance checks when configured
- Registration succeeds even when matching places active holds; holds block posting, not registration
- Registration writes each purchase-order sourced line's `matchedPurchaseOrderUnitPrice` from the purchase order line it matched against, fixing the base price posting measures variances from
- Registration replaces the derived (non-MANUAL) distributions of receipt-required purchase-order lines with rows re-derived at the matched price, leaving caller-supplied MANUAL rows untouched; the rows still sum to the line net amount, so the validated totals are unaffected
- Registration feeds purchase-order billing progress back to purchase for INVOICE documents with purchase-order sourced lines

## Process Flow

```mermaid
flowchart TD
    A[Receive register AP document request] --> B{Document exists?}
    B -->|No| C[Return error: AP document not found]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return error: invalid AP document status]
    D -->|Yes| F{Lines and due schedule valid?}
    F -->|No| G[Return validation error]
    F -->|Yes| H[Reconcile purchase-order matching holds]
    H --> H2[Snapshot the matched order price on PO-sourced lines]
    H2 --> H3[Re-derive the accrual/invoice-price-variance split at the matched price]
    H3 --> I[Transition AP document to REGISTERED]
    I --> J[Sync purchase-order billing status]
    J --> K[Return registered AP document]
```

## External Dependencies

- [listPurchaseOrderLinesForMatching](../../../purchase/docs/query/ListPurchaseOrderLinesForMatching.md) - Provides ordered and received quantity projections per purchase order line for matching
- [recalculatePurchaseOrderBillingStatus](../../../purchase/docs/command/RecalculatePurchaseOrderBillingStatus.md) - Recalculates PO billing progress from registered AP invoice quantities
- [inventory::ResolveItemValuationPolicies](../../../inventory/docs/query/ResolveItemValuationPolicies.md) - Resolves the valuation policy whose accrual and invoice price variance accounts the re-derived split posts to

## Error Scenarios

- **AP_PURCHASE_ORDER_ACCOUNT_MISMATCH**: Referenced purchase order belongs to a different company or supplier account

- **AP_DOCUMENT_NOT_FOUND**: Referenced AP document does not exist
- **AP_INVALID_DOCUMENT_STATUS**: AP document status does not allow this operation
- **AP_MINIMUM_LINES_NOT_MET**: AP document must have at least one line and one distribution
- **AP_LINE_TOTAL_MISMATCH**: AP line gross total or distribution total does not match the document total
- **AP_DUE_SCHEDULE_INVALID**: AP due schedule must have positive amounts and sum to the document total
- **AP_PURCHASE_ORDER_BILLING_SYNC_FAILED**: Purchase-order billing status sync failed for the AP document

## Test Cases

- registers DRAFT AP document without creating a journal entry
- snapshots the matched purchase order unit price on registration
- re-derives the accrual and signed invoice price variance distributions against the matched price
- registers but places a system hold when the invoiced unit differs from the purchase order
- registers but places a system hold when the invoiced unit price differs from the purchase order
- registers without placing a system hold when supplier tolerance covers the variance
- returns error when AP document does not exist
- returns error when AP document is not DRAFT
- returns error when AP document has no lines
- returns error when line total does not match document total
- returns error when distribution total does not match document total
- returns error when AP document has no due schedule
- returns error when due schedule total does not match document total
- returns error when purchase-order billing sync fails