Skip to main content
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

​
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

​
Available Services

​
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

​
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:

​
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
  • Methods: Secure web upload, file upload
  • Contract: CSV file download from Encore OS → manual upload to portal with instructions

​
Secrets Requirements

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.