Guías

Plataformas multi-emisor

Administrá muchos emisores desde una sola cuenta, como ERP, sistema de punto de venta o despacho contable, con llaves de cuenta y llaves por organización.

Si tu sistema factura en nombre de muchos contribuyentes (un ERP, un sistema de punto de venta, un despacho contable), en Aster cada contribuyente es una organización dentro de tu cuenta. Creás las organizaciones por API, cada una con su certificado, sus credenciales de Hacienda, su marca y sus llaves. Para tu sistema todas comparten la misma integración.

Más detalles comerciales en /plataformas.

Dos tipos de llave

Llave	Prefijo	Para qué sirve
De cuenta	`aster_test_` / `aster_live_` sin organización	Administrar la cuenta: crear, listar, modificar y borrar organizaciones; crear y revocar llaves; ver el uso
De organización	`aster_test_` / `aster_live_`	Operar con una organización: emitir comprobantes, configurar su certificado y su marca, registrar webhooks

La llave de organización decide a la vez el emisor y el ambiente: aster_test_ va al ambiente de pruebas de Hacienda y aster_live_ a producción. Ninguna solicitud lleva un identificador de organización: la llave alcanza.

Las llaves de cuenta también tienen modo. Una llave de cuenta de prueba no puede crear llaves aster_live_ ni borrar organizaciones, así que una filtración de esa llave no compromete producción.

Alta de un emisor

1. Crear la organización

curl https://aster.astranexo.com/api/v1/organizations \
  -H "Authorization: Bearer aster_live_3NhR7wPz5KcY2mQdXb8LfT4vJs9GqE1uWa6RyZ0o" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: alta-cliente-3101654321" \
  --data '{
    "name": "Ferretería La Sabana",
    "legal_name": "Ferretería La Sabana S.A.",
    "identification_type": "02",
    "identification_number": "3101654321",
    "email": "facturas@ferreterialasabana.cr",
    "phone": "22905511",
    "economic_activities": ["475201"]
  }'

{
  "success": true,
  "message": "Organization created.",
  "data": {
    "id": "6f1c2a9e-4b7d-4e2a-9c31-0d8e5b7a2f14",
    "name": "Ferretería La Sabana",
    "legal_name": "Ferretería La Sabana S.A.",
    "identification_type": "02",
    "identification_number": "3101654321",
    "email": "facturas@ferreterialasabana.cr",
    "phone": "22905511",
    "economic_activities": ["475201"],
    "certificate_test": false,
    "certificate_live": false,
    "created_at": "2026-10-08T15:00:12Z"
  }
}

identification_type acepta 01 (física), 02 (jurídica), 03 (DIMEX) y 04 (NITE). La cantidad de organizaciones depende del plan; ver la tabla al final.

2. Crear sus llaves

curl https://aster.astranexo.com/api/v1/api-keys \
  -H "Authorization: Bearer aster_live_3NhR7wPz5KcY2mQdXb8LfT4vJs9GqE1uWa6RyZ0o" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "ERP, Ferretería La Sabana, pruebas",
    "mode": "test",
    "organization_id": "6f1c2a9e-4b7d-4e2a-9c31-0d8e5b7a2f14"
  }'

{
  "success": true,
  "message": "API key created. Store the secret now: it isn't shown again.",
  "data": {
    "id": "b2e7c1d4-9a3f-4c8e-8d21-5f6a7b8c9d0e",
    "name": "ERP, Ferretería La Sabana, pruebas",
    "mode": "test",
    "organization_id": "6f1c2a9e-4b7d-4e2a-9c31-0d8e5b7a2f14",
    "secret": "aster_test_8KfQ2mVx3TzL9pRw"
  }
}

El secreto se muestra una sola vez. Guardalo cifrado en tu base, asociado al cliente. Para producción, creá otra con "mode": "live" usando una llave de cuenta live; tu cuenta necesita un plan pagado.

Revocá una llave con DELETE /api-keys/{id}. Una llave no se puede revocar a sí misma.

3. Subir el certificado y las credenciales de Hacienda

Desde aquí, todo se hace con la llave de la organización, en las rutas /organizations/me/….

curl https://aster.astranexo.com/api/v1/organizations/me/certificate \
  -H "Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw" \
  -H "Content-Type: application/json" \
  --data @certificado.json

{
  "certificate": "MIIKYgIBAzCCCh4GCSqGSIb3DQEHAaCCCg8EggoLMIIKBzCCBX8GCSqGSIb3DQEH...",
  "pin": "1234",
  "environment": "staging",
  "atv_user": "cpj-3-101-654321@stag.comprobanteselectronicos.go.cr",
  "atv_password": "contraseña-generada-en-hacienda"
}

Campo	Descripción
`certificate`	El archivo `.p12` de firma de Hacienda, en base64
`pin`	El PIN del certificado
`environment`	`staging` (pruebas) o `production`
`atv_user`, `atv_password`	Usuario y contraseña del sistema de comprobantes electrónicos de Hacienda para ese ambiente

{
  "success": true,
  "data": {
    "serial_number": "4E1A7C33",
    "subject": "FERRETERIA LA SABANA SOCIEDAD ANONIMA",
    "expiry_date": "2028-03-14T00:00:00Z",
    "is_expired": false
  }
}

Aster cifra el PIN y la contraseña y nunca los devuelve. Para producción, la cédula del certificado tiene que coincidir con la de la organización. Aster te avisa por correo 30, 7 y 1 día antes de que venza un certificado.

GET /organizations/me/certificate indica qué ambientes tienen certificado y credenciales; DELETE /organizations/me/certificate?environment=staging los borra.

4. Verificar las credenciales

curl "https://aster.astranexo.com/api/v1/utils/verify-credentials?env=staging" \
  -H "Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw"

{
  "success": true,
  "data": {
    "valid": true,
    "environment": "staging",
    "credentials": { "configured": true, "valid": true, "message": "Authentication successful." },
    "certificate": { "configured": true, "file_exists": true }
  }
}

Aster se autentica contra Hacienda con las credenciales en el momento, sin enviar ningún comprobante. Hacelo al terminar el alta para detectar una contraseña equivocada antes de la primera factura.

5. Datos, marca y numeración

Endpoint	Para qué
`GET` / `PUT /organizations/me/settings`	Datos del emisor: nombre, nombre comercial, correo, teléfono y actividades económicas
`GET` / `PUT /organizations/me/branding`	Logo, color, pie del PDF, remitente y dirección de respuesta de los correos. Ver PDF y correo
`GET` / `PUT /organizations/me/consecutives`	Contadores de consecutivo por sucursal, terminal y tipo. Ver migrar

Los webhooks también son por organización: crealos con la llave de cada una. Ver webhooks.

Emitir

Con la llave de la organización, POST /electronic-documents funciona igual que para un solo emisor. Aster verifica que issuer.id sea la cédula de esa organización (en una Factura de Compra, receiver.id); si no coincide, responde 422 organization_mismatch y no firma nada. Así una llave nunca firma comprobantes de otro contribuyente.

Proveedor de sistemas

Desde la versión 4.4 todo comprobante declara al proveedor del sistema que lo generó, en el campo ProveedorSistemas. Por defecto Aster pone la cédula de AstraNexo, proveedor de sistemas inscrito ante Hacienda.

Si tu empresa está inscrita como proveedor de sistemas y querés figurar vos, enviá tu cédula en cada comprobante:

{
  "document_type": "01",
  "activity_code": "475201",
  "provider_system_id": "3101998877"
}

Borrar una organización

DELETE /organizations/{id} con una llave de cuenta live revoca todas las llaves de la organización. Sus comprobantes se conservan según la política de retención de la cuenta.

El plan Plataforma


Precio	$149 al mes más $2 por cada emisor activo (USD, más IVA)
Emisor activo	Una organización con al menos un comprobante de producción en el mes. Las organizaciones sin movimiento no se cobran
Documentos	25 000 al mes, compartidos entre todas las organizaciones
Emisores	Sin límite
Solicitudes	1 000 por minuto
Archivo fiscal	Archeion incluido: 5 años para todas las organizaciones
Integración	Si preferís que lo integremos nosotros: integración a la medida desde $500, según el alcance

Si tus organizaciones necesitan más documentos, agregá paquetes en cualquier momento. Ver límites de uso.

Organizaciones por plan:

Plan	Organizaciones
Sandbox	1
Inicial	1
Crecimiento	10
Escala	50
Plataforma	Sin límite

Ver precios.