# Servidor API — api.digixop.com (`dist-server/`)

Documentación del **paquete de producción** en la raíz del repositorio: carpeta **`dist-server/`**.  
Estos archivos **no** forman parte del ZIP del plugin WordPress; se despliegan en el host que sirve **`https://api.digixop.com`** (o tu subruta equivalente bajo HTTPS).

---

## Contenido de `dist-server/`

| Archivo | Función |
|---------|---------|
| **`translate-proxy.php`** | Endpoint POST modo **DTL**: valida licencia en MySQL, llama a **Google Cloud Translation v2** (POST JSON con todos los `texts`), aplica glosario UI opcional, **descuenta saldo** tras éxito. Acepta `google_format` (`text`/`html`) y cabeceras/cuerpo como describe [API-SAAS.md](./API-SAAS.md). Variantes con transacción previa + reembolso + `dx_usage_events` están en `docs/ejemplo-servidor-licencias/`. |
| **`polar-webhook.php`** | Webhook **Polar** (firma HMAC): crea/renueva licencias, asigna saldo y metadatos (`metadata.domain`, etc.). **Referencia de billing** en el `dist-server/` actual desde v2.0.9. |
| **`activate-license.php`** | Activación/desactivación consultada por el plugin WordPress; enforcement de dominio y respuesta JSON (`license_key`, `instance`, saldo). |
| **`config.php`** | Plantilla de configuración (MySQL, tablas, API key de Google solo en servidor, secretos webhook). Copiar y completar en el servidor; **no** subir secretos reales a repositorios públicos. |
| **`schema.sql`** | Estructura MySQL: `dx_licenses` (incl. columna `domain` desde migraciones 2.0.10), `dx_usage_events`, `dx_usage_daily`. |

> **Nota histórica:** versiones antiguas del repositorio incluían `lemon-webhook.php`. En el árbol actual de **`dist-server/`** el flujo de referencia es **Polar** + `activate-license.php`. Si aún despliegas Lemon, usa una copia archivada o `docs/ejemplo-servidor-licencias/`.

---

## Flujo de `translate-proxy.php` (archivo en `dist-server/` del repo)

1. Parsear JSON (o `$_POST`) y leer `license_key`, `texts`, `target_lang`, `source_lang`, `google_format`.
2. Validar licencia activa y saldo **> 0** (comprobación simple; el descuento es por caracteres enviados tras éxito).
3. Llamar a **Google v2** en un único POST con array `q` = `texts`, `format` = `text` o `html`.
4. Si Google falla: responder error JSON **sin** descontar saldo en este script.
5. Si Google OK: aplicar glosario UI a cada cadena, **descontar** `total_balance` por la suma de caracteres de `texts`, responder **200** con `translations`, `balance_remaining`, `request_id`.

Para un flujo **atómico** (reservar saldo antes de Google + reembolso si falla + tablas `dx_usage_events` / `dx_usage_daily`), usa la variante documentada en **`docs/ejemplo-servidor-licencias/translate-proxy.php`** como referencia de implementación extendida.

---

## Webhook Lemon Squeezy (solo legado / archivos propios)

El **`dist-server/`** de referencia en este repositorio **ya no incluye** `lemon-webhook.php` (eliminado en v2.0.9). Si necesitas Lemon, conserva tu propio despliegue o parte de **`docs/ejemplo-servidor-licencias/`**.

---

## Webhook Polar (producción de referencia)

- **Secreto:** `POLAR_WEBHOOK_SECRET` (o `polar_webhook_secret` en `config.php`).
- **Proveedor activo:** `BILLING_PROVIDER=polar` para ejecutar lógica Polar de forma explícita.
- **Mapa producto->saldo:** `POLAR_BALANCE_BY_PRODUCT_ID_JSON` (JSON) o `polar_balance_by_product_id` (array) en `config.php`.
- **Reglas DTP por producto:** `POLAR_PRODUCT_CONFIG` (env) o `polar_product_config` (array en `config.php`), ejemplo:
  `{"ID_PRODUCTO_INICIAL":{"balance":120000,"days":365,"type":"initial"},"ID_PRODUCTO_RENOVACION":{"balance":120000,"days":365,"type":"renewal"},"ID_BONO_EXPANSION":{"balance":1000000,"days":0,"type":"topup"}}`
- **Metadata recomendada en checkout:** `metadata[license_key]` (o `metadata[license_id]`) y `metadata[client_url]`.

URL típica de despliegue:  
`https://api.digixop.com/polar-webhook.php`

---

## Relación con el plugin WordPress

- **Activación de licencia en el cliente:** el plugin (`includes/class-digixop-translator-license.php`) llama a **`activate-license.php`** (URL por defecto en `traductor-digixop-pro.php`). El servidor responde con JSON compatible con la UI (saldo, caducidad, errores de dominio, etc.). El billing que alimenta `dx_licenses` en producción de referencia es **Polar** (`polar-webhook.php`).
- **Traducción DTL:** el plugin envía la misma **clave de licencia** que el usuario activó; el proxy valida contra **`dx_licenses`**. El plugin puede enviar **menos** segmentos si parte ya está en **memoria de traducción** local (`{prefijo}dx_translations_cache`); el proxy solo factura lo recibido.

---

## Diferencia respecto a `docs/ejemplo-servidor-licencias/`

La carpeta **`docs/ejemplo-servidor-licencias/`** contiene variantes de ejemplo (API `action=validate`, JSON de demo, generadores de clave, etc.).  
Para **producción Digixop** en api.digixop.com se usa **`dist-server/`** como referencia única de archivos y esquema **`dx_*`**.

---

## Lecturas relacionadas

- [API-SAAS.md](./API-SAAS.md) — Contrato HTTP visto desde el plugin.
- [LICENCIAS.md](./LICENCIAS.md) — Estado de licencia en WordPress.
- [COMERCIALIZACION-PLUGIN.md](./COMERCIALIZACION-PLUGIN.md) — Modelo de venta y operación.