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

# FA-05 Enhancement: Recurring Invoicing & Collections - Integration Documentation

> This document covers integration points for the FA-05 Enhancement (Recurring Invoicing, Payment Plans, and Collection Workflow).

**Spec:** `specs/fa/specs/FA-05-ENHANCEMENT-recurring-invoicing-collections.md`\
**Owner:** FA (Finance & Accounting)\
**Created:** 2026-04-26\
**Status:** ✅ Implemented (2026-04-27)

***

## Integration Overview

This document covers integration points for the FA-05 Enhancement (Recurring Invoicing, Payment Plans, and Collection Workflow).

***

## Platform Foundation (PF) Integrations

### PF-01 (Organizations & Sites)

* **Type:** Direct dependency
* **Usage:** `organization_id` on all tables for multi-tenant isolation
* **Direction:** FA-05 Enhancement → PF-01

### PF-02 (RBAC)

* **Type:** Direct dependency
* **Usage:** Permission checks for AR operations using `fa_has_recurring_invoice_access()` and `fa_is_org_admin()` SECURITY DEFINER functions
* **Direction:** FA-05 Enhancement → PF-02

### PF-10 (Notifications)

* **Type:** Platform Integration Layer via `@/platform/notifications`
* **Usage:** Invoice generation notifications, collection notices, overdue installment alerts
* **Events consumed:** None
* **Events published:**
  * `recurring_invoice.generated` → triggers email/in-app notification to customer
  * `payment_plan.installment_due` → triggers reminder notification
  * `payment_plan.installment_overdue` → triggers overdue alert
  * `collection.workflow_started` → triggers collection notice to customer
  * `bad_debt.written_off` → triggers internal notification to finance team

***

## Forms & Workflow (FW) Integration

### FW-03 (Workflow Engine)

* **Type:** Platform Integration Layer
* **Usage:** Payment plan approval, collection workflow automation, bad debt write-off approval

#### Payment Plan Approval

* **Trigger Event:** `payment_plan.submitted_for_approval`
* **Payload:** `{ payment_plan_id: UUID, customer_id: UUID, total_amount: DECIMAL, organization_id: UUID }`
* **Condition:** Triggered when `total_amount > payment_plan_approval_threshold` (from `fa_module_settings`)
* **Outcome:** Workflow approval → payment plan status changes from 'pending\_approval' to 'approved'/'active'

#### Collection Workflow

* **Trigger Event:** `invoice.past_due_threshold`
* **Payload:** `{ invoice_id: UUID, customer_id: UUID, days_past_due: INTEGER, balance_due: DECIMAL, organization_id: UUID }`
* **Default Template:** Notice (Day 1) → Follow-up Notice (Day 15) → Final Notice (Day 30) → Write-off Review (Day 60)
* **Outcome:** Automated escalation through collection steps with PF-10 notifications at each stage

#### Bad Debt Write-Off Approval

* **Trigger Event:** `bad_debt.write_off_requested`
* **Payload:** `{ invoice_id: UUID, customer_id: UUID, write_off_amount: DECIMAL, reason: TEXT, organization_id: UUID }`
* **Outcome:** Approval → creates FA-02 journal entry, updates invoice status, creates bad debt reserve record

***

## FA-02 (General Ledger) Integration

* **Type:** Direct data dependency (same core)
* **Usage:** Bad debt write-off creates journal entries
* **Direction:** FA-05 Enhancement → FA-02
* **Tables Referenced:** `fa_journal_entries` (FK from `fa_bad_debt_reserves.journal_entry_id`)

***

## Edge Function Contracts

### `fa-generate-recurring-invoices`

* **Schedule:** Hourly (`0 * * * *`)
* **Auth:** Service-role key (cron-triggered)
* **Input:** None (queries `fa_recurring_invoices` where `status = 'active'` and `next_generation_date <= now()`)
* **Output:** Creates `fa_invoices` records, publishes `recurring_invoice.generated` events
* **Error Handling:** Logs errors per template; does not advance `next_generation_date` on failure

### `fa-check-collection-thresholds`

* **Schedule:** Daily at midnight (`0 0 * * *`)
* **Auth:** Service-role key (cron-triggered)
* **Input:** None (queries past-due invoices against `collection_threshold_days` setting)
* **Output:** Creates FW-03 workflow instances, publishes `invoice.past_due_threshold` events

### `fa-check-installment-due-dates`

* **Schedule:** Daily at 6 AM (`0 6 * * *`)
* **Auth:** Service-role key (cron-triggered)
* **Input:** None (queries `fa_payment_plan_installments` for upcoming/overdue due dates)
* **Output:** Publishes `payment_plan.installment_due` and `payment_plan.installment_overdue` events

***

## Security & Tenant Isolation

* All integrations include `organization_id` in event payloads
* Edge functions filter by `organization_id` for all queries
* RLS policies enforce tenant isolation on all FA-05 Enhancement tables
* SECURITY DEFINER functions (`fa_has_recurring_invoice_access`, `fa_is_org_admin`) used for RLS helpers

***

**Last Updated:** 2026-04-26