Emilio Rodríguez

Project · API de facturación electrónica

ESContact

Project 04 / 07: API de facturación electrónica

2026 · Arclo Systems · Architecture and development

Arclo Systems · 2026

Issues, signs and validates Costa Rica e-invoices in-house; its AI follows each invoice through to the tax return.

The problem

Arclo invoiced through an outside provider, and every project had to redo the Hacienda integration: key custody, sequence numbers, retries and annex changes. This API solves it once for every Arclo system, starting with its ERP.

What I did

  1. 01 / 07

    I wrote an in-house core with Hacienda's rules.

    And no third-party SDKs. XAdES-EPES signing follows Hacienda's policy and runs on node:crypto, with no homemade crypto.

  2. 02 / 07

    I generate the 50-character key and sequence number.

    And validate each XML against the official v4.4 XSDs in an isolated process. One API issues every document type for several companies and receives supplier invoices.

  3. 03 / 07

    If Hacienda doesn't respond, a queue retries.

    Each invoice gets a PDF, notifies by webhook and email, and goes into the legal archive. With the dashboard, API keys, OpenAPI docs and client library, a project integrates invoicing in a day.

  4. 04 / 07

    The .p12 key and its PIN live only in memory.

    And are never written to disk, logs or error messages. I documented eight architecture decisions and wrote about 190 tests, and an independent library verifies every signature.

  5. 05 / 07

    Signing, amounts and VAT run on deterministic code.

    And AI stays outside that core. AI suggests the CABYS code, explains Hacienda's rejections, classifies received invoices and detects suppliers that are no longer registered.

  6. 06 / 07

    From issued and received XML, I draft the D-150 VAT return box by box.

    Each inconsistency is flagged before filing, so the TRIBU-CR cross-check doesn't find it first, and AI explains how to fix it.

  7. 07 / 07

    When Hacienda publishes new annexes.

    A workflow proposes each rule with its citation and tests, and a person approves it. Through the MCP server, a client's agent queries its invoices and only issues within a mandate a person signed.

Results

  1. Its first user is Arclo's ERP, which stops depending on an outside provider to invoice.

Stack

  • TypeScript
  • NestJS
  • PostgreSQL
  • AWS
  • XAdES-EPES
  • OpenAPI
  • Claude
  • MCP

End of the project

Next project

Gaceta AI

Back to the series