# API / Proxy — Contrato actual del plugin

Documento de referencia para el **backend que sirve traducciones** al plugin **Traductor Digixop Pro** (modo **DTL** / créditos en pantalla).

---

## Resumen de ejecución

El plugin elige el motor según la opción **`translation_mode`** (`DTL` = créditos / proxy, o `BYO`):

1. **Modo BYO** — Traduce directamente contra **Google Cloud Translation API v2** con la API Key guardada en ajustes. No usa el proxy ni envía la clave de licencia a Google.

2. **Modo DTL** — Traduce contra el endpoint **`DIGIXOP_TDL_TRANSLATE_PROXY_URL`** (HTTPS), enviando **`license_key`** y los fragmentos de texto que el plugin aún no tenga en **memoria de traducción** (ver más abajo).

La **activación de licencias en WordPress** llama al endpoint **`activate-license.php`** de tu API Digixop (no sustituye la lógica de descuento de saldo del proxy). Ver `docs/LICENCIAS.md`.

### Interfaz de administración (referencia)

En el cliente WordPress, la configuración y las métricas viven en **una sola pantalla** (**Traductor Digixop** o **Ajustes → Traductor Digixop**): licencia (clave + activar/desactivar), modo DTL/BYO, API Key opcional, idiomas, opciones y **Memoria de Traducción** (activar / vaciar caché). Plantilla: `includes/admin-unified-view.php`.

---

## Endpoints que usa el plugin

### 1) Licencia en WordPress (no es tu `/validate` legacy)

- **Digixop** — `POST` JSON a **`DIGIXOP_TDL_LICENSE_ACTIVATE_URL`** / **`DIGIXOP_TDL_LICENSE_DEACTIVATE_URL`** (por defecto `activate-license.php`) con `license_key`, `instance_name`, `site_url`.
- La constante **`DIGIXOP_TDL_LICENSE_URL`** puede existir en el plugin por compatibilidad o ejemplos legacy; **el cliente actual no la usa** para activar. Si montas un backend propio con `POST action=validate`, documéntalo en tu despliegue; el contrato de referencia histórico sería:

```http
POST (URL personalizada)
Content-Type: application/x-www-form-urlencoded

action=validate&key=...&domain=...
```

Respuesta JSON de ejemplo (solo referencia para integraciones custom):

```json
{
  "valid": true,
  "message": "Licencia activada",
  "balance_remaining": 120000,
  "expiration_date": "2026-12-31 23:59:59",
  "license_type": "PREPAID"
}
```

---

### 2) Proxy único de traducción (modo DTL)

- Constante: **`DIGIXOP_TDL_TRANSLATE_PROXY_URL`**
- Método: **POST** (el plugin exige URL `https://`)
- Formato enviado (por defecto): **`application/json`** con cabecera **`Authorization: Bearer {license_key}`** y réplica **`X-Digixop-License-Key`** (la clave también va en el cuerpo JSON). El proxy debe leer la clave del cuerpo o de cualquiera de esas cabeceras si el hosting oculta `Authorization`.
- Cuerpo JSON:
  - `license_key`
  - `source_lang`
  - `target_lang`
  - `texts` — array de fragmentos (hasta ~4500 caracteres cada uno en el cliente). El proxy en `dist-server/` acepta también `chunks` / `contents` / `text` por compatibilidad.
  - **`google_format`** (opcional): `html` (por defecto) o `text`. El plugin envía `text` para segmentos de texto plano (p. ej. nodos visibles del widget HTML de Elementor) y `html` para bloques con marcado.
  - **`system_prompt`** (opcional): cadena de contexto enviada por el plugin; **Google Translate v2 no aplica system prompts**. El plugin y el proxy aplican un **glosario UI** coherente tras la traducción (p. ej. términos frecuentes en interfaces hacia español).
  - `site_url` — URL del sitio (métricas / auditoría en backends extendidos).
- Valor por defecto de **`DIGIXOP_TDL_TRANSLATE_PROXY_URL`**: `https://api.digixop.com/translate-proxy.php`.
- Legado: con `define('DIGIXOP_TDL_PROXY_USE_JSON', false);` en `wp-config.php` el plugin envía **`application/x-www-form-urlencoded`** con `texts[]`.

Respuesta esperada (200 JSON):

```json
{
  "success": true,
  "translations": ["...", "..."],
  "balance_remaining": 49210,
  "expiration_date": "2026-12-31 23:59:59",
  "request_id": "a1b2c3d4e5f6g7h8"
}
```

El campo `request_id` puede incluirse en respuestas JSON para trazabilidad.

### Comportamiento en servidor (`dist-server/`)

El archivo **`dist-server/translate-proxy.php`** del repositorio es una **variante compacta**: valida licencia y saldo, llama a **Google v2 en un solo POST JSON** con todos los `texts`, aplica glosario UI a las cadenas devueltas y **descuenta el saldo tras una traducción correcta**.  
Implementaciones de producción más avanzadas (transacción **antes** de Google, reembolso si falla el proveedor, `dx_usage_events` / `dx_usage_daily`) se documentan en **[docs/ejemplo-servidor-licencias/](./ejemplo-servidor-licencias/README.md)** y **[SERVIDOR-API-DIGIXOP.md](./SERVIDOR-API-DIGIXOP.md)**.

Errores esperados:

- **402** (sin saldo / licencia caducada en tu backend): el plugin detiene la traducción y muestra  
  `Traducción detenida por falta de créditos`.
- **401/403/500**: error genérico de traducción y registro en debug/log según configuración.

Ejemplo de payload en 402:

```json
{
  "success": false,
  "message": "Créditos agotados. Por favor, recarga tu bono en el portal de cliente",
  "balance_remaining": 0,
  "expiration_date": "2026-12-31 23:59:59"
}
```

---

### 3) Google BYO (modo BYO)

Si `translation_mode` es **BYO** y hay API Key configurada:

- Endpoint: `POST https://translation.googleapis.com/language/translate/v2?key={API_KEY}`
- Body: `q` (uno o varios segmentos), `source`, `target`, `format` = `html` o `text` según el tipo de contenido.

Errores pueden registrarse en:

- `wp-content/uploads/digixop-translator.log` (si `DIGIXOP_TRANSLATOR_DEBUG` está activo u otros fallbacks).

---

### 4) Memoria de traducción (solo en WordPress)

- **Tabla:** `{prefijo}dx_translations_cache` (clave `hash_id` MD5, columnas `texto_original`, `texto_traducido`, `lang_dest`).
- **Opción:** `digixop_translator_lite_options['translation_memory_enabled']` (por defecto activa). Si está desactivada, no se consulta ni se escribe la tabla; todo va a la API.
- **Vacía:** acción AJAX `digixop_empty_translation_memory` (nonce dedicado, capacidad `manage_options`) ejecuta `TRUNCATE` sobre la tabla.
- El proxy **no** implementa esta caché: solo recibe los segmentos que el plugin no resolvió en local.

---

## Estado local en WordPress (sin llamadas extra)

Tras traducir por proxy con éxito, el plugin puede guardar:

- `digixop_translator_local_balance_remaining`
- `digixop_translator_local_expiration_date`

El dashboard usa esos valores para actualizarse al instante.

---

## Seguridad mínima recomendada

- Proxy siempre bajo **HTTPS**.
- `config.php` del servidor fuera de acceso público.
- Nunca exponer la API key maestra de Google en el plugin ni en respuestas JSON.