# 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.

## 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 and goods-receipt matching 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 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 --> I[Transition AP document to REGISTERED]
    I --> J[Sync purchase-order billing status]
    J --> K[Return registered AP document]
```

## External Dependencies

- [listPurchaseReceiptQuantitiesForMatching](../../../inventory/docs/query/ListPurchaseReceiptQuantitiesForMatching.md) - Provides posted goods-receipt quantities per purchase order line for matching
- [recalculatePurchaseOrderBillingStatus](../../../purchase/docs/command/RecalculatePurchaseOrderBillingStatus.md) - Recalculates PO billing progress from registered AP invoice quantities

## Error Scenarios

- **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
- 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
