Descripción

Descarga el PDF de un contrato eléctrico al que tenga acceso tu canal. La respuesta es un archivo binario, listo para guardar o incorporar a tu ERP.

Puedes elegir entre el original del contrato y la copia firmada. La descarga es síncrona, de solo lectura y no inicia un proceso de firma.

Identificar el contrato

  1. Consulta GET /contratos?pagina=1&por_pagina=10.
  2. Localiza el contrato por su código o por el CUPS de su punto de suministro. Recorre las páginas si es necesario.
  3. Utiliza el campo id de ese contrato en la URL de descarga.

id_contrato es el identificador numérico interno de Neuro. Es diferente del código comercial, del CUPS y del identificador del documento.

{
  "contratos": [
    {
      "id": 12345,
      "codigo": "00012345",
      "punto_suministro": { "cups": "CUPS_DEL_SUMINISTRO" }
    }
  ]
}

En este ejemplo utilizarías /contrato/12345/pdf.

Endpoints

Documento original

GET/contrato/{id_contrato}/pdf

Devuelve el PDF original del contrato con sus anexos pendientes de firma, tal como lo sirve Neuro. No incluye anexos ya firmados, documentos de identidad, información bancaria ni evidencias de firma.

Copia firmada

GET/contrato/{id_contrato}/firmado

Devuelve la copia firmada que sirve Neuro, tanto si se firmó digitalmente como si se adjuntó ya firmada en papel. Neuro determina qué documento corresponde entregar.

Si no hay copia firmada disponible, recibirás un 404; no se entregará el original como sustituto.

Usa la URL base del entorno que te haya facilitado Imagina Energía. Los ejemplos de esta guía utilizan https://pre-webhooks.imaginaenergia.com.

Autenticación y permisos

Ambas operaciones utilizan la autenticación JWT habitual de la API.

CabeceraUso
Authorization: Bearer <JWT>Obligatoria. Identifica la cuenta que solicita la descarga.
X-CanalOpcional. Selecciona otro canal mediante el mecanismo de suplantación autorizado para la cuenta.

Sin X-Canal, se utiliza el canal de tu cuenta. Si seleccionas otro canal, se aplican los mismos controles de suplantación que en las consultas de contratos.

Solo se descarga un contrato al que tenga acceso el canal efectivo. Conocer o cambiar un ID no concede acceso a contratos de otro canal. No necesitas una credencial de Neuro para utilizar estas operaciones.

Ejemplos de uso

cURL: descargar el original

curl --fail --show-error \
  "https://pre-webhooks.imaginaenergia.com/contrato/12345/pdf" \
  -H "Authorization: Bearer <JWT>" \
  --dump-header cabeceras.txt \
  --output contrato-original.pdf

cURL: descargar la copia firmada

curl --fail --show-error \
  "https://pre-webhooks.imaginaenergia.com/contrato/12345/firmado" \
  -H "Authorization: Bearer <JWT>" \
  --output contrato-firmado.pdf

Para actuar por otro canal autorizado, añade -H "X-Canal: <selector_autorizado>". Mantén el JWT de la cuenta que realiza la llamada.

Python: guardar el PDF y conservar la referencia

from pathlib import Path
import requests

response = requests.get(
    f"{base_url}/contrato/{contrato_id}/firmado",
    headers={"Authorization": f"Bearer {jwt}"},
    timeout=(5, 90),
)
response.raise_for_status()
if response.headers.get("Content-Type", "").split(";")[0] != "application/pdf":
    raise ValueError("La respuesta no es un PDF")

Path("contrato-firmado.pdf").write_bytes(response.content)
request_id = response.headers.get("X-Request-ID")

Respuesta y seguimiento

Una descarga correcta devuelve HTTP 200, Content-Type: application/pdf y Content-Disposition: attachment. No devuelve un JSON ni una URL de almacenamiento.

La cabecera X-Request-ID identifica la solicitud para soporte. Se admite un PDF de hasta 20 MiB y la respuesta utiliza Cache-Control: no-store.

Guarda el archivo como contenido binario. Si la respuesta es un error, su cuerpo será JSON. Esta operación permite que tu programa solicite la copia cuando la necesite; no configura un envío automático a Odoo.

Se aplican los límites de peticiones habituales de la API.

Manejo de errores

HTTPSignificado y actuación
400El ID debe ser un entero positivo.
401JWT ausente, inválido o caducado, o selección de canal no autorizada. Revisa la autenticación.
403El canal no tiene una credencial de acceso configurada. Contacta con soporte.
404El contrato no existe, no pertenece al canal o el documento solicitado no está disponible.
429Se ha alcanzado el límite de peticiones. Respeta la cabecera Retry-After.
500No se pudo completar o registrar la operación. Conserva la referencia para soporte.
502No se obtuvo una respuesta documental válida o se superó el tamaño permitido.
503El servicio de descarga no está disponible. Contacta con soporte.
504Neuro no respondió a tiempo. Puedes volver a intentar la consulta más tarde.
{
  "error": "El documento contractual no está disponible",
  "request_id": 123
}

Una petición de descarga no crea un contrato ni inicia una firma, por lo que no necesitas una clave de idempotencia.