Cómo funciona Fiscalbase
El mapa, no el recorrido. Las piezas de la plataforma y cómo se relacionan, antes de escribir código.
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ía
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.
| Pieza | Qué es | Cómo se crea |
|---|---|---|
| Organización | Tu espacio. Agrupa a tu equipo, tus negocios y tus claves API. | Sola, la primera vez que entras; puedes cambiarle el nombre |
| Negocio | Lo que emite. De Sandbox: datos inventados, el RUC de práctica, gratis. En vivo: un RUC real, con su razón social, régimen y obligaciones del registro del SRI, y su propio plan. Se elige al crearlo y no cambia. | POST /v1/ec/entities con kind |
| Numeración (serie) | Un establecimiento y un punto de emisión para un tipo de comprobante, en un ambiente. Lleva la cuenta del próximo número. | Se abre sola en un negocio de Sandbox; en uno en vivo, en Pruebas y Producción, POST …/series |
| Certificado | La firma electrónica (.p12) de un negocio en vivo. Firma todo lo que emite en Pruebas y Producción. | POST …/certificates |
| Comprobante | Lo que emites. Lleva su número, su clave de acceso y su estado. | POST /v1/ec/invoices, /credit-notes… |
Si solo tienes un negocio de la clase que tu clave emite, no necesitas pensar más en esto: la API lo usa solo. Si tienes varios, cada comprobante dice con entity_id cuál emite.
Tres ambientes, tres claves
Cada organización trabaja en tres ambientes separados. La clave API que usas decide en cuál estás: no hay un parámetro para elegirlo, así que nunca emites en Producción por accidente.
| Clave | Ambiente | Llega al SRI | Validez tributaria |
|---|---|---|---|
fb_sandbox_… | Sandbox | No: un simulador responde como el SRI | No |
fb_test_… | Pruebas | Sí, al ambiente de pruebas del SRI | No |
fb_live_… | Producción | Sí | Sí |
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 claves.
La vida de un comprobante
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:
- Aceptado (
pending): validamos, calculamos, numeramos y guardamos. Un rechazo aquí no consume número. - Firmado: armamos el XML exacto de la ficha técnica y lo firmamos con tu certificado.
- Recibido (
submitted): el SRI tiene el comprobante y lo está revisando. - 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 resultado
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
201constatus: "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
422sí es definitivo: la venta tiene un error y no se numeró nada.
Cómo se ve en la práctica
Una factura recién emitida en Sandbox:
{
"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 frecuentes
¿Necesito un certificado para empezar?
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?
Sí. Registra cada RUC como negocio en vivo dentro de tu organización e indica entity_id al emitir. Cada negocio en vivo tiene su propio plan.
¿Qué pasa si envío la misma venta dos veces?
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?
Nosotros, en Producción, apenas se autoriza: el RIDE y el XML van al correo del comprador. Tu cliente también los encuentra en tu portal.