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 conMOCK: 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 responde429 SANDBOX_LIMIT_REACHED. - Tipos de DTE implementados:
FACT,FPEQ,FCAM,FCAP,FESP,NCRE,NDEB,RECI. Los tiposRDON,NABN,FACA,FCCAresponden501. 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_notaen NCRE/NDEB,abonosen FCAM/FCAP,retencionesen FESP.exportacion_infoes obligatorio cuandoexportacion: true—salvo enNCREyNDEB, 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).
Autorización
ApiKeyAuth 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
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"
}