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

# Tax Reporting & Compliance — Integration

> This document describes the integration interfaces between FA-10 (Tax Reporting & Compliance) and linked systems: FA-03 (Accounts Payable), HR-07 (Payroll), an…

**Spec ID:** FA-10\
**Status:** 📝 Planned\
**Last Updated:** 2026-02-12

This document describes the integration interfaces between FA-10 (Tax Reporting & Compliance) and linked systems: FA-03 (Accounts Payable), HR-07 (Payroll), and PF (Notifications, Documents).

***

## Integration Summary

| From  | To    | Pattern        | Description                                                                              |
| ----- | ----- | -------------- | ---------------------------------------------------------------------------------------- |
| FA-10 | PF-10 | Event          | Tax form generated / tax year closed → notifications (deadlines, delivery confirmations) |
| FA-10 | PF-11 | Platform Layer | Tax form PDF storage via Documents                                                       |
| HR-07 | FA-10 | API / Event    | Payroll data for W-2 and 941/940; `payroll_run_completed` event                          |
| FA-03 | FA-10 | API / Event    | Vendor payments for 1099; `vendor_payment_processed` event                               |

***

## Event Contracts (FA-10 as Publisher)

* **`tax_1099_generated`** — PF-10 (Notifications). Payload: `organization_id`, `tax_year_id`, `vendor_id`, `form_type`, `generated_at`. See [EVENT\_CONTRACTS.md](/architecture/integrations/EVENT_CONTRACTS) when implemented.
* **`tax_w2_generated`** — PF-10, HR-07. Payload: `organization_id`, `tax_year_id`, `employee_id`, `generated_at`.
* **`tax_year_closed`** — PF-10, FA-07. Payload: `organization_id`, `tax_year_id`, `tax_year`, `closed_at`, `closed_by`.

## Event Contracts (FA-10 as Consumer)

* **`payroll_run_completed`** (HR-07) — Trigger W-2 generation.
* **`vendor_payment_processed`** (FA-03) — Update 1099 totals.

***

## API Contracts

**APIs Exposed by FA-10:**

* `POST /api/v1/fa/tax/1099/generate` — Request: `tax_year_id`, optional `form_type`. Response: job or form identifiers. Internal (FA module) only.

**APIs Consumed by FA-10:**

* `/api/v1/hr/payroll/tax-data` (HR-07) — Payroll data for W-2 and 941/940.
* `/api/v1/fa/vendors/payments` (FA-03) — Vendor payments for 1099.

Full request/response schemas to be defined in implementation plan or OpenAPI.

***

## CROSS\_CORE\_INTEGRATIONS.md

FA-10 is already referenced in [CROSS\_CORE\_INTEGRATIONS.md](/architecture/integrations/CROSS_CORE_INTEGRATIONS) (events and APIs). This doc is the detailed integration reference for FA-10.

***

## Dual-System Architecture: HR-PAY-04 vs FA-10

Tax forms are generated by **two independent systems** with different data sources:

| System        | Data Source                                                | Form Types                                                                       | Authoritative For                                               |
| ------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **HR-PAY-04** | Payroll runs (hr\_payroll\_runs, hr\_payroll\_line\_items) | W-2, W-3, 941, 940, AZ A1-QRT, AZ A1-R, 1099-NEC (payroll contractors), New Hire | Employee wage statements, employer payroll tax returns          |
| **FA-10**     | General ledger (fa\_journal\_entries, fa\_transactions)    | 1099-NEC/MISC (AP vendors), W-2 (GL reconciliation), 941 (GL view)               | Vendor 1099s from Accounts Payable, GL-based tax reconciliation |

### Key Design Decisions

1. **HR-PAY-04 is authoritative for payroll-derived forms** (W-2, 941, 940). These are generated from actual payroll run data with employee-level detail.
2. **FA-10 is authoritative for AP-derived 1099s**. Vendor payments tracked through Accounts Payable generate 1099-NEC/MISC forms.
3. **Cross-core sync**: HR-PAY-04 publishes `hr.employer_tax_liability.calculated` events via Supabase Realtime (`hr_events` channel). FA subscribes for GL posting of employer FICA, FUTA, and SUTA liabilities.
4. **No direct imports**: Integration uses event-based patterns only. HR-PAY-04 never imports from FA, and vice versa.

### Event Flow

```
HR-PAY-04 (quarterly run) → publishEmployerTaxLiabilityEvent()
  → Supabase Realtime channel: hr_events
    → FA listener: creates GL journal entries for employer tax liabilities
```

***

## Spec Reference

* **HR-PAY-04 Spec:** [HR-PAY-04 Tax Forms & Compliance](https://github.com/Encore-OS/encoreos/blob/development/specs/hr/specs/HR-PAY-04-tax-forms-compliance.md)
* **FA-10 Spec:** [FA-10 Tax Reporting & Compliance](https://github.com/Encore-OS/encoreos/blob/development/specs/fa/specs/FA-10-tax-reporting-compliance.md)