Establecimientos y secuenciales

El número de una factura ecuatoriana tiene tres partes:

001 - 001 - 000000042
 │     │        └── secuencial, 9 dígitos, correlativo
 │     └── punto de emisión (caja, terminal, canal)
 └── establecimiento (sucursal, local)

El SRI asigna al negocio sus establecimientos y puntos de emisión. Cada combinación tiene su propia serie, que avanza de uno en uno y no puede tener huecos ni repeticiones.

Ver los que tiene el negocio

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",
      "ciudad": "Quito",
      "por_defecto": true,
      "puntos_emision": [
        { "codigo": "001", "nombre": "Principal", "por_defecto": true },
        { "codigo": "002", "nombre": "Caja 2", "por_defecto": false }
      ]
    },
    {
      "codigo": "002",
      "nombre": "Sucursal Norte",
      "por_defecto": false,
      "puntos_emision": [{ "codigo": "001", "nombre": "Principal", "por_defecto": true }]
    }
  ]
}

Cómo se elige al emitir

Olympus resuelve en este orden:

1. Lo que envías en establecimiento:

   { "establecimiento": { "codigo": "002", "punto_emision": "001" } }

2. El que tenga configurado la API key. Cada clave puede llevar su establecimiento y punto de emisión por defecto (Configuración → Integraciones).

3. El del negocio: el establecimiento marcado por defecto y su punto de emisión por defecto.

Una clave por punto de emisión

Si tu sistema factura desde varias cajas o sucursales, dale a cada una su propia API key con su establecimiento por defecto. El código queda más simple y el registro de peticiones te dice qué caja emitió cada factura.

Si el código no existe o el punto de emisión está inactivo, la respuesta es 422 establishment_not_found.

Numeración automática (recomendado)

Si no envías secuencial, Olympus toma el siguiente de la serie. El contador está protegido contra concurrencia: dos emisiones simultáneas desde el mismo punto de emisión no pueden llevarse el mismo número.

{ "comprador": { … }, "items": [ … ] }

{ "secuencial": "001-001-000000042" }

Esta es la opción sensata en casi todos los casos: Olympus ya lleva la cuenta y garantiza que no haya saltos ni duplicados, que es justo lo que el SRI exige.

Numeración propia

Si tu sistema ya controla la numeración —por ejemplo, porque migras desde otro proveedor y tienes que continuar una serie— envía el número:

{ "secuencial": "43", "comprador": { … }, "items": [ … ] }

Se rellena a nueve dígitos automáticamente (43 → 000000043) y se compone con el establecimiento y el punto de emisión.

Si ese número ya existe en el negocio, la respuesta es 409 sequence_conflict.

Si numeras tú, numeras siempre

No mezcles. Si en unas facturas envías secuencial y en otras no, los dos contadores se pisan y acabarás con conflictos. Elige una estrategia para cada punto de emisión y mantenla.

Migrar desde otro proveedor

Para continuar una serie que empezó en otro sistema:

1. Averigua el último número emitido en cada punto de emisión.
2. Emite tu primera factura en Olympus con secuencial explícito, el siguiente al último.
3. A partir de ahí puedes dejar de enviarlo: Olympus sigue desde donde lo dejaste.

{ "establecimiento": { "codigo": "001", "punto_emision": "001" }, "secuencial": "1847" }

Preguntas frecuentes

¿Los secuenciales se reinician cada año? No. La serie es continua hasta que el negocio decida abrir otra en el SRI.

¿Pruebas y producción comparten la serie? Sí. Si emitiste 50 facturas de pruebas, la primera real será la 51. Ver Ambientes.

¿Puedo reservar un número sin emitir? No por la API. El número se asigna al emitir, que es lo que evita los huecos.

¿Qué pasa si el SRI rechaza por “secuencial registrado” (error 70)? POST /invoices/{id}/retry: Olympus toma el siguiente libre, recalcula la clave de acceso y reenvía. Ver Errores del SRI.