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

GET/facturas

Devuelve 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ámetroUso
paginaDesde 1. Por defecto, 1.
por_paginaEntre 1 y 100. Por defecto, 10.
codigoNúmero o código de factura.
cupsCUPS del suministro.
contrato_codigoCó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

GET/factura/{id_factura}/pdf

Devuelve 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.

HTTPQué significa
400Parámetros inválidos, tipo de factura no admitido o Neuro no puede componer el PDF. Si persiste, contacta con soporte.
401JWT inválido o selección de canal no autorizada.
403El canal no tiene una credencial de acceso configurada.
404Factura inexistente, sin contrato o no accesible al canal.
429Límite de peticiones alcanzado; respeta Retry-After.
500Fallo interno o al registrar la auditoría.
502Respuesta de Neuro inválida o demasiado grande.
503Servicio no disponible o Neuro rechaza la credencial del canal.
504Neuro 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.