> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# El proxy de ATC

El proxy es la frontera HTTP entre el workflow de Dani y los servicios de
Naturgy. Recibe las llamadas de las herramientas, valida y transforma sus
contratos, coordina las consultas necesarias y devuelve una respuesta estable
que el agente puede interpretar.

Esta página fija el papel del proxy dentro del caso de uso. Los contratos de
cada endpoint, la configuración y la operación se mantienen en la documentación
técnica del propio servicio.

## Dónde encaja

```mermaid
flowchart LR
    hr["Workflow de Dani<br/>HTTP actions"] --> edge["Proxy ATC<br/>FastAPI"]
    edge --> routes["Rutas y esquemas<br/>por dominio"]
    routes --> services["Servicios y reglas<br/>de orquestación"]
    services --> upstream["Servicios Naturgy<br/>MULE / FUA / auth"]
    upstream --> normalize["Normalizar, sanear<br/>y preparar respuesta"]
    normalize --> hr
    edge --> telemetry["Trazabilidad y analytics<br/>metadatos permitidos"]
```

El proxy no conversa con el cliente ni decide el triaje. El workflow conserva
la conversación, la selección del especialista y las decisiones de salida. Los
servicios de Naturgy conservan el estado de negocio. El proxy conecta ambos
lados y evita que el workflow tenga que conocer los detalles de cada servicio
upstream.

## Responsabilidad por capa

| Capa | Responsabilidad principal |
|---|---|
| Workflow ATC | Conversación, autenticación como recorrido, triaje, especialistas y escalados |
| Proxy ATC | Autenticación de entrada, esquemas, transformación, orquestación, errores y trazabilidad |
| Servicios Naturgy | Estado y operaciones de negocio: clientes, facturas, pagos, lecturas y productos |
| Analytics del proxy | Metadatos allowlisted para fiabilidad, diagnóstico y agregados operativos |

El proxy puede preparar el texto `next_steps` que guía al agente, pero no
sustituye las instrucciones del workflow ni convierte una respuesta upstream en
una decisión de negocio.

## Catálogo de endpoints

El catálogo siguiente refleja las rutas montadas por la aplicación actual. Las
rutas de negocio requieren `X-API-Key` y, para correlación, `X-Run-ID`; las rutas
de analytics usan `X-Analytics-Key`. El método `GET/POST` en algunos endpoints
no es duplicación funcional: se aceptan ambos formatos porque una HTTP action de
HappyRobot puede enviar un payload como `POST` aunque el nodo se diseñe como
consulta.

### Autenticación y ficha

| Método | Endpoint | Propósito |
|---|---|---|
| `POST` | `/enviar-otp` | Valida el documento de entrada y solicita el envío de un código OTP por SMS. Devuelve el contexto temporal que necesita la siguiente llamada. |
| `POST` | `/validar-codigo` | Comprueba el código recibido y completa la validación; devuelve los tokens de sesión que usan las consultas autenticadas posteriores. |
| `POST` | `/obtener-ficha-cliente` | Agrega la ficha del cliente, contratos, direcciones, facturas, lecturas, fraccionamientos y órdenes o alertas disponibles para el triaje. |

### Atención y operaciones de negocio

| Método | Endpoint | Propósito |
|---|---|---|
| `POST` | `/gasReadSend` | Registra una lectura de contador de gas asociada al CUPS del contrato. |
| `POST` | `/reclamar-lectura` | Crea una reclamación de factura de gas cuando procede una lectura corregida; localiza internamente el cliente, contrato y factura relacionados. |
| `GET/POST` | `/invoiceDetailAgent` | Consulta el desglose de una factura a partir del cliente y el identificador de factura. |
| `POST` | `/duplicado-factura` | Localiza una factura y solicita el envío de un duplicado al cliente. |
| `GET/POST` | `/productDetail` | Consulta el detalle del producto o tarifa de un contrato. |
| `GET` | `/recommendedRates` | Obtiene alternativas de tarifa para un producto, con los precios o componentes que el agente debe comparar. |
| `POST` | `/productChange` | Inicia el cambio de producto o tarifa; el cliente completa la firma desde el enlace enviado por SMS antes de que el cambio sea efectivo. |
| `POST` | `/paymentPreparation` | Prepara un pago de facturas o de cuotas y envía al cliente un enlace de pago por SMS. |
| `POST` | `/subdivision` | Crea un fraccionamiento de deuda con las facturas, cuotas y fecha indicadas. |
| `GET` | `/subdivision` | Consulta los fraccionamientos existentes del cliente, opcionalmente filtrados por cuenta de contrato. |
| `DELETE` | `/subdivision` | Anula un fraccionamiento existente identificado por su plan o cuenta de contrato. |
| `POST` | `/createFiscalAddress` | Crea o actualiza la dirección fiscal del cliente. |
| `PUT` | `/clients` | Actualiza los datos del cliente dentro del alcance actual, en particular el teléfono preferido. |
| `PUT` | `/contractsAccounts` | Actualiza el IBAN de las cuentas de contrato que correspondan y desencadena la firma digital cuando el servicio la requiere. |

Las operaciones anteriores no son equivalentes en riesgo: lecturas de datos
como `/invoiceDetailAgent`, `/productDetail` y `/recommendedRates` pueden
reintentarse solo cuando el contrato lo permite; pagos, envíos SMS, reclamaciones,
fraccionamientos y actualizaciones son mutaciones y no se reintentan a ciegas.

### Observabilidad del proxy

| Método | Endpoint | Propósito |
|---|---|---|
| `GET` | `/analytics/summary` | Resume volumen, éxitos, KO de negocio, errores técnicos y percentiles de latencia de un periodo. |
| `GET` | `/analytics/history` | Consulta snapshots históricos y, opcionalmente, filtra por dataset y periodo. |
| `GET` | `/analytics/endpoints` | Desglosa volumen, errores y latencia por método y endpoint. |
| `GET` | `/analytics/errors` | Agrupa fallos por categoría controlada, endpoint y código upstream. |
| `GET` | `/analytics/run?run_id=<UUID>` | Devuelve la línea temporal segura de una run y de sus intentos hacia Naturgy. |

Analytics no expone payloads, tokens ni datos de cliente. Los cuatro primeros
endpoints aceptan `from` y `to` en UTC; `/analytics/run` recibe un UUID y limita
el número de eventos devueltos.

### Utilidad y contrato publicado

| Método | Endpoint | Propósito |
|---|---|---|
| `GET` | `/` | Publica la identidad, versión e inventario resumido del servicio. |
| `GET` | `/health` | Comprueba que el proceso está vivo. No ejecuta una operación de negocio. |
| `GET` | `/docs` y `/redoc` | Sirve Swagger UI y ReDoc para consultar el contrato; requieren la autenticación propia de documentación. |
| `GET` | `/openapi.json` | Expone el esquema OpenAPI que usan las herramientas de documentación y las comprobaciones de contrato. |

El workflow suele recorrer `/enviar-otp`, `/validar-codigo` y
`/obtener-ficha-cliente` antes de llamar al endpoint del especialista. Después,
la respuesta del proxy se interpreta junto con el estado final del sistema
responsable; el catálogo de endpoints no convierte una respuesta HTTP exitosa
en una prueba de resultado de negocio.

## Contrato de una llamada

```mermaid
sequenceDiagram
    participant W as Workflow
    participant P as Proxy
    participant U as Servicio Naturgy
    participant A as Analytics

    W->>P: Petición autenticada + correlación de run
    P->>P: Validar key, esquema y entorno
    P->>U: Petición transformada
    U-->>P: Resultado o error upstream
    P->>P: Clasificar, sanear y normalizar
    P-->>W: Respuesta estable + next_steps
    P-->>A: Metadatos permitidos
```

Reglas que condicionan el comportamiento:

* las llamadas de negocio usan `X-API-Key` y pueden llevar `X-Run-ID`, el
  identificador común de la run; si falta, el proxy genera uno para esa petición,
  por lo que la correlación completa debe enviarlo desde el workflow;
* `/analytics/*` usa una credencial independiente de solo lectura y no la
  credencial de negocio;
* los resultados funcionales y técnicos se expresan en el cuerpo con `status`
  (`OK` o `KO`) para conservar la compatibilidad con las HTTP actions;
* los errores de autenticación de entrada mantienen su respuesta HTTP propia;
* `technical_issue` y `next_steps` son categorías controladas: no se propagan
  excepciones, cuerpos sin sanear, tokens ni datos personales;
* solo se reintentan lecturas idempotentes cuando el contrato lo permite;
  OTP, pagos, escrituras y otras mutaciones no se reintentan a ciegas;
* cada petición conserva identificadores de correlación para poder unir
  workflow, proxy y upstream sin registrar cargas sensibles.

## Ficha de cliente

`/obtener-ficha-cliente` es el punto de agregación más importante. Después de
validar al cliente, el proxy coordina varias consultas y entrega al workflow un
contexto preparado para los especialistas: contratos, direcciones, facturas,
lecturas, fraccionamientos, órdenes o alertas que estén dentro del contrato
vigente.

Desde el 6-oct-2026 la ficha trae también tres datos nuevos:

* **Autoconsumo**, por suministro de luz: la línea «Autoconsumo: sí/no» en
  el resumen de contratos. La comparativa lo usa para excluir la Tarifa
  Plana. El código de la instalación no se expone.
* **Inspección periódica**, por suministro de gas: la última inspección
  registrada, la fecha límite de la próxima (cinco años después) y si está
  vigente o vencida.
* **Límites de fraccionamiento**, por dirección: si la cuenta contrato ha
  alcanzado el máximo de fraccionamientos activos o el de desactivados por
  impago. Si el facturador no lo informa, el dato no aparece.

El especialista lee ese contexto; no debe reconstruirlo llamando directamente
a cada servicio ni inferir un estado que el proxy no haya devuelto. Si una
parte de la ficha falla, la respuesta debe conservar la diferencia entre dato
no disponible, error técnico y ausencia de un registro.

## Entornos y diagnóstico

El despliegue del proxy determina el entorno upstream: desarrollo se usa para
validar contra PRE y producción contra PRO. El caller no cambia el entorno con
un valor libre en cada petición. Antes de probar o publicar una modificación se
confirma el entorno y se registra la versión del workflow y la fecha.

Para diagnosticar una incidencia se sigue la cadena, en este orden:

1. versión y nodo del workflow;
2. petición y respuesta del proxy;
3. servicio upstream y resultado de negocio;
4. estado final en el sistema responsable;
5. efecto en CRM, transferencia o analytics, si aplica.

Un HTTP 200 no prueba que la operación de negocio haya tenido éxito, y una
respuesta `OK` del proxy no prueba por sí sola la entrega de un SMS, un pago,
una transferencia ni la escritura final. Usa el [contrato de evidencia de ATC](/use-cases/atc/reference/evidence)
para elegir las comprobaciones necesarias.

## Cambios en el proxy

Un cambio del proxy puede afectar a varios especialistas aunque el workflow no
cambie. Antes de tratarlo como una release de ATC hay que identificar las rutas,
los consumidores y los efectos laterales afectados; validar el contrato de
respuesta; comprobar errores, reintentos y trazabilidad; y probar los recorridos
que dependan de él.

La publicación del proxy y la publicación del workflow son operaciones
separadas. La [metodología de releases](/method/explanations/release-methodology)
coordina la decisión, pero cada capa conserva sus propias pruebas, revisión y
reversión.

Para ver cómo se conecta el proxy con los módulos de conversación, consulta
[flujos de trabajo de ATC](/use-cases/atc/explanations/workflows).