Provex API

Documentación de referencia para los endpoints de consulta de Documentos Tributarios Electrónicos (DTEs) de Compras en Guatemala.

URL Base

Todos los endpoints comparten la siguiente URL base:

https://api.provex.com.gt

Endpoints disponibles:

Método Endpoint Descripción
GET /dte Consulta un DTE individual por autorización o por serie y número.
GET /dte/compras Listado paginado de DTEs recibidos (compras) por rango de fechas.

Autenticación

Todas las solicitudes requieren un Bearer Token en el encabezado Authorization, proporcionado por Provex al activar el acceso a la API. Aplica para todos los endpoints.

⚠ Importante El token es de uso exclusivo para tu organización. No lo compartas ni lo incluyas en código fuente público. Si crees que tu token fue comprometido, contáctanos para renovarlo.
Header HTTP 
Authorization: Bearer TU_TOKEN_AQUÍ

GET/dte — Consulta de DTE

Consulta un Documento Tributario Electrónico individual. La búsqueda puede realizarse por número de autorización de SAT, o bien por serie y número del documento.

GET https://api.provex.com.gt/dte

Modos de búsqueda

La API acepta dos modos de búsqueda mutuamente excluyentes. No es posible combinarlos; debes elegir uno u otro.

Modo 1
Por autorización
Busca el DTE usando el UUID de autorización emitido por SAT.
?autorizacion=<UUID>
Modo 2
Por serie y número
Busca el DTE usando la serie del documento junto con su número correlativo. Ambos campos son obligatorios en este modo.
?serie=<SERIE>&numero=<NÚMERO>

Parámetros de consulta (Query Params)

Parámetro Tipo Requerido Descripción
autorizacion string Condicional UUID de autorización de SAT. Requerido en el Modo 1. Ejemplo: 4A21ED77-CCC1-48AA-8F9A-706A016039A6
serie string Condicional Serie del documento tributario. Requerido en el Modo 2, junto con numero.
numero string Condicional Número correlativo del documento. Requerido en el Modo 2, junto con serie.
incluirXml boolean Opcional Si es true, la respuesta incluye el XML del DTE en el campo xml. Por defecto: false.
incluirJsonDetalle boolean Opcional Si es true, la respuesta incluye el JSON completo del DTE (con frases, tipo, etc.) en el campo json. Por defecto: false.

Ejemplos de solicitud

Modo 1 — Búsqueda por número de autorización

cURL 
curl 'https://api.provex.com.gt/dte?autorizacion=4A21ED77-CCC1-48AA-8F9A-706A016039A6' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Modo 2 — Búsqueda por serie y número

cURL 
curl 'https://api.provex.com.gt/dte?serie=4A21ED77&numero=3435219114' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Incluyendo XML y detalle JSON en la respuesta

cURL 
curl 'https://api.provex.com.gt/dte?autorizacion=4A21ED77-CCC1-48AA-8F9A-706A016039A6&incluirXml=true&incluirJsonDetalle=true' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Ejemplo con JavaScript (fetch)

JavaScript 
const consultarDTE = async (autorizacion) => {
  const params = new URLSearchParams({ autorizacion })

  const res = await fetch(
    `https://api.provex.com.gt/dte?${params}`,
    {
      headers: {
        Authorization: `Bearer ${TU_TOKEN}`
      }
    }
  )

  const data = await res.json()
  return data
}

Respuesta exitosa

Cuando el DTE es encontrado, la API retorna un objeto JSON con el estado 200 OK.

JSON · 200 OK 
{
  "codigo": 0,
  "mensaje": "Ok",
  "data": {
    "dte": {
      "fechaEmision": "2025-10-11 04:30:00",
      "fechaCertificacion": "2025-10-11 10:31:17",
      "numeroUuid": "4A21ED77-CCC1-48AA-8F9A-706A016039A6",
      "tipo": "FACT",
      "serie": "4A21ED77",
      "numeroDocumento": "3435219114",
      "nitEmisor": "91354374",
      "nombreEmisor": "AVIA PARQUEO, SOCIEDAD ANONIMA",
      "nitReceptor": "1000178900",
      "nombreReceptor": "DEVCOM, SOCIEDAD ANÓNIMA",
      "nitCertificador": "50510231",
      "nombreCertificador": "Megaprint, S.A.",
      "moneda": "GTQ",
      "granTotal": "50.000000",
      "totalIva": "5.360000",
      "fechaAnulacion": null,
      "anulado": "V"
      // ...otros campos de impuestos
    },
    "xml": "<?xml version=\"1.0\" ...>",  // solo si incluirXml=true
    "json": { /* detalle completo */ }, // solo si incluirJsonDetalle=true
    "existente": true
  }
}
Campo Descripción
codigo 0 indica éxito. Cualquier otro valor indica un error.
mensaje Descripción legible del resultado. En éxito: "Ok".
data.dte Objeto con los campos principales del documento: emisor, receptor, montos, fechas, tipo, serie, número de documento, certificador, etc.
data.xml XML original firmado del DTE. Solo presente si se envió incluirXml=true.
data.json JSON estructurado con frases, leyendas, items, totales y certificación. Solo presente si se envió incluirJsonDetalle=true.
data.existente true si el DTE fue encontrado en la base de datos local; false si fue consultado en tiempo real al SAT.

Códigos de error

En caso de error, la API retorna un objeto descriptivo que indica qué salió mal.

HTTP Causa Mensaje típico
400 Parámetros inválidos o combinación no permitida Si viene autorización, NO deben venir serie ni número.
400 Serie sin número o viceversa Serie y número deben venir juntos, y autorización debe ser null.
400 Ningún parámetro de búsqueda enviado Debes enviar: autorización sola, o serie y número juntos con autorización null.
401 Token ausente o inválido Unauthorized
404 DTE no encontrado Datos no existentes
500 Error interno del servidor Error interno, contactar soporte.
JSON · Error de validación 
{
  "codigo": 8,
  "mensaje": "Datos del formulario no adecuados para la acción.",
  "data": "Si viene autorización, NO deben venir serie ni número."
}

GET/dte/compras — Listado de Compras

Retorna un listado paginado de los DTEs recibidos (compras) dentro de un rango de fechas. Ideal para conciliación contable y auditoría de documentos recibidos.

GET https://api.provex.com.gt/dte/compras

Parámetros de consulta

Todos los parámetros se envían como query params. Las fechas son obligatorias.

Parámetro Tipo Requerido Default Descripción
fechaInicio string Requerido — Fecha de inicio del rango en formato ISO 8601. Ej: 2025-10-01
fechaFin string Requerido — Fecha de fin del rango en formato ISO 8601. Ej: 2025-10-31. Debe ser mayor o igual a fechaInicio.
pagina integer Opcional 1 Número de página a retornar. Mínimo: 1.
tamano integer Opcional 100 Cantidad de registros por página. Mínimo: 1, Máximo: 1000.
ℹ Paginación El servidor limita el tamaño máximo a 1000 registros por página. Usa el campo paginacion.totalPaginas de la respuesta para saber cuántas páginas hay en total.

Ejemplos de solicitud

Consulta básica por rango de fechas

cURL 
curl 'https://api.provex.com.gt/dte/compras?fechaInicio=2025-10-01&fechaFin=2025-10-31' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Con paginación personalizada

cURL 
curl 'https://api.provex.com.gt/dte/compras?fechaInicio=2025-10-01&fechaFin=2025-10-31&pagina=2&tamano=50' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

JavaScript — iterar todas las páginas

JavaScript 
const obtenerTodasLasCompras = async (fechaInicio, fechaFin) => {
  let pagina = 1
  let todos = []

  while (true) {
    const params = new URLSearchParams({ fechaInicio, fechaFin, pagina, tamano: 1000 })
    const res = await fetch(`https://api.provex.com.gt/dte/compras?${params}`, {
      headers: { Authorization: `Bearer ${TU_TOKEN}` }
    })
    const { data } = await res.json()
    todos = [...todos, ...data.dtes]

    if (pagina >= data.paginacion.totalPaginas) break
    pagina++
  }

  return todos
}

Respuesta exitosa

JSON · 200 OK 
{
  "codigo": 0,
  "mensaje": "Ok",
  "data": {
    "dtes": [
      {
        "dteRecibidoId": 33049,
        "nitEmisor": "91354374",
        "nombreEmisor": "AVIA PARQUEO, SOCIEDAD ANONIMA",
        "nombreReceptor": "DEVCOM, SOCIEDAD ANÓNIMA",
        "receptorId": "1000178900",
        "nombreComercial": "AVIA PARQUEO",
        "codigoEstablecimiento": "2",
        "fechaCertificacion": "2025-10-11 10:31:17",
        "tipoDteId": 727,
        "tipoDteNombre": "Factura",
        "monedaId": 1,
        "monedaNombre": "Quetzal",
        "total": "50.000000",
        "totalIVA": "5.360000",
        "autorizacion": "4A21ED77-CCC1-48AA-8F9A-706A016039A6",
        "serie": "4A21ED77",
        "numeroDte": "3435219114",
        "estadoId": 8,
        "estadoNombre": "Certificado"
      }
    ],
    "paginacion": {
      "pagina": 1,
      "tamano": 100,
      "total": 1,
      "totalPaginas": 1
    }
  }
}

Objeto de paginación

Campo Descripción
pagina Página actual retornada.
tamano Cantidad de registros por página usada en esta consulta.
total Total de registros que coinciden con el filtro de fechas.
totalPaginas Total de páginas disponibles. Calculado como ceil(total / tamano).

Errores

HTTP codigo Causa
400 4 Faltan fechaInicio o fechaFin, o tienen formato inválido.
400 4 fechaInicio es mayor que fechaFin.
401 — Token ausente o inválido.
500 — Error interno del servidor.

Ejemplo — campos requeridos faltantes

JSON · Error de validación 
{
  "codigo": 4,
  "mensaje": "Faltan datos requeridos",
  "data": {
    "detalle": [
      ""fechaInicio" is required",
      ""fechaFin" is required"
    ]
  }
}

v2 — Novedades y nuevos endpoints BETA

Cambios y funcionalidades nuevas. Esta es una versión beta que pasa a producción el 10 de agosto de 2026.

URL de pruebas Para probar los nuevos endpoints y cambios, utilice la siguiente URL base:
https://pw2pyuwl77.execute-api.us-east-1.amazonaws.com

Nuevos endpoints

Método Endpoint Descripción
GET /dte/compras-pro Listado paginado con detalle completo (XML, JSON) de DTEs recibidos. Redirect automático a S3 para respuestas grandes.
GET /dte/anuladas Listado liviano de DTEs anulados con campos esenciales.

GET /dte/compras-pro — Compras con detalle

Retorna un listado paginado de DTEs recibidos con detalle completo, incluyendo opcionalmente el XML firmado y el JSON estructurado de cada documento. Ideal para sincronización masiva.

GET https://pw2pyuwl77.execute-api.us-east-1.amazonaws.com/dte/compras-pro
Redirect automático a S3 Cuando la respuesta supera 1 MB, el servidor sube el JSON a S3 y responde con un redirect HTTP 302. El cliente recibe el JSON completo de forma transparente al seguir el redirect. No requiere cambios en la integración si el cliente HTTP sigue redirects (comportamiento por defecto).

Parámetros

Parámetro Tipo Requerido Default Descripción
fechaInicio string Requerido — Fecha de inicio en formato YYYY-MM-DD.
fechaFin string Requerido — Fecha de fin en formato YYYY-MM-DD.
pagina integer Opcional 1 Número de página. Mínimo: 1.
tamano integer Opcional 100 Registros por página. Mínimo: 1, Máximo: 1000.
incluirXml boolean Opcional false Si es true, incluye el XML firmado de cada DTE.
incluirJsonDetalle boolean Opcional false Si es true, incluye el JSON estructurado con items, frases, totales, etc.
estadoId integer Opcional — Filtrar por estado: 7 = anulados, 8 = certificados (vigentes).

Ejemplos

Listado liviano (sin XML ni JSON)

cURL 
curl 'https://pw2pyuwl77.execute-api.us-east-1.amazonaws.com/dte/compras-pro?fechaInicio=2026-07-01&fechaFin=2026-07-31' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Con XML y JSON incluidos

cURL 
curl 'https://pw2pyuwl77.execute-api.us-east-1.amazonaws.com/dte/compras-pro?fechaInicio=2026-07-01&fechaFin=2026-07-31&incluirXml=true&incluirJsonDetalle=true' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Respuesta exitosa

JSON · 200 OK 
{
  "codigo": 0,
  "mensaje": "Ok",
  "data": {
    "dtes": [
      {
        "dte": {
          "fechaEmision": "2026-07-15 10:30:00",
          "fechaCertificacion": "2026-07-15 10:30:01",
          "numeroUuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
          "tipo": "FACT",
          "serie": "A1B2C3D4",
          "numeroDocumento": "1234567890",
          "nitEmisor": "12345678",
          "nombreEmisor": "EMPRESA EJEMPLO, S.A.",
          "granTotal": "1500.000000",
          "anulado": "V"
          // ...campos de receptor, certificador, impuestos
        },
        "xml": "<?xml ...>",  // solo si incluirXml=true
        "json": { /* detalle */ }  // solo si incluirJsonDetalle=true
      }
    ],
    "paginacion": {
      "pagina": 1,
      "tamano": 100,
      "total": 520,
      "totalPaginas": 6
    }
  }
}

GET /dte/anuladas — DTEs anulados

Retorna un listado paginado de los DTEs anulados dentro de un rango de fechas de emisión. Respuesta liviana con solo los campos esenciales para identificar cada documento.

GET https://pw2pyuwl77.execute-api.us-east-1.amazonaws.com/dte/anuladas

Parámetros

Parámetro Tipo Requerido Default Descripción
fechaInicio string Requerido — Fecha de inicio en formato YYYY-MM-DD.
fechaFin string Requerido — Fecha de fin en formato YYYY-MM-DD.
pagina integer Opcional 1 Número de página. Mínimo: 1.
tamano integer Opcional 1000 Registros por página. Mínimo: 1, Máximo: 2000.

Ejemplo

cURL 
curl 'https://pw2pyuwl77.execute-api.us-east-1.amazonaws.com/dte/anuladas?fechaInicio=2026-07-01&fechaFin=2026-07-31' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Respuesta exitosa

JSON · 200 OK 
{
  "codigo": 0,
  "mensaje": "Ok",
  "data": {
    "dtes": [
      {
        "dteRecibidoId": 100234,
        "serie": "F1E2D3C4",
        "numero": "987654321",
        "autorizacion": "F1E2D3C4-B5A6-7890-CDEF-1234567890AB",
        "fechaAnulacion": "2026-07-20 14:30:00"
      }
    ],
    "paginacion": {
      "pagina": 1,
      "tamano": 1000,
      "total": 85,
      "totalPaginas": 1
    }
  }
}

Campos del DTE anulado

Campo Descripción
dteRecibidoId ID interno del documento recibido.
serie Serie del documento tributario.
numero Número correlativo del documento.
autorizacion UUID de autorización emitido por SAT.
fechaAnulacion Fecha y hora en que fue anulado el documento (YYYY-MM-DD HH:mm:ss).
Uso recomendado Use este endpoint para detectar qué documentos fueron anulados en un período. Si necesita el detalle completo de un DTE anulado, consulte /dte?autorizacion=UUID con el UUID obtenido.

Cambios en GET /dte

El endpoint existente /dte incorpora los siguientes cambios:

Nuevo parámetro: consultarSAT

Se agrega el parámetro consultarSAT al endpoint /dte. Este parámetro permite forzar la consulta directamente al servicio de SAT, incluso si el DTE ya existe en la base de datos local.

Parámetro Tipo Default Descripción
consultarSAT boolean false Si es true, fuerza la consulta al servicio de SAT en tiempo real, sin importar si el DTE existe en la BD local. Si es false (default), primero busca en la BD local y solo consulta SAT si no lo encuentra.

Ejemplo de uso:

cURL 
curl 'https://pw2pyuwl77.execute-api.us-east-1.amazonaws.com/dte?autorizacion=A1B2C3D4-E5F6-7890-ABCD-EF1234567890&consultarSAT=true' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

Cambio en formato de fechas

Las fechas en la respuesta ahora se devuelven en formato simple en lugar de ISO 8601 con timezone.

Campo Antes Después
data.dte.fechaAnulacion 2026-07-28T14:12:20-06:00 2026-07-28 14:12:20
Accion requerida Si su integración parsea fechas con timezone (formato ISO 8601 con T y -06:00), debe actualizarse para aceptar el formato simple YYYY-MM-DD HH:mm:ss.

Nuevos campos en la respuesta

Se agregan los siguientes campos al objeto data.dte:

Campo Tipo Descripción
fechaCertificacion string Fecha y hora de certificación del DTE.
origen integer 0 = Compras, 1 = Ventas.
dteRecibidoId integer ID interno del documento recibido.

Campo removido

Campo Nota
emisionUbicacionTemporal Removido. Este campo siempre devolvía null y no aportaba información.