Emitir factura

Crea y envía una factura al certificador. Responde `202` con `status: "PROCESSING"` inmediatamente — la certificación es asíncrona. Consultá el estado final con `GET /v1/invoices/{id}` (polling) o configurá un webhook. Con una API key `qapi_test_` la factura siempre certifica con MOCK (sin validez tributaria, no consume cuota). Tipos implementados: `FACT` (Régimen General, con IVA) y `FPEQ` (Pequeño Contribuyente, sin IVA) — los demás responden 501. En modo live, el tipo debe corresponder a la afiliación IVA del emisor configurado (GEN → FACT, PEQ → FPEQ) y el NIT del payload debe coincidir con el del emisor (cuenta o proyecto).

Authorization

ApiKeyAuth

AuthorizationBearer <token>

API key con prefijo qapi_live_ o qapi_test_, o JWT (access_token) obtenido vía POST /v1/auth/login. QAPI detecta el tipo automáticamente por el prefijo del token.

In: header

Header Parameters

Idempotency-Key?string

Identificador único para evitar facturas duplicadas en reintentos (recomendado: el ID de tu orden). Ventana de 24 horas, por tenant. Reenviar la misma key con el mismo body devuelve la respuesta original con el header Idempotency-Replayed: true, sin crear una segunda factura. La misma key con un body distinto responde 409 IDEMPOTENCY_CONFLICT. Solo se guardan respuestas exitosas: si recibís un error de validación podés corregir el payload y reusar la key. Formato: ASCII imprimible sin espacios, 1-200 caracteres.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tipo_dte*string

Implementados: FACT (Régimen General, con IVA) y FPEQ (Pequeño Contribuyente, sin IVA); los demás tipos responden 501 NOT_IMPLEMENTED. En modo live el tipo debe corresponder a la afiliación IVA del emisor configurado (GEN emite FACT, PEQ emite FPEQ).

moneda*string

exportacion?boolean

fecha_emision*string

ISO 8601 con offset de zona horaria (Guatemala: -06:00). Máximo 5 días en el pasado, no futura (tolerancia de reloj: 5 minutos).

emisor*

receptor*

frases*array<>

items*array<>

metadata?

Datos propios del cliente. referencia_interna se persiste y se devuelve en las respuestas.

webhook_url?string

URL para notificaciones de estado de esta factura. No se permiten IPs privadas ni internas (protección SSRF).

referencia_dte_origen?string

UUID del DTE original. Obligatorio para NCRE y NDEB.

Response Body

`application/json`

curl -X POST "https://example.com/v1/invoices" \  -H "Content-Type: application/json" \  -d '{    "tipo_dte": "FACT",    "moneda": "GTQ",    "fecha_emision": "2026-06-08T10:00:00-06:00",    "emisor": {      "nit": "12345678",      "nombre": "Mi Empresa S.A.",      "nombre_comercial": "Mi Empresa",      "codigo_establecimiento": 1,      "afiliacion_iva": "GEN",      "direccion": {        "calle": "6a Avenida 1-36 Zona 1",        "municipio": "Guatemala",        "departamento": "Guatemala",        "codigo_postal": "01001",        "pais": "GT"      },      "correo": "facturacion@miempresa.com"    },    "receptor": {      "id": "CF",      "nombre": "Consumidor Final"    },    "frases": [      {        "tipo_frase": 1,        "codigo_escenario": 1      }    ],    "items": [      {        "tipo": "S",        "cantidad": 1,        "unidad_medida": "UND",        "descripcion": "Servicio de consultoría",        "precio_unitario": 100,        "impuestos": [          {            "nombre": "IVA",            "codigo_unidad_gravable": 1,            "monto_gravable": 100,            "monto_impuesto": 12          }        ]      }    ]  }'

{
  "id": "inv_V1StGXR8_Z5jdHi6",
  "status": "PROCESSING",
  "sandbox": false,
  "tipo_dte": "FACT",
  "gran_total": 112,
  "moneda": "GTQ",
  "numero_acceso": 543219876,
  "created_at": "2019-08-24T14:15:22Z",
  "links": {
    "self": "/v1/invoices/inv_V1StGXR8_Z5jdHi6"
  }
}

{
  "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": "items.0.impuestos.0.monto_impuesto",
      "message": "MontoImpuesto IVA inválido. Esperado ~12 (MontoGravable 100 × 0.12), recibido 10"
    }
  ]
}

{
  "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": "items.0.impuestos.0.monto_impuesto",
      "message": "MontoImpuesto IVA inválido. Esperado ~12 (MontoGravable 100 × 0.12), recibido 10"
    }
  ]
}

{
  "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": "items.0.impuestos.0.monto_impuesto",
      "message": "MontoImpuesto IVA inválido. Esperado ~12 (MontoGravable 100 × 0.12), recibido 10"
    }
  ]
}

{
  "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": "items.0.impuestos.0.monto_impuesto",
      "message": "MontoImpuesto IVA inválido. Esperado ~12 (MontoGravable 100 × 0.12), recibido 10"
    }
  ]
}

{
  "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": "items.0.impuestos.0.monto_impuesto",
      "message": "MontoImpuesto IVA inválido. Esperado ~12 (MontoGravable 100 × 0.12), recibido 10"
    }
  ]
}

Authorization

Header Parameters

Request Body

Response Body

202application/json

401application/json

409application/json

422application/json

429application/json

501application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`