Costa Rica
In Costa Rica, Floogos connects directly to the Ministerio de Hacienda (version 4.4 of the electronic document schema). There is no mandatory intermediate provider: the engine itself builds the XML, computes the numeric key, signs it with the issuer’s certificate, and speaks Hacienda’s REST protocol, authenticating with OAuth2 against the ATV (Administración Tributaria Virtual).
Integration model
Section titled “Integration model”- Direct, no intermediate provider: the flow goes straight to the Ministerio de Hacienda’s REST services, not through an external PAC or certifier.
- Own v4.4 schema: documents (invoices, notes) are built in Hacienda’s own XML format, version 4.4.
- 50-digit numeric key: every document carries a key that includes the country code (506), the issuer’s ID, the sequential number and a security situation code, and it is what identifies the document before Hacienda and in the QR code.
- Digital signature: the XML is signed with the issuer’s certificate (.p12) before sending.
- OAuth2 authentication: each submission obtains a token from the ATV’s IDP (Hacienda username and password) before calling the reception and status services.
- Reception + status query: the document is sent by POST to reception and its status (ind-estado) is then queried with a GET by key.
- 13% VAT: the value-added tax (IVA) is calculated using Hacienda’s rate catalog, with 13% (code 08) being the general rate.
When a document becomes valid
Section titled “When a document becomes valid”A document is not valid just by being sent: it only becomes valid once Hacienda responds with an accepted status. If the response comes back as received or processing, it must be reconciled later by querying the key again. If Hacienda rejects it, the document has no tax validity and must be corrected and reissued.
Available nodes
Section titled “Available nodes”| Node | Description |
|---|---|
| HaciendaEmitirFactura | Issues the invoice: builds the v4.4 XML, computes the key, signs it, gets the OAuth2 token and does reception + status query |
| HaciendaEmitirNota | Issues a credit (03) or debit (02) note referencing the original document’s key |
| HaciendaConsultarEstado | Queries a document’s status by its numeric key; reconciles and updates the database |
| HaciendaRepresentacion | Generates the printable representation (HTML/PDF) with the document’s QR code |
Typical flow
Section titled “Typical flow”- HaciendaEmitirFactura — issues the invoice (or the note with HaciendaEmitirNota), obtaining the numeric key and an initial status.
- HaciendaConsultarEstado — if the status came back as received or processing, it is queried again later until it becomes accepted or rejected.
- HaciendaRepresentacion — once accepted, the HTML with the QR code is generated to hand the customer their printed or PDF document.
- The
haciendacredential type stores the certificate (.p12), its password, the issuer’s cedula/tax ID, the ATV username and password, and the environment (sandbox or production). - The Floogos engine validates that the certificate is not expired before attempting to sign and send a document.
- The 50-digit numeric key is the same one encoded in the QR code of the printable representation.