Autenticación y permisos
Usa el JWT habitual en Authorization: Bearer <JWT>. Si tu cuenta tiene autorización para seleccionar otro canal, utiliza la cabecera X-Canal con el selector por lista o master correspondiente.
Solo puedes consultar y descargar facturas del canal efectivo. No necesitas otra clave. La descarga cubre facturas eléctricas normales de un suministro.
Localizar una factura
/facturasDevuelve las facturas eléctricas emitidas y numeradas del canal, ordenadas por fecha e ID descendentes. Los filtros son exactos y se combinan entre sí.
| Parámetro | Uso |
|---|---|
pagina | Desde 1. Por defecto, 1. |
por_pagina | Entre 1 y 100. Por defecto, 10. |
codigo | Número o código de factura. |
cups | CUPS del suministro. |
contrato_codigo | Código comercial del contrato, no su ID interno. |
{
"request_id": 123,
"facturas": [{
"id": 201, "codigo": "FE_EJEMPLO", "producto": "Electricidad",
"tipo": "Normal", "fecha": "2026-11-01",
"fecha_desde": "2026-10-01", "fecha_hasta": "2026-10-31",
"total": "100.00", "contrato_codigo": "CONTRATO_EJEMPLO",
"cups": "CUPS_DEL_SUMINISTRO",
"url_pdf": "/factura/201/pdf"
}],
"paginacion": {
"pagina": 1, "por_pagina": 10, "total": 1,
"ultima_pagina": 1, "hay_mas": false
}
}
Para recorrer la cartera, incrementa pagina mientras hay_mas sea verdadero. El listado puede cambiar mientras se emiten nuevas facturas; no es una instantánea contable.
id identifica la factura en Neuro. Es diferente de su número, del ID de contrato y del CUPS. Si url_pdf tiene valor, puedes seguir esa ruta sobre la URL base de esta API. En las facturas multipunto y albaranes el valor es null: no tienen descarga disponible.
Descarga de una factura normal
/factura/{id_factura}/pdfDevuelve el mismo PDF que sirve Neuro para la factura eléctrica de un punto de suministro. Guarda la respuesta como binario. La primera descarga puede tardar más: Neuro compone el PDF y lo reutiliza posteriormente.
La descarga no envía la factura a terceros ni cambia sus importes o estado. Es independiente de los envíos automáticos de facturas.
Ejemplos de uso
Usa la URL base que te haya facilitado Imagina Energía. Estos ejemplos utilizan PRE.
Buscar por número de factura
curl --get "https://pre-webhooks.imaginaenergia.com/facturas" \
--header "Authorization: Bearer $JWT" \
--data-urlencode "codigo=FE_EJEMPLO"
Guardar el PDF
curl --fail-with-body \
"https://pre-webhooks.imaginaenergia.com/factura/201/pdf" \
--header "Authorization: Bearer $JWT" \
--output factura.pdf
Python: localizar y descargar
from pathlib import Path
import os
import requests
base = "https://pre-webhooks.imaginaenergia.com"
headers = {"Authorization": "Bearer " + os.environ["JWT"]}
listing = requests.get(base + "/facturas",
params={"codigo": "FE_EJEMPLO"},
headers=headers, timeout=60)
listing.raise_for_status()
facturas = listing.json()["facturas"]
if not facturas:
raise ValueError("No se encontró la factura")
if not facturas[0]["url_pdf"]:
raise ValueError("Esta factura no tiene descarga disponible")
pdf = requests.get(base + facturas[0]["url_pdf"], headers=headers, timeout=60)
pdf.raise_for_status()
if pdf.headers.get("Content-Type", "").split(";")[0] != "application/pdf":
raise ValueError("La respuesta no es un PDF")
Path("factura.pdf").write_bytes(pdf.content)
request_id = pdf.headers.get("X-Request-ID")Errores y seguimiento
Una descarga correcta devuelve 200, Content-Type: application/pdf, Content-Disposition: attachment y Cache-Control: no-store. El límite es 20 MiB. Los errores son JSON; conserva X-Request-ID o request_id para soporte.
| HTTP | Qué significa |
|---|---|
| 400 | Parámetros inválidos, tipo de factura no admitido o Neuro no puede componer el PDF. Si persiste, contacta con soporte. |
| 401 | JWT inválido o selección de canal no autorizada. |
| 403 | El canal no tiene una credencial de acceso configurada. |
| 404 | Factura inexistente, sin contrato o no accesible al canal. |
| 429 | Límite de peticiones alcanzado; respeta Retry-After. |
| 500 | Fallo interno o al registrar la auditoría. |
| 502 | Respuesta de Neuro inválida o demasiado grande. |
| 503 | Servicio no disponible o Neuro rechaza la credencial del canal. |
| 504 | Neuro no respondió a tiempo. |
Se aplican los límites habituales de la API. Ante un fallo de generación del documento, evita repetir peticiones en bucle.