Quickstart

In this guide you send a Factura Electrónica (type 01) in test mode and read Hacienda’s verdict. You don’t need a certificate or a paid plan.

1. Create your account

   Sign up at /app/signup with your email and confirm it. Then, under Organizaciones (Organizations), add your first organization (the issuer) with its ID number, name and economic activity.

   Your account starts on the Sandbox plan: test mode, free and unlimited.

2. Copy your test key

   In the dashboard, open Llaves de API (API keys) and create a test key for your organization. It starts with aster_test_. It is shown only once: store it in an environment variable.

   Terminal

   export ASTER_API_KEY="aster_test_8KfQ2mVx3TzL9pRw"

   The key decides the environment: an aster_test_ key always works against the test environment. More in Authentication and keys.

3. Prepare the invoice

   Save this JSON as factura.json. It is a cash sale of two power drills with 13% VAT. You don’t send totals, clave or consecutivo: Aster computes them.

   factura.json

   {
     "document": {
       "document_type": "01",
       "activity_code": "475201",
       "branch": "001",
       "terminal": "00001"
     },
     "commercial_info": {
       "currency": "CRC",
       "sale_condition": "01",
       "payment_method": "01"
     },
     "issuer": {
       "type": "02",
       "id": "3101654321",
       "name": "Ferretería La Sabana S.A.",
       "email": "facturas@ferreterialasabana.cr",
       "address": {
         "province": "1",
         "canton": "08",
         "district": "01",
         "details": "Del Más x Menos 200 m sur"
       }
     },
     "receiver": {
       "type": "01",
       "id": "109870654",
       "name": "Laura Jiménez Mora",
       "email": "laura.jimenez@example.com"
     },
     "items": [
       {
         "cabys_code": "4423201000100",
         "quantity": 2,
         "unit": "Unid",
         "description": "Taladro percutor de 1/2 pulgada",
         "price": 15000,
         "tax": [
           { "type": "01", "rate_code": "08", "rate": 13 }
         ]
       }
     ]
   }

   Use your organization's real data

   The data in this example is fictitious. Before sending it, put your key’s organization ID in issuer (if it doesn’t match, the API answers 422 organization_mismatch). Aster also checks that the issuer and receiver IDs are registered with Hacienda (error -38), so use a real receiver, for example your own ID.

4. Send it

   Make a POST /electronic-documents. The X-Idempotency-Key header is optional but recommended: if you repeat the same request with the same key, Aster returns the original response instead of issuing another invoice.

   curl

   Terminal

   curl https://aster.astranexo.com/api/v1/electronic-documents \
     -H "Authorization: Bearer $ASTER_API_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Idempotency-Key: pedido-1042" \
     --data @factura.json

   Node.js

   send.mjs

   import { readFile } from 'node:fs/promises';
   
   const body = await readFile('factura.json', 'utf8');
   
   const res = await fetch('https://aster.astranexo.com/api/v1/electronic-documents', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.ASTER_API_KEY}`,
       'Content-Type': 'application/json',
       'X-Idempotency-Key': 'pedido-1042',
     },
     body,
   });
   
   console.log(res.status, await res.json());

   PHP

   send.php

   <?php
   $ch = curl_init('https://aster.astranexo.com/api/v1/electronic-documents');
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER => [
           'Authorization: Bearer ' . getenv('ASTER_API_KEY'),
           'Content-Type: application/json',
           'X-Idempotency-Key: pedido-1042',
       ],
       CURLOPT_POSTFIELDS => file_get_contents('factura.json'),
   ]);
   
   $body = curl_exec($ch);
   $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
   
   echo $status, PHP_EOL, $body, PHP_EOL;

   Python

   send.py

   import os
   
   import requests
   
   with open("factura.json", "rb") as f:
       body = f.read()
   
   res = requests.post(
       "https://aster.astranexo.com/api/v1/electronic-documents",
       headers={
           "Authorization": f"Bearer {os.environ['ASTER_API_KEY']}",
           "Content-Type": "application/json",
           "X-Idempotency-Key": "pedido-1042",
       },
       data=body,
       timeout=30,
   )
   
   print(res.status_code, res.json())

   Go

   main.go

   package main
   
   import (
     "fmt"
     "io"
     "net/http"
     "os"
   )
   
   func main() {
     body, err := os.Open("factura.json")
     if err != nil {
       panic(err)
     }
     defer body.Close()
   
     req, err := http.NewRequest(http.MethodPost,
       "https://aster.astranexo.com/api/v1/electronic-documents", body)
     if err != nil {
       panic(err)
     }
     req.Header.Set("Authorization", "Bearer "+os.Getenv("ASTER_API_KEY"))
     req.Header.Set("Content-Type", "application/json")
     req.Header.Set("X-Idempotency-Key", "pedido-1042")
   
     res, err := http.DefaultClient.Do(req)
     if err != nil {
       panic(err)
     }
     defer res.Body.Close()
   
     out, _ := io.ReadAll(res.Body)
     fmt.Println(res.StatusCode, string(out))
   }

5. Read the response

   Aster answers 201 Created as soon as it has validated and signed the document and put it on its way to Hacienda. It doesn’t wait for the verdict.

   201 Created

   {
     "success": true,
     "message": "Document submitted successfully",
     "data": {
       "id": 318,
       "document_key": "50608102600310165432100100001010000001042147201936",
       "consecutive_number": "00100001010000001042",
       "document_type": "01",
       "document_type_name": "Factura Electrónica",
       "status": "processing",
       "environment": "staging",
       "queued_at": "2026-10-08T16:20:11Z"
     },
     "timestamp": "2026-10-08T16:20:11Z",
     "api_version": "1.0"
   }

   • document_key is the 50-digit clave (in Spanish). Store it: it identifies the document at Hacienda and in Aster.
   • consecutive_number is the 20-digit consecutivo (in Spanish) Aster assigned.
   • status: "processing" means the document is on its way to Hacienda. The verdict arrives within seconds.

   If validation fails, the response is 422 validation_error with the list of fields in error.errors. See Errors.

6. Get the verdict

   Fetch the document by its clave until status is accepted or rejected. Polling every 2 to 5 seconds is enough.

   curl

   Terminal

   curl https://aster.astranexo.com/api/v1/electronic-documents/50608102600310165432100100001010000001042147201936 \
     -H "Authorization: Bearer $ASTER_API_KEY"

   Node.js

   fetch.mjs

   const clave = '50608102600310165432100100001010000001042147201936';
   
   const res = await fetch(`https://aster.astranexo.com/api/v1/electronic-documents/${clave}`, {
     headers: { Authorization: `Bearer ${process.env.ASTER_API_KEY}` },
   });
   const { data } = await res.json();
   
   console.log(data.status, data.hacienda_message);

   PHP

   fetch.php

   <?php
   $clave = '50608102600310165432100100001010000001042147201936';
   
   $ch = curl_init("https://aster.astranexo.com/api/v1/electronic-documents/{$clave}");
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ASTER_API_KEY')],
   ]);
   
   $data = json_decode(curl_exec($ch), true)['data'];
   
   echo $data['status'], ' ', $data['hacienda_message'], PHP_EOL;

   Python

   fetch.py

   import os
   
   import requests
   
   clave = "50608102600310165432100100001010000001042147201936"
   
   res = requests.get(
       f"https://aster.astranexo.com/api/v1/electronic-documents/{clave}",
       headers={"Authorization": f"Bearer {os.environ['ASTER_API_KEY']}"},
       timeout=30,
   )
   data = res.json()["data"]
   
   print(data["status"], data["hacienda_message"])

   Go

   main.go

   package main
   
   import (
     "fmt"
     "io"
     "net/http"
     "os"
   )
   
   func main() {
     clave := "50608102600310165432100100001010000001042147201936"
   
     req, err := http.NewRequest(http.MethodGet,
       "https://aster.astranexo.com/api/v1/electronic-documents/"+clave, nil)
     if err != nil {
       panic(err)
     }
     req.Header.Set("Authorization", "Bearer "+os.Getenv("ASTER_API_KEY"))
   
     res, err := http.DefaultClient.Do(req)
     if err != nil {
       panic(err)
     }
     defer res.Body.Close()
   
     out, _ := io.ReadAll(res.Body)
     fmt.Println(string(out))
   }

   200 OK (excerpt)

   {
     "success": true,
     "data": {
       "id": 318,
       "document_key": "50608102600310165432100100001010000001042147201936",
       "consecutive_number": "00100001010000001042",
       "document_type": "01",
       "status": "accepted",
       "environment": "staging",
       "emisor_name": "Ferretería La Sabana S.A.",
       "emisor_identification": "3101654321",
       "receptor_name": "Laura Jiménez Mora",
       "receptor_identification": "109870654",
       "total_amount": 33900,
       "tax_amount": 3900,
       "net_amount": 30000,
       "currency": "CRC",
       "hacienda_status": "aceptado",
       "hacienda_message": "Documento aceptado"
     }
   }

   In production, avoid polling in a loop: register a webhook and Aster notifies you with document.accepted or document.rejected. See the webhooks guide (in Spanish).

Try a rejection

If your organization has no test certificate, Aster returns a simulated verdict. To simulate a rejection, add "metadata": { "simulate": "rejected" } to the JSON. See Ambientes (in Spanish).

Going live

Once your integration works in test mode, these are the steps to issue real documents:

• Choose a paid plan in the dashboard, under Facturación (Billing). Live keys can only be created with an active plan.
• Upload your production certificate: Hacienda’s .p12 signing file and its PIN. The certificate’s ID must match the organization’s.
• Set your production Hacienda credentials (the electronic invoicing system username and password). The dashboard checks them against Hacienda on the spot.
• Create an aster_live_ key under Llaves de API and replace the test key on your server. Nothing else in your requests changes: the key decides the environment.
• Register a webhook to receive verdicts without polling.
• Check your numbering. Production consecutivos are independent from test ones and start at 1 per branch, terminal and document type. If you are moving from another provider, read Migrar (in Spanish).

Production documents that receive a final verdict from Hacienda count toward your plan’s usage. If you reach the limit, upgrade your plan or add a pack at any time from the dashboard.