# CorrectAccountReceivableDocument

## Permission Scope

accountReceivableDocumentOperation

## Overview

correctAccountReceivableDocument atomically creates and posts an AR correction document for a POSTED AR document. The original document remains immutable. Header, line, and distribution correction references preserve provenance, while the correction creates its own journal entry, due schedule, and sales-order billing effect.

## Business Rules

- Only POSTED AR documents can be corrected
- The correction inherits company, customer, and currency from the corrected document
- A correction document is created directly in POSTED status
- At least one correction line, distribution, and due-schedule line is required
- Correction amounts remain positive; documentType determines whether AR exposure increases or decreases
- Every correction line references a line on the corrected document
- PRICE and QUANTITY corrections require a sales-order sourced corrected line
- AMOUNT corrections can target sales-order sourced or amount-only lines
- Sales-order source identifiers and units cannot be changed by a correction
- Distribution correction references must belong to the corrected line
- Sales-order sourced correction lines snapshot the current sales-order unit price
- QUANTITY corrections change sales-order billed quantity; PRICE and AMOUNT corrections do not
- The correction journal entry is created and posted in the same transaction
- Sales-order billing quantities are synchronized after accounting succeeds

## Process Flow

```mermaid
flowchart TD
    A[Lock corrected AR document] --> B{Document is POSTED?}
    B -->|No| C[Return invalid status]
    B -->|Yes| D[Validate correction references and totals]
    D --> E[Resolve accounts and accounting period]
    E --> F[Create POSTED correction document and children]
    F --> G[Create and post journal entry]
    G --> H[Synchronize sales-order billing]
```

## External Dependencies

- organization getCompany
- customerAccounts getCustomerAccount
- primitives getCurrency
- coa-management listAccounts
- financial-accounting getPeriodByDate, createJournalEntry, and postJournalEntry
- sales recalculateSalesOrderBillingStatus

## Error Scenarios

- **INVALID_CUSTOMER_ACCOUNT**: Business partner is unavailable for transactions or belongs to another company

- **DOCUMENT_NOT_FOUND**: Referenced AR document does not exist
- **INVALID_DOCUMENT_STATUS**: AR document status does not allow this operation
- **DOCUMENT_LINE_NOT_FOUND**: A correction line targets another document
- **DISTRIBUTION_LINE_NOT_FOUND**: A distribution target is missing or belongs to another line
- **LINE_SOURCE_INCONSISTENT**: Sales-order source fields are incomplete or inconsistent
- **DUE_SCHEDULE_INVALID**: Due schedule must be positive and equal the document total
- **ACCOUNTING_PERIOD_NOT_FOUND**: No open accounting period contains the posting date
- **JOURNAL_ENTRY_CREATE_FAILED**: Invoice journal entry could not be created
- **JOURNAL_ENTRY_POST_FAILED**: Invoice journal entry could not be posted
- **SALES_ORDER_BILLING_SYNC_FAILED**: Sales-order billing projection could not be synchronized

## Test Cases

- creates and posts a correction with provenance, accounting, and sales feedback
- rejects correction of a document that is not posted
- rejects a correction line outside the corrected document
- rejects a correction distribution outside the corrected line
- rejects price corrections for amount-only lines
- requires a complete due schedule