Get started
Introduction
What Aster is, what it handles for you, and how this documentation is organized.
Aster is the Costa Rica electronic invoicing API (Hacienda’s Factura Electrónica) sold by AstraNexo. It takes a JSON request, validates it against the version 4.4 rules, builds the XML, signs it, sends it to Hacienda and tells you the outcome. It is the same engine Astra uses to issue its own documents.
The API lives under a single base URL:
https://aster.astranexo.com/api/v1What Aster handles for you
Section titled “What Aster handles for you”- All 7 document types of version 4.4: Factura Electrónica (FE,
01), Nota de Débito (ND,02), Nota de Crédito (NC,03), Tiquete Electrónico (TE,04), Factura Electrónica de Compra (FEC,08), Factura Electrónica de Exportación (FEE,09) and Recibo Electrónico de Pago (REP,10). Plus the Mensaje Receptor (in Spanish) to accept or reject supplier invoices. - XAdES-EPES signing with each issuer’s
.p12certificate. You never touch XML or cryptography. - Validation before sending. Aster checks calculations, CABYS codes, tax rates, note references and taxpayer IDs before signing, and catches Hacienda rejections such as
-107,-400,-509and-512before they happen. Details in Errors. - A Hacienda verdict, guaranteed. Aster receives Hacienda’s callback and, when it doesn’t arrive, queries the status itself. When Hacienda is down, Aster keeps the document and resends it automatically once Hacienda is back. See Ciclo de vida (in Spanish).
- HMAC-SHA256 signed webhooks for every status change. See Webhooks (in Spanish).
- Idempotency on every write with
X-Idempotency-Key, so you can retry without issuing duplicates. See Idempotencia (in Spanish). - PDF and email to the receiver, with the signed XML and Hacienda’s response. See PDF y correo (in Spanish).
- Ready-made catalogs: CABYS, provinces, cantons and districts, Hacienda code tables, taxpayer lookup and BCCR exchange rates. See Catálogos (in Spanish).
- Storage: every plan keeps the signed XML, Hacienda’s response and the PDF for 90 days, with bulk download. Archeion keeps them for 5 years, the period the law requires of the issuer: included from Escala up, and $5 per company a month on Inicial and Crecimiento.
Systems provider
Section titled “Systems provider”Since version 4.4 every document carries a ProveedorSistemas field with the ID of the company providing the invoicing system. AstraNexo is registered with Hacienda as a systems provider and Aster fills that field for you. If your company is also a registered provider and you want to use your own ID, send it in document.provider_system_id.
How this documentation is organized
Section titled “How this documentation is organized”- Get started: the Quickstart sends your first invoice in five minutes, and Authentication and keys explains API keys.
- Concepts (in Spanish): what is worth understanding once before you integrate: the clave, the consecutivo, environments, branch and terminal, the document lifecycle and the Mensaje Receptor.
- Document types and guides (in Spanish): a complete example per document type and guides for specific cases (exemptions, foreign currency, voiding, webhooks, platforms with many issuers).
- Reference: the interactive API reference, where you can try every endpoint with your test key, the error catalog, the catalogs, the changelog and the service and Hacienda status.