Documentación API FEL

Introducción

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.

Base URL
https://apifelcore.com/api

Dos tokens, funciones diferentes

Credencial	Ubicación	Función
`Bearer token`	Header Authorization	Autentica al usuario. Su vigencia depende de dónde fue creado.
`token_fel`	Body JSON	Identifica las credenciales FEL cifradas del cliente.

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

Quickstart

Tu primera petición

1. Obtén un token de 24 horas mediante la API

terminal

curl --request POST 'https://apifelcore.com/api/login' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "dev@tuempresa.com",
    "password": "tu_password",
    "device_name": "produccion"
  }'

2. Consulta un receptor

terminal

curl --request POST 'https://apifelcore.com/api/agencia-virtual/nombre-receptor' \
  --header 'Authorization: Bearer TU_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "nit": "1234567",
    "token_fel": "TOKEN_FEL_DEL_CLIENTE",
    "nit_receptor": "CF"
  }'

Seguridad

Autenticación

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

HTTP header

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

Vigencia según el origen

Origen	Vigencia	Uso recomendado
Gestor de tokens dentro de la plataforma	Sin vencimiento automático	Integraciones permanentes administradas desde el portal.
`POST /api/login`	24 horas desde su creación	Sesiones e integraciones que renuevan credenciales por API.

Importante: un token sin vencimiento automático permanece válido hasta que sea revocado manualmente dentro de la plataforma. Los tokens generados por API deben renovarse cada 24 horas.

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

Respuestas

Errores frecuentes

Estado	Significado	Acción recomendada
`400`	Datos inválidos o NIT inconsistente.	Revisa el body y la relación entre NIT y token FEL.
`401`	Token Bearer ausente, inválido, revocado o vencido.	Si fue creado por API, genera uno nuevo; si fue creado en la plataforma, comprueba que no haya sido revocado.
`403`	Plan inactivo o límite alcanzado.	Revisa el plan del cliente en el portal.
`404`	Documento o receptor no encontrado.	Valida identificadores y vuelve a consultar.
`422`	Error de validación.	Corrige los campos indicados en la respuesta.
`500`	Error interno o del servicio externo.	Conserva el contexto y contacta soporte si persiste.

Reintentos: no reintentes automáticamente una emisión si no conoces su resultado. Primero consulta el documento o solicita asistencia para evitar duplicados.

Operación 01

POST

/agencia-virtual/emitir-documento

Emite un documento FEL para un cliente y establecimiento activos.

Campo	Tipo	Descripción
`nit` REQUERIDO	string	NIT del emisor asociado al token FEL.
`token_fel` REQUERIDO	string	Token FEL cifrado del cliente.
`nit_receptor` REQUERIDO	string	NIT o CF.
`nombre_receptor` REQUERIDO	string	Nombre fiscal del receptor.
`direccion_receptor` REQUERIDO	string	Dirección del receptor.
`correo_receptor` OPCIONAL	string	Correo electrónico del receptor.
`municipio_receptor` OPCIONAL	string	Municipio del receptor. Predeterminado: GUATEMALA.
`departamento_receptor` OPCIONAL	string	Departamento del receptor. Predeterminado: GUATEMALA.
`pais` OPCIONAL	string	Código del país. Predeterminado: GT.
`codigo_postal` OPCIONAL	integer	Código postal del receptor. Predeterminado: 1.
`establecimiento` REQUERIDO	integer	Número del establecimiento.
`items` REQUERIDO	array	Entre 1 y 100 líneas de detalle.
`items[].cantidad` REQUERIDO	number	Cantidad entre 0.01 y 999999.99.
`items[].descripcion` REQUERIDO	string	Descripción, máximo 255 caracteres.
`items[].precio` REQUERIDO	number	Precio entre 0 y 999999.99.
`items[].tipo` REQUERIDO	string	`B` para bien o `S` para servicio.
`items[].descuento` OPCIONAL	number	Descuento entre 0 y 999999.99. Predeterminado: 0.
`periodos` OPCIONAL	integer	Períodos de crédito entre 0 y 12.
`abono` OPCIONAL	number	Abono inicial entre 0 y 999999.99.
`fecha_fin` OPCIONAL	date	Fecha posterior al día actual, formato YYYY-MM-DD.
`fecha_emision` OPCIONAL	date	Fecha entre cinco dias atras y el ultimo dia del mes actual. Vacia usa fecha y hora actuales.

JSON

{
  "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"
}

Response · HTTP 200

{
  "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": "PDF_EN_BASE64",
    "estado": "EMITIDO"
  },
  "error": null
}

Operación 02

POST

/agencia-virtual/anular-documento

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

Campo	Tipo	Descripción
`nit` REQUERIDO	string	NIT del emisor asociado al token FEL.
`token_fel` REQUERIDO	string	Token FEL cifrado del cliente.
`numero_autorizacion` REQUERIDO	string	UUID del documento, máximo 255 caracteres.
`nit_receptor` REQUERIDO	string	NIT del receptor o CF, máximo 20 caracteres.
`observacion` OPCIONAL	string	Motivo de anulación, máximo 255 caracteres.
`nombre_receptor` OPCIONAL	string	Nombre fiscal del receptor, máximo 255 caracteres.

JSON

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

Response · HTTP 200

{
  "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",
    "pdf": "PDF_EN_BASE64"
  },
  "error": null
}

Operación 03

POST

/agencia-virtual/nombre-receptor

Consulta el nombre registrado de un receptor mediante su NIT.

Campo	Tipo	Descripción
`nit` REQUERIDO	string	NIT del emisor asociado al token FEL.
`token_fel` REQUERIDO	string	Token FEL cifrado del cliente.
`nit_receptor` REQUERIDO	string	NIT que se consultará en SAT.

JSON

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

Response · HTTP 200

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

Operación 04

POST

/agencia-virtual/consultar-documentos

Consulta documentos emitidos o recibidos dentro de un rango de fechas.

Campo	Tipo	Descripción
`nit` REQUERIDO	string	NIT del emisor asociado al token FEL.
`token_fel` REQUERIDO	string	Token FEL cifrado del cliente.
`tipo_operacion` REQUERIDO	string	`EMITIDOS`, `RECIBIDOS`, `E` o `R`.
`fecha_inicio` OPCIONAL	string	Fecha inicial en formato DD-MM-YYYY.
`fecha_fin` OPCIONAL	string	Fecha final en formato DD-MM-YYYY.
`tipo_documento` OPCIONAL	string	FACT, FPEQ, FCAM, FCAP, NDEB o NCRE.
`estado_dte` OPCIONAL	string	VIGENTE, ANULADO, V o I. Predeterminado: V.
`nit_receptor` OPCIONAL	string	Filtra por NIT del receptor o CF.

JSON

{
  "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"
}

Response · HTTP 200

{
  "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
}

Operación 05

POST

/agencia-virtual/descargar-xml

Obtiene el XML de un documento mediante su receptor y número de autorización.

Campo	Tipo	Descripción
`nit` REQUERIDO	string	NIT del emisor asociado al token FEL.
`token_fel` REQUERIDO	string	Token FEL cifrado del cliente.
`nit_receptor` REQUERIDO	string	NIT del receptor o CF.
`numero_autorizacion` REQUERIDO	string	UUID del documento.

JSON

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

Response · HTTP 200

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

Operación 06

POST

/agencia-virtual/json

Obtiene el contenido del XML convertido a una estructura JSON.

Campo	Tipo	Descripción
`nit` REQUERIDO	string	NIT del emisor asociado al token FEL.
`token_fel` REQUERIDO	string	Token FEL cifrado del cliente.
`nit_receptor` REQUERIDO	string	NIT del receptor o CF.
`numero_autorizacion` REQUERIDO	string	UUID del documento.

JSON

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

Response · HTTP 200

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

Operación 07

POST

/agencia-virtual/descargar-pdf

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

Campo	Tipo	Descripción
`nit` REQUERIDO	string	NIT del emisor asociado al token FEL.
`token_fel` REQUERIDO	string	Token FEL cifrado del cliente.
`nit_receptor` REQUERIDO	string	NIT del receptor o CF.
`numero_autorizacion` REQUERIDO	string	UUID del documento.

JSON

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

Response · HTTP 200

{
  "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
}