Documentación de la API FEL para Guatemala

Contrato de integración

Las operaciones públicas de Agencia Virtual utilizan el método POST, reciben datos en JSON y requieren autenticación Bearer.

Si comienzas una integración, consulta qué es FEL en Guatemala y la guía para integrar API FEL con tu ERP o POS.

Dos tokens, funciones diferentes

No envíes contraseñas SAT o FEL en query strings, rutas, logs o repositorios.

Tiempos de respuesta

Las rutas de Agencia Virtual y /v1/integrador/* incluyen Server-Timing en respuestas exitosas y errores. Los valores están en milisegundos y también pueden leerse desde JavaScript mediante CORS.

Server-Timing: total;dur=2400, apifelcore;dur=350.0, sat;dur=2050.0;desc="SAT + red"

sat acumula las transferencias HTTP a SAT, incluida la red; apifelcore es el resto del tramo medido, incluidas pausas locales. Ambos suman total. No mide exclusivamente el procesamiento interno de SAT, ni incluye la conexión del consumidor, el arranque previo al middleware o el envío final de la respuesta.

En el panel, el histórico con duración conocida se reparte 50/50 y aparece como Estimado 50/50. Las solicitudes nuevas y este encabezado usan mediciones reales. Estos tiempos son calculados por el servidor; no se envían como parámetros de entrada.

Tu primera petición

Obtén un token y úsalo para ejecutar tu primera operación FEL.

Genera un token Bearer válido durante 24 horas.

{
  "email": "dev@tuempresa.com",
  "password": "tu_password",
  "device_name": "produccion"
}

Consulta el nombre registrado de un receptor mediante su NIT.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "CF"
}

Autenticación

Genera un token Bearer válido durante 24 horas.

{
  "email": "dev@tuempresa.com",
  "password": "tu_password",
  "device_name": "produccion"
}

Cabecera general

Envía un token Bearer válido en todas las operaciones FEL:

Authorization: Bearer TU_TOKEN
Accept: application/json
Content-Type: application/json

Vigencia según el origen

No almacenes tokens en código fuente ni los expongas en el navegador.

Alta de clientes, planes y boletas

El contrato /v1/integrador usa el token Bearer administrable del portal. El usuario debe tener rol INTEGRATOR y un único integrador asociado.

Cabecera general de los POST

Authorization: Bearer TU_TOKEN_ADMINISTRABLE
Accept: application/json
Content-Type: application/json
Idempotency-Key: 018f3b59-4e31-7bcb-b9cc-10d6f6522d77

Cómo crear y reutilizar Idempotency-Key

La clave la genera el backend del integrador antes de iniciar cada operación nueva; la plataforma no la entrega. Usa un UUID aleatorio, guárdalo junto con el payload y el identificador local de la operación, y no lo derives del NIT, correo ni otros datos predecibles.

1. Genera una clave nueva para una operación nueva.
2. Persiste la clave antes de enviar el POST.
3. Si ocurre un timeout, corte de red o no se recibe respuesta, reenvía la misma clave con el mismo payload. No generes otra.
4. Conserva la clave después del éxito; nunca la reutilices para otro cliente, inscripción o pago.

JavaScript / Node.js
const idempotencyKey = crypto.randomUUID();

PHP / Laravel
$idempotencyKey = (string) \Illuminate\Support\Str::uuid();

PowerShell (pruebas manuales)
$idempotencyKey = [guid]::NewGuid().ToString()

Flujo

Lista únicamente los clientes del integrador autenticado. Acepta page y per_page; el valor predeterminado es 25 y el máximo es 100. Cada cliente incluye el inscripcion_id, plan vigente, solicitudes utilizadas, solicitudes disponibles y sus fechas. plan_vigente es null cuando el cliente no tiene un ciclo vigente. Se incluyen planes contratados desde el portal o desde la API.

{
  "success": true,
  "data": [
    {
      "id": 1042,
      "nombre": "Cliente de ejemplo",
      "nit": "12345678",
      "plan_vigente": {
        "inscripcion_id": 2054,
        "plan": {
          "id": 3,
          "nombre": "EMPRENDEDOR"
        },
        "solicitudes_utilizadas": 13,
        "solicitudes_disponibles": 431,
        "fecha_inicio": "2026-10-01",
        "fecha_fin": "2026-10-31"
      }
    }
  ],
  "error": null,
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Único paso: consulta SAT, valida FEL con un DTE de prueba, genera el token y guarda el cliente, todos los establecimientos y el plan seleccionado. El nombre SAT solo se devuelve cuando el registro termina correctamente.

{
  "nit": "1234567-8",
  "password_sat": "CREDENCIAL_SAT",
  "password_fel": "CREDENCIAL_FEL",
  "email": "cliente@ejemplo.com",
  "telefono": "55551234",
  "plan_id": 2,
  "external_id": "cliente-1042",
  "receptor_factura": "cliente",
  "correos_plan": {
    "factura": { "destinatario": "cliente" },
    "pagos": { "destinatario": "integrador" }
  }
}

La respuesta incluye el cliente, su nombre SAT, token_fel y inscripcion. PREPAGO inicia con un máximo de 15 solicitudes hasta que las boletas aprobadas completen el precio; después habilita el cupo total. FREE y POSTPAGO usan su cupo normal. Las contraseñas no se devuelven. La contraseña del usuario cliente es aleatoria y puede recuperarse mediante restablecimiento.

Solicita la inscripción de un plan para un cliente propio.

{
  "plan_id": 2
}

Precio, límites, fechas, modalidad, receptor_factura y estado se calculan en el servidor. El receptor queda congelado para el ciclo. PREPAGO inicia en uso_limitado con un máximo de 15 solicitudes hasta completar y aprobar el pago; FREE y POSTPAGO inician en aprobado. La respuesta agrega estado_vigencia (pendiente, vigente o finalizado), origen_ciclo, solicitudes_utilizadas y solicitudes_disponibles. Si hay un plan vigente, una compra pagada queda pendiente: fecha_inicio y fecha_fin son estimadas y se recalculan a la fecha de activación y 30 días después. Si el mismo NIT se registra después de borrar el cliente, solicitar FREE restaura las fechas y consumo del ciclo anterior; origen_ciclo será restauracion. FREE se renueva después del vencimiento y el scheduler procesa esa renovación automáticamente. Un conflicto FREE o una segunda inscripción pendiente responde 409 subscription_conflict.

Presenta una boleta de pago total o parcial.

{
  "banco_cuenta_id": 1,
  "referencia": "DEP-92812",
  "valor": "75.50",
  "deposito_comprobante": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

deposito_comprobante acepta Base64 puro o un Data URI. La plataforma decodifica los bytes, detecta el MIME real y adjunta el archivo a Media Library; el Base64 no se persiste en operaciones ni se devuelve. Formatos: JPG, JPEG, PNG, WebP o PDF; máximo 4 MB decodificados. La boleta no tiene URL pública y cargarla no activa la vigencia. DEV/SUPERADMIN la aprueba o rechaza; la aprobación cambia el estado de pago, pero un ciclo pendiente espera a que el vigente venza o agote sus solicitudes. Las boletas pendientes cuentan para impedir sobrepago.

Las boletas pendientes o aprobadas no pueden repetir cuenta bancaria y referencia dentro del mismo plan; se ignoran mayúsculas y espacios exteriores. El intento responde 409 payment_conflict, incluso con otra clave idempotente. Los ciclos reemplazados no reciben pagos ni generan bloqueo por deuda. Las boletas aprobadas o rechazadas conservan sus datos; si una boleta fue rechazada, puede presentar otra con una nueva clave idempotente. Completar un PREPAGO habilita su cupo total, conserva el consumo y las fechas originales y no adelanta un ciclo pendiente.

Polling y estados inciertos

Consulta GET /v1/integrador/operaciones/{idempotency_key}. Estados: processing, sat_validated, succeeded, failed y uncertain. Si el estado es uncertain, no envíes otra clave para el mismo NIT: el sistema bloquea otra emisión/anulación de prueba hasta resolver el resultado.

{
  "success": false,
  "data": null,
  "error": {
    "code": "idempotency_conflict",
    "message": "La clave de idempotencia ya fue usada con otra solicitud."
  }
}

Errores frecuentes

Emite FACT para régimen general o FPEQ para pequeño contribuyente. La ruta determina el tipo; no envíes periodos, abono ni fecha_fin.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "CF",
  "nombre_receptor": "Consumidor Final",
  "direccion_receptor": "Ciudad de Guatemala",
  "establecimiento": 1,
  "items": [
    { "cantidad": 1, "descripcion": "Servicio", "precio": 100, "tipo": "S", "descuento": 0 }
  ]
}

Emite FCAM para régimen general o FCAP para pequeño contribuyente. Requiere entre 1 y 12 periodos y una fecha_fin posterior al día actual.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "1234567",
  "nombre_receptor": "CLIENTE DE EJEMPLO",
  "direccion_receptor": "Ciudad de Guatemala",
  "establecimiento": 1,
  "items": [
    { "cantidad": 1, "descripcion": "Servicio", "precio": 100, "tipo": "S", "descuento": 0 }
  ],
  "periodos": 1,
  "abono": 0,
  "fecha_fin": "2099-12-31"
}

Conservado para clientes existentes. Infiere factura normal o cambiaria según periodos; se retirará en una versión futura. Las integraciones nuevas deben usar una de las dos rutas específicas.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "CF",
  "nombre_receptor": "Consumidor Final",
  "direccion_receptor": "Ciudad de Guatemala",
  "establecimiento": 1,
  "items": [
    { "cantidad": 1, "descripcion": "Servicio", "precio": 100, "tipo": "S", "descuento": 0 }
  ],
  "fecha_emision": "2026-08-20"
}

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "cui_receptor": "1234567890101",
  "nombre_receptor": "CLIENTE DE EJEMPLO",
  "direccion_receptor": "Ciudad de Guatemala",
  "establecimiento": 1,
  "items": [
    { "cantidad": 1, "descripcion": "Servicio", "precio": 100, "tipo": "S", "descuento": 0 }
  ]
}

{
  "success": true,
  "message": "Documento emitido correctamente",
  "data": {
    "fase_id": 1,
    "numero_autorizacion": "UUID-DEL-DOCUMENTO",
    "serie": "ABC123",
    "numero": "123456789",
    "fecha_emision": "2026-07-28T10:30:00-06:00",
    "fecha_certificacion": "2026-07-28T10:30:05-06:00",
    "numero_acceso": "123456789",
    "xml": "XML_DEL_DOCUMENTO",
    "pdf": null,
    "estado": "EMITIDO"
  },
  "error": null
}

{
  "success": false,
  "message": "No se permite facturar con CF cuando el monto es Q2,500.00 o superior; debe proporcionar un NIT válido.",
  "data": null,
  "error": null
}

Notas y recibo de anticipo

Estos endpoints conservan autenticación, establecimiento, plan, respuesta y PDF opcional de /emitir-documento. Envía exactamente uno entre nit_receptor y cui_receptor.

Nota de Abono

tipo_nota acepta rebaja_inventario (Documento de rebaja de inventarios) o vendedor_intermediario (Vendedor intermediario de productos agropecuarios, artesanales y productos reciclados).

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "CF",
  "nombre_receptor": "CONSUMIDOR FINAL",
  "direccion_receptor": "Ciudad",
  "establecimiento": 1,
  "tipo_nota": "rebaja_inventario",
  "items": [
    { "cantidad": 1, "descripcion": "Ajuste", "precio": 100, "tipo": "B" }
  ]
}

Nota de Crédito

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "5487981",
  "nombre_receptor": "RECEPTOR DE EJEMPLO",
  "direccion_receptor": "Ciudad",
  "establecimiento": 1,
  "items": [
    { "cantidad": 1, "descripcion": "Rebaja", "precio": 112, "tipo": "S" }
  ],
  "referencia": {
    "numero_autorizacion": "AAAAAAAA-BBBB-4CCC-8DDD-EEEEEEEEEEEE",
    "fecha_emision": "2026-09-01",
    "serie": "AAAA",
    "numero": "123456789",
    "motivo_ajuste": "Ajuste de precio"
  }
}

Nota de Débito

Usa el mismo contrato de Nota de Crédito; cambia únicamente el endpoint y el sentido del ajuste.

Nota de Envío

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "cui_receptor": "1234567890101",
  "nombre_receptor": "RECEPTOR DE EJEMPLO",
  "direccion_receptor": "Ciudad",
  "establecimiento": 1,
  "items": [
    { "cantidad": 1, "descripcion": "Mercancía", "precio": 100, "tipo": "B" }
  ],
  "traslado": {
    "id_transportista": "5487981",
    "tipo_documento_transportista": "NIT",
    "nombre_transportista": "TRANSPORTISTA DE EJEMPLO",
    "placa": "P123ABC",
    "direccion_procedencia": "Bodega central",
    "nit_cui_consignatario": "1234567",
    "nombre_consignatario": "CONSIGNATARIO DE EJEMPLO",
    "direccion_destino": "Bodega destino",
    "motivo": "Traslado de mercancía"
  }
}

Recibo de Anticipo

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "5487981",
  "nombre_receptor": "RECEPTOR DE EJEMPLO",
  "direccion_receptor": "Ciudad",
  "establecimiento": 1,
  "items": [
    { "cantidad": 1, "descripcion": "Anticipo de servicio", "precio": 500, "tipo": "S" }
  ]
}

Anula un documento emitido utilizando su número de autorización.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "numero_autorizacion": "UUID-DEL-DOCUMENTO",
  "nit_receptor": "CF",
  "observacion": "Anulación solicitada por el cliente",
  "descargar_pdf": false
}

{
  "success": true,
  "message": "Documento anulado correctamente",
  "data": {
    "fase_id": 1,
    "fecha_hora_respuesta": "2026-07-28T10:35:00-06:00",
    "estado": "ANULADO",
    "mensaje": "Documento anulado exitosamente",
    "xml": "XML_ANULACION_FIRMADO",
    "pdf": null
  },
  "error": null
}

{
  "success": false,
  "message": "SAT no respondio a tiempo; consulte el DTE antes de reintentar.",
  "data": null,
  "error": {
    "step": "anulacion_dte",
    "timeout": true,
    "resultado_indeterminado": true,
    "estado_consultado": "V"
  }
}

{
  "success": true,
  "message": "El documento no se puede anular porque no esta vigente",
  "data": {
    "estado": "I"
  },
  "error": null
}

Consulta el nombre registrado de un receptor mediante su NIT o DPI/CUI.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "5487981"
}

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "cui_receptor": "1234567890101"
}

{
  "success": true,
  "message": "Nombre obtenido correctamente",
  "data": {
    "nit": "5487981",
    "cui": "",
    "nombre": "CLIENTE DE EJEMPLO",
    "encontrado": true
  },
  "error": null
}

Consulta documentos emitidos o recibidos dentro de un rango de fechas. Si falta nit, token_fel o tipo_operacion, o el tipo de operación no es válido, devuelve HTTP 422 antes de consultar SAT y sin consumir solicitudes del plan.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "tipo_operacion": "EMITIDOS",
  "fecha_inicio": "01-01-2026",
  "fecha_fin": "31-01-2026",
  "tipo_documento": "FACT",
  "estado_dte": "VIGENTE",
  "nit_receptor": "CF"
}

{
  "success": true,
  "message": "Documentos obtenidos correctamente",
  "data": [
    {
      "numero_autorizacion": "UUID-DEL-DOCUMENTO",
      "fecha_emision": "2026-01-15T10:30:00-06:00",
      "tipo_documento": "FACT",
      "serie": "ABC123",
      "numero_documento": "123456789",
      "estado": "VIGENTE",
      "nit_emisor": "1234567",
      "nombre_emisor": "EMPRESA EMISORA",
      "nit_receptor": "CF",
      "nombre_receptor": "CONSUMIDOR FINAL",
      "monto": 100,
      "moneda": "GTQ",
      "fecha_anulacion": null,
      "total_iva": 10.71
    }
  ],
  "error": null
}

Obtiene el XML de un documento mediante su receptor y número de autorización. Si se emitió con CUI, envía ese CUI en nit_receptor.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "CF",
  "numero_autorizacion": "UUID-DEL-DOCUMENTO"
}

{
  "success": true,
  "message": "XML obtenido correctamente",
  "data": {
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
  },
  "error": null
}

Obtiene el contenido del XML convertido a una estructura JSON.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "CF",
  "numero_autorizacion": "UUID-DEL-DOCUMENTO"
}

{
  "success": true,
  "message": "JSON obtenido correctamente",
  "data": {
    "json": {
      "dte:GTDocumento": {
        "@attributes": {
          "Version": "0.1"
        }
      }
    }
  },
  "error": null
}

Genera la representación PDF y devuelve su URL de descarga junto con el contenido base64.

{
  "nit": "1234567",
  "token_fel": "TOKEN_FEL_DEL_CLIENTE",
  "nit_receptor": "CF",
  "numero_autorizacion": "UUID-DEL-DOCUMENTO"
}

{
  "success": true,
  "message": "PDF generado correctamente",
  "data": {
    "file_name": "UUID-DEL-DOCUMENTO.pdf",
    "url_download": "https://apifelcore.com/storage/UUID-DEL-DOCUMENTO.pdf", //Valido por 1 mes
    "base64": "PDF_EN_BASE64"
  },
  "error": null
}