{"openapi":"3.1.0","info":{"title":"Volty API","description":"\n**API REST para automatizar descarga, parseo y monitoreo de facturación eléctrica.**\n\nPensada para integradores que quieren consumir recibos de electricidad de sus\nclientes finales sin construir su propia infraestructura de extracción.\n\n---\n\n### Cómo empezar\n\n1. **Solicita una API key** escribiendo a `danna@volty.mx` con tus datos.\n2. **Autentica cada request** con el header:\n   `Authorization: Bearer volty_live_xxxxxxxx`\n3. **Llama `/v1/rpus/{numero_rpu}/recibos`** — devuelve los recibos disponibles\n   con URLs firmadas de S3 (válidas 5 minutos).\n4. **(Opcional) Registra webhooks** para recibir notificaciones push cuando\n   Volty descargue un recibo nuevo.\n\n---\n\n### Recursos clave\n\n| Recurso | Endpoint | Descripción |\n|---|---|---|\n| Recibos | `GET /v1/rpus/{rpu}/recibos` | Recibos de un RPU (auto-detecta GDMTH vs mensual) |\n| Refresh | `POST /v1/rpus/{rpu}/refresh` | Forzar descarga ad-hoc (solo Enterprise) |\n| Webhooks | `POST /webhooks` | Suscribir URL a eventos |\n\n---\n\n### Conceptos\n\n- **RPU**: identificador único del servicio eléctrico (12 dígitos). Una empresa\n  puede tener varios.\n- **Tarifa**: GDMTO, GDMTH, PDBT, GDBT, DAC, 1A-1F, etc. Volty maneja todas.\n- **NETMET**: Net Metering — esquema de compensación bidireccional para\n  clientes con paneles solares.\n- **Webhook**: notificación push (POST) con HMAC-SHA256 cuando ocurre un\n  evento (recibo nuevo, alerta disparada, etc.).\n\n---\n\n### Soporte\n\n- Email: `danna@volty.mx` — respuesta <24h horario laboral CDMX\n","contact":{"name":"Soporte Volty","url":"https://docs.volty.mx/","email":"danna@volty.mx"},"license":{"name":"Términos de Servicio Volty","url":"https://volty.mx/terminos"},"version":"0.1.0"},"servers":[{"url":"https://api.volty.mx","description":"Producción"},{"url":"https://staging-api.volty.mx","description":"Staging"},{"url":"http://localhost:8000","description":"Local (dev)"}],"paths":{"/":{"get":{"tags":["meta"],"summary":"Raiz","operationId":"raiz__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/salud/live":{"get":{"tags":["meta"],"summary":"Salud Live","description":"Liveness probe — responde 200 sin tocar dependencias externas.\n\nUso: monitoreo frecuente (Better Stack cada 3 min, Railway internal\nhealthcheck, Cloudflare probes). Cero costo en KMS/DB/S3, latencia <5ms.\n\nSemántica: \"¿el proceso responde HTTP?\". No valida upstream health.\nPara eso ver `/salud/ready`.\n\nMotivación empírica (18 jul 2026): Better Stack pingueaba `/salud`\ncada 3 min disparando kms.ping() sin cache → ~14,400 KMS calls/mes\nconsumiendo ~70% del free tier AWS. Migrar Better Stack a este\nendpoint elimina el 100% de esas llamadas. Ver ADR pendiente.","operationId":"salud_live_salud_live_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/salud/ready":{"get":{"tags":["meta"],"summary":"Salud Ready","description":"Readiness probe — verifica que los 3 componentes externos respondan.\n\nUsa cache TTL en `kms.ping()` (default 300s) para no hammerear KMS.\nVer `apps/api/app/core/kms.py` docstring del bloque health check.\n\nUso: monitoreo menos frecuente (ej: cada 15 min), diagnóstico manual,\ndashboards de estado interno.","operationId":"salud_ready_salud_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/salud":{"get":{"tags":["meta"],"summary":"Salud","description":"Alias backward-compatible de `/salud/ready`.\n\nPreserva el contract original para Better Stack + otros consumers\nque apunten a `/salud`. Recomendado migrar clientes a\n`/salud/live` (monitoreo frecuente sin costo KMS) o\n`/salud/ready` (validación completa) según semántica requerida.","operationId":"salud_salud_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/planes":{"get":{"tags":["catalogos"],"summary":"Listar Planes","description":"Catálogo público de planes — demuestra conexión a Supabase.","operationId":"listar_planes_planes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/organizaciones/mias":{"get":{"tags":["organizaciones"],"summary":"Listar Mis Organizaciones","description":"Todas las organizaciones a las que pertenezco.","operationId":"listar_mis_organizaciones_organizaciones_mias_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Organization"},"type":"array","title":"Response Listar Mis Organizaciones Organizaciones Mias Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/organizaciones":{"post":{"tags":["organizaciones"],"summary":"Crear Organizacion","description":"Crea una organización nueva y agrega al usuario actual como `admin`.\nSi el slug ya existe, regresa 409 Conflict.","operationId":"crear_organizacion_organizaciones_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/organizaciones/{organization_id}":{"get":{"tags":["organizaciones"],"summary":"Obtener Organizacion","operationId":"obtener_organizacion_organizaciones__organization_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["organizaciones"],"summary":"Actualizar Organizacion","description":"Solo admin puede editar.","operationId":"actualizar_organizacion_organizaciones__organization_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/organizaciones/{organization_id}/miembros":{"get":{"tags":["organizaciones"],"summary":"Listar Miembros","operationId":"listar_miembros_organizaciones__organization_id__miembros_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Membership"},"title":"Response Listar Miembros Organizaciones  Organization Id  Miembros Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["organizaciones"],"summary":"Agregar Miembro","description":"Solo admin puede invitar miembros. El usuario invitado ya debe existir.","operationId":"agregar_miembro_organizaciones__organization_id__miembros_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Membership"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/organizaciones/{organization_id}/miembros/{membership_id}":{"patch":{"tags":["organizaciones"],"summary":"Actualizar Rol Miembro","operationId":"actualizar_rol_miembro_organizaciones__organization_id__miembros__membership_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}},{"name":"membership_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Membership Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Membership"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["organizaciones"],"summary":"Quitar Miembro","operationId":"quitar_miembro_organizaciones__organization_id__miembros__membership_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}},{"name":"membership_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Membership Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaOk"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/clientes":{"get":{"tags":["clientes"],"summary":"Listar Clientes","operationId":"listar_clientes_clientes_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"},{"name":"buscar","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtro por nombre o RFC","title":"Buscar"},"description":"Filtro por nombre o RFC"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customer"},"title":"Response Listar Clientes Clientes Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["clientes"],"summary":"Crear Cliente","operationId":"crear_cliente_clientes_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/clientes/{customer_id}":{"get":{"tags":["clientes"],"summary":"Obtener Cliente","operationId":"obtener_cliente_clientes__customer_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Customer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["clientes"],"summary":"Actualizar Cliente","operationId":"actualizar_cliente_clientes__customer_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Customer Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["clientes"],"summary":"Eliminar Cliente","description":"Hard delete vía CASCADE — borra cliente + RPUs + recibos + credenciales.\nCuidado: los archivos en S3 NO se borran automáticamente (eso es otro job).","operationId":"eliminar_cliente_clientes__customer_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Customer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaOk"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/credenciales":{"get":{"tags":["credenciales"],"summary":"Listar Credenciales","operationId":"listar_credenciales_credenciales_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"},{"name":"customer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filtrar por cliente","title":"Customer Id"},"description":"Filtrar por cliente"},{"name":"solo_pool","in":"query","required":false,"schema":{"type":"boolean","description":"Solo credenciales del pool","default":false,"title":"Solo Pool"},"description":"Solo credenciales del pool"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Credential"},"title":"Response Listar Credenciales Credenciales Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["credenciales"],"summary":"Crear Credencial","description":"Cifra usuario+password con KMS y guarda. El plaintext nunca toca la DB.","operationId":"crear_credencial_credenciales_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credential"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/credenciales/{credencial_id}":{"get":{"tags":["credenciales"],"summary":"Obtener Credencial","operationId":"obtener_credencial_credenciales__credencial_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"credencial_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Credencial Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credential"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["credenciales"],"summary":"Actualizar Credencial","description":"Permite cambiar etiqueta/es_activa sin tocar el password.\nSi vienen cfe_username o cfe_password, re-cifra todo.","operationId":"actualizar_credencial_credenciales__credencial_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"credencial_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Credencial Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credential"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["credenciales"],"summary":"Eliminar Credencial","description":"Borra la credencial. Solo admin, y sujeta a la guarda de última credencial.\n\nAmbas restricciones se agregaron junto con el retiro: una guarda que impide\nRETIRAR la última credencial no protege nada mientras el endpoint de al lado\npermita BORRARLA. La invariante —una organización nunca se queda sin\ncredenciales que el selector pueda usar— es del dato, no de un endpoint.","operationId":"eliminar_credencial_credenciales__credencial_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"credencial_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Credencial Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaOk"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/credenciales/{credencial_id}/retirar":{"post":{"tags":["credenciales"],"summary":"Retirar","description":"Saca la credencial de circulación sin borrarla, con auditoría.\n\nEl worker deja de elegirla en cuanto el UPDATE confirma: `retirada` está en\n`ESTADOS_NO_USABLES` y el criterio vive en un solo lugar\n(`core/pool_credenciales.py`), así que los consumidores lo heredan.\n\nUn job que ya la tenía asignada termina normal — la selección ya ocurrió.","operationId":"retirar_credenciales__credencial_id__retirar_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"credencial_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Credencial Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialRetiro"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialAdmin"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/credenciales/{credencial_id}/reactivar":{"post":{"tags":["credenciales"],"summary":"Reactivar","description":"Devuelve la credencial a `sin_validar` — el mismo camino que un cambio de\ncontraseña.\n\nLa respuesta conserva `motivo_retiro`: si la cuenta se había retirado por\nestar comprometida, ese texto es lo único que se lo advierte a quien la\nreactiva. `es_activa` NO se restaura — actívala con el PATCH si corresponde.","operationId":"reactivar_credenciales__credencial_id__reactivar_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"credencial_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Credencial Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialAdmin"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rpus":{"get":{"tags":["rpus"],"summary":"Listar Rpus","operationId":"listar_rpus_rpus_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"},{"name":"customer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filtrar por cliente","title":"Customer Id"},"description":"Filtrar por cliente"},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"enum":["pendiente","procesando","activo","fallido","pausado","archivado"],"type":"string"},{"type":"null"}],"description":"Filtrar por estado","title":"Estado"},"description":"Filtrar por estado"},{"name":"buscar","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Texto en RPU o nombre","title":"Buscar"},"description":"Texto en RPU o nombre"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Rpu"},"title":"Response Listar Rpus Rpus Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["rpus"],"summary":"Crear Rpu","operationId":"crear_rpu_rpus_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RpuCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rpu"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rpus/{rpu_id}":{"get":{"tags":["rpus"],"summary":"Obtener Rpu","operationId":"obtener_rpu_rpus__rpu_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"rpu_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Rpu Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rpu"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["rpus"],"summary":"Actualizar Rpu","operationId":"actualizar_rpu_rpus__rpu_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"rpu_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Rpu Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RpuUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rpu"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["rpus"],"summary":"Eliminar Rpu","description":"Soft delete: marca el RPU como `archivado` (deja la historia y los recibos\npara auditoría).\n\nSi `quitar_de_cfe=true` y la función NO está suspendida, encola un job\nque loguea en MiEspacio CFE y lo elimina ahí también.\n\nEn alpha la baja en CFE está suspendida (`BAJA_EN_CFE_SUSPENDIDA=True`)\npara evitar trigger antibot por bulk deletes. El RPU se archiva en\nVolty pero NO se elimina en CFE. El mensaje de respuesta indica el caso.","operationId":"eliminar_rpu_rpus__rpu_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"rpu_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Rpu Id"}},{"name":"quitar_de_cfe","in":"query","required":false,"schema":{"type":"boolean","description":"Si true, intenta encolar un job para eliminar el RPU también de MiEspacio CFE. **Suspendido en alpha** (Sprint B Bloque 3) — ver `app/core/feature_flags.py::BAJA_EN_CFE_SUSPENDIDA`. Default: false (solo archiva en Volty).","default":false,"title":"Quitar De Cfe"},"description":"Si true, intenta encolar un job para eliminar el RPU también de MiEspacio CFE. **Suspendido en alpha** (Sprint B Bloque 3) — ver `app/core/feature_flags.py::BAJA_EN_CFE_SUSPENDIDA`. Default: false (solo archiva en Volty)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaOk"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rpus/{rpu_id}/recibos":{"get":{"tags":["recibos"],"summary":"Listar Recibos","operationId":"listar_recibos_rpus__rpu_id__recibos_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"rpu_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Rpu Id"}},{"name":"desde_anio","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2010},{"type":"null"}],"title":"Desde Anio"}},{"name":"hasta_anio","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2010},{"type":"null"}],"title":"Hasta Anio"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BillResumen"},"title":"Response Listar Recibos Rpus  Rpu Id  Recibos Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rpus/{rpu_id}/recibos/{anio}/{mes}":{"get":{"tags":["recibos"],"summary":"Obtener Recibo","operationId":"obtener_recibo_rpus__rpu_id__recibos__anio___mes__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"rpu_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Rpu Id"}},{"name":"anio","in":"path","required":true,"schema":{"type":"integer","title":"Anio"}},{"name":"mes","in":"path","required":true,"schema":{"type":"integer","title":"Mes"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rpus/{rpu_id}/recibos/{anio}/{mes}/archivos":{"get":{"tags":["recibos"],"summary":"Archivos Del Recibo","description":"Si el PDF/XML del periodo ya está en S3, devuelve URLs firmadas (300s).\nSi no, opcionalmente encola un job y devuelve `en_cache=False`.\nEl frontend puede hacer polling al job para mostrar progreso.","operationId":"archivos_del_recibo_rpus__rpu_id__recibos__anio___mes__archivos_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"rpu_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Rpu Id"}},{"name":"anio","in":"path","required":true,"schema":{"type":"integer","title":"Anio"}},{"name":"mes","in":"path","required":true,"schema":{"type":"integer","title":"Mes"}},{"name":"encolar_si_falta","in":"query","required":false,"schema":{"type":"boolean","description":"Si no está en cache, encolar un job de scrape automáticamente","default":true,"title":"Encolar Si Falta"},"description":"Si no está en cache, encolar un job de scrape automáticamente"},{"name":"expira_seg","in":"query","required":false,"schema":{"type":"integer","maximum":3600,"minimum":60,"description":"Duración de la URL firmada","default":300,"title":"Expira Seg"},"description":"Duración de la URL firmada"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillArchivos"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api-keys":{"get":{"tags":["api-keys"],"summary":"Listar Api Keys","description":"Lista las keys de la org. NO incluye los secretos.","operationId":"listar_api_keys_api_keys_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"},"title":"Response Listar Api Keys Api Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["api-keys"],"summary":"Crear Api Key","description":"Crea una API key nueva. Devuelve el secreto completo UNA vez.\nSi el usuario lo pierde, debe revocar y crear otra (no se puede recuperar).","operationId":"crear_api_key_api_keys_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Organization Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyConSecreto"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api-keys/{api_key_id}":{"delete":{"tags":["api-keys"],"summary":"Revocar Api Key","description":"Revoca (no borra) una API key. Quedará en DB para auditoría.","operationId":"revocar_api_key_api_keys__api_key_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"api_key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Api Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaOk"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks":{"get":{"tags":["webhooks"],"summary":"Listar Webhooks","description":"Lista todos los webhooks registrados para una organización.","operationId":"listar_webhooks_webhooks_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"},"title":"Response Listar Webhooks Webhooks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["webhooks"],"summary":"Crear Webhook","description":"Crea un webhook nuevo. Devuelve el secreto HMAC UNA vez (no se puede recuperar).\nEl cliente debe guardarlo para verificar las firmas de los POSTs.","operationId":"crear_webhook_webhooks_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"organization_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Organización","title":"Organization Id"},"description":"Organización"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConSecreto"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/{webhook_id}":{"get":{"tags":["webhooks"],"summary":"Obtener Webhook","description":"Lee detalles de un webhook (sin el secreto).","operationId":"obtener_webhook_webhooks__webhook_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["webhooks"],"summary":"Actualizar Webhook","description":"Modifica nombre, URL, eventos o estado activo. NO permite cambiar el secreto.","operationId":"actualizar_webhook_webhooks__webhook_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["webhooks"],"summary":"Eliminar Webhook","description":"Elimina un webhook. Su historial de deliveries se borra en cascada.","operationId":"eliminar_webhook_webhooks__webhook_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaOk"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/{webhook_id}/probar":{"post":{"tags":["webhooks"],"summary":"Probar Webhook","description":"Envía un evento `webhook.test` al endpoint registrado.\nÚtil para que el cliente verifique que su URL responde correctamente\nantes de empezar a recibir eventos reales.","operationId":"probar_webhook_webhooks__webhook_id__probar_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/{webhook_id}/deliveries":{"get":{"tags":["webhooks"],"summary":"Listar Deliveries","description":"Histórico de los últimos N intentos de envío para este webhook.","operationId":"listar_deliveries_webhooks__webhook_id__deliveries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limite"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"},"title":"Response Listar Deliveries Webhooks  Webhook Id  Deliveries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rpus/{numero_rpu}/recibos":{"get":{"tags":["v1-publica"],"summary":"Obtener los recibos de un RPU","description":"**Devuelve los recibos disponibles para un RPU**, con URLs firmadas de S3 (PDF y XML) que expiran en 5 minutos.\n\n### Lógica auto-detectada\n\nEl endpoint decide solo cuántos recibos devolver según la tarifa:\n\n| Tarifa | Recibos devueltos |\n|---|---|\n| `GDMTH` / `HM` | Últimos 12 (necesarios para análisis horario) |\n| Otras mensuales (`GDMTO`, `PDBT`, `GDBT`...) | Solo el último |\n| Residenciales bimestrales (`DAC`, `1A`-`1F`...) | Solo el último bimestre |\n\n### Histórico inicial (Fleet)\nSi tu organización tiene la bandera `historico_completo_pendiente=true` (activada en onboarding), la **primera llamada devuelve TODO el histórico disponible** y la bandera se apaga automáticamente. Llamadas siguientes vuelven al modo normal arriba.\n\n### Override manual\nPuedes forzar con `?limite=N` (entre 1 y 120) para obtener un número específico independiente de la tarifa.\n\n### Freshness automático\nSi la cache está atrasada (falta el recibo más reciente esperado), Volty encola un scrape en background **sin bloquear tu respuesta**. Llámanos otra vez en ~60s para tener el dato nuevo. Mira el campo `freshness` para saber qué pasó.","operationId":"obtener_recibos_de_rpu_v1_rpus__numero_rpu__recibos_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}},{"name":"limite","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":120,"minimum":1},{"type":"null"}],"description":"Sobreescribe la lógica automática. Útil si necesitas N recibos específicos.","title":"Limite"},"description":"Sobreescribe la lógica automática. Útil si necesitas N recibos específicos."}],"responses":{"200":{"description":"Recibos del RPU con URLs firmadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RpuConRecibos-Output"},"example":{"rpu":"508941006021","nombre_servicio":"VAMSA Las Fuentes","tarifa_actual":"GDMTH","division":"Jalisco","modo_entrega":"gdmth_12_meses","total_recibos":12,"recibos":[{"anio":2026,"mes":4,"periodo_inicio":"2026-03-25","periodo_fin":"2026-04-22","cfdi_uuid":"10383CEB-9C04-4E8A-916B-543958C52F22","serie":"LA","folio":"000321273269","tarifa":"GDMTH","tarifa_legacy":"HM","kwh_total":1310,"kwh_punta":1310,"kw_max":148,"factor_potencia":94.77,"monto_a_pagar":6090.29,"tiene_generacion_distribuida":true,"netmet_saldo_a_favor":0,"netmet_bolsa_aplicada":0,"pdf_url":"https://s3.../recibo.pdf?X-Amz-Signature=...","xml_url":"https://s3.../recibo.xml?X-Amz-Signature=...","expira_en_seg":300,"tipo_dato":"Medido"}],"freshness":{"estado":"fresca","periodicidad":"mensual","ultimo_recibo_en_cache":"2026-04","periodo_esperado_mas_reciente":"2026-04","razon":"Cache al día"}}}}},"401":{"description":"API key faltante o inválida","content":{"application/json":{"example":{"detail":{"codigo":"api_key_invalida","mensaje":"API key inválida o revocada."}}}}},"402":{"description":"Servicio temporalmente no disponible. Response NEUTRAL fija (no expone info interna de la plataforma upstream al end-user). El detalle interno (estado real de la suscripcion, dias vencida) se preserva como tags de Sentry para debugging.","content":{"application/json":{"example":{"detail":{"codigo":"servicio_no_disponible","mensaje":"Servicio temporalmente no disponible. Contacta a tu proveedor de servicio."}}}}},"404":{"description":"No hay datos históricos del RPU en cache cross-org. Antes del PR #175 este 404 usaba código `rpu_no_encontrado` con mensaje técnico interno; ahora usa `rpu_sin_datos` neutral. Si el RPU SÍ tiene bills cross-org, el endpoint auto-alta la fila `rpus` per-org transparentemente y responde 200.","content":{"application/json":{"example":{"detail":{"codigo":"rpu_sin_datos","mensaje":"No hay recibos disponibles para el RPU 508941006021. Solicita una descarga con POST /v1/rpus/508941006021/recibos/descargar o dalo de alta via POST /v1/rpus para monitoreo continuo."}}}}},"429":{"description":"Rate limit excedido (300 req/min por API key)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rpus/{numero_rpu}/refresh":{"post":{"tags":["v1-publica"],"summary":"Forzar descarga inmediata (solo planes Enterprise)","description":"Encola un scrape ad-hoc del RPU. Útil cuando necesitas el último recibo sin esperar a la actualización mensual automática.\n\n**Restricciones:**\n- Solo planes Enterprise (`permite_refresh: true` en configuración).\n- Tope de 5 refreshes/hora por organización.\n- Si todas las credenciales están en cooldown, devuelve 503.\n- CFE tarda 30-60s en entregar — la respuesta es **202 Accepted** con el `job_id`. Consulta el resultado con GET /v1/jobs/{id}.\n\n**No es instantáneo.** Para la mayoría de casos, el endpoint normal `GET /recibos` ya tiene el último recibo en caché.","operationId":"forzar_refresh_rpu_v1_rpus__numero_rpu__refresh_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/info":{"get":{"tags":["v1-publica"],"summary":"Validar API key y obtener info de la organización","description":"Endpoint útil para confirmar que tu API key funciona y conocer información básica de tu organización en Volty. Pega tu API key en el header `Authorization: Bearer ...` — si responde 200, tu key está activa.","operationId":"auth_info_v1_auth_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthInfoResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/clientes":{"post":{"tags":["v1-publica"],"summary":"Crear cliente final","description":"Crea un cliente final dentro de tu organización. Un cliente representa un usuario o empresa cuya cuenta CFE quieres monitorear. Puede tener múltiples RPUs y múltiples credenciales asociadas.","operationId":"crear_cliente_v1_clientes_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["v1-publica"],"summary":"Listar clientes (paginado)","description":"Lista todos los clientes finales de tu organización. Útil para reconciliación con tu DB interna o auditoría.","operationId":"listar_clientes_v1_clientes_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Tamaño de página","default":50,"title":"Limit"},"description":"Tamaño de página"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset desde el inicio","default":0,"title":"Offset"},"description":"Offset desde el inicio"},{"name":"buscar","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Texto en nombre o RFC","title":"Buscar"},"description":"Texto en nombre o RFC"},{"name":"external_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtrar por referencia externa","title":"External Ref"},"description":"Filtrar por referencia externa"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Customer_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/clientes/{customer_id}":{"get":{"tags":["v1-publica"],"summary":"Obtener cliente por ID","operationId":"obtener_cliente_v1_clientes__customer_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Customer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["v1-publica"],"summary":"Actualizar cliente","description":"Permite modificar nombre, razón social, RFC, email, teléfono o external_ref.","operationId":"actualizar_cliente_v1_clientes__customer_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Customer Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["v1-publica"],"summary":"Eliminar cliente (cascade a RPUs, credenciales, recibos)","description":"Hard delete vía CASCADE de Postgres — borra el cliente y todos sus RPUs, credenciales y recibos asociados. **Los archivos PDF/XML en S3 NO se borran automáticamente** (eso es otro job). Usar con cuidado.","operationId":"eliminar_cliente_v1_clientes__customer_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Customer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaOkSimple"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/credenciales":{"post":{"tags":["v1-publica"],"summary":"Guardar credenciales CFE de un cliente","description":"Guarda usuario+password CFE de un cliente final. Volty cifra el password con AWS KMS envelope encryption antes de persistir. El plaintext nunca toca disco — solo memoria efímera en el worker al momento de scrapear.\n\nEl cliente debe existir antes (crear vía `POST /v1/clientes`).","operationId":"crear_credencial_v1_credenciales_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credential"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["v1-publica"],"summary":"Listar credenciales (metadata únicamente, NO passwords)","description":"Lista metadata de las credenciales (estado, último login, etiqueta). **Nunca devuelve usuario_cfe ni password cifrado** — esos campos viven solo en KMS y solo el worker los descifra al momento de scrapear.","operationId":"listar_credenciales_v1_credenciales_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"customer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filtrar por cliente","title":"Customer Id"},"description":"Filtrar por cliente"},{"name":"solo_activas","in":"query","required":false,"schema":{"type":"boolean","description":"Solo credenciales activas","default":false,"title":"Solo Activas"},"description":"Solo credenciales activas"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Credential_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/credenciales/{credencial_id}":{"patch":{"tags":["v1-publica"],"summary":"Actualizar credencial (etiqueta o re-cifrar password)","description":"Si vienen `cfe_username` y `cfe_password` juntos, re-cifra con KMS y resetea el estado a 'sin_validar'. Si solo viene `etiqueta` o `es_activa`, actualiza esos campos sin tocar el password.","operationId":"actualizar_credencial_v1_credenciales__credencial_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"credencial_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Credencial Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credential"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rpus":{"post":{"tags":["v1-publica"],"summary":"Dar de alta un RPU","description":"Registra un medidor CFE (RPU) bajo un cliente. Al crearse, automáticamente se encola un job de descarga inicial según el `modo` elegido (último recibo / últimos 12 / histórico completo).\n\nEl cliente debe existir antes (crear vía `POST /v1/clientes`).","operationId":"crear_rpu_v1_rpus_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RpuCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rpu"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["v1-publica"],"summary":"Listar RPUs (paginado)","description":"Lista todos los RPUs de tu organización. Filtros opcionales por cliente, estado, y búsqueda libre en numero_rpu / nombre_servicio.","operationId":"listar_rpus_v1_rpus_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"customer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filtrar por cliente","title":"Customer Id"},"description":"Filtrar por cliente"},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"enum":["pendiente","procesando","activo","fallido","pausado","archivado"],"type":"string"},{"type":"null"}],"description":"Filtrar por estado","title":"Estado"},"description":"Filtrar por estado"},{"name":"buscar","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Texto en numero_rpu o nombre_servicio","title":"Buscar"},"description":"Texto en numero_rpu o nombre_servicio"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Rpu_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rpus/{numero_rpu}":{"get":{"tags":["v1-publica"],"summary":"Obtener RPU por número CFE (con auto-alta cross-org)","description":"Obtén el detalle de un RPU usando su número (12 dígitos de CFE), no su UUID interno. Es lo más natural para integradores que ya tienen el número en su DB.\n\n**Auto-alta cross-org (ADR 0013)**: si el RPU no está dado de alta en tu organización pero SÍ hay bills previamente scrapeados por otro partner en la cache global, el endpoint auto-crea la fila `rpus` per-org heredando `nombre_servicio` de la última bill disponible. Esto pasa transparentemente y el partner recibe 200 con los datos.\n\nSolo devuelve 404 (`codigo=rpu_sin_datos`) cuando no hay dato per-org NI cache cross-org disponible.","operationId":"obtener_rpu_v1_rpus__numero_rpu__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rpu"}}}},"404":{"description":"No hay datos del RPU per-org ni en cache cross-org. Antes de la deuda #65 este 404 usaba mensaje genérico `RPU no encontrado`; ahora usa código `rpu_sin_datos` neutral. Si el RPU SÍ tiene bills cross-org, el endpoint auto-alta la fila `rpus` per-org transparentemente y responde 200.","content":{"application/json":{"example":{"detail":{"codigo":"rpu_sin_datos","mensaje":"No encontramos datos históricos del RPU 508941006021. Solicita una descarga con POST /v1/rpus/508941006021/recibos/descargar o dalo de alta via POST /v1/rpus para monitoreo continuo."}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["v1-publica"],"summary":"Actualizar campos editables del RPU","description":"Permite modificar `nombre_servicio`, `nombre_corto`, `alias`, `modo`, `auto_actualizar`, `alertas_activas`. **No** permite cambiar `numero_rpu`, `customer_id` ni `organization_id`.\n\n**Caso de uso típico:** corregir `nombre_servicio` cuando CFE rechazó el alta con `ultimo_scrape_estado='rpu_no_encontrado_cfe'`. Después de actualizar, llama `POST /v1/rpus/{numero_rpu}/retry` para volver a intentar el scrape sin destruir el cliente ni la credencial.","operationId":"actualizar_rpu_v1_rpus__numero_rpu__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RpuUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rpu"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["v1-publica"],"summary":"Archivar RPU (opcional: encolar baja en MiEspacio CFE)","description":"Marca el RPU como archivado en Volty. Los recibos descargados quedan en historial para auditoría — solo deja de scrapearse.\n\n**Sincronización con MiEspacio CFE (opcional)**: si pasas `?quitar_de_cfe=true`, Volty intentará encolar un job `baja_rpu_cfe` para eliminar el RPU también de la cuenta CFE del cliente.\n\n**Suspendido en alpha (Sprint B Bloque 3)**: la baja en CFE está temporalmente suspendida para evitar trigger antibot por bulk deletes. Si pasas `quitar_de_cfe=true`, el RPU se archiva en Volty pero NO se elimina en CFE. La respuesta incluye un campo `aviso_quitar_de_cfe` explicando la suspensión. Para vaciar cuentas CFE en alpha, contacta soporte.","operationId":"archivar_rpu_v1_rpus__numero_rpu__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}},{"name":"quitar_de_cfe","in":"query","required":false,"schema":{"type":"boolean","description":"Si true, intenta encolar un job para eliminar el RPU también de MiEspacio CFE del cliente. **Suspendido en alpha** — ver descripción del endpoint. Default: false (solo archiva en Volty).","default":false,"title":"Quitar De Cfe"},"description":"Si true, intenta encolar un job para eliminar el RPU también de MiEspacio CFE del cliente. **Suspendido en alpha** — ver descripción del endpoint. Default: false (solo archiva en Volty)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaArchivarRpu"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rpus/{numero_rpu}/retry":{"post":{"tags":["v1-publica"],"summary":"Solicitar scrape del RPU (con cache check)","description":"Sprint B Bloque 6.5 — el endpoint primero evalúa el cache global de bills (compartido cross-org por numero_rpu). Si el cliente pide datos que ya tenemos vigentes según el ciclo de facturación CFE, devolvemos **HTTP 200 + cache_hit=true + job_id=null** sin tocar CFE. Si el cache no cubre lo solicitado, encolamos job y devolvemos **HTTP 202 + cache_hit=false + job_id=<uuid>**.\n\nQuery param `force_refresh=true` salta el cache y siempre encola scrape — útil cuando cliente sabe que necesita data más reciente que la ventana del cache (raro, ej. cliente detectó error en bill).\n\nAcepta body opcional `{\"modo\": \"ultimo\"}` para overridear el modo. Si no se especifica, el modo se infiere por tarifa (GDMTH → ultimos_12, resto → ultimo).\n\nDevuelve **409** si ya hay un job `en_cola` o `corriendo` del mismo RPU (evita duplicar trabajo).","operationId":"retry_rpu_v1_rpus__numero_rpu__retry_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}},{"name":"force_refresh","in":"query","required":false,"schema":{"type":"boolean","description":"Si true, salta el cache y siempre encola scrape. Default false (usa cache si está vigente).","default":false,"title":"Force Refresh"},"description":"Si true, salta el cache y siempre encola scrape. Default false (usa cache si está vigente)."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RpuUpdate"},{"type":"null"}],"title":"Payload"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryRpuResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/jobs":{"get":{"tags":["v1-publica"],"summary":"Listar jobs de tu organización (paginado)","description":"Lista todos los jobs partner-facing (descargas, sincronizaciones, bajas). Útil para monitorear actividad de scrape. Filtros opcionales por estado, tipo, y RPU específico.\n\n**Nota:** los jobs internos del sistema (mecanismo de emisión de webhooks, watchdogs, etc.) NO aparecen aquí — son plomería interna de Volty. Para monitorear tus webhooks salientes usa `GET /v1/webhooks/{id}/deliveries`.","operationId":"listar_jobs_v1_jobs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"enum":["en_cola","corriendo","exitoso","parcial","fallido","cancelado"],"type":"string"},{"type":"null"}],"description":"Filtrar por estado del job","title":"Estado"},"description":"Filtrar por estado del job"},{"name":"tipo","in":"query","required":false,"schema":{"anyOf":[{"enum":["descarga_inicial","actualizacion_periodica","descarga_ultimos_12","carga_masiva_csv","sync_volty_cfe","generar_reporte","baja_rpu_cfe"],"type":"string"},{"type":"null"}],"description":"Filtrar por tipo de job (solo partner-facing)","title":"Tipo"},"description":"Filtrar por tipo de job (solo partner-facing)"},{"name":"rpu_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filtrar por RPU","title":"Rpu Id"},"description":"Filtrar por RPU"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Job_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/jobs/{job_id}":{"get":{"tags":["v1-publica"],"summary":"Obtener detalle de un job (status + progreso)","description":"Útil para hacer polling después de encolar un job (alta de RPU, refresh, baja). El campo `estado` te dice si está `en_cola`, `corriendo`, `exitoso`, `parcial`, `fallido` o `cancelado`. Los campos `progreso_hecho`/`progreso_total` te dan barra de progreso.","operationId":"obtener_job_v1_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks":{"post":{"tags":["v1-publica"],"summary":"Crear webhook (con API key)","description":"Registra un endpoint HTTP que recibirá POSTs cuando ocurran eventos en Volty (recibo nuevo, alerta, etc.). Devuelve un secreto HMAC compartido — **se muestra UNA SOLA VEZ**, guárdalo para validar las firmas de los POSTs entrantes (header `X-Volty-Signature`).\n\nEquivalente a `POST /webhooks` pero auth vía API key en vez de JWT.","operationId":"crear_webhook_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConSecreto"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/webhooks/{webhook_id}/deliveries":{"get":{"tags":["v1-publica"],"summary":"Histórico de envíos de un webhook (debugging)","description":"Devuelve el log de cada intento de envío para un webhook. Útil para debuggear por qué un evento no llegó o falló. Cada delivery incluye status_code, intento (1-N), duración, y error si lo hubo.","operationId":"listar_webhook_deliveries_v1_webhooks__webhook_id__deliveries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_WebhookDelivery_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rpus/{numero_rpu}/recibos/descargar":{"post":{"tags":["v1-publica"],"summary":"Descargar recibos de un RPU (sync con polling para modo=ultimo)","description":"**Endpoint sync principal del Sprint B Bloque 3.** Devuelve recibos del RPU directamente cuando es posible, o un `job_id` para consulta async cuando no.\n\n### Modos\n\n| modo | Mecánica | Timeout |\n|---|---|---|\n| `ultimo` (default) | Sync con polling 90s + fallback async | 90s |\n| `ultimos_12` | Async desde el inicio (202 + job_id) | — |\n| `historico` | Async desde el inicio (202 + job_id) | — |\n\n### Cache global\n\nAntes de scrapear, Volty revisa si tiene bills frescos para este `numero_rpu` en cualquier org. Si hay hit, responde 200 en ~50ms.\n\n### Auto-creación de RPU\n\nSi el `numero_rpu` no está dado de alta en tu organización, Volty crea el row automáticamente usando `nombre_titular`. No requiere POST /v1/rpus previo.\n\n### Gating técnico por scope\n\nCada API key tiene contratados unos modos específicos en su campo `scopes`. Si pides un modo que tu key no tiene contratado, recibes `403 modo_no_contratado` con la lista de modos disponibles para tu key. Contacta a `soporte@volty.mx` para actualizar el plan.\n\n### `force_scrape` (opcional, admin)\n\nQuery param opt-in **restringido a Volty Internal** (scope `admin:force_scrape`). Cuando es `true`, el endpoint ignora el cache y dispara un scrape real contra CFE. Usado para smokes post-deploy, debugging de cache, y CI. Partners externos que lo intenten reciben `403 admin_no_contratado`. Costo: ~30-90s + 1 slot del pool.\n\n### Respuestas\n\n- **200**: scrape exitoso o cache hit. Body: `RpuConRecibos`.\n- **202**: scrape encolado. Body: `{job_id, estado, razon, mensaje}`.\n- **400**: datos del cliente incorrectos (`sub_caso=dato_malo`).\n- **403**: modo no contratado (`modo_no_contratado`) o `force_scrape=true` sin scope admin (`admin_no_contratado`).\n- **409**: ya hay un job activo del mismo RPU (cualquier org).\n- **422**: validación del body o path (RPU != 12 dígitos, etc.).\n- **502**: error de CFE no atribuible al cliente (timeout, captcha, etc.).","operationId":"descargar_recibos_sync_v1_rpus__numero_rpu__recibos_descargar_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}},{"name":"modo","in":"query","required":false,"schema":{"enum":["ultimo","ultimos_12","historico","historico_completo"],"type":"string","description":"Cuántos recibos pedir. Solo `ultimo` es sync. `historico` es alias deprecated de `historico_completo` — se mantiene por compat con partners existentes pero se eliminará cuando versionemos la API (Sprint E). Nuevos integrations deben usar `historico_completo`.","default":"ultimo","title":"Modo"},"description":"Cuántos recibos pedir. Solo `ultimo` es sync. `historico` es alias deprecated de `historico_completo` — se mantiene por compat con partners existentes pero se eliminará cuando versionemos la API (Sprint E). Nuevos integrations deben usar `historico_completo`."},{"name":"force_scrape","in":"query","required":false,"schema":{"type":"boolean","description":"**Solo Volty Internal** (scope `admin:force_scrape`). Cuando es `true`, el endpoint ignora el cache check y encola un scrape real contra CFE incluso si hay bills frescos. Usado para smokes post-deploy, debugging de cache, y CI. Costo: ~30-90s + 1 slot del pool por llamada. Partners externos reciben 403 si lo intentan.","default":false,"title":"Force Scrape"},"description":"**Solo Volty Internal** (scope `admin:force_scrape`). Cuando es `true`, el endpoint ignora el cache check y encola un scrape real contra CFE incluso si hay bills frescos. Usado para smokes post-deploy, debugging de cache, y CI. Costo: ~30-90s + 1 slot del pool por llamada. Partners externos reciben 403 si lo intentan."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DescargarBody"}}}},"responses":{"200":{"description":"Cache hit o scrape exitoso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RpuConRecibos-Input"}}}},"202":{"description":"Encolado async","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEncoladoResponse"}}}},"400":{"description":"Datos del cliente incorrectos"},"403":{"description":"Modo no contratado por la API key"},"409":{"description":"Job activo del mismo RPU en curso"},"422":{"description":"Validación de input"},"502":{"description":"Error de CFE"}}}},"/v1/rpus/{numero_rpu}/reporte-consumo":{"post":{"tags":["v1-publica"],"summary":"Pedir el reporte de consumo de un RPU","description":"Encola el reporte de consumo del RPU: histórico de todos sus recibos más el historial que trae cada recibo de CFE, diagnóstico de su tarifa y gráfica.\n\nCubre tarifas residenciales (1, 1A a 1F y DAC), PDBT, GDBT, GDMTO y GDMTH.\n\nConsulta el resultado con `GET /v1/jobs/{job_id}` o suscríbete al webhook `report.completed`. Requiere el scope `reportes:consumo`.","operationId":"pedir_reporte_consumo_v1_rpus__numero_rpu__reporte_consumo_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReporteConsumoBody"},{"type":"null"}],"title":"Body"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReporteEncolado"}}}},"403":{"description":"La API key no tiene el scope `reportes:consumo`."},"404":{"description":"`rpu_sin_datos`: no hay recibos de este RPU."},"422":{"description":"`numero_rpu_invalido`, `sin_xml` (ningún recibo con XML), `tarifa_no_soportada` o un campo desconocido en el body."},"429":{"description":"`reporte_limite_excedido`; reintenta tras `Retry-After`."}}}},"/v1/rpus/{numero_rpu}/reporte-consumo/{job_id}/xlsx":{"get":{"tags":["v1-publica"],"summary":"Descargar el Excel de un reporte de consumo","description":"Devuelve una URL firmada, válida 5 minutos, del Excel del reporte: la tabla de todos los periodos, la gráfica y el diagnóstico. El trabajo debe haber terminado `exitoso` y traer `xlsx_disponible: true` en `GET /v1/jobs/{job_id}`. Requiere el scope `reportes:consumo`.","operationId":"descargar_reporte_xlsx_v1_rpus__numero_rpu__reporte_consumo__job_id__xlsx_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"numero_rpu","in":"path","required":true,"schema":{"type":"string","title":"Numero Rpu"}},{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReporteXlsx"}}}},"403":{"description":"La API key no tiene el scope `reportes:consumo`."},"404":{"description":"`reporte_no_encontrado` (no existe, es de otra organización o de otro RPU) o `xlsx_no_disponible` (reporte anterior al Excel o el Excel falló)."},"409":{"description":"`reporte_no_listo` (en cola o corriendo) o `reporte_fallido`."},"422":{"description":"`numero_rpu_invalido` o `job_id` que no es UUID."}}}},"/admin/canary/scrape":{"post":{"tags":["admin-canary"],"summary":"Encolar job canary para testing de vendored playwright-stealth (admin)","description":"**Solo Volty Internal** (scope `admin:force_scrape`). Encola un job que sera reclamado exclusivamente por el worker canary del backend especificado (`worker-canary-soax` o `worker-canary-vpn`).\n\nEl worker canary usa el fork vendorizado de playwright-stealth con `importlib.resources` (sin `pkg_resources`) + setuptools moderno. Permite validar empiricamente el cambio antes de promoverlo a workers productivos.\n\nDeuda #158 (fase canary). Cerrar cuando `USE_VENDORED_STEALTH=true` se promueva a workers productivos + se elimine la dep externa.\n\n**Ver resultado**: `GET /v1/jobs/{job_id}` (endpoint publico existente).\n\n**Diferencia con `POST /v1/rpus/{rpu}/recibos/descargar`**: este endpoint NO checa cache global, NO respeta anti-duplicado por RPU productivo (porque el flag worker_role='canary' aisla), y siempre encola async.\n\n**`force_scrape`** (opcional): bypass end-to-end del cache del worker (freshness early return + filtro periodos ya cacheados). Util para re-testear el vendorizado con el mismo RPU N veces sin depender de RPUs frescos. Ver ADR 0018.","operationId":"encolar_canary_scrape_admin_canary_scrape_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanaryScrapeRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanaryScrapeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"ApiKey":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"nombre":{"type":"string","title":"Nombre"},"prefijo":{"type":"string","title":"Prefijo"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"ultimo_uso_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Uso At"},"expira_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expira At"},"revocada_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revocada At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","organization_id","nombre","prefijo","scopes","created_at"],"title":"ApiKey","description":"Lo que devolvemos al listar (sin la key completa)."},"ApiKeyConSecreto":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"nombre":{"type":"string","title":"Nombre"},"prefijo":{"type":"string","title":"Prefijo"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"ultimo_uso_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Uso At"},"expira_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expira At"},"revocada_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revocada At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"key":{"type":"string","title":"Key","description":"Cópiala AHORA. Solo se muestra una vez y no se puede recuperar."}},"type":"object","required":["id","organization_id","nombre","prefijo","scopes","created_at","key"],"title":"ApiKeyConSecreto","description":"Respuesta al CREAR — incluye la key completa que NUNCA más veremos."},"ApiKeyCreate":{"properties":{"nombre":{"type":"string","maxLength":80,"minLength":2,"title":"Nombre","description":"Descripción humana (ej. 'CtrlSun production')"},"entorno":{"type":"string","enum":["live","test"],"title":"Entorno","default":"live"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Permisos. Por ahora: ['read'] o ['read', 'write']"},"expira_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expira At","description":"Fecha de expiración. Null = sin expiración."}},"type":"object","required":["nombre"],"title":"ApiKeyCreate"},"AuthInfoResponse":{"properties":{"api_key_id":{"type":"string","format":"uuid","title":"Api Key Id","description":"ID interno de la API key usada"},"api_key_nombre":{"type":"string","title":"Api Key Nombre","description":"Nombre humano de la key (ej. 'ctrlsun prod')"},"api_key_prefijo":{"type":"string","title":"Api Key Prefijo","description":"Prefijo visible (ej. 'volty_test_aBcD')"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id","description":"ID de tu organización en Volty"},"organization_nombre":{"type":"string","title":"Organization Nombre","description":"Nombre de tu organización"},"organization_slug":{"type":"string","title":"Organization Slug","description":"Slug URL-safe de tu organización"},"tier":{"type":"string","title":"Tier","description":"'test' (sandbox/alpha) o 'live' (producción)"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Permisos: 'read', 'write'"},"plan_id":{"type":"string","title":"Plan Id","description":"Plan actual (trial, alpha, paid, etc.)"}},"type":"object","required":["api_key_id","api_key_nombre","api_key_prefijo","organization_id","organization_nombre","organization_slug","tier","scopes","plan_id"],"title":"AuthInfoResponse","description":"Respuesta de `GET /v1/auth/info`.\nÚtil para que el partner valide su API key sin necesidad de un RPU."},"Bill":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"numero_rpu":{"type":"string","title":"Numero Rpu"},"periodo_inicio":{"type":"string","format":"date","title":"Periodo Inicio"},"periodo_fin":{"type":"string","format":"date","title":"Periodo Fin"},"periodo_dias":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Periodo Dias"},"anio":{"type":"integer","title":"Anio"},"mes":{"type":"integer","title":"Mes"},"fecha_limite_pago":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Fecha Limite Pago"},"fecha_emision":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Fecha Emision"},"cfdi_uuid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cfdi Uuid"},"serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serie"},"folio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folio"},"receptor_rfc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Receptor Rfc"},"receptor_nombre":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Receptor Nombre"},"tarifa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa"},"tarifa_legacy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa Legacy"},"kwh_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Total"},"kwh_base":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Base"},"kwh_intermedia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Intermedia"},"kwh_punta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Punta"},"kwh_exportada":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Exportada"},"kw_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Max"},"kw_base":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Base"},"kw_intermedia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Intermedia"},"kw_punta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Punta"},"kvarh":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kvarh"},"factor_potencia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Factor Potencia"},"carga_contratada_kw":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Carga Contratada Kw"},"kw_base_sp1":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Base Sp1"},"kw_base_sp2":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Base Sp2"},"kw_intermedia_sp1":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Intermedia Sp1"},"kw_intermedia_sp2":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Intermedia Sp2"},"kw_punta_sp1":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Punta Sp1"},"kw_punta_sp2":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Punta Sp2"},"importe_suministro":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Suministro"},"importe_transmision":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Transmision"},"importe_scnmem":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Scnmem"},"importe_cenace":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Cenace"},"importe_base":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Base"},"importe_intermedia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Intermedia"},"importe_punta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Punta"},"importe_energia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Energia"},"importe_capacidad":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Capacidad"},"importe_distribucion":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Distribucion"},"importe_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Total"},"importe_factor_potencia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Factor Potencia"},"importe_2_baja_tension":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe 2 Baja Tension"},"importe_dap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Dap"},"importe_iva":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Iva"},"importe_subtotal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Subtotal"},"monto_a_pagar":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto A Pagar"},"tarifa_promedio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tarifa Promedio"},"factor_carga":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Factor Carga"},"tipo_dato":{"anyOf":[{"type":"string","enum":["Medido","Estimado"]},{"type":"null"}],"title":"Tipo Dato"},"scraped_at":{"type":"string","format":"date-time","title":"Scraped At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"tiene_pdf":{"type":"boolean","title":"Tiene Pdf","default":false},"tiene_xml":{"type":"boolean","title":"Tiene Xml","default":false}},"type":"object","required":["id","numero_rpu","periodo_inicio","periodo_fin","anio","mes","scraped_at","created_at"],"title":"Bill","description":"Recibo completo con todos los importes y conceptos.\n\nSprint B deuda #8 PR 3a — eliminados `rpu_id: UUID` y `organization_id: UUID`\n(legacy local). Bills es cache global cross-org cuya identidad es\n(numero_rpu, anio, mes). La info de \"que org genero cada scrape\" vive\ncanonical en jobs.organization_id + scrape_attempts.organization_id.\nMantener bills.organization_id duplicada generaba un bug conceptual en\ncache cross-org: el bill quedaba marcado con la PRIMERA org que scrapeo,\nfalseando ownership. Por eso se elimina sin sustituto."},"BillArchivos":{"properties":{"pdf_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Url"},"xml_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xml Url"},"expira_seg":{"type":"integer","title":"Expira Seg","default":300},"en_cache":{"type":"boolean","title":"En Cache"},"job_id_si_no":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Job Id Si No","description":"Si no estaba en cache y se encoló un scrape, el ID del job."}},"type":"object","required":["en_cache"],"title":"BillArchivos","description":"Respuesta de GET /rpus/{id}/recibos/{anio}/{mes}/archivos\nSi el archivo está en cache, devuelve URL firmada. Si no, está en None y\nse sugiere encolar un scrape."},"BillResumen":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"numero_rpu":{"type":"string","title":"Numero Rpu"},"anio":{"type":"integer","title":"Anio"},"mes":{"type":"integer","title":"Mes"},"periodo_inicio":{"type":"string","format":"date","title":"Periodo Inicio"},"periodo_fin":{"type":"string","format":"date","title":"Periodo Fin"},"periodo_dias":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Periodo Dias"},"fecha_limite_pago":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Fecha Limite Pago"},"tarifa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa"},"kwh_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Total"},"kw_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Max"},"factor_potencia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Factor Potencia"},"monto_a_pagar":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto A Pagar"},"tarifa_promedio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tarifa Promedio"},"tipo_dato":{"anyOf":[{"type":"string","enum":["Medido","Estimado"]},{"type":"null"}],"title":"Tipo Dato"},"tiene_pdf":{"type":"boolean","title":"Tiene Pdf","default":false},"tiene_xml":{"type":"boolean","title":"Tiene Xml","default":false}},"type":"object","required":["id","numero_rpu","anio","mes","periodo_inicio","periodo_fin"],"title":"BillResumen","description":"Vista ligera de un recibo — para listados, gráficas, tablas resumen.\nNo incluye los importes detallados ni el raw_xml.\n\nSprint B deuda #8 PR 3a — eliminado `rpu_id: UUID` (legacy local).\nEl nuevo identificador de continuidad es `numero_rpu` (clave CFE global\nde 12 digitos). Mas util para dashboards admin que el UUID interno\nporque corresponde al numero real del recibo CFE. La columna\nbills.rpu_id sera dropeada fisicamente en PR 3b tras soak."},"CanaryScrapeRequest":{"properties":{"numero_rpu":{"type":"string","maxLength":12,"minLength":12,"pattern":"^\\d{12}$","title":"Numero Rpu","description":"Numero de RPU CFE (12 digitos). Sera scrapeado por el worker canary.","examples":["508941006021"]},"nombre_titular":{"type":"string","maxLength":200,"minLength":2,"title":"Nombre Titular","description":"Nombre del titular tal como aparece en el recibo CFE. Usado para el alta automatica del RPU en la cuenta MiEspacio del pool canary. CFE valida exactitud (mayusculas, acentos, espacios).","examples":["EMPRESA EJEMPLO SA DE CV"]},"modo":{"type":"string","enum":["ultimo","ultimos_12","historico_completo"],"title":"Modo","description":"Modo de descarga a testear en el canary.","default":"ultimo"},"backend":{"type":"string","enum":["soax","vpn"],"title":"Backend","description":"Backend de proxy a usar. Determina que worker canary reclama el job ('worker-canary-soax' o 'worker-canary-vpn'). Permite testear vendorizado vs cada backend independientemente.","examples":["soax"]},"force_scrape":{"type":"boolean","title":"Force Scrape","description":"Si True, el worker canary bypasea TODOS los cache checks del handler de descarga: (a) early return por freshness (Bug #7, descarga.py L386), (b) filtro de periodos ya descargados (descarga.py L584). Fuerza scrape real contra CFE aunque el RPU tenga bills recientes.\n\nReutiliza el mismo mecanismo que `POST /v1/rpus/{rpu}/recibos/descargar?force_scrape=true`: propaga `params.force_scrape=True` al job y el worker respeta el flag end-to-end (fix del bug pre-existente descubierto durante fase canary vendorizacion playwright-stealth, 5 ago 2026). Ver ADR 0018.\n\n**Uso legitimo**: validar vendorizado con RPUs ya cacheados sin depender de RPUs frescos. Elimina la friccion 'para probar necesito RPUs nuevos'.\n\n**Costo**: 1 slot pool credenciales CFE + data plan proxy (SOAX/VPN) + ~30-90s CPU + riesgo Imperva si se abusa. NO usar en batch — el gating por scope `admin:force_scrape` + rate limit 300/min ya limitan, pero la responsabilidad operativa es del caller.","default":false}},"type":"object","required":["numero_rpu","nombre_titular","backend"],"title":"CanaryScrapeRequest","description":"Body del `POST /admin/canary/scrape`."},"CanaryScrapeResponse":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"worker_role":{"type":"string","title":"Worker Role","examples":["canary"]},"canary_backend":{"type":"string","title":"Canary Backend","examples":["soax"]},"mensaje":{"type":"string","title":"Mensaje"}},"type":"object","required":["job_id","worker_role","canary_backend","mensaje"],"title":"CanaryScrapeResponse","description":"Response 202 del POST /admin/canary/scrape."},"Credential":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"customer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Customer Id"},"etiqueta":{"type":"string","title":"Etiqueta"},"es_pool":{"type":"boolean","title":"Es Pool"},"es_activa":{"type":"boolean","title":"Es Activa"},"estado":{"type":"string","enum":["sin_validar","valida","invalida","requiere_2fa","en_descanso","bloqueada","retirada"],"title":"Estado"},"ultimo_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Login At"},"ultimo_uso_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Uso At"},"proximo_uso_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Proximo Uso At"},"exitos_total":{"type":"integer","title":"Exitos Total","default":0},"fallos_total":{"type":"integer","title":"Fallos Total","default":0},"fallos_consecutivos":{"type":"integer","title":"Fallos Consecutivos","default":0},"ultimo_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimo Error"}},"type":"object","required":["created_at","id","organization_id","etiqueta","es_pool","es_activa","estado"],"title":"Credential"},"CredentialAdmin":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"customer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Customer Id"},"etiqueta":{"type":"string","title":"Etiqueta"},"es_pool":{"type":"boolean","title":"Es Pool"},"es_activa":{"type":"boolean","title":"Es Activa"},"estado":{"type":"string","enum":["sin_validar","valida","invalida","requiere_2fa","en_descanso","bloqueada","retirada"],"title":"Estado"},"ultimo_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Login At"},"ultimo_uso_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Uso At"},"proximo_uso_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Proximo Uso At"},"exitos_total":{"type":"integer","title":"Exitos Total","default":0},"fallos_total":{"type":"integer","title":"Fallos Total","default":0},"fallos_consecutivos":{"type":"integer","title":"Fallos Consecutivos","default":0},"ultimo_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimo Error"},"retirada_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Retirada At"},"retirada_por":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Retirada Por"},"motivo_retiro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivo Retiro"}},"type":"object","required":["created_at","id","organization_id","etiqueta","es_pool","es_activa","estado"],"title":"CredentialAdmin","description":"`Credential` + los campos de auditoría del retiro.\n\nExiste como modelo SEPARADO, y no como campos dentro de `Credential`,\nporque `Credential` es el `response_model` de los endpoints de credenciales\nde `routers/v1/recursos.py`, que se autentican con **API key de partner**.\nPoner `motivo_retiro` —texto libre escrito por un administrador— en el\nmodelo compartido lo expondría por la API pública.\n\nAun saliendo en `null`, declarar campos que el partner no puede usar es el\nanti-patrón del ADR 0024: capacidades anunciadas y no implementadas fue lo\nque produjo cuatro eventos de webhook falsos y un mes de documentación\nequivocada para los partners.\n\nÚsalo SOLO en `routers/credentials.py` (sesión de usuario, rol admin)."},"CredentialCreate":{"properties":{"customer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Customer Id","description":"ID del cliente al que pertenece. Null = credencial de pool (CtrlSun/Fleet)."},"etiqueta":{"type":"string","maxLength":80,"minLength":2,"title":"Etiqueta"},"es_pool":{"type":"boolean","title":"Es Pool","default":false},"es_activa":{"type":"boolean","title":"Es Activa","default":false},"cfe_username":{"type":"string","maxLength":200,"minLength":1,"format":"password","title":"Cfe Username","writeOnly":true},"cfe_password":{"type":"string","maxLength":200,"minLength":1,"format":"password","title":"Cfe Password","writeOnly":true}},"type":"object","required":["etiqueta","cfe_username","cfe_password"],"title":"CredentialCreate","description":"El cliente envía usuario+password CFE. La API los cifra con KMS y los guarda.\nSecretStr evita que aparezcan en logs/reprs por accidente."},"CredentialRetiro":{"properties":{"motivo":{"type":"string","maxLength":500,"minLength":10,"title":"Motivo"}},"type":"object","required":["motivo"],"title":"CredentialRetiro","description":"Cuerpo de `POST /credenciales/{id}/retirar`.\n\nEl motivo es obligatorio y con mínimo real: si una cuenta se retiró por\nestar comprometida y alguien la reactiva sin saberlo, vuelve a circulación\nen el siguiente scrape, y este texto es lo único que se lo advierte. Un\nmotivo de 3 caracteres no advierte nada."},"CredentialUpdate":{"properties":{"etiqueta":{"anyOf":[{"type":"string","maxLength":80,"minLength":2},{"type":"null"}],"title":"Etiqueta"},"es_activa":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Es Activa"},"cfe_username":{"anyOf":[{"type":"string","format":"password","writeOnly":true},{"type":"null"}],"title":"Cfe Username"},"cfe_password":{"anyOf":[{"type":"string","format":"password","writeOnly":true},{"type":"null"}],"title":"Cfe Password"}},"type":"object","title":"CredentialUpdate","description":"Permite cambiar metadatos sin re-introducir la contraseña.\nSi vienen `cfe_username` o `cfe_password`, se re-cifra todo."},"Customer":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"nombre":{"type":"string","title":"Nombre"},"razon_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon Social"},"rfc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rfc"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"telefono":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telefono"},"notas":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notas"},"external_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Ref"},"rpus_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rpus Total"},"credenciales_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credenciales Total"}},"type":"object","required":["created_at","id","organization_id","nombre"],"title":"Customer"},"CustomerCreate":{"properties":{"nombre":{"type":"string","maxLength":200,"minLength":2,"title":"Nombre"},"razon_social":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Razon Social"},"rfc":{"anyOf":[{"type":"string","maxLength":13},{"type":"null"}],"title":"Rfc"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"telefono":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Telefono"},"notas":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notas"},"external_ref":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"External Ref","description":"ID del cliente en el sistema externo (CtrlSun/Fleet) para sincronización."}},"type":"object","required":["nombre"],"title":"CustomerCreate"},"CustomerUpdate":{"properties":{"nombre":{"anyOf":[{"type":"string","maxLength":200,"minLength":2},{"type":"null"}],"title":"Nombre"},"razon_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon Social"},"rfc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rfc"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"telefono":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telefono"},"notas":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notas"},"external_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Ref"}},"type":"object","title":"CustomerUpdate"},"DescargarBody":{"properties":{"nombre_titular":{"type":"string","maxLength":200,"minLength":2,"title":"Nombre Titular","description":"Nombre del titular tal como aparece en el recibo CFE. Usado para el alta automática del RPU en la cuenta MiEspacio del pool. CFE valida exactitud (mayúsculas, acentos, espacios) — si no coincide, el alta falla con `sub_caso=nombre_no_coincide`.","examples":["JUAN PEREZ GOMEZ"]},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Metadata","description":"Metadata opcional del partner para trazabilidad. Backward compat 100%: si no se envia, el endpoint funciona identico al pre-fix.\n\nConvencion Volty reconocida:\n\n- `installer_id`: identificador del usuario de la plataforma partner (ej. instalador de paneles solares) que origino la solicitud. Se propaga a Sentry como User ID -> activa feature 'Affected Users' + permite filtrar issues por instalador. Se propaga tambien al webhook de completado (`datos.installer_id`). Max 100 chars, chars permitidos: `a-z A-Z 0-9 - _ . : @`.\n\nKeys custom (no reconocidas por Volty) se persisten en `jobs.params.metadata` pero NO se propagan a Sentry ni logs. Partners pueden usarlas para tracking interno propio.","examples":[{"installer_id":"instalador_abc_123"},{"installer_id":"juan.perez@ctrlfleet.com"}]}},"type":"object","required":["nombre_titular"],"title":"DescargarBody","description":"Body del `POST /v1/rpus/{numero_rpu}/recibos/descargar`."},"FreshnessInfo":{"properties":{"estado":{"type":"string","enum":["fresca","stale","sin_datos"],"title":"Estado"},"periodicidad":{"type":"string","enum":["mensual","bimestral","desconocida"],"title":"Periodicidad"},"ultimo_recibo_en_cache":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimo Recibo En Cache"},"periodo_esperado_mas_reciente":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Periodo Esperado Mas Reciente"},"periodos_a_descargar":{"items":{"type":"string"},"type":"array","title":"Periodos A Descargar","default":[]},"razon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon"},"refresh_encolado":{"type":"boolean","title":"Refresh Encolado","default":false},"job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Job Id"}},"type":"object","required":["estado","periodicidad"],"title":"FreshnessInfo","description":"Resumen del estado de freshness de un RPU, listo para devolverlo al\ncliente en la respuesta JSON o usarlo internamente para decidir scrapes."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Job":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"rpu_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Rpu Id"},"customer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Customer Id"},"creado_por_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Creado Por User Id"},"tipo":{"type":"string","enum":["descarga_inicial","actualizacion_periodica","descarga_ultimos_12","carga_masiva_csv","sync_volty_cfe","generar_reporte","baja_rpu_cfe"],"title":"Tipo"},"estado":{"type":"string","enum":["en_cola","corriendo","exitoso","parcial","fallido","cancelado"],"title":"Estado"},"progreso_total":{"type":"integer","title":"Progreso Total","default":0},"progreso_hecho":{"type":"integer","title":"Progreso Hecho","default":0},"progreso_fallido":{"type":"integer","title":"Progreso Fallido","default":0},"progreso_mensaje":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Progreso Mensaje"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"resultado":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Resultado"},"error_mensaje":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Mensaje"},"credencial_usada_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Credencial Usada Id"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url"},"comenzado_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Comenzado At"},"terminado_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Terminado At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","organization_id","tipo","estado","created_at"],"title":"Job","description":"Modelo publico expuesto en `GET /v1/jobs` y `GET /v1/jobs/{id}`.\n\nIMPORTANTE: `tipo` es `TipoJobPartnerFacing` (NO `TipoJob`) por diseno —\nlos jobs internos como `webhook_dispatch` existen en BD pero NO se\nserializan en response publico. Ver ADR 0017 y modulo docstring arriba."},"JobEncoladoResponse":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"estado":{"type":"string","title":"Estado","description":"`en_cola` siempre en este response.","examples":["en_cola"]},"razon":{"type":"string","enum":["modo_async","pool_saturado","timeout_sync"],"title":"Razon","description":"Por qué se devuelve 202 en lugar de 200:\n\n- `modo_async`: el modo es `ultimos_12` o `historico` y siempre   es async.\n- `pool_saturado`: el modo era `ultimo` pero no hay credenciales   libres ahora. Se encoló con prioridad sync; consulta GET /v1/jobs/{id}.\n- `timeout_sync`: el modo era `ultimo` y el polling de 90s   terminó sin que el worker procesara. El job sigue corriendo;   consulta GET /v1/jobs/{id}."},"mensaje":{"type":"string","title":"Mensaje","description":"Mensaje humano-legible para el cliente B2B."}},"type":"object","required":["job_id","estado","razon","mensaje"],"title":"JobEncoladoResponse","description":"Response 202 cuando se encola async (o sync hace fallback)."},"Membership":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"rol":{"type":"string","enum":["admin","operador","lector"],"title":"Rol"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"nombre":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre"}},"type":"object","required":["id","user_id","organization_id","rol","created_at"],"title":"Membership"},"MembershipCreate":{"properties":{"user_id":{"type":"string","format":"uuid","title":"User Id"},"rol":{"type":"string","enum":["admin","operador","lector"],"title":"Rol","default":"operador"}},"type":"object","required":["user_id"],"title":"MembershipCreate","description":"Invitar un usuario existente a una organización."},"MembershipUpdate":{"properties":{"rol":{"type":"string","enum":["admin","operador","lector"],"title":"Rol"}},"type":"object","required":["rol"],"title":"MembershipUpdate"},"Organization":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"id":{"type":"string","format":"uuid","title":"Id"},"nombre":{"type":"string","title":"Nombre"},"slug":{"type":"string","title":"Slug"},"tipo":{"type":"string","enum":["saas","api","interno"],"title":"Tipo"},"plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Id"},"stripe_customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Customer Id"},"stripe_subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Subscription Id"},"ciclo_facturacion_inicio":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ciclo Facturacion Inicio"},"rpus_cuota":{"type":"integer","title":"Rpus Cuota","default":3},"rpus_activos":{"type":"integer","title":"Rpus Activos","default":0},"configuracion":{"additionalProperties":true,"type":"object","title":"Configuracion"}},"type":"object","required":["created_at","id","nombre","slug","tipo"],"title":"Organization","description":"Lo que la API devuelve."},"OrganizationCreate":{"properties":{"nombre":{"type":"string","maxLength":120,"minLength":2,"title":"Nombre"},"slug":{"type":"string","maxLength":60,"minLength":2,"pattern":"^[a-z0-9-]+$","title":"Slug"},"tipo":{"type":"string","enum":["saas","api","interno"],"title":"Tipo","default":"saas"},"plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Id","default":"trial"}},"type":"object","required":["nombre","slug"],"title":"OrganizationCreate","description":"Lo que el cliente envía al crear una organización nueva."},"OrganizationUpdate":{"properties":{"nombre":{"anyOf":[{"type":"string","maxLength":120,"minLength":2},{"type":"null"}],"title":"Nombre"},"plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Id"},"configuracion":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Configuracion"}},"type":"object","title":"OrganizationUpdate","description":"Solo lo modificable. Slug y tipo no se cambian a la ligera."},"PaginatedResponse_Credential_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Credential"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total","description":"Total de items sin paginar"},"limit":{"type":"integer","title":"Limit","description":"Tamaño de página solicitado"},"offset":{"type":"integer","title":"Offset","description":"Offset usado"},"has_more":{"type":"boolean","title":"Has More","description":"True si hay más resultados después de este page"}},"type":"object","required":["data","total","limit","offset","has_more"],"title":"PaginatedResponse[Credential]"},"PaginatedResponse_Customer_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Customer"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total","description":"Total de items sin paginar"},"limit":{"type":"integer","title":"Limit","description":"Tamaño de página solicitado"},"offset":{"type":"integer","title":"Offset","description":"Offset usado"},"has_more":{"type":"boolean","title":"Has More","description":"True si hay más resultados después de este page"}},"type":"object","required":["data","total","limit","offset","has_more"],"title":"PaginatedResponse[Customer]"},"PaginatedResponse_Job_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Job"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total","description":"Total de items sin paginar"},"limit":{"type":"integer","title":"Limit","description":"Tamaño de página solicitado"},"offset":{"type":"integer","title":"Offset","description":"Offset usado"},"has_more":{"type":"boolean","title":"Has More","description":"True si hay más resultados después de este page"}},"type":"object","required":["data","total","limit","offset","has_more"],"title":"PaginatedResponse[Job]"},"PaginatedResponse_Rpu_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Rpu"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total","description":"Total de items sin paginar"},"limit":{"type":"integer","title":"Limit","description":"Tamaño de página solicitado"},"offset":{"type":"integer","title":"Offset","description":"Offset usado"},"has_more":{"type":"boolean","title":"Has More","description":"True si hay más resultados después de este page"}},"type":"object","required":["data","total","limit","offset","has_more"],"title":"PaginatedResponse[Rpu]"},"PaginatedResponse_WebhookDelivery_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookDelivery"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total","description":"Total de items sin paginar"},"limit":{"type":"integer","title":"Limit","description":"Tamaño de página solicitado"},"offset":{"type":"integer","title":"Offset","description":"Offset usado"},"has_more":{"type":"boolean","title":"Has More","description":"True si hay más resultados después de este page"}},"type":"object","required":["data","total","limit","offset","has_more"],"title":"PaginatedResponse[WebhookDelivery]"},"ReciboPublico":{"properties":{"anio":{"type":"integer","title":"Anio","description":"Año del periodo facturado (ej. 2026)","examples":[2026]},"mes":{"type":"integer","title":"Mes","description":"Mes del periodo facturado (1-12)","examples":[4]},"periodo_inicio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Periodo Inicio","examples":["2026-03-25"]},"periodo_fin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Periodo Fin","examples":["2026-04-22"]},"periodo_dias":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Periodo Dias","examples":[29]},"fecha_limite_pago":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fecha Limite Pago","examples":["2026-05-13"]},"fecha_emision":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fecha Emision","examples":["2026-04-24T11:45:11"]},"cfdi_uuid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cfdi Uuid","description":"UUID del Timbre Fiscal del SAT. Puede ser `null` para clientes residenciales sin RFC registrado en CFE (CFE no timbra esos). Usa `serie + folio` como identificador alternativo.","examples":["10383CEB-9C04-4E8A-916B-543958C52F22"]},"serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serie","examples":["LA"]},"folio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folio","examples":["000321273269"]},"tarifa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa","description":"Código interno CFE de la tarifa: `GDMTO`, `GDMTH`, `PDBT`, `GDBT`, `DAC`, `DB1`, etc.","examples":["GDMTH"]},"tarifa_legacy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa Legacy","description":"Código público antiguo (ej. `HM`, `OM`, `01`, `02`).","examples":["HM"]},"kwh_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Total","examples":[1310.0]},"kwh_base":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Base","examples":[null]},"kwh_intermedia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Intermedia","examples":[null]},"kwh_punta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Punta","examples":[1310.0]},"kwh_exportada":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kwh Exportada","description":"kWh exportados a la red (clientes con paneles solares + NETMET). 0 o `null` si no aplica.","examples":[0.0]},"kw_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kw Max","examples":[148.0]},"factor_potencia":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Factor Potencia","description":"Factor de potencia en %, ideal >95%. CFE penaliza <90%.","examples":[94.77]},"monto_a_pagar":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto A Pagar","examples":[6090.29]},"importe_subtotal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Subtotal","examples":[5250.25]},"importe_iva":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Importe Iva","examples":[840.04]},"tarifa_promedio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tarifa Promedio","description":"$/kWh promedio del periodo.","examples":[4.6491]},"tiene_generacion_distribuida":{"type":"boolean","title":"Tiene Generacion Distribuida","description":"`true` si el cliente tiene NETMET o instalación solar.","default":false,"examples":[true]},"netmet_saldo_a_favor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Netmet Saldo A Favor","description":"kWh a favor en la bolsa de energía al cierre del periodo, como los reporta CFE (medición neta). Crece con lo que el cliente genera de más y baja cuando CFE lo abona a su consumo.","examples":[850.0]},"netmet_bolsa_aplicada":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Netmet Bolsa Aplicada","description":"kWh de la bolsa de energía que CFE abonó en este periodo. Con paneles, lo facturado es `max(0, kwh_total - kwh_exportada - netmet_bolsa_aplicada)`.","examples":[116.0]},"pdf_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Url","description":"URL firmada de S3 al PDF del recibo. **Expira en 5 minutos.**","examples":["https://s3.us-east-1.amazonaws.com/volty-recibos/recibos/508941006021/2026-04/recibo.pdf?X-Amz-Signature=..."]},"xml_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xml Url","description":"URL firmada de S3 al XML CFDI. **Expira en 5 minutos.**","examples":["https://s3.us-east-1.amazonaws.com/volty-recibos/recibos/508941006021/2026-04/recibo.xml?X-Amz-Signature=..."]},"expira_en_seg":{"type":"integer","title":"Expira En Seg","description":"Segundos hasta que las URLs firmadas dejen de funcionar.","default":300,"examples":[300]},"tipo_dato":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Dato","description":"`Medido` (lectura real) o `Estimado` (CFE no pudo leer el medidor).","examples":["Medido"]}},"type":"object","required":["anio","mes"],"title":"ReciboPublico","description":"Una factura individual del recibo CFE.\n\nTodos los datos vienen parseados del XML CFDI 4.0. Los archivos PDF/XML\nestán en `pdf_url`/`xml_url` con URLs firmadas que **expiran en 5 minutos**.\nSi necesitas el archivo después, vuelve a llamar al endpoint — las URLs\nse generan al vuelo."},"ReporteConsumoBody":{"properties":{},"additionalProperties":false,"type":"object","title":"ReporteConsumoBody","description":"Parametros del reporte. Hoy ninguno: el dimensionamiento FV y BESS\nllega en una version posterior. Un campo desconocido es 422, no se ignora."},"ReporteEncolado":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id","description":"Id del trabajo. Consúltalo en GET /v1/jobs/{job_id}."},"estado":{"type":"string","title":"Estado","examples":["en_cola"]},"reutilizado":{"type":"boolean","title":"Reutilizado","description":"true si ya había un reporte igual en cola o corriendo para este RPU y se devolvió ese mismo trabajo."}},"type":"object","required":["job_id","estado","reutilizado"],"title":"ReporteEncolado"},"ReporteXlsx":{"properties":{"url":{"type":"string","title":"Url","description":"URL firmada para descargar el Excel del reporte."},"expira_en_seg":{"type":"integer","title":"Expira En Seg","description":"Segundos de vigencia de la URL. Al vencer, pide otra.","examples":[300]}},"type":"object","required":["url","expira_en_seg"],"title":"ReporteXlsx"},"RespuestaArchivarRpu":{"properties":{"ok":{"type":"boolean","title":"Ok","default":true},"mensaje":{"type":"string","title":"Mensaje"},"aviso_quitar_de_cfe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aviso Quitar De Cfe"}},"type":"object","required":["mensaje"],"title":"RespuestaArchivarRpu","description":"Respuesta de DELETE /v1/rpus/{numero_rpu}. Extiende RespuestaOkSimple\ncon un campo opcional `aviso_quitar_de_cfe` que solo aparece cuando el\npartner pidió `quitar_de_cfe=true` pero la función está suspendida\nen alpha (Sprint B Bloque 3).\n\nCuando el partner ve este aviso, sabe que el RPU SÍ se archivó en Volty\n(cuando ya NO seguirá scrapeando) pero que el RPU NO se eliminó de la\ncuenta CFE del cliente. Si necesita vaciar la cuenta CFE, contacta\nsoporte para procesar manualmente."},"RespuestaOk":{"properties":{"ok":{"type":"boolean","title":"Ok","default":true},"mensaje":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mensaje"}},"type":"object","title":"RespuestaOk","description":"Para endpoints que solo confirman éxito (DELETE, acciones)."},"RespuestaOkSimple":{"properties":{"ok":{"type":"boolean","title":"Ok","default":true},"mensaje":{"type":"string","title":"Mensaje"}},"type":"object","required":["mensaje"],"title":"RespuestaOkSimple"},"RetryRpuResponse":{"properties":{"rpu_id":{"type":"string","format":"uuid","title":"Rpu Id"},"job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Job Id"},"estado_anterior":{"type":"string","title":"Estado Anterior"},"estado_actual":{"type":"string","title":"Estado Actual"},"modo":{"type":"string","title":"Modo"},"mensaje":{"type":"string","title":"Mensaje"},"cache_hit":{"type":"boolean","title":"Cache Hit","default":false}},"type":"object","required":["rpu_id","estado_anterior","estado_actual","modo","mensaje"],"title":"RetryRpuResponse"},"Rpu":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"customer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Customer Id"},"numero_rpu":{"type":"string","title":"Numero Rpu"},"nombre_servicio":{"type":"string","title":"Nombre Servicio"},"nombre_corto":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre Corto"},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias"},"tarifa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa"},"tarifa_legacy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa Legacy"},"division":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Division"},"division_codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Division Codigo"},"rmu":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rmu"},"medidor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Medidor"},"carga_contratada_kw":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Carga Contratada Kw"},"carga_conectada_kw":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Carga Conectada Kw"},"direccion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direccion"},"entre_calle_1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entre Calle 1"},"entre_calle_2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entre Calle 2"},"colonia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colonia"},"municipio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipio"},"estado_geo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estado Geo"},"codigo_postal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo Postal"},"estado":{"type":"string","enum":["pendiente","procesando","activo","fallido","pausado","archivado"],"title":"Estado"},"modo":{"type":"string","enum":["ultimo","ultimos_12","historico_completo"],"title":"Modo"},"auto_actualizar":{"type":"boolean","title":"Auto Actualizar"},"periodicidad":{"anyOf":[{"type":"string","enum":["mensual","bimestral","irregular"]},{"type":"null"}],"title":"Periodicidad"},"ultimo_scrape_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Scrape At"},"ultimo_scrape_estado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimo Scrape Estado"},"ultimo_scrape_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimo Scrape Error"},"proximo_scrape_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Proximo Scrape At"},"intentos_fallidos":{"type":"integer","title":"Intentos Fallidos","default":0},"ultimo_periodo_inicio":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Ultimo Periodo Inicio"},"ultimo_periodo_fin":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Ultimo Periodo Fin"},"ultimo_consumo_kwh":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ultimo Consumo Kwh"},"ultimo_monto_a_pagar":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ultimo Monto A Pagar"},"alertas_activas":{"type":"boolean","title":"Alertas Activas","default":true},"cache_ttl_dias":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cache Ttl Dias"}},"type":"object","required":["created_at","id","organization_id","numero_rpu","nombre_servicio","estado","modo","auto_actualizar"],"title":"Rpu"},"RpuConRecibos-Input":{"properties":{"rpu":{"type":"string","title":"Rpu","description":"Número del RPU consultado (12 dígitos)"},"nombre_servicio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre Servicio"},"tarifa_actual":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa Actual"},"division":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Division"},"modo_entrega":{"type":"string","title":"Modo Entrega","description":"Cómo se decidió cuántos recibos devolver: 'historico_completo' | 'gdmth_12_meses' | 'mensual_uno' | 'limite_explicito'"},"total_recibos":{"type":"integer","title":"Total Recibos"},"recibos":{"items":{"$ref":"#/components/schemas/ReciboPublico"},"type":"array","title":"Recibos"},"freshness":{"$ref":"#/components/schemas/FreshnessInfo","description":"Estado de actualización de la cache. Si `estado='stale'` significa que hay periodos más recientes pendientes de descargar — se encoló automáticamente. Vuelve a llamar en ~60s para tener los más nuevos."},"rpu_status":{"anyOf":[{"$ref":"#/components/schemas/RpuStatus"},{"type":"null"}],"description":"Estado del scrape del RPU (intentos automáticos, próximo retry, acción requerida del partner). Null en clientes que aún no consultan el campo — solo agrega información, no rompe contratos."}},"type":"object","required":["rpu","modo_entrega","total_recibos","recibos","freshness"],"title":"RpuConRecibos","description":"Respuesta completa de GET /v1/rpus/{rpu}/recibos"},"RpuConRecibos-Output":{"properties":{"rpu":{"type":"string","title":"Rpu","description":"Número del RPU consultado (12 dígitos)"},"nombre_servicio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre Servicio"},"tarifa_actual":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifa Actual"},"division":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Division"},"modo_entrega":{"type":"string","title":"Modo Entrega","description":"Cómo se decidió cuántos recibos devolver: 'historico_completo' | 'gdmth_12_meses' | 'mensual_uno' | 'limite_explicito'"},"total_recibos":{"type":"integer","title":"Total Recibos"},"recibos":{"items":{"$ref":"#/components/schemas/ReciboPublico"},"type":"array","title":"Recibos"},"freshness":{"$ref":"#/components/schemas/FreshnessInfo","description":"Estado de actualización de la cache. Si `estado='stale'` significa que hay periodos más recientes pendientes de descargar — se encoló automáticamente. Vuelve a llamar en ~60s para tener los más nuevos."},"rpu_status":{"anyOf":[{"$ref":"#/components/schemas/RpuStatus"},{"type":"null"}],"description":"Estado del scrape del RPU (intentos automáticos, próximo retry, acción requerida del partner). Null en clientes que aún no consultan el campo — solo agrega información, no rompe contratos."}},"type":"object","required":["rpu","modo_entrega","total_recibos","recibos","freshness"],"title":"RpuConRecibos","description":"Respuesta completa de GET /v1/rpus/{rpu}/recibos"},"RpuCreate":{"properties":{"customer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Customer Id"},"numero_rpu":{"type":"string","maxLength":12,"minLength":12,"pattern":"^\\d{12}$","title":"Numero Rpu","description":"Número del RPU CFE — exactamente 12 dígitos numéricos."},"nombre_servicio":{"type":"string","maxLength":200,"minLength":2,"title":"Nombre Servicio"},"nombre_corto":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Nombre Corto"},"alias":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Alias"},"modo":{"type":"string","enum":["ultimo","ultimos_12","historico_completo"],"title":"Modo","default":"historico_completo"},"auto_actualizar":{"type":"boolean","title":"Auto Actualizar","default":false},"alertas_activas":{"type":"boolean","title":"Alertas Activas","default":true}},"type":"object","required":["numero_rpu","nombre_servicio"],"title":"RpuCreate"},"RpuStatus":{"properties":{"estado":{"type":"string","title":"Estado","description":"pendiente | procesando | activo | fallido | archivado","examples":["pendiente"]},"ultimo_scrape_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Scrape At","description":"Timestamp del último intento de scrape. Pydantic acepta tanto `datetime` (lo que devuelve Supabase para columnas timestamptz) como strings ISO y serializa siempre a ISO en el JSON output."},"ultimo_scrape_estado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimo Scrape Estado","description":"Código del último resultado: exitoso | fallido | sin_recibos | timeout_parcial | rpu_no_encontrado_cfe (definitivo, requiere acción del partner) | rpu_no_encontrado_cfe_retry (en reintento automático, no requiere acción)"},"ultimo_scrape_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultimo Scrape Error","description":"Mensaje de error humano-legible del último intento"},"intentos_realizados":{"type":"integer","title":"Intentos Realizados","description":"Posición en el CICLO ACTIVO de retry automático (1..intentos_max). Se resetea cuando el partner llama POST /retry (que arranca un ciclo nuevo). Para conteo acumulado total ver `intentos_historicos`.","default":0,"examples":[2]},"intentos_max":{"type":"integer","title":"Intentos Max","description":"Tope total de ejecuciones automáticas por ciclo (incl. la original). Después de agotarse, el partner debe usar PATCH + POST /retry para reactivar el ciclo manualmente.","default":6,"examples":[6]},"intentos_historicos":{"type":"integer","title":"Intentos Historicos","description":"Conteo acumulado HISTÓRICO de fallos del RPU. Solo crece, nunca se resetea. Útil para identificar RPUs crónicamente problemáticos.","default":0,"examples":[8]},"esta_reintentando":{"type":"boolean","title":"Esta Reintentando","description":"True si hay un retry programado en el futuro (no requiere acción)","default":false},"proximo_reintento_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Proximo Reintento At","description":"Timestamp del próximo retry programado (null si no hay retry pendiente). Pydantic acepta datetime y string ISO; serializa a ISO en el JSON output."},"accion_partner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accion Partner","description":"Si está seteado, el partner debe intervenir. Caso típico: tras agotarse los retries automáticos, verifica datos del cliente y haz PATCH /v1/rpus/{numero_rpu} + POST .../retry."},"ultimo_intento":{"anyOf":[{"$ref":"#/components/schemas/UltimoIntento"},{"type":"null"}],"description":"Detalle estructurado del último intento del RPU. Fuente autoritativa para el partner: `codigo` semántico, `mensaje_cfe` literal, `mensaje_usuario` pre-formateado para display al end-user, y `sub_caso` (`dato_malo` | `intermitente`) cuando aplica. None si el RPU nunca ha tenido intentos fallidos o si el último job es legacy pre-Pieza 8 sin resultado estructurado. Introducido en PR Z (C3) — bug UX partner Ctrlsun 20 jul 2026. Los campos legacy `ultimo_scrape_estado` y `ultimo_scrape_error` se conservan para backward compat pero deriva canónicamente de aquí."}},"type":"object","required":["estado"],"title":"RpuStatus","description":"Estado actual del scrape del RPU.\n\nÚtil para que el partner sepa qué pasó con el último intento, si está\nreintentando automáticamente, o si necesita intervención manual."},"RpuUpdate":{"properties":{"nombre_servicio":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Nombre Servicio"},"nombre_corto":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre Corto"},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias"},"modo":{"anyOf":[{"type":"string","enum":["ultimo","ultimos_12","historico_completo"]},{"type":"null"}],"title":"Modo"},"auto_actualizar":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Auto Actualizar"},"alertas_activas":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Alertas Activas"},"estado":{"anyOf":[{"type":"string","enum":["pendiente","procesando","activo","fallido","pausado","archivado"]},{"type":"null"}],"title":"Estado"}},"type":"object","title":"RpuUpdate"},"UltimoIntento":{"properties":{"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","description":"Código semántico del error. Uno de: `login_fallido` | `captcha_detectado` | `rpu_no_encontrado` | `cfe_mantenimiento` | `error_red` | `recibo_no_disponible` | `descarga_timeout` | `error_parser` | `credencial_bloqueada` | `imperva_bloqueado_vpn` | `timeout_parcial` | `desconocido`. None si último intento exitoso.","examples":["rpu_no_encontrado"]},"mensaje_cfe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mensaje Cfe","description":"Mensaje LITERAL del sistema CFE o del scraper (para debugging o cuando el partner quiera citar exacto al end-user). Truncado a 500 caracteres para evitar payloads gigantes.","examples":["El RPU 508941006021 no existe en el sistema de MiEspacio."]},"mensaje_usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mensaje Usuario","description":"Mensaje pre-formateado listo para mostrar al end-user del partner sin lógica extra. Deriva de la constante `mensaje_usuario` class-level de la subclase `ScraperError` correspondiente. None si el `codigo` no matchea ninguna subclase conocida (subclase futura no mapeada).","examples":["El RPU no existe en tu cuenta CFE o no se pudo dar de alta. Verifica el número y reintenta."]},"sub_caso":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Caso","description":"Solo cuando `codigo == 'rpu_no_encontrado'`: `dato_malo` (el partner mandó info incorrecta como nombre_titular o RPU — requiere corrección manual, sin retry automático) | `intermitente` (bug conocido de CFE — sistema reintenta automáticamente con backoff ADR 0002). None en otros códigos.","examples":["intermitente"]},"ocurrio_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ocurrio At","description":"Timestamp del job del que se derivan estos campos. Toma `terminado_at` si existe (el job cerró), sino `created_at` (el job sigue en curso — raro para intentos fallidos). Nota: la tabla `jobs` NO tiene `updated_at` (hallazgo empírico del incidente SEV-1 20 jul 2026 — fix hotfix)."}},"type":"object","title":"UltimoIntento","description":"Detalle estructurado del último intento de scrape del RPU.\n\nFuente de verdad: `jobs.resultado` del último job del RPU (cualquier\ntipo). Poblado desde Sprint B B3 P8. Los campos legacy\n`ultimo_scrape_estado` y `ultimo_scrape_error` de `RpuStatus` se\nconservan para backward compat pero se derivan canónicamente de aquí.\n\nTodos los campos son `Optional`. Un `UltimoIntento` con todos los\ncampos en None NO se emite — el helper retorna `None` en ese caso\ny el response omite el bloque."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Webhook":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"nombre":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre"},"url":{"type":"string","title":"Url"},"eventos":{"items":{"type":"string"},"type":"array","title":"Eventos"},"activo":{"type":"boolean","title":"Activo","default":true},"pausado_hasta":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Pausado Hasta"},"ultimo_envio_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Envio At"},"ultimo_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ultimo Status"},"fallos_consec":{"type":"integer","title":"Fallos Consec","default":0},"total_enviados":{"type":"integer","title":"Total Enviados","default":0},"total_fallidos":{"type":"integer","title":"Total Fallidos","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","organization_id","url","eventos","created_at"],"title":"Webhook","description":"Webhook como se devuelve al cliente — SIN el secreto."},"WebhookConSecreto":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"nombre":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre"},"url":{"type":"string","title":"Url"},"eventos":{"items":{"type":"string"},"type":"array","title":"Eventos"},"activo":{"type":"boolean","title":"Activo","default":true},"pausado_hasta":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Pausado Hasta"},"ultimo_envio_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ultimo Envio At"},"ultimo_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ultimo Status"},"fallos_consec":{"type":"integer","title":"Fallos Consec","default":0},"total_enviados":{"type":"integer","title":"Total Enviados","default":0},"total_fallidos":{"type":"integer","title":"Total Fallidos","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"},"secreto":{"type":"string","title":"Secreto","description":"Secreto HMAC para verificar las firmas. Guárdalo seguro — no podrás verlo de nuevo. Volty firma cada request con HMAC-SHA256."}},"type":"object","required":["id","organization_id","url","eventos","created_at","secreto"],"title":"WebhookConSecreto","description":"Respuesta al CREAR — incluye el secreto que solo vemos una vez."},"WebhookCreate":{"properties":{"nombre":{"type":"string","maxLength":80,"minLength":2,"title":"Nombre","description":"Descripción humana (ej. 'Notificaciones CtrlSun prod')"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url","description":"URL HTTPS donde Volty va a hacer POST cuando ocurra un evento"},"eventos":{"items":{"type":"string","enum":["bill.created","cfe.down","rpu.alta_fallo","report.completed"]},"type":"array","minItems":1,"title":"Eventos","description":"Lista de eventos que quieres recibir"}},"type":"object","required":["nombre","url","eventos"],"title":"WebhookCreate","description":"Lo que el cliente envía al registrar un webhook nuevo."},"WebhookDelivery":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"webhook_id":{"type":"string","format":"uuid","title":"Webhook Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"evento":{"type":"string","title":"Evento"},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"url_destino":{"type":"string","title":"Url Destino"},"intento":{"type":"integer","title":"Intento","default":1},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code"},"response_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Body"},"duracion_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duracion Ms"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"exitoso":{"type":"boolean","title":"Exitoso","default":false},"proximo_reintento_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Proximo Reintento At"},"enviado_at":{"type":"string","format":"date-time","title":"Enviado At"}},"type":"object","required":["id","webhook_id","organization_id","evento","payload","url_destino","enviado_at"],"title":"WebhookDelivery"},"WebhookUpdate":{"properties":{"nombre":{"anyOf":[{"type":"string","maxLength":80,"minLength":2},{"type":"null"}],"title":"Nombre"},"url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Url"},"eventos":{"anyOf":[{"items":{"type":"string","enum":["bill.created","cfe.down","rpu.alta_fallo","report.completed"]},"type":"array"},{"type":"null"}],"title":"Eventos"},"activo":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Activo"}},"type":"object","title":"WebhookUpdate","description":"Para modificar un webhook existente."}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"API key con formato volty_live_xxx o volty_test_xxx","scheme":"bearer"}}},"tags":[{"name":"v1-publica","description":"**Endpoints para consumidores de API** (CtrlSun, Fleet, integraciones de terceros). Requieren API key con formato `volty_live_xxx`. Versionados — estables hacia atrás dentro de v1."},{"name":"webhooks","description":"**Suscripciones a eventos** — recibe POSTs cuando algo pasa en Volty. Cada webhook tiene un secreto HMAC para validar firmas. Retry exponencial automático en caso de fallo."},{"name":"api-keys","description":"**Gestión de API keys** desde el dashboard. Solo accesible con JWT (no con otra API key). Genera, lista, revoca."},{"name":"organizaciones","description":"Cuentas Volty — pueden ser tipo `saas` (cliente directo), `api` (integrador como CtrlSun/Fleet), o `interno`."},{"name":"clientes","description":"Los clientes finales (dueños físicos de los RPUs) dentro de tu organización. Una org tiene N clientes, cada cliente tiene M RPUs."},{"name":"credenciales","description":"Credenciales del proveedor eléctrico — siempre cifradas con AWS KMS antes de guardarse. **Nunca** vemos el password en claro fuera de memoria del worker en el momento del scrape."},{"name":"rpus","description":"Servicios eléctricos monitoreados (un RPU = una toma eléctrica)."},{"name":"recibos","description":"Facturas históricas parseadas con URLs firmadas de S3."},{"name":"meta","description":"Endpoints de salud y catálogos públicos (sin auth)."},{"name":"catalogos","description":"Catálogos públicos (planes, tarifas, etc.)."}]}