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

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.

GET
/v1/invoices

Autorización

ApiKeyAuth
AutorizaciónBearer <token>

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

page?integer
limit?integer
status?string

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

tipo_dte?string

Filtrar por tipo de DTE (ej. FACT). Mismo comportamiento que status: un valor que no existe da lista vacía, no error.

exclude_mock?boolean

Con "true" excluye las facturas certificadas con MOCK (pruebas) — útil para conciliación contable.

origen?string

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.

project_id?string

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.

from?string

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.

to?string

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"
}