Ambientes y API keys
Sandbox, Pruebas y Producción. Qué hace cada uno, qué comparten y cómo tu API key decide dónde emites.
Tienes tres ambientes y una API key para cada uno. La API key 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 | |
|---|---|---|---|
| API key | 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 | Con el plan del negocio; sus comprobantes no se cobran | Con el plan del negocio, según tu volumen |
| Correo a tus clientes | Automático al autorizarse | Automático al autorizarse | Automático al autorizarse |
| RIDE | Lleva «Sandbox, sin validez tributaria» | Lleva «Pruebas, sin validez tributaria» | Sin leyenda |
| 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. Como en los otros ambientes, el correo llega a la dirección del comprador que pongas, así que usa una que puedas leer.
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.
Cada API key es de un solo negocio, que eliges al crearla: una API key de Sandbox es de un negocio de Sandbox; una de Pruebas o de Producción, de un negocio en vivo. Ninguna petición dice con qué negocio trabaja, porque la API key ya lo sabe. Para emitir con otro negocio, crea una API key en ese negocio. Si envías Fiscalbase-Entity con otro negocio que el suyo, respondemos 422 con el código entity_mismatch.
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 API key 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 es de un negocio y un ambiente, y recibe solo los eventos de ese negocio y de ese ambiente.
- Idempotencia: un
Idempotency-Keyusado en Sandbox no afecta a Producción.
Tus API keys
Creas y revocas tus API keys en la plataforma, en API (cómo). Envíalas en cada solicitud:
Authorization: Bearer fb_live_…Tus API keys 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 API key sin prefijo conocido, revocada o inexistente recibe 401 unauthorized.