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

Emitir factura

Crea una factura y la envía al certificador. Responde 202 con status: "PROCESSING" de inmediato: la certificación es asíncrona. El estado final se obtiene con GET /v1/invoices/{id} (polling) o configurando un webhook.

Consideraciones

  • Con una API key qapi_test_, la factura siempre certifica con MOCK: sin validez tributaria y sin consumir cuota mensual. Sí consume el cupo diario de pruebas por tipo de DTE de tu plan, con el mismo contador que el Playground: al agotarlo responde 429 SANDBOX_LIMIT_REACHED.
  • Tipos de DTE implementados: FACT, FPEQ, FCAM, FCAP, FESP, NCRE, NDEB, RECI. Los tipos RDON, NABN, FACA, FCCA responden 501. Ver Tipos de DTE. Los ocho están certificados contra el certificador real, salvo la combinación de un recibo emitido por un Pequeño Contribuyente.
  • Cada tipo con complemento exige el suyo y rechaza los ajenos con 422: referencia_nota en NCRE/NDEB, abonos en FCAM/FCAP, retenciones en FESP. exportacion_info es obligatorio cuando exportacion: true —salvo en NCRE y NDEB, que heredan la marca del documento origen— y se rechaza si llega sin esa marca.

En modo live el emisor manda

El tipo_dte debe corresponder a la afiliación IVA del emisor configurado (GEN emite FACT, FCAM, FESP, NCRE, NDEB, RECI; PEQ emite FPEQ, FCAP, FESP y RECI), y el emisor.nit del payload debe coincidir con el del emisor (cuenta o proyecto).

POST
/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 cabecera

Idempotency-Key?string

Identificador único para evitar facturas duplicadas en reintentos (recomendado: el ID de tu orden). Ventana de 24 horas, por proyecto y por endpoint. 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.

Cuerpo del request

application/json

Definiciones de TypeScript

Usá el tipo request body en TypeScript.

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

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"    },    "items": [      {        "tipo": "S",        "cantidad": 1,        "unidad_medida": "UND",        "descripcion": "Servicio de consultoría",        "precio_unitario": 100,        "impuestos": [          {            "nombre": "IVA",            "codigo_unidad_gravable": 1,            "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/ssrf-blocked",
  "title": "SSRF_BLOCKED",
  "status": 400,
  "detail": "La URL del webhook apunta a una dirección privada o interna",
  "instance": "/v1/invoices"
}
{
  "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. Te enviamos un enlace al registrarte; podés pedir uno nuevo desde el panel.",
  "instance": "/v1/invoices"
}
{
  "type": "https://docs.dtevia.com.gt/errors/emisor-not-provisioned",
  "title": "EMISOR_NOT_PROVISIONED",
  "status": 409,
  "detail": "El emisor NIT 12345678 de el proyecto 'Mi Tienda' aún no está habilitado ante el certificador. Solicitá la habilitación desde el dashboard; te avisaremos al completarse.",
  "instance": "/v1/invoices",
  "context": {
    "scope": "project",
    "project_id": "prj_8Kd2mQ",
    "nit_emisor": "12345678"
  }
}
{
  "type": "https://docs.dtevia.com.gt/errors/payload-too-large",
  "title": "PAYLOAD_TOO_LARGE",
  "status": 413,
  "detail": "El cuerpo del request excede el límite de 1024KB",
  "instance": "/v1/invoices",
  "context": {
    "max_bytes": 1048576
  }
}
{
  "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/monthly-quota-exceeded",
  "title": "MONTHLY_QUOTA_EXCEEDED",
  "status": 429,
  "detail": "El proyecto 'Cliente A' agotó su cuota mensual (800/800 DTEs). Reasigná cuota o mejorá tu plan.",
  "instance": "/v1/invoices",
  "context": {
    "project_id": "prj_8Kd2mQ",
    "used": 800,
    "quota": 800
  }
}
{
  "type": "https://docs.dtevia.com.gt/errors/internal-error",
  "title": "INTERNAL_ERROR",
  "status": 500,
  "detail": "Error interno del servidor",
  "instance": "/v1/invoices"
}
{
  "type": "https://docs.dtevia.com.gt/errors/not-implemented",
  "title": "NOT_IMPLEMENTED",
  "status": 501,
  "detail": "Tipo DTE 'RDON' no implementado aún. Disponibles: FACT, FPEQ, FCAM, FCAP, FESP, NCRE, NDEB, RECI.",
  "instance": "/v1/invoices"
}