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.
Spec ID: HR-PAY-08-AZ
Status: 📝 Planned
Last Updated: 2026-02-16
This document describes the outbound integration from Encore Health 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 |
- 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 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 Health 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 hostnameAZ_DES_SFTP_USERNAME — SFTP usernameAZ_DES_SFTP_PASSWORD — SFTP password (or SSH key)
- Library:
npm:ssh2 in Supabase Edge Functions (Deno)
- 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
- Methods: Secure web upload, file upload
- Contract: CSV file download from Encore Health 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 |
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.
