# GetPurchaseBill

## Overview

GetPurchaseBill retrieves a supplier bill together with its matching outcome, payable schedule snapshot, tax snapshot, and line-level purchase references.

## Business Rules

- Accepts lookup by `{ id }` or by `{ companyId, supplierId, invoiceNumber }`
- Returns bills in any status so blocked, matched, and cancelled evidence remains available for audit
- Response includes matching mode, variance reason, and due-schedule lines when available
- Returns null when no purchase bill matches the lookup

## Process Flow

```mermaid
flowchart TD
    A[Receive lookup input] --> B{Lookup by id or supplier invoice identity?}
    B -->|id| C[Select PurchaseBill by id]
    B -->|invoice identity| D[Select PurchaseBill by company + supplier + invoice number]
    C --> E{Bill found?}
    D --> E
    E -->|Yes| F[Load bill lines, tax snapshot, and due schedule]
    E -->|No| G[Return null]
    F --> H[Return purchase bill]
```

## External Dependencies

- None

## Error Scenarios

- **PURCHASE_BILL_NOT_FOUND**: No purchase bill matches the given lookup; caller receives null

## Test Cases

- returns purchase bill when found by id
- returns purchase bill when found by supplier invoice identity
- returns matching outcome and due schedule with the bill
- returns null when purchase bill is not found
