Plataformas multi-emisor

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

Terminal

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"]
  }'

201 Created

{
  "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

Terminal

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"
  }'

201 Created

{
  "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/….

Terminal

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

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

200 OK

{
  "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

Terminal

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

200 OK

{
  "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

{
  "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.