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

# HR-PAY-08-AZ: Arizona E-Filing — Outbound Integration

> This document describes the outbound integration from Encore OS to Arizona Department of Revenue (AZ DOR) and Arizona Department of Economic Security (AZ DES).…

**Spec ID:** HR-PAY-08-AZ\
**Status:** 📝 Planned\
**Last Updated:** 2026-02-16

This document describes the **outbound** integration from Encore OS to Arizona Department of Revenue (AZ DOR) and Arizona Department of Economic Security (AZ DES). No cross-core dependencies; integration is external agency only.

***

## Integration Summary

| From         | To     | Pattern  | Protocol                      | Phase     | Description                                                            |
| ------------ | ------ | -------- | ----------------------------- | --------- | ---------------------------------------------------------------------- |
| HR-PAY-08-AZ | AZ DOR | Outbound | SOAP Web Services (AZFSET)    | Phase 2   | A1-QRT, A1-R, A1-APR, W-2/W-2c state data via AZFSET `SendSubmissions` |
| HR-PAY-08-AZ | AZ DOR | Outbound | File Download (Manual Upload) | Phase 1   | XML file generation for manual upload to AZFSET portal                 |
| HR-PAY-08-AZ | AZ DES | Outbound | SFTP over SSH                 | Phase 2/3 | New hire CSV upload to AZ DES SFTP server                              |
| HR-PAY-08-AZ | AZ DES | Outbound | File Download (Manual Upload) | Phase 1   | CSV file generation for manual upload to AZ DES portal                 |

***

## AZ DOR (Arizona Department of Revenue)

### AZFSET SOAP Web Services API

* **API Version:** Implementation Guide v1.5
* **Protocol:** SOAP 1.1/1.2 with MTOM attachments
* **Authentication:** WS-Security username/password token per request
  * SAML and X.509 documented but "not released for use at this time"
* **Credentials:** Stored in Lovable Cloud Secrets (`AZ_DOR_WS_USERNAME`, `AZ_DOR_WS_PASSWORD`)

### Endpoints

| Environment | Base URL                                 | Purpose                |
| ----------- | ---------------------------------------- | ---------------------- |
| Production  | `efile.azdor.gov/fset/{ServiceName}`     | Live submissions       |
| Test        | `quatefile.azdor.gov/fset/{ServiceName}` | Validation and testing |

### Available Services

| Service           | Purpose                                  | Request                     |
| ----------------- | ---------------------------------------- | --------------------------- |
| `SendSubmissions` | Submit returns (XML in nested ZIP, MTOM) | Submission package          |
| `GetNewAcks`      | Retrieve unread acknowledgments          | Transmitter ID              |
| `GetAcks`         | Retrieve acks by date range              | Date range + Transmitter ID |
| `GetAck`          | Retrieve specific ack by submission ID   | Submission ID               |
| `GetAcksByMsgID`  | Retrieve acks by message ID              | Message ID                  |

### Submission Format

* **Payload:** XML per AZFSET schemas (A1-QRT, A1-R, A1-APR, A1-WP)
* **Packaging:** Nested ZIP per PKWARE 6.2.0
  * Inner submission ZIPs: compressed
  * Outer container ZIP: uncompressed (store mode)
  * Transmitted as MTOM attachment in SOAP envelope
* **Submission ID:** 20 chars = `EFIN(6) + ccyyddd(7) + sequence(7)`
* **Message ID:** `ETIN + ccyyddd + 8-char alphanumeric`

### Submission Categories

| Category       | Form Types                            |
| -------------- | ------------------------------------- |
| `StateWH`      | A1-QRT, A1-WP (quarterly withholding) |
| `StateAnnual`  | A1-APR, A1-R (annual reconciliation)  |
| `StatePayment` | Payment submissions                   |
| `Enrollment`   | Transmitter enrollment                |

### Registration Requirements

* **ETIN:** IRS-issued Electronic Transmitter ID (stored in Cloud Secrets as `AZ_DOR_ETIN`)
* **EFIN:** IRS-issued Electronic Filer ID (stored in Cloud Secrets as `AZ_DOR_EFIN`)
* **Portal:** Register at [AZFSET](https://efile.aztaxes.gov/AZFSETPortal) as "Web Service – Transmitter"
* **Client list:** Must be updated by the first of each month

### Error Codes

AZFSET returns error codes in the pattern `1xxyyy`:

| Code Range | Category                | Description                                 |
| ---------- | ----------------------- | ------------------------------------------- |
| 101xxx     | Missing required fields | EIN, name, address, period                  |
| 102xxx     | Incorrect amounts       | Withholding, wages, payments mismatch       |
| 103xxx     | Quarter/year/liability  | Invalid quarter, year, or liability         |
| 104xxx     | Submission format       | Invalid XML, ZIP, or field format           |
| 109xxx     | Payment/bank errors     | Invalid routing, account, or payment amount |

### Manual Upload (Phase 1 Fallback)

* **Portals:** AZ Web File (AZFSET) at efile.aztaxes.gov/AZFSETPortal; AZTaxes at aztaxes.gov/Home/Page
* **Formats:** XML per AZFSET schemas (same format as SOAP, without SOAP envelope/ZIP)
* **Contract:** File download from Encore OS → manual upload to portal with instructions

***

## AZ DES (Arizona Department of Economic Security) — New Hire

### SFTP Integration (Phase 2/3)

* **Protocol:** SFTP over SSH
* **Credentials:** Stored in Lovable Cloud Secrets:
  * `AZ_DES_SFTP_HOST` — SFTP server hostname
  * `AZ_DES_SFTP_USERNAME` — SFTP username
  * `AZ_DES_SFTP_PASSWORD` — SFTP password (or SSH key)
* **Library:** `npm:ssh2` in Supabase Edge Functions (Deno)

### CSV Format

* **Layout:** 35-field CSV (see spec for complete field list)
* **Key fields:**
  * Fields 1-2: Record header ("AZ Newhire Record", "CSV1")
  * Fields 3-20: Employee data (name, SSN, address, DOB, hire date, medical insurance)
  * Fields 21-35: Employer data (FEIN, name, DBA, address, phone, multistate indicator)
* **Date format:** MMDDYYYY (no separators)
* **SSN/FEIN:** 9 digits, no hyphens
* **Frequency:** Within 20 days of hire

### Manual Upload (Phase 1 Fallback)

* **Portal:** [AZ DES New Hire Reporting](https://newhire-reporting.com/AZ-newhire/instruct.aspx)
* **Methods:** Secure web upload, file upload
* **Contract:** CSV file download from Encore OS → manual upload to portal with instructions

***

## Secrets Requirements

| Secret                 | Purpose                       | Phase     |
| ---------------------- | ----------------------------- | --------- |
| `AZ_DOR_WS_USERNAME`   | AZFSET Web Service username   | Phase 2   |
| `AZ_DOR_WS_PASSWORD`   | AZFSET Web Service password   | Phase 2   |
| `AZ_DOR_ETIN`          | Electronic Transmitter ID     | Phase 2   |
| `AZ_DOR_EFIN`          | Electronic Filer ID           | Phase 2   |
| `AZ_DES_SFTP_HOST`     | New Hire SFTP server hostname | Phase 2/3 |
| `AZ_DES_SFTP_USERNAME` | SFTP username                 | Phase 2/3 |
| `AZ_DES_SFTP_PASSWORD` | SFTP password (or SSH key)    | Phase 2/3 |

All secrets stored via **Lovable Cloud Secrets** (Settings > Cloud > Secrets). Accessed in edge functions via `Deno.env.get('SECRET_NAME')`. Never in code, migrations, or database columns.

***

## Technical Implementation Notes

* **SOAP from Deno:** No native SOAP library; XML hand-built with template strings. WS-Security username/password header is straightforward. MTOM attachment requires ZIP packaging.
* **ZIP packaging:** AZFSET requires PKWARE 6.2.0 nested ZIPs. Outer ZIP uncompressed (store mode), inner ZIPs compressed. Use `fflate` npm package (`npm:fflate` in Deno).
* **SFTP from Deno:** Use `npm:ssh2` package. `Deno.Command` not available in Supabase Edge Functions.
* **Test routing:** `hr_module_settings.az_efile_test_mode` determines endpoint (production vs test). All test submissions tagged `test_mode = true` in `hr_tax_efile_submissions`.

***

## CROSS\_CORE\_INTEGRATIONS.md

No cross-core integration; HR-PAY-08-AZ depends only on HR-PAY-04 (data source) and PF. External integrations are outbound to AZ DOR (SOAP/manual) and AZ DES (SFTP/manual) only.