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

Proyectos

Cómo funcionan los proyectos en QAPI — la unidad emisora con su propio NIT, su cuota de DTEs, sus API keys y su webhook.

En QAPI, el proyecto es la unidad emisora: cada DTE que emitís pertenece a un proyecto, y el proyecto define con qué NIT se emite, cuánta cuota mensual puede consumir, su API key y a qué webhook se notifica. Los proyectos se crean y se configuran en el dashboard; tu integración solo usa la API key del proyecto.

Sandbox y proyectos live

Al crear tu cuenta, QAPI te crea automáticamente tu Proyecto Sandbox con su API key de prueba ya lista. Es único, vive fuera del límite de proyectos del plan y no consume cuota: es tu entorno de pruebas con el certificador MOCK desde el primer minuto.

Los proyectos live son los que emiten DTEs reales ante la SAT. Cuentan contra el límite del plan y reparten la cuota mensual de DTEs. Lo que hace falta para que un proyecto live emita está en Requisitos para activar live.

TipoPara quéLímiteCuota
Sandbox (test)Pruebas con MOCK, sin validez fiscal1 por cuenta, aparteNo consume
LiveFacturas reales ante la SAT1 / 3 / 8 según planReparte la del plan
Emisor de tu cuenta (live)Facturas reales con el NIT de tu cuenta1 por cuenta, aparteReparte la del plan

Los proyectos live habilitan dos modelos de uso:

ModeloCómo se usa
Empresa que factura para sí mismaUn proyecto live (o varios por sucursal/sistema), todos con tu NIT
Developer/SaaS que integra para tercerosUn proyecto live por cliente final, cada uno con el NIT de ese cliente

El NIT emisor vive en el proyecto

Cada proyecto tiene su propio nit_emisor — el de tu negocio, o el de tu cliente si integrás para terceros. En live, QAPI valida que el emisor.nit de cada factura coincida con el del proyecto de la key (si no, 422 en emisor.nit): no es posible emitir con el NIT del cliente A usando una key del cliente B.

Perfil fiscal del emisor

Además del NIT, cada proyecto declara el perfil fiscal de su emisor, y el payload de cada factura live tiene que respetarlo:

  • Afiliación IVA — GEN (Régimen General) o PEQ (Pequeño Contribuyente). Define qué documentos emite ese proyecto: un emisor GEN factura con FACT (con IVA 12%) y uno PEQ con FPEQ (sin IVA, con la frase "No genera derecho a crédito fiscal"). El catálogo también cambia: un emisor GEN ajusta con notas de crédito y débito, y uno PEQ no. Los dos pueden emitir facturas especiales y recibos (el recibo depende de la personería del emisor). Un emisor PEQ no traslada IVA en ninguno de sus documentos. En live, QAPI valida que el tipo_dte y la emisor.afiliacion_iva de cada factura correspondan al perfil del proyecto — ver Tipos de DTE.
  • Código de establecimiento — el número de establecimiento registrado ante la SAT para ese NIT (casi siempre 1). Es del NIT, no de tu cuenta: si el proyecto usa otro NIT, revisá su número en la constancia del RTU. Si no coincide, la SAT rechaza la factura con la regla 2.2.3.1.

Ambos se configuran en el proyecto, en el dashboard. Los del emisor de tu cuenta se configuran en Configuración → Empresa.

El emisor de tu cuenta

El NIT de tu cuenta también puede emitir DTEs reales, por su propio proyecto live ("Cuenta"), que QAPI crea cuando lo habilitás como emisor en Configuración → Empresa. Para tu integración es un proyecto como cualquier otro: generá una API key en él y emití con ella.

Lo que lo distingue de los demás proyectos:

  • No ocupa lugar en el límite de proyectos de tu plan.
  • Su NIT, su afiliación IVA y su código de establecimiento se cambian en Configuración → Empresa, no en el proyecto: son los datos de tu cuenta.
  • Un NIT, un emisor. El NIT de tu cuenta no puede usarse en otro proyecto, y la cuenta no puede tomar el NIT de un proyecto live activo.
  • Si lo archivás, la cuenta deja de emitir y sus API keys se revocan. Al reactivarlo, generá una key nueva.

Cuota de DTEs repartible

Tu plan incluye una cuota mensual de DTEs (Basic 100, Starter 500, Business 2,000). Esa cuota se reparte entre tus proyectos como quieras desde el dashboard: 100/200/200, 150/250/100, todo en uno — cualquier combinación cuyo total no exceda la cuota del plan. También podés dejar DTEs sin asignar como reserva.

Lo que esto significa para tu integración:

  • Cada proyecto consume solo de su cuota. Cuando la agota, sus emisiones live responden 429 MONTHLY_QUOTA_EXCEEDED hasta que le reasignes cuota o empiece el mes siguiente (hora de Guatemala). Los DTEs libres de la cuenta o los que no usó otro proyecto no pasan solos al que se quedó sin cuota: los reasignás vos.
  • Las emisiones y las anulaciones consumen 1 DTE cada una; un intento que falló no consume. Anular nunca se bloquea por cuota.
  • Para archivar un proyecto, su cuota asignada tiene que estar consumida. Si todavía le queda, bajá su cuota a lo que lleva consumido: lo que liberás queda disponible para repartir entre los demás, y ya podés archivarlo. Lo que emitió en el mes queda reservado hasta el día 1.
  • Te avisamos antes de que se acabe: un correo al 80% y al 100% del saldo del plan, y el evento quota.threshold_reached en el webhook de la cuenta (ver Aviso de consumo). Reasignar en ese momento evita que un proyecto quede bloqueado.
  • Los excedentes no reemplazan la reasignación. Aunque los tengas activados, mientras te queden DTEs del plan sin usar (libres o en otros proyectos), el proyecto que agotó su cuota se bloquea y te pide reasignar. El excedente arranca recién cuando consumiste todo el saldo del plan. Ver Excedentes.

Las pruebas no consumen cuota

Solo las emisiones live descuentan cuota. Las emisiones con keys de test (certificador MOCK) y el sandbox no consumen nada — un proyecto de pruebas puede vivir con cuota 0.

API keys por proyecto

El entorno de las keys de un proyecto (test o live) lo hereda el proyecto — la del Sandbox siempre es test, la de un proyecto live siempre es live; no se elige al crear la key. Lo que sí elegís es el acceso: cada proyecto puede tener hasta dos keys activas a la vez, una de acceso completo y una de solo lectura (ver Autenticación).

Al emitir con la key, QAPI sabe qué NIT corresponde y a qué cuota descontar. Cada key ve solo las facturas de su proyecto. Si necesitás separar credenciales por sistema o cliente, creá otro proyecto: cada uno con su NIT, su cuota y sus propias keys.

Webhook por proyecto

Cada proyecto puede tener su propia URL de webhook con su propio secret HMAC — útil cuando cada cliente final quiere recibir las notificaciones en su sistema. La resolución al emitir es:

  1. webhook_url enviada en el request (si la mandás), o
  2. webhook del proyecto, o
  3. webhook general de la cuenta.

El secret del webhook de proyecto se muestra una sola vez al generarlo — guardalo en ese momento (a diferencia de la API key, el secret del webhook no es recuperable después).

Límites por plan

Propiedad

Tipo

El emisor de tu cuenta no cuenta para este límite. Para sumar un proyecto cuando llegaste al límite, archivá uno que no uses (antes bajá su cuota a lo consumido) o mejorá tu plan.

Archivar conserva las facturas emitidas y el proyecto puede restaurarse después, pero revoca sus API keys: la integración que las use deja de funcionar al instante. El proyecto vuelve sin keys, así que al restaurarlo hay que generar una nueva y cambiarla en tu integración. Restaurar exige que haya lugar en tu plan y cuota disponible.

Un proyecto eliminado vuelve primero a Archivados, y desde ahí lo restaurás.

En esta página