Tu primera factura

En cinco minutos vas a emitir una factura de prueba, ver cómo el SRI la autoriza y descargar su RIDE.

Necesitas una API key

Si todavía no la tienes, créala en Olympus en Configuración → Integraciones: es un minuto y está explicado paso a paso en Crear tu API key. En los ejemplos, $OLYMPUS_API_KEY es esa clave.

Hazlo en pruebas

Antes de empezar, comprueba que el negocio está en ambiente pruebas (Configuración → Fiscal). Los comprobantes de pruebas no tienen validez tributaria y puedes emitir los que quieras. Ver Ambientes.

1. Comprueba que puedes emitir

curl https://olympus.atharix.com/api/v1/me \
  -H "X-API-Key: $OLYMPUS_API_KEY"

{
  "negocio": {
    "id": "8f2c…",
    "ruc": "1790012345001",
    "razon_social": "COMERCIAL ANDINA S.A.",
    "nombre_comercial": "Andina",
    "pais": "EC"
  },
  "ambiente": "pruebas",
  "listo_para_emitir": true,
  "requisitos_faltantes": [],
  "clave": { "nombre": "ERP Odoo", "prefijo": "dlt_a1b2c3d4", "scopes": ["invoices:write", "invoices:read"] },
  "establecimiento_por_defecto": { "codigo": "001", "punto_emision": "001" },
  "limites": { "lectura_por_minuto": 600, "escritura_por_minuto": 120 }
}

Si listo_para_emitir es false, resuelve lo que diga requisitos_faltantes desde la aplicación web antes de seguir.

2. Mira tus establecimientos

curl https://olympus.atharix.com/api/v1/establishments \
  -H "X-API-Key: $OLYMPUS_API_KEY"

{
  "data": [
    {
      "codigo": "001",
      "nombre": "Matriz",
      "direccion": "Av. Amazonas N24-03, Quito",
      "por_defecto": true,
      "puntos_emision": [{ "codigo": "001", "nombre": "Principal", "por_defecto": true }]
    }
  ]
}

Puedes omitir establecimiento al emitir: se usa el que marca por_defecto.

3. Emite la factura

curl

curl -X POST https://olympus.atharix.com/api/v1/invoices/issue \
  -H "X-API-Key: $OLYMPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: primera-factura-001" \
  -d '{
    "referencia_externa": "SO-2026-0912",
    "comprador": {
      "tipo_identificacion": "04",
      "identificacion": "1792060346001",
      "razon_social": "COMERCIAL ANDINA S.A.",
      "email": "facturas@andina.ec"
    },
    "items": [
      {
        "codigo_principal": "SRV-001",
        "descripcion": "Servicio de soporte mensual",
        "cantidad": 1,
        "precio_unitario": 100.00,
        "impuestos": [{ "codigo": "2", "codigo_porcentaje": "4" }]
      }
    ],
    "totales": { "total_sin_impuestos": 100.00, "importe_total": 115.00 }
  }'

Python

import os, httpx

client = httpx.Client(
    base_url="https://olympus.atharix.com/api/v1",
    headers={"X-API-Key": os.environ["OLYMPUS_API_KEY"]},
    timeout=20,
)

respuesta = client.post(
    "/invoices/issue",
    headers={"Idempotency-Key": "primera-factura-001"},
    json={
        "referencia_externa": "SO-2026-0912",
        "comprador": {
            "tipo_identificacion": "04",
            "identificacion": "1792060346001",
            "razon_social": "COMERCIAL ANDINA S.A.",
            "email": "facturas@andina.ec",
        },
        "items": [
            {
                "codigo_principal": "SRV-001",
                "descripcion": "Servicio de soporte mensual",
                "cantidad": 1,
                "precio_unitario": 100.00,
                "impuestos": [{"codigo": "2", "codigo_porcentaje": "4"}],
            }
        ],
        "totales": {"total_sin_impuestos": 100.00, "importe_total": 115.00},
    },
)
respuesta.raise_for_status()
factura = respuesta.json()
print(factura["id"], factura["clave_acceso"])

Node

const respuesta = await fetch("https://olympus.atharix.com/api/v1/invoices/issue", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.OLYMPUS_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "primera-factura-001",
  },
  body: JSON.stringify({
    referencia_externa: "SO-2026-0912",
    comprador: {
      tipo_identificacion: "04",
      identificacion: "1792060346001",
      razon_social: "COMERCIAL ANDINA S.A.",
      email: "facturas@andina.ec",
    },
    items: [
      {
        codigo_principal: "SRV-001",
        descripcion: "Servicio de soporte mensual",
        cantidad: 1,
        precio_unitario: 100.0,
        impuestos: [{ codigo: "2", codigo_porcentaje: "4" }],
      },
    ],
    totales: { total_sin_impuestos: 100.0, importe_total: 115.0 },
  }),
});

const factura = await respuesta.json();
console.log(factura.id, factura.clave_acceso);

PHP

$payload = [
    "referencia_externa" => "SO-2026-0912",
    "comprador" => [
        "tipo_identificacion" => "04",
        "identificacion" => "1792060346001",
        "razon_social" => "COMERCIAL ANDINA S.A.",
        "email" => "facturas@andina.ec",
    ],
    "items" => [[
        "codigo_principal" => "SRV-001",
        "descripcion" => "Servicio de soporte mensual",
        "cantidad" => 1,
        "precio_unitario" => 100.00,
        "impuestos" => [["codigo" => "2", "codigo_porcentaje" => "4"]],
    ]],
    "totales" => ["total_sin_impuestos" => 100.00, "importe_total" => 115.00],
];

$ch = curl_init("https://olympus.atharix.com/api/v1/invoices/issue");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        "X-API-Key: " . getenv("OLYMPUS_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: primera-factura-001",
    ],
]);
$factura = json_decode(curl_exec($ch), true);

Respuesta 202 Accepted:

{
  "id": "6f1e8a24-91cd-4c73-9a1f-2b0f5d7e4c88",
  "tipo": "factura",
  "estado": "pendiente",
  "clave_acceso": "2409202601179001234500110010010000000011234567813",
  "secuencial": "001-001-000000001",
  "ambiente": "pruebas",
  "fecha_emision": "2026-09-24",
  "referencia_externa": "SO-2026-0912",
  "totales": { "total_sin_impuestos": 100.0, "descuento": 0.0, "iva": 15.0, "importe_total": 115.0 },
  "urls": {
    "detalle": "https://olympus.atharix.com/api/v1/invoices/6f1e8a24-…",
    "pdf": null,
    "xml": null,
    "publica": null
  }
}

Guarda el id y la clave_acceso: son tu referencia para todo lo demás.

¿Por qué 202 y no 201?

Porque la factura todavía no está autorizada. Olympus la aceptó, la numeró y la está enviando al SRI. El 202 significa “recibido y en curso”, que es exactamente lo que pasa.

4. Consulta el estado

El SRI suele tardar unos segundos. Consulta el detalle:

curl https://olympus.atharix.com/api/v1/invoices/6f1e8a24-… \
  -H "X-API-Key: $OLYMPUS_API_KEY"

{
  "id": "6f1e8a24-…",
  "estado": "autorizado",
  "clave_acceso": "2409202601179001234500110010010000000011234567813",
  "numero_autorizacion": "2409202601179001234500110010010000000011234567813",
  "fecha_autorizacion": "2026-09-24T10:31:07-05:00",
  "mensajes": [],
  "urls": {
    "pdf": "https://olympus.atharix.com/api/v1/invoices/6f1e8a24-…/pdf",
    "xml": "https://olympus.atharix.com/api/v1/invoices/6f1e8a24-…/xml",
    "publica": "https://olympus.atharix.com/api/public/sri/2409…13/"
  }
}

Cuando estado es autorizado, ya está: el comprobante tiene validez y el RIDE salió por correo al comprador. Si es no_autorizado, mensajes dice por qué; consulta Errores del SRI.

No consultes en bucle apretado

Espera 3–5 segundos antes de la primera consulta y ve espaciando los intentos. Consultar cada 200 ms solo gasta tu cuota de peticiones. Lee Buenas prácticas.

5. Descarga el RIDE

curl https://olympus.atharix.com/api/v1/invoices/6f1e8a24-…/pdf \
  -H "X-API-Key: $OLYMPUS_API_KEY" \
  -o factura.pdf

Y el XML autorizado, que es el documento con valor legal:

curl https://olympus.atharix.com/api/v1/invoices/6f1e8a24-…/xml \
  -H "X-API-Key: $OLYMPUS_API_KEY" \
  -o factura.xml

Ya está

Has emitido, consultado y descargado tu primera factura. A partir de aquí:

• Emitir una factura: el payload completo, campo a campo.
• Impuestos (IVA): cómo declarar cada tarifa.
• Estados de un comprobante: qué significa cada estado y cuándo consultar.
• Referencia de la API: todos los endpoints y campos.