Ambientes y claves
Sandbox, Pruebas y Producción. Qué hace cada uno, qué comparten y cómo tu clave API decide dónde emites.
Tienes tres ambientes y una clave API para cada uno. La clave decide el ambiente: no hay un campo environment que puedas equivocar, así que emitir en Producción siempre es una decisión explícita.
| Sandbox | Pruebas | Producción | |
|---|---|---|---|
| Clave | fb_sandbox_… | fb_test_… | fb_live_… |
| Quién autoriza | Un simulador de Fiscalbase | El ambiente de pruebas del SRI | El SRI |
| Certificado | Uno de práctica, nuestro | El tuyo | El tuyo |
| Numeración | 001-001 lista al crear el negocio | La abres tú | La abres tú |
| Negocio | De Sandbox, con datos inventados | En vivo, con tu RUC | En vivo, con tu RUC |
| Costo | Gratis | Según el plan del negocio | Según el plan del negocio |
| Correo a tus clientes | Solo a las direcciones que pidas | Solo a las direcciones que pidas | Automático al autorizarse |
| RIDE | Marca de agua SANDBOX | Marca de agua PRUEBAS | Sin marca |
| Validez tributaria | No | No | Sí |
Para qué sirve cada uno
Sandbox es para construir y practicar. Responde en segundos, no necesita certificado y puedes forzar cualquier respuesta del SRI con simulate. Úsalo en tu entorno de desarrollo y en tus pruebas automatizadas.
Pruebas es para confirmar con el SRI. Usa tu certificado real y el ambiente de pruebas del SRI (celcer): si algo de tus datos no le gusta al SRI, aquí lo descubres sin consecuencias.
Producción es la emisión real. Cada comprobante autorizado tiene validez tributaria, se le envía a tu cliente y aparece en tu portal. Se enciende una vez por negocio, cuando una persona lo pasa a Producción; Pruebas sigue disponible después, y Sandbox, con sus negocios de práctica, para siempre.
Dos clases de negocio
Un negocio (en la API, una entity) es de una de dos clases, que eliges al crearlo y no cambia:
- Sandbox: un negocio de práctica. Sus datos legales son inventados y usa siempre el RUC de práctica
9999999999001. Emite solo en Sandbox, es gratis, puedes tener los que quieras y puedes borrarlos. - En vivo: tu RUC real, consultado en el SRI. Emite solo en Pruebas y en Producción, tiene su propio plan y no se borra.
La clave decide con qué negocio trabajas: una clave de Sandbox emite con tu negocio de Sandbox; una de Pruebas o de Producción, con tu negocio en vivo. Si tienes varios de esa clase, dices cuál con entity_id. Nombrar un negocio de la otra clase da un 422 que te dice de qué clase es.
Qué comparten y qué no
Los negocios y sus certificados son de la organización: los registras una vez. Un negocio en vivo usa el mismo certificado en Pruebas y Producción; uno de Sandbox no lo necesita.
Todo lo operativo está separado por ambiente:
- Comprobantes: una factura de Sandbox no existe para una clave de Producción.
- Numeración: cada ambiente cuenta sus propios números. La factura 001-001-000000001 de Sandbox y la de Producción son distintas.
- Webhooks: cada endpoint recibe solo los eventos de su ambiente.
- Idempotencia: un
Idempotency-Keyusado en Sandbox no afecta a Producción.
Tus claves
Creas y revocas tus claves en la plataforma, en Desarrollo → Claves API (cómo). Envíalas en cada solicitud:
Authorization: Bearer fb_live_…Tus claves de Producción emiten con validez tributaria
Guárdalas como guardarías una contraseña: en variables de entorno o en un gestor de secretos, nunca en el código ni en el navegador. Si una se filtra, revócala en la plataforma y crea otra.
Una clave sin prefijo conocido, revocada o inexistente recibe 401 unauthorized.