Entornos
Diferencias entre los entornos test y live, el certificador MOCK y cómo activar la certificación real con la SAT.
QAPI separa completamente el tráfico de pruebas del tráfico de producción mediante dos entornos independientes, cada uno con su propia API key.
Comparación
| Test | Live | |
|---|---|---|
| API key | qapi_test_... | qapi_live_... |
| Certificador | MOCK (siempre) | Certificador autorizado por la SAT |
| Conecta a la SAT | No | Sí |
| Consume cuota del plan | No | Sí |
| UUID SAT | Generado localmente | Real, válido ante la SAT |
| Generado por QAPI, con marca "DOCUMENTO DE PRUEBA" | PDF oficial del certificador | |
| Webhooks | Sí se disparan¹ | Sí se disparan |
Sandbox /v1/sandbox | Disponible (siempre MOCK) | Disponible (siempre MOCK) |
¹ Los webhooks se disparan en cualquier emisión, incluso con API key de test y también
desde POST /v1/sandbox/invoices. Las emisiones de prueba llegan con data.test: true en el
payload para distinguirlas de una real (el sandbox usa el webhook de la cuenta o el
webhook_url que mandes en el request). Ver Webhooks.
Entorno Test
El entorno test usa el certificador MOCK, que simula el proceso completo de certificación sin conectarse a la SAT ni a ningún certificador externo.
El certificador MOCK responde en milisegundos y nunca falla por causas externas. Ideal para pruebas de integración, CI/CD y desarrollo local.
Comportamiento del certificador MOCK
- Acepta cualquier factura que pase las 21 validaciones de QAPI
- Genera un
uuid_sataleatorio (no es válido ante la SAT) - Genera
serieynumero_dtede prueba - El
pdf_urlsí funciona: QAPI genera el PDF al vuelo, marcado como "DOCUMENTO DE PRUEBA" - El campo
certificadoren la respuesta siempre es"MOCK"
Cupo diario de pruebas
Las emisiones de prueba no consumen cuota, pero tienen un cupo diario según tu plan:
| Plan | DTEs de prueba por tipo, por día |
|---|---|
| Basic | 10 |
| Starter | 30 |
| Business | 50 |
Cuenta toda emisión con MOCK, por POST /v1/sandbox/invoices o por POST /v1/invoices
con tu key qapi_test_...: el contador es uno solo. El límite es por tipo de DTE, no un
total, y se reinicia a las 00:00 hora de Guatemala. Cuando lo superás:
429 SANDBOX_LIMIT_REACHED con detalle de cuántos llevás. Ver
Sandbox.
Entorno Live
El entorno live enruta tus DTEs al certificador autorizado por la SAT que QAPI tiene configurado en tu cuenta.
Las facturas live son legales
Cada DTE emitido en entorno live es un documento tributario válido ante la SAT. Cancelarlo requiere una nota de crédito o el proceso de anulación. No hay forma de "deshacer" una factura certificada.
Requisitos para activar live
Cada DTE live sale de un proyecto, y el proyecto define con qué NIT se emite. Para emitir con ese NIT hacen falta cuatro cosas:
-
Una suscripción activa. Sin el plan pagado no se activa el certificador real (ver abajo). Y si el plan deja de estar activo después, la emisión live se pausa con
403 SUBSCRIPTION_INACTIVE; el Sandbox sigue disponible. -
El NIT habilitado como emisor FEL ante la SAT. ¿De quién es ese NIT?
- Si facturás para tu propio negocio: el tuyo.
- Si sos un desarrollador que integra para terceros (SaaS, POS): el de cada cliente final — el trámite le corresponde al dueño del negocio. Verificalo en tu onboarding.
El trámite es gratuito, en línea y por una sola vez en Agencia Virtual (sección FEL → habilitación como emisor).
-
Los requisitos del contribuyente listos: RTU actualizado, el certificador que te indiquemos acreditado en la Agencia Virtual de la SAT (menú FEL → acreditar certificador), firma electrónica vigente, y un correo y un contacto comercial para el trámite. El dashboard te muestra la lista al solicitar la habilitación.
-
El emisor habilitado en QAPI. Con el plan pagado, en el dashboard, dentro del proyecto, tocás Solicitar habilitación: DTEVIA gestiona el alta del NIT ante el certificador y te avisa al completarse. Hasta entonces, la emisión live con ese proyecto responde
409 EMISOR_NOT_PROVISIONED.
No necesitás contrato ni credenciales propias con ningún certificador, ni configurar nada técnico: QAPI gestiona esa relación por vos.
Activación del certificador
El certificador real de tu cuenta lo activa DTEVIA, y solo con el plan pagado: no se
activa solo al pagar. Mientras tu cuenta no esté activada, una key qapi_live_... emite
igual que una de prueba: certifica con MOCK, sin validez fiscal y contando contra el cupo
diario de pruebas.
Por eso, mirá el campo certificador de cada factura: con el live activo trae el certificador
real que la certificó, y en una prueba siempre es "MOCK":
{
"id": "inv_01jx...",
"status": "CERTIFIED",
"tipo_dte": "FACT",
"certificador": "TOTALDOC"
}Tratá certificador como un string informativo, no como un enum cerrado: los valores
posibles ("MOCK", "TOTALDOC", …) pueden ampliarse cuando QAPI integre más
certificadores. Tu integración no cambia — QAPI enruta el DTE por vos.
Planes y cuotas
| Plan | DTEs/mes en live | Rate limit | Proyectos activos | Precio |
|---|---|---|---|---|
| Basic | 100 | 30 req/min | 1 | Por confirmar |
| Starter | 500 | 60 req/min | 3 | Por confirmar |
| Business | 2,000 | 200 req/min | 8 | Por confirmar |
Basic es el plan de entrada: toda cuenta nueva nace ahí
Una cuenta recién creada arranca en Basic con el sandbox abierto y la emisión live cerrada. Los 100 DTEs se habilitan cuando el plan queda pagado — ver Requisitos para activar live.
La cuota se reparte entre tus proyectos
Los DTEs/mes del plan se asignan entre tus proyectos como quieras (ej. 100/200/200 de 500). Ver Proyectos.
Los DTEs emitidos en entorno test (API key qapi_test_...) no consumen cuota de tu plan.
Solo los emitidos en live (qapi_live_...) cuentan contra tu límite mensual.
Headers de rate limit
Cada respuesta de QAPI incluye headers para monitorear tu consumo:
| Header | Descripción |
|---|---|
X-RateLimit-Limit | Límite total de requests por ventana |
X-RateLimit-Remaining | Requests restantes en la ventana actual |
Retry-After | Segundos a esperar si recibís 429 |
X-Request-ID | ID único del request (útil para soporte) |
X-Response-Checksum | Checksum de la respuesta para verificar integridad |