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

Anular una Factura

Cómo cancelar una factura CERTIFIED ante la SAT usando POST /v1/invoices/:id/cancel.

En Guatemala, anular una factura electrónica es un proceso formal ante la SAT. QAPI expone POST /v1/invoices/:id/cancel para ejecutarlo.

Solo facturas CERTIFIED se pueden anular

Solo se pueden cancelar facturas en estado CERTIFIED. Intentar cancelar una factura PENDING, PROCESSING, FAILED o CANCELLED retorna 409 INVALID_STATUS.

Antes de anular

Considerá si realmente necesitás anular o si es más apropiado emitir una Nota de Crédito (NCRE) para ajustes parciales. La anulación es permanente e irreversible.

CasoAcción recomendada
Error total en la facturaAnulación (cancel)
Devolución parcialNota de Crédito (NCRE)
Ajuste de precioNota de Débito (NDEB) o Nota de Crédito

Cómo cancelar

Verificar el estado actual

Asegurate de que la factura está en estado CERTIFIED:

curl https://api.dtevia.com.gt/v1/invoices/inv_01jxyz \
  -H "Authorization: Bearer qapi_live_xxxxxxxxxxxx"
const res = await fetch('https://api.dtevia.com.gt/v1/invoices/inv_01jxyz', {
  headers: { Authorization: 'Bearer qapi_live_xxxxxxxxxxxx' },
});
const invoice = await res.json();

if (invoice.status !== 'CERTIFIED') {
  throw new Error(`No se puede cancelar: estado actual es ${invoice.status}`);
}
res = httpx.get(
    "https://api.dtevia.com.gt/v1/invoices/inv_01jxyz",
    headers={"Authorization": "Bearer qapi_live_xxxxxxxxxxxx"},
)
invoice = res.json()

if invoice["status"] != "CERTIFIED":
    raise ValueError(f"No se puede cancelar: estado es {invoice['status']}")

Enviar la solicitud de cancelación

El body requiere dos campos obligatorios:

CampoTipoReglas
motivostringMínimo 5 caracteres
fecha_anulacionstringISO 8601 con timezone Guatemala: YYYY-MM-DDTHH:mm:ss-06:00. Normalmente, la del momento en que anulás

El offset -06:00 es obligatorio

fecha_anulacion debe terminar exactamente en -06:00 (hora de Guatemala). Enviar Z, otro offset, milisegundos u omitir el campo retorna 422 VALIDATION_ERROR.

Necesitás una key de acceso completo

POST /v1/invoices/:id/cancel requiere el scope invoices:write, igual que emitir. Una key de solo lectura recibe 403 FORBIDDEN.

# Ahora, en hora de Guatemala (UTC+6 en notación POSIX = 6 horas detrás de UTC)
FECHA=$(TZ=UTC+6 date +%Y-%m-%dT%H:%M:%S-06:00)

curl -X POST https://api.dtevia.com.gt/v1/invoices/inv_01jxyz/cancel \
  -H "Authorization: Bearer qapi_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "Error en datos del receptor",
    "fecha_anulacion": "'"$FECHA"'"
  }'
const res = await fetch('https://api.dtevia.com.gt/v1/invoices/inv_01jxyz/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer qapi_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    motivo: 'Error en datos del receptor',
    // Ahora, en hora de Guatemala (UTC-6)
    fecha_anulacion: new Date(Date.now() - 6 * 3600_000).toISOString().slice(0, 19) + '-06:00',
  }),
});

const invoice = await res.json();
// invoice.status === "CANCELLED"
const { data } = await axios.post(
  'https://api.dtevia.com.gt/v1/invoices/inv_01jxyz/cancel',
  {
    motivo: 'Error en datos del receptor',
    // Ahora, en hora de Guatemala (UTC-6)
    fecha_anulacion: new Date(Date.now() - 6 * 3600_000).toISOString().slice(0, 19) + '-06:00',
  },
  { headers: { Authorization: 'Bearer qapi_live_xxxxxxxxxxxx' } }
);
// data.status === "CANCELLED"
from datetime import datetime, timedelta, timezone

res = httpx.post(
    "https://api.dtevia.com.gt/v1/invoices/inv_01jxyz/cancel",
    json={
        "motivo": "Error en datos del receptor",
        # Ahora, en hora de Guatemala
        "fecha_anulacion": datetime.now(timezone(timedelta(hours=-6))).isoformat(timespec="seconds"),
    },
    headers={"Authorization": "Bearer qapi_live_xxxxxxxxxxxx"},
)
invoice = res.json()
# invoice["status"] == "CANCELLED"

Verificar la cancelación

La respuesta exitosa es 200 con un resumen de la anulación:

{
  "id": "inv_01jxyz",
  "status": "CANCELLED",
  "cancelled_at": "2026-06-09T16:30:00.000Z"
}

Si necesitás el objeto completo de la factura (con uuid_sat, totales, etc.), consultalo con GET /v1/invoices/:id.

El PDF después de anular

La factura anulada conserva sus datos de certificación (uuid_sat, serie, numero_dte, pdf_url) — la autorización de la SAT existió y es parte del rastro fiscal del documento. El pdf_url sigue siendo accesible y el PDF sale con la marca de agua "ANULADO", que es el comprobante visual de la anulación (en live lo genera el certificador; en el Sandbox, QAPI).

Errores comunes

Código HTTPErrorCausa
409INVALID_STATUSLa factura no está en estado CERTIFIED
404NOT_FOUNDEl id no existe, o la factura es de otro proyecto o de otra cuenta
422VALIDATION_ERRORFalta motivo (mín. 5 caracteres) o fecha_anulacion no tiene el formato YYYY-MM-DDTHH:mm:ss-06:00
502CERTIFIER_ERROREl certificador rechazó la anulación

Un 502 no anula nada

Si el certificador rechaza la anulación, la factura queda tal cual estaba — sigue CERTIFIED y vigente ante la SAT. QAPI solo marca CANCELLED después de que el certificador confirma. Es seguro reintentar cancel con el mismo id.

Webhook de cancelación

Si tenés webhooks configurados, recibirás el evento invoice.cancelled cuando la cancelación se complete:

{
  "event": "invoice.cancelled",
  "data": {
    "id": "inv_01jxyz",
    "status": "CANCELLED",
    "test": false
  }
}

El payload de este evento trae id, status y test (true si la factura se emitió con el certificador MOCK —sandbox o cuenta sin activar—, false en emisiones reales); la fecha de anulación está en cancelled_at vía GET /v1/invoices/:id.

Ver la guía de Webhooks para la configuración completa.

En esta página