> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts Payable Automation – Integration

> FA-22 adds invoice scan/OCR, duplicate detection, and 3-way match automation. It integrates with PF-27 (Platform AI), FA-03/FA-04 (bills, POs, receipts), and F…

**Spec:** [specs/fa/specs/FA-22-accounts-payable-automation.md](https://github.com/Encore-OS/encoreos/blob/development/specs/fa/specs/FA-22-accounts-payable-automation.md)\
**Status:** 📝 Planned\
**Constitution:** §1.3 (Integration Patterns), §2.1 (Integration documentation)

***

## Overview

FA-22 adds invoice scan/OCR, duplicate detection, and 3-way match automation. It integrates with PF-27 (Platform AI), FA-03/FA-04 (bills, POs, receipts), and FW-16 (workflow events).

***

## Integration Points (from spec)

| Dependency        | Pattern                        | Purpose                                                                                                                                 |
| ----------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **PF-27 (AI)**    | Platform Layer (edge function) | Document extraction in `fa-scan-invoice`; no PHI in prompts.                                                                            |
| **FA-03 / FA-04** | Same core (FA)                 | Read fa\_vendor\_bills, fa\_purchase\_orders, fa\_po\_receipts; write/update fa\_vendor\_bills when linking scan or flagging duplicate. |
| **FW-16**         | Event-Based                    | Publish `fa_bill_scan_completed`, `fa_bill_duplicate_flagged` for workflow subscriptions.                                               |

***

## Event Contracts (FW-16)

**Channel:** `fa_events` (or equivalent).\
**Subscribers:** FW-16 (Workflow Events) – register event\_type values below for workflow triggers.

Canonical event names use snake\_case past-tense: **fa\_bill\_scan\_completed**, **fa\_bill\_duplicate\_flagged**. Full contracts: [EVENT\_CONTRACTS.md](/architecture/integrations/EVENT_CONTRACTS#fa-22-accounts-payable-automation-events).

### fa\_bill\_scan\_completed

**When:** After invoice scan completes and result is stored in fa\_invoice\_scans.

**Payload schema (JSON):**

| Field             | Type              | Required | Description                |
| ----------------- | ----------------- | -------- | -------------------------- |
| event\_type       | string            | yes      | `"fa_bill_scan_completed"` |
| organization\_id  | uuid              | yes      | Tenant scope               |
| timestamp         | string (ISO 8601) | yes      | Event time                 |
| user\_id          | uuid              | no       | When user-initiated        |
| correlation\_id   | string            | no       | When chaining events       |
| scan\_id          | uuid              | yes      | fa\_invoice\_scans.id      |
| vendor\_bill\_id  | uuid \| null      | yes      | Set when linked to bill    |
| confidence\_score | number            | yes      | OCR confidence             |
| scanned\_text     | string            | no       | Optional extracted text    |
| scan\_status      | string            | no       | e.g. success, partial      |
| source\_system    | string            | no       | e.g. fa-scan-invoice       |
| metadata          | object            | no       | Extra key-value            |

**Example payload:**

```json theme={null}
{
  "event_type": "fa_bill_scan_completed",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-12T12:00:00Z",
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "scan_id": "770e8400-e29b-41d4-a716-446655440002",
  "vendor_bill_id": null,
  "confidence_score": 0.92,
  "scan_status": "success",
  "source_system": "fa-scan-invoice"
}
```

### fa\_bill\_duplicate\_flagged

**When:** After duplicate detection creates a fa\_duplicate\_detection\_log entry.

**Payload schema (JSON):**

| Field                        | Type              | Required | Description                      |
| ---------------------------- | ----------------- | -------- | -------------------------------- |
| event\_type                  | string            | yes      | `"fa_bill_duplicate_flagged"`    |
| organization\_id             | uuid              | yes      | Tenant scope                     |
| timestamp                    | string (ISO 8601) | yes      | Event time                       |
| user\_id                     | uuid              | no       | When user-initiated              |
| correlation\_id              | string            | no       | When chaining (e.g. batch)       |
| vendor\_bill\_id             | uuid              | yes      | Bill that was flagged            |
| suspected\_duplicate\_of\_id | uuid              | yes      | Existing bill it matches         |
| match\_score                 | number            | yes      | Similarity score                 |
| match\_reason                | string            | yes      | Short reason                     |
| log\_id                      | uuid              | yes      | fa\_duplicate\_detection\_log.id |
| invoice\_id                  | string            | no       | Invoice number if available      |
| detected\_duplicates         | array             | no       | Optional list of match ids       |
| source\_system               | string            | no       | e.g. fa-detect-duplicates        |
| metadata                     | object            | no       | Extra key-value                  |

**Example payload:**

```json theme={null}
{
  "event_type": "fa_bill_duplicate_flagged",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-12T12:05:00Z",
  "vendor_bill_id": "880e8400-e29b-41d4-a716-446655440003",
  "suspected_duplicate_of_id": "990e8400-e29b-41d4-a716-446655440004",
  "match_score": 0.98,
  "match_reason": "Same vendor, amount within 2%, date within 30 days",
  "log_id": "aa0e8400-e29b-41d4-a716-446655440005",
  "source_system": "fa-detect-duplicates"
}
```

***

## API / Edge Functions

* **fa-scan-invoice:** Invokes PF-27 for extraction; writes to fa\_invoice\_scans and storage bucket `fa-invoice-scans`. No direct API contract with other cores; called from FA UI.
* **fa-detect-duplicates:** Runs on bill insert or cron; writes fa\_duplicate\_detection\_log. Internal to FA.
* **fa-auto-match-3way:** Returns suggested matches for PO-Receipt-Bill; internal to FA or called from FA UI.

***

## Security & Tenant Isolation

* All FA-22 tables and storage bucket are scoped by `organization_id`.
* PF-27 calls use edge function only; no PHI in prompts (anonymized identifiers if needed).
* Event payloads include `organization_id` for subscriber filtering.

***

## Cross-Core Integration Matrix

See [CROSS\_CORE\_INTEGRATIONS.md](/architecture/integrations/CROSS_CORE_INTEGRATIONS): FA → FW-16 (Event) for fa\_bill\_scan\_completed and fa\_bill\_duplicate\_flagged.