QAPI está en beta — la API puede cambiar sin previo aviso. Usá sandbox para pruebas.
QAPIQAPIDocs · by DTEVIA
Empezar

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

TestLive
API keyqapi_test_...qapi_live_...
CertificadorMOCK (siempre)Certificador autorizado por la SAT
Conecta a la SATNoSí
Consume cuota del planNoSí
UUID SATGenerado localmenteReal, válido ante la SAT
PDFGenerado por QAPI, con marca "DOCUMENTO DE PRUEBA"PDF oficial del certificador
WebhooksSí se disparan¹Sí se disparan
Sandbox /v1/sandboxDisponible (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_sat aleatorio (no es válido ante la SAT)
  • Genera serie y numero_dte de prueba
  • El pdf_url sí funciona: QAPI genera el PDF al vuelo, marcado como "DOCUMENTO DE PRUEBA"
  • El campo certificador en 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:

PlanDTEs de prueba por tipo, por día
Basic10
Starter30
Business50

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:

  1. 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.

  2. 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).

  3. 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.

  4. 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

PlanDTEs/mes en liveRate limitProyectos activosPrecio
Basic10030 req/min1Por confirmar
Starter50060 req/min3Por confirmar
Business2,000200 req/min8Por 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:

HeaderDescripción
X-RateLimit-LimitLímite total de requests por ventana
X-RateLimit-RemainingRequests restantes en la ventana actual
Retry-AfterSegundos a esperar si recibís 429
X-Request-IDID único del request (útil para soporte)
X-Response-ChecksumChecksum de la respuesta para verificar integridad

En esta página