GETConsulta de DTE

Permite consultar un Documento Tributario Electrónico (DTE) emitido en Guatemala. La búsqueda puede realizarse por número de autorización del SAT, o bien por serie y número del documento.

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

Autenticación

Todas las solicitudes deben incluir un Bearer Token en el encabezado Authorization. Este token es proporcionado por Provex al momento de habilitar el acceso a la API.

⚠ 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Í

cURL

curl 'https://api.provex.com.gt/dte?autorizacion=241F6CE0-0D4B-4D48-9142-230531F44A37' \
  --header 'Authorization: Bearer TU_TOKEN_AQUÍ'

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 el SAT de Guatemala.

?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>

ℹ Regla de validación Si envías autorizacion, no debes enviar serie ni numero.
Si envías serie y numero, no debes enviar autorizacion.
Enviar todos juntos o ninguno resulta en un error de validación.

Parámetros de consulta (Query Params)

Parámetro	Tipo	Requerido	Descripción
autorizacion	string	Condicional	UUID de autorización del 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."
}

Flujo de consulta

Internamente, la API sigue el siguiente proceso para responder cada solicitud:

Validación de parámetros. Se verifica que la combinación de campos sea válida según los modos permitidos.

Búsqueda local. Se consulta la base de datos interna con los criterios recibidos.

Respuesta inmediata (si existe). Si el DTE ya está registrado, se devuelve directamente con existente: true.

Consulta externa (si no existe). Si no se encontró localmente, la API consulta la fuente externa del SAT de forma transparente.

Retorno del resultado. Se devuelve el DTE con los campos solicitados según los parámetros opcionales (incluirXml, incluirJsonDetalle).