Diferencias entre los entornos test y live, el certificador MOCK y cómo activar la certificación real con la SAT.

Entornos

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
PDF	El enlace no resuelve (UUID ficticio)	PDF oficial del certificador
Webhooks	Sí se disparan¹	Sí se disparan
Sandbox `/v1/sandbox`	JWT o API key	JWT o API key

¹ 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 14 validaciones de QAPI
Genera un uuid_sat aleatorio (no es válido ante la SAT)
Genera serie y numero_dte de prueba
Devuelve una URL de PDF de prueba
El campo certificador en la respuesta siempre es "MOCK"

Límites del sandbox (para `/v1/sandbox`)

Si usas el endpoint especial de sandbox (/v1/sandbox/invoices), hay límites diarios adicionales:

Prop

Type

Cuando superas el límite: 429 SANDBOX_LIMIT_REACHED con detalle de cuántos llevas.

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

Solo dos cosas:

El NIT emisor de la cuenta habilitado como emisor FEL ante la SAT. Cada DTE se emite con el NIT configurado en la cuenta, así que la SAT exige que esté habilitado — si no lo está, el certificador rechazará las facturas live. ¿De quién es ese NIT?
- Si facturas para tu propio negocio: el tuyo.
- Si eres un desarrollador que integra para terceros (SaaS, POS): el de cada cliente final — el trámite le corresponde al dueño del negocio. Verifícalo 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).
Una suscripción activa. Al activar tu plan de pago, el live se habilita automáticamente: QAPI conmuta el certificador de tu cuenta de MOCK al certificador real y tu API key qapi_live_... queda operativa. No necesitas contrato ni credenciales propias con ningún certificador, ni configurar nada técnico — QAPI gestiona todo eso internamente.

Activación del certificador

La activación la dispara el pago de la suscripción (no hay un paso manual). Una vez activado, el campo certificador en GET /v1/auth/me mostrará el certificador configurado en tu cuenta:

{
  "tenant": {
    "id": "ten_...",
    "nombre": "Mi Empresa",
    "nit_emisor": "12345678",
    "plan": "business",
    "certificador": "TOTALDOC"
  }
}

Trata 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 ti.

Planes y cuotas

Prop

Type

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 recibes `429`
`X-Request-ID`	ID único del request (útil para soporte)
`X-Response-Checksum`	Checksum de la respuesta para verificar integridad

Entornos

On this page