Cómo funciona Fiscalbase

Esta página no tiene código. Es el modelo mental: con él, cada endpoint de la referencia tiene sentido a la primera.

La jerarquíaCopiar enlace a esta sección

Todo en Fiscalbase cuelga de una organización, tu espacio, que se crea sola cuando entras por primera vez. Dentro de ella viven tus negocios (en la API, entity): de práctica, para Sandbox, o en vivo, con un RUC real que emite comprobantes.

Cada API key es de un negocio: emite con él y solo ve lo suyo, así que ninguna petición dice cuál negocio emite. Para emitir con otro, usa la API key de ese otro.

Tres ambientes, tres API keysCopiar enlace a esta sección

Cada organización trabaja en tres ambientes separados. La API key que usas decide en cuál estás: no hay un parámetro para elegirlo, así que nunca emites en Producción por accidente.

Un negocio de Sandbox emite solo en Sandbox; uno en vivo, solo en Pruebas y Producción, y paga un plan: hasta que validamos su primer pago, no emite. Los comprobantes, la numeración y los webhooks no: una factura de Sandbox nunca aparece en Producción. Más en Ambientes y API keys.

La vida de un comprobanteCopiar enlace a esta sección

Cuando emites, Fiscalbase acepta la venta, la numera y responde enseguida con el comprobante en pending. El resto ocurre después, sin que tengas que hacer nada:

1. Aceptado (pending): validamos, calculamos, numeramos y guardamos. Un rechazo aquí no consume número.
2. Firmado: armamos el XML exacto de la ficha técnica y lo firmamos con tu certificado.
3. Recibido (submitted): el SRI tiene el comprobante y lo está revisando.
4. Autorizado (authorized): es válido. Generamos el RIDE y lo enviamos a tu cliente.

Si el SRI lo devuelve o no lo autoriza, el comprobante espera tu corrección, con los mensajes del SRI en sri_messages. Lo corriges con resubmit y conserva el mismo número y la misma clave de acceso: así lo exige el SRI. El detalle está en Ciclo de vida.

Por qué la respuesta HTTP no es el resultadoCopiar enlace a esta sección

La respuesta a POST /v1/ec/invoices te dice que aceptamos la venta, no que el SRI la autorizó. El SRI decide en segundos, pero a veces tarda horas: responder solo al final dejaría tu sistema esperando.

• Un 201 con status: "pending" es el caso normal: la factura está numerada y en camino.
• El resultado llega por webhook (invoice.authorized, invoice.returned…) o consultando el comprobante.
• Un 422 sí es definitivo: la venta tiene un error y no se numeró nada.

Cómo se ve en la prácticaCopiar enlace a esta sección

Una factura recién emitida en Sandbox, recortada a lo esencial:

{
  "id": "01a0ef7b-1c3a-7d01-b6b4-b248c6b735de",
  "object": "invoice",
  "environment": "sandbox",
  "country": "ec",
  "currency": "USD",
  "status": "pending",
  "status_transitions": { "pending": "2026-09-29T15:42:07.000Z" },
  "entity_id": "0193f1c2-6b0a-7c4e-9d51-3a2f8e1b7c90",
  "number": "001-001-000000001",
  "access_key": "2909202601179214673900110010010000000019936283414",
  "authorization": null,
  "sri_messages": [],
  "metadata": { "order_id": "1041" },
  "issue_date": "2026-09-29",
  "buyer": {
    "identification_type": "cedula",
    "identification": "1710034065",
    "name": "María Robles",
    "address": null,
    "email": "maria@example.com"
  },
  "subtotal": "10.00",
  "iva": "1.50",
  "total": "11.50",
  "created_at": "2026-09-29T15:42:07.000Z",
  "updated_at": "2026-09-29T15:42:07.000Z"
}

Primero vienen los campos que todo comprobante comparte (id, country, currency, status, number, access_key…) y después los de su tipo (buyer, lines, total…), calculados por nosotros.

Preguntas frecuentesCopiar enlace a esta sección

¿Necesito un certificado para empezar?Copiar enlace a esta sección

No. Sandbox firma con un certificado de práctica y un simulador responde por el SRI. Lo necesitas para Pruebas y Producción.

¿Puedo emitir por varios RUC?Copiar enlace a esta sección

Sí. Registra cada RUC como negocio en vivo dentro de tu organización y crea una API key en cada uno: cada API key emite con el RUC de su negocio. Cada negocio en vivo tiene su propio plan.

¿Qué pasa si envío la misma venta dos veces?Copiar enlace a esta sección

Con el mismo Idempotency-Key, recibes el mismo comprobante: no se emite dos veces. Mira Idempotencia y reintentos.

¿Quién le envía el comprobante a mi cliente?Copiar enlace a esta sección

Nosotros, en cualquier ambiente, apenas se autoriza: el RIDE y el XML van al correo del comprador, que es obligatorio salvo para consumidor final. En Sandbox y Pruebas el correo lo dice en el asunto. Tu cliente también los encuentra en tu portal.

Qué leer despuésCopiar enlace a esta sección