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
- Consulta
GET /contratos?pagina=1&por_pagina=10. - Localiza el contrato por su código o por el CUPS de su punto de suministro. Recorre las páginas si es necesario.
- Utiliza el campo
idde 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
/contrato/{id_contrato}/pdfDevuelve 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
/contrato/{id_contrato}/firmadoDevuelve 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.
| Cabecera | Uso |
|---|---|
Authorization: Bearer <JWT> | Obligatoria. Identifica la cuenta que solicita la descarga. |
X-Canal | Opcional. 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
| HTTP | Significado y actuación |
|---|---|
| 400 | El ID debe ser un entero positivo. |
| 401 | JWT ausente, inválido o caducado, o selección de canal no autorizada. Revisa la autenticación. |
| 403 | El canal no tiene una credencial de acceso configurada. Contacta con soporte. |
| 404 | El contrato no existe, no pertenece al canal o el documento solicitado no está disponible. |
| 429 | Se ha alcanzado el límite de peticiones. Respeta la cabecera Retry-After. |
| 500 | No se pudo completar o registrar la operación. Conserva la referencia para soporte. |
| 502 | No se obtuvo una respuesta documental válida o se superó el tamaño permitido. |
| 503 | El servicio de descarga no está disponible. Contacta con soporte. |
| 504 | Neuro 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.