# Paquete para agentes de FineProxy

Versión: 2026-09-22

Utilice este archivo para evaluar si una integración de proxy existente puede migrar a FineProxy. No contiene ninguna clave de API, datos de la cuenta ni endpoints privados.

## Fuentes oficiales

- Documentación interactiva de la API para clientes: `https://fineproxy.org/account_new/docs`
- Configuración de MCP: `https://fineproxy.org/account_new/mcp`
- Especificación OpenAPI actual para clientes: descárguela desde la documentación de la API en el panel del cliente.
- Creación y gestión de claves de API: `https://fineproxy.org/account_new/settings`
- Endpoint de MCP: `https://fineproxy.org/account_new/api/v1/mcp`

No invente nunca un endpoint a partir de este resumen. Utilice la especificación OpenAPI actual para consultar las rutas de solicitud, los esquemas, los parámetros y las respuestas.

## Resumen de la plataforma

- API REST: OpenAPI 3.1, 49 operaciones documentadas para clientes.
- MCP: 49 herramientas mediante JSON-RPC 2.0 sin estado y Streamable HTTP.
- Autenticación: claves de API bearer creadas en el panel del cliente.
- La API y MCP utilizan los mismos permisos con scopes.
- La documentación de la API para partners solo es visible para las cuentas con estado de partner activo.

## Flujos de trabajo compatibles

### Compra y aprovisionamiento

- Consultar los países y el inventario de IP disponible en tiempo real.
- Cotizar un paquete exacto para varios países sin comprarlo.
- Comprar con el monedero del panel, protección de precio y clave de idempotencia.

La secuencia de compra estándar de MCP es:

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### Gestión de servicios

- Consultar y gestionar servicios.
- Renovar, suspender, restaurar o cancelar cuando sea compatible.
- Activar o desactivar la renovación automática.
- Sustituir o añadir direcciones IP.
- Cambiar las credenciales del servicio.
- Consultar y gestionar los límites de las listas blancas.
- Consultar, comprar y cancelar complementos compatibles.

### Análisis y diagnóstico

- Resumen de uso y series temporales.
- Principales destinos.
- Categorías de errores.
- Recomendaciones operativas.

### Facturación y soporte

- Consultar facturas y descargar sus archivos PDF.
- Consultar las pasarelas de pago.
- Iniciar un depósito en el monedero y consultar su estado.
- Crear, consultar, responder y cerrar tickets de soporte.

### Acceso a proxies y a la cuenta

- Consultar la configuración de conexión de proxies rotativos.
- Cambiar el nombre de usuario y la contraseña del servicio.
- Gestionar los límites de conexión por IP en la lista blanca.
- Consultar la información del perfil, la IP del solicitante y el historial de inicios de sesión.
- Configurar webhooks.

## Scopes de permisos

- `customer:read` — consultar la información del cliente y de la cuenta.
- `customer:write` — actualizar la información del cliente.
- `wallet:read` — consultar la información del monedero.
- `wallet:deposit` — crear y supervisar depósitos.
- `wallet:spend` — gastar fondos del monedero. Debe tratarse como un permiso financiero.
- `services:read` — consultar los servicios y la configuración de los proxies.
- `services:write` — crear o modificar servicios y complementos.
- `tickets:read` — consultar tickets de soporte.
- `tickets:write` — crear, responder, actualizar o cerrar tickets.
- `catalog:read` — consultar productos, opciones, países e inventario.
- `usage:read` — consultar el uso y los diagnósticos.
- `webhooks` — gestionar suscripciones a webhooks.

Comience una auditoría de migración con permisos de solo lectura. Añada permisos de escritura o financieros únicamente después de revisar los cambios propuestos.

## Comportamiento de seguridad

- Las herramientas financieras requieren `wallet:spend`.
- Las compras incluyen el total previsto de la cotización. Si el precio no coincide, la operación se rechaza.
- Las operaciones irreversibles requieren confirmación explícita.
- Los reintentos financieros utilizan una clave de idempotencia para que la misma operación no se cobre dos veces.
- El inventario disponible, los requisitos del plan y los permisos de la cuenta pueden impedir una operación que, por lo demás, sería válida.
- MCP de FineProxy gestiona la cuenta del cliente. No obtiene acceso al código fuente a menos que el usuario proporcione por separado al agente de programación acceso a un repositorio.

## Plantilla de configuración de MCP

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

Guarde la clave real en una variable de entorno o en un gestor de secretos. No la incluya en el repositorio junto con la configuración de MCP.

## Lista de comprobación de compatibilidad para la migración

Revise la integración existente para localizar:

1. La inicialización del cliente del proveedor y todas las importaciones específicas del proveedor.
2. Las cabeceras de autenticación, las credenciales, las variables de entorno y el almacenamiento de secretos.
3. Los flujos de compra, renovación, cancelación y sustitución de IP.
4. Los identificadores de países y las suposiciones sobre el inventario.
5. Los formatos de listas de proxies, protocolos, puertos, nombres de usuario, contraseñas y listas blancas de IP.
6. La paginación y el filtrado.
7. El comportamiento de los reintentos, la gestión de tiempos de espera y la idempotencia.
8. Los modelos de errores y la gestión de límites.
9. Los análisis de uso y los diagnósticos.
10. La facturación, las facturas y los depósitos.
11. La integración con tickets de soporte.
12. Los webhooks y las suposiciones sobre las cargas útiles de los eventos.
13. Las pruebas, los datos de prueba, los mocks y los secretos de CI vinculados al proveedor actual.

Clasifique cada flujo de trabajo como:

- Compatible sin cambios.
- Compatible mediante un cambio de configuración.
- Requiere un adaptador o una transformación de datos.
- Requiere un flujo de trabajo operativo diferente.
- No compatible o no confirmado por la documentación actual.

## Resultado obligatorio de la auditoría

La auditoría debe incluir:

1. Un inventario de todas las dependencias del proveedor actual.
2. Una evaluación de compatibilidad de cada flujo de trabajo.
3. Los scopes necesarios de FineProxy.
4. Los archivos y las rutas de código exactos que cambiarían.
5. Los cambios de autenticación y gestión de secretos.
6. Las preguntas abiertas que requieran la especificación OpenAPI actual o la confirmación del equipo de soporte.
7. Un plan de migración por fases con reversión.
8. Las pruebas de integración necesarias antes de la transición.

No modifique el código durante la primera revisión de la auditoría.