Documentación de la API

Integra la facturación electrónica FEL de Guatemala en tu sistema. URL base: https://apifel.voltgo.net

Autenticación

Todas las llamadas a /v1/* requieren tu API key en el header X-Api-Key (o el parámetro ?k=).

X-Api-Key: fel_tu_api_key

La encontrás en tu panel → ⚙️ Configuración. También ahí conectás las credenciales de tu certificador (EcoFactura u otro) — sin eso la API no puede firmar documentos.

Integraciones server-to-server: las rutas /v1/ y /api/ aceptan llamadas sin User-Agent — no necesitás simular un navegador.

POST /v1/factura

Emite y certifica una factura FEL. Devuelve el UUID de autorización y los enlaces del documento.

Cuerpo (JSON)

Campo	Tipo		Descripción
`nit`	string	opcional	NIT del receptor. Default `CF` (consumidor final).
`nombre`	string	opcional	Nombre del receptor. Default "Consumidor Final".
`direccion`	string	opcional	Dirección del receptor.
`monto`	number	*	Total de la venta — crea un solo ítem genérico. *Requerido si no enviás `items`.
`descripcion`	string	opcional	Detalle del ítem cuando usás `monto`.
`items`	array	*	Detalle línea por línea (ver abajo).

Items

Campo	Alias	Default	Descripción
`cod`	—	`GEN`	Código del producto/servicio.
`nom`	`descripcion`	"Item"	Descripción (máx. 120 caracteres).
`can`	`cantidad`	`1`	Cantidad.
`precio`	`monto`	—	Precio unitario (debe ser > 0).
`um`	—	`UNI`	Unidad de medida.
`bienSer`	—	`B`	`B` = bien, `S` = servicio.

Ejemplo

# Venta simple
curl -X POST https://apifel.voltgo.net/v1/factura \
  -H "X-Api-Key: fel_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"nit":"CF","nombre":"José Martínez","monto":250.00,"descripcion":"Venta mostrador"}'

# Con detalle de ítems
curl -X POST https://apifel.voltgo.net/v1/factura \
  -H "X-Api-Key: fel_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"nit":"1234567-8","nombre":"Distribuidora X","items":[
    {"nom":"Producto A","can":2,"precio":100},
    {"nom":"Servicio B","can":1,"precio":50,"bienSer":"S"}
  ]}'

const res = await fetch('https://apifel.voltgo.net/v1/factura', {
  method: 'POST',
  headers: { 'X-Api-Key': 'fel_tu_api_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    nit: '1234567-8', nombre: 'Distribuidora X',
    items: [
      { nom: 'Producto A', can: 2, precio: 100 },
      { nom: 'Servicio B', can: 1, precio: 50, bienSer: 'S' }
    ]
  })
});
const { uuid, pdf_url, xml_url } = await res.json();

$ch = curl_init('https://apifel.voltgo.net/v1/factura');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-Api-Key: fel_tu_api_key', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'nit' => '1234567-8', 'nombre' => 'Distribuidora X',
    'items' => [
      ['nom' => 'Producto A', 'can' => 2, 'precio' => 100],
      ['nom' => 'Servicio B', 'can' => 1, 'precio' => 50, 'bienSer' => 'S'],
    ],
  ]),
]);
$factura = json_decode(curl_exec($ch), true);
// $factura['uuid'], $factura['pdf_url']

import requests

res = requests.post(
    'https://apifel.voltgo.net/v1/factura',
    headers={'X-Api-Key': 'fel_tu_api_key'},
    json={
        'nit': '1234567-8', 'nombre': 'Distribuidora X',
        'items': [
            {'nom': 'Producto A', 'can': 2, 'precio': 100},
            {'nom': 'Servicio B', 'can': 1, 'precio': 50, 'bienSer': 'S'},
        ],
    },
)
factura = res.json()
# factura['uuid'], factura['pdf_url']

Respuesta 200

{
  "ok": true,
  "uuid": "DFC48A87-F496-4008-9B1F-7574A382DBF0",   ← número de autorización SAT
  "serie": "DFC48A87",
  "numero": "4103487496",
  "pdf_url": "https://apifel.voltgo.net/v1/dte/DFC48A87-…-A382DBF0.pdf",
  "xml_url": "https://apifel.voltgo.net/v1/dte/DFC48A87-…-A382DBF0.xml"
}

Idempotencia: cada llamada crea un documento nuevo. Si tu sistema reintenta por timeout, verificá primero si la factura ya se creó (aparece en tu panel → Facturas) antes de reintentar, o usá la consulta de NIT para confirmar. Si por accidente se emite duplicada, podés anular una.

Descargar el documento

GET/v1/dte/{uuid}.pdf — abre el PDF directo en el navegador (sirve para mostrarla al cliente o descargarla desde tu sistema).

GET/v1/dte/{uuid}.xml — el XML firmado/certificado.

Los enlaces no requieren autenticación — el UUID actúa como llave (no es adivinable). Podés mandarle el pdf_url a tu cliente final por el canal que uses (tu sistema, correo, WhatsApp desde tu número, etc.).

La API no envía WhatsApp. El envío por WhatsApp lo hace FELisa cuando facturás desde el bot o el panel. Desde la API recibís los links y tu sistema decide cómo entregar el documento.

GET /v1/receptor/{nit}

Consulta el nombre y dirección registrados en SAT para un NIT o DPI (DPI<numero>), antes de facturar.

curl https://apifel.voltgo.net/v1/receptor/1234567-8 \
  -H "X-Api-Key: fel_tu_api_key"

# DPI
curl https://apifel.voltgo.net/v1/receptor/DPI12345678901 \
  -H "X-Api-Key: fel_tu_api_key"

const res = await fetch('https://apifel.voltgo.net/v1/receptor/1234567-8', {
  headers: { 'X-Api-Key': 'fel_tu_api_key' }
});
const { nombre, direccion } = await res.json();

$ch = curl_init('https://apifel.voltgo.net/v1/receptor/1234567-8');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-Api-Key: fel_tu_api_key'],
]);
$receptor = json_decode(curl_exec($ch), true);
// $receptor['nombre'], $receptor['direccion']

import requests

res = requests.get(
    'https://apifel.voltgo.net/v1/receptor/1234567-8',
    headers={'X-Api-Key': 'fel_tu_api_key'},
)
receptor = res.json()
# receptor['nombre'], receptor['direccion']

Respuesta

{
  "ok": true,
  "nombre": "JOSÉ MARTÍNEZ",
  "direccion": "GUATEMALA, GUATEMALA"
}

Si responde ok:false con codigo:"1051", el NIT existe pero el certificador aún no lo tiene dado de alta — debe registrarse ante SAT (con EcoFactura lo gestiona el proveedor). Si hay urgencia podés emitir con "nit":"CF".

POST /v1/anular

Anula un documento certificado. La anulación también se certifica y queda inválida ante SAT.

curl -X POST https://apifel.voltgo.net/v1/anular \
  -H "X-Api-Key: fel_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"uuid":"DFC48A87-…","motivo":"Emitida por error"}'

const res = await fetch('https://apifel.voltgo.net/v1/anular', {
  method: 'POST',
  headers: { 'X-Api-Key': 'fel_tu_api_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({ uuid: 'DFC48A87-…', motivo: 'Emitida por error' })
});

$ch = curl_init('https://apifel.voltgo.net/v1/anular');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-Api-Key: fel_tu_api_key', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['uuid' => 'DFC48A87-…', 'motivo' => 'Emitida por error']),
]);

import requests

res = requests.post(
    'https://apifel.voltgo.net/v1/anular',
    headers={'X-Api-Key': 'fel_tu_api_key'},
    json={'uuid': 'DFC48A87-…', 'motivo': 'Emitida por error'},
)

Respuesta

{ "ok": true, "uuid": "DFC48A87-…", "estado": "anulada" }

Solo se pueden anular documentos con estado certificada.

Errores

Los errores siempre responden { "ok": false, "error": "…" }:

HTTP	Causa	Qué hacer
400	`items o monto requerido` / precio inválido / certificador sin credenciales	Revisá el cuerpo; si es el certificador, cargá las credenciales en el panel.
401	`INVALID_API_KEY`	Verificá el header `X-Api-Key`.
402	`PLAN_VENCIDO`	La prueba o el plan venció — el cliente renueva en su panel.
403	Firewall (sec-guard)	No debería pasar en integraciones — si lo ves, escribinos por el ticket de soporte.
404	`uuid no encontrado`	El UUID no existe o no pertenece a tu cuenta.
429	Límite mensual del plan	Se alcanzó el tope de facturas del mes — subí de plan en el panel.
502	El certificador rechazó o no respondió	Revisá `error`; suele ser credenciales vencidas o NIT no registrado.

Notas

• Las facturas emitidas por API aparecen igual en tu panel → Facturas, cuentan para el límite del plan y salen en los reportes (marcadas como vía api).

• ¿Dudas o un certificador distinto? Abrí un ticket desde tu panel → Soporte — respondemos por ahí y te avisamos por WhatsApp.