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.
Proyectos
En QAPI, el proyecto es la unidad emisora: cada DTE que emites 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.
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.
Cuando activás tu suscripción, el live se habilita automáticamente (QAPI conmuta tu certificador de MOCK al real) y podés crear proyectos live — los que emiten DTEs reales ante la SAT. Estos sí cuentan contra el límite del plan y reparten la cuota mensual de DTEs.
| Tipo | Para qué | Límite | Cuota |
|---|---|---|---|
| Sandbox (test) | Pruebas con MOCK, sin validez fiscal | 1 por cuenta, aparte | No consume |
| Live | Facturas reales ante la SAT | 3 / 8 / ∞ según plan | Reparte la del plan |
Los proyectos live habilitan dos modelos de uso:
| Modelo | Cómo se usa |
|---|---|
| Empresa que factura para sí misma | Un proyecto live (o varios por sucursal/sistema), todos con tu NIT |
| Developer/SaaS que integra para terceros | Un 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
integras para terceros. Ese NIT debe estar
habilitado como emisor FEL ante la SAT
para emitir en live, y QAPI valida que el emisor.nit de cada factura live coincida con
el del proyecto: 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:
- Afiliación IVA —
GEN(Régimen General) oPEQ(Pequeño Contribuyente). Define el documento que ese proyecto emite: un emisor GEN emiteFACT(con IVA 12%) y un emisor PEQ emiteFPEQ(sin IVA, con la frase "No genera derecho a crédito fiscal"). En live, QAPI valida que eltipo_dtey laafiliacion_ivade cada factura correspondan al perfil del proyecto. - Código de establecimiento — el número de establecimiento registrado ante la SAT para ese emisor.
Ambos se configuran al crear o editar el proyecto en el dashboard. El emisor de tu cuenta (para emitir sin proyecto, con el pool libre) tiene su propio perfil fiscal en Configuración → Empresa.
Cuota de DTEs repartible
Tu plan incluye una cuota mensual de DTEs (Starter 500, Business 2,000). Esa cuota se reparte entre tus proyectos como quieras: 100/200/200, 150/250/100, todo en uno — cualquier combinación cuyo total no exceda la cuota del plan. También puedes dejar DTEs sin asignar como reserva.
Plan Business — 2,000 DTEs/mes
├─ Proyecto "Cliente A" → 800 DTEs
├─ Proyecto "Cliente B" → 600 DTEs
├─ Proyecto "Mi POS" → 400 DTEs
└─ Sin asignar (reserva) → 200 DTEsReglas de la asignación:
- La suma de cuotas de los proyectos activos no puede exceder la cuota del plan
(
422 QUOTA_ALLOCATION_EXCEEDEDsi lo intentas). - Puedes reasignar en cualquier momento, pero la cuota de un proyecto no puede quedar por debajo de lo que ya consumió en el mes en curso.
- Archivar un proyecto libera su cuota para repartirla entre los demás.
- Si un proyecto agota su cuota del mes, sus emisiones live responden
429 MONTHLY_QUOTA_EXCEEDEDhasta que le reasignes cuota o inicie el mes siguiente (hora de Guatemala).
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
Cada proyecto tiene una API key, y su tipo lo define el proyecto: la key del Sandbox es
test, la de un proyecto live es live. Al emitir con esa key, QAPI sabe qué NIT corresponde
y a qué cuota descontar.
- Una key activa por proyecto. Para rotarla, regenerala — eso revoca la anterior de
inmediato (
429 API_KEY_LIMIT_REACHEDsi intentas crear una segunda sin revocar). - La key es recuperable. A diferencia de otros servicios, no la pierdes si no la copiaste al crearla: podés volver a verla y copiarla completa desde el dashboard (ícono del ojo). Cada vez que se revela queda registrado en el log de auditoría de tu cuenta.
- Si necesitas separar credenciales por sistema o cliente, creá otro proyecto — cada uno con su NIT, su cuota y su key.
Si emites desde el dashboard (Playground o Generar Factura) en lugar de con una key, eliges el proyecto emisor en el formulario.
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:
webhook_urlenviada en el request (si la mandas), o- webhook del proyecto, o
- 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
Prop
Type
Al alcanzar el límite recibirás 429 PROJECT_LIMIT_REACHED — archiva un proyecto que no
uses o mejora tu plan. Archivar no borra nada: las facturas emitidas se conservan y el
proyecto puede restaurarse después.