Listar facturas
Devuelve las facturas del tenant con paginación, ordenadas de la más reciente a la más antigua.
Tres ejes que se combinan
Los filtros de procedencia son independientes entre sí y conviene no confundirlos:
project_id— dónde vive la factura (qué proyecto la emitió).exclude_mock— con qué validez se certificó (MOCK = prueba, sin efecto tributario).origen— desde dónde se hizo el request (Playground del dashboard o integración propia).
Una emisión del Playground y una hecha con API key de prueba comparten proyecto y certificador MOCK: solo origen las separa.
Autorización
ApiKeyAuth API key con prefijo qapi_test_ (Sandbox) o qapi_live_ (producción), enviada en el header Authorization: Bearer <api_key>. Se genera en el dashboard, dentro de cada proyecto.
Va en: header
Parámetros de query
Filtrar por estado exacto. A diferencia de origen, un valor fuera del enum NO responde 422 — se pasa tal cual al filtro y simplemente no matchea ninguna fila (lista vacía, no error).
Filtrar por tipo de DTE (ej. FACT). Mismo comportamiento que status: un valor que no existe da lista vacía, no error.
Con "true" excluye las facturas certificadas con MOCK (pruebas) — útil para conciliación contable.
Filtrar por procedencia del request: playground (editor JSON del dashboard) o api (tu integración). Un valor distinto responde 422 en vez de ignorarse en silencio, para que un filtro mal escrito no devuelva la lista completa aparentando haber filtrado.
Filtrar por proyecto emisor. Debe ser un UUID: cualquier otro valor devuelve 422. Incluye los proyectos archivados: sus facturas siguen siendo tuyas y no desaparecen del historial.
Fecha de inicio del rango, formato YYYY-MM-DD. El día se interpreta en hora de Guatemala (UTC-6) e incluye desde las 00:00. Un formato inválido se ignora.
Fecha de fin del rango, formato YYYY-MM-DD, inclusive: abarca hasta las 23:59:59 de ese día en hora de Guatemala. Un formato inválido se ignora.
Cuerpo de la respuesta
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/invoices"{
"data": [
{
"id": "inv_V1StGXR8_Z5jdHi6",
"status": "PENDING",
"tipo_dte": "FACT",
"moneda": "GTQ",
"gran_total": 112,
"numero_acceso": 543219876,
"certificador": "MOCK",
"origen": "api",
"project_id": "prj_8kQm2Xb1",
"project_nombre": "POS MARKET",
"modo": "sandbox",
"uuid_sat": "91cfb67b-89f6-4d15-a97b-76fa68e0db9c",
"serie": "QAPI",
"numero_dte": 42,
"pdf_url": "http://example.com",
"referencia_interna": "string",
"integrity_checksum": "string",
"error_code": "string",
"error_message": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"certified_at": "2019-08-24T14:15:22Z",
"cancelled_at": "2019-08-24T14:15:22Z"
}
],
"total": 0,
"page": 0,
"limit": 0
}{
"type": "https://docs.dtevia.com.gt/errors/invalid-api-key",
"title": "INVALID_API_KEY",
"status": 401,
"detail": "API key inválida o revocada",
"instance": "/v1/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/email-not-verified",
"title": "EMAIL_NOT_VERIFIED",
"status": 403,
"detail": "Confirmá el correo de tu cuenta para usar Facturas y Sandbox.",
"instance": "/v1/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/validation-error",
"title": "VALIDATION_ERROR",
"status": 422,
"detail": "Error de validación",
"instance": "/v1/invoices",
"invalid_params": [
{
"field": "origen",
"message": "Solo acepta playground o api"
}
]
}{
"type": "https://docs.dtevia.com.gt/errors/rate-limited",
"title": "RATE_LIMITED",
"status": 429,
"detail": "Límite de requests excedido. Reintentar en 60s",
"instance": "/v1/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/internal-error",
"title": "INTERNAL_ERROR",
"status": 500,
"detail": "Error interno del servidor",
"instance": "/v1/invoices"
}Planes y facturación
Ciclo de vida de la suscripción — cambio de plan, cobros fallidos, baja, qué implica el corte y la política de reembolso.
Emitir factura
Crea una factura y la envía al certificador. Responde 202 con status: "PROCESSING" de inmediato: la certificación es asíncrona. El estado final se obtiene con GET /v1/invoices/{id} (polling) o configurando un webhook.