certimine/docs/mobiliseme-api.md
remaster 84e94dcb55 seguridad: token DC3 vía env, config o config/token.php (gitignored)
- Elimina lectura del token desde DatosPdf; nuevo token.example.php y token.php ignorado.
- DatosPdf.txt deja de versionarse; docs/DatosPdf.example.txt con TOKEN redactado.
- Ajusta README, docs API, i18n y banderolas de consulta/diagnóstico previos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-13 18:49:11 -06:00

71 lines
3 KiB
Markdown

# API DC3 Peñasquito (Wotbi) — CertiMine
Fuente detallada del flujo: copia de trabajo sin secretos en [DatosPdf.example.txt](DatosPdf.example.txt). El archivo local **DatosPdf.txt** (si lo tienes) está en `.gitignore` y no debe contener el token en repositorios compartidos; use **`config/token.php`** o **`CERTIMINE_DC3_TOKEN`**.
## Autenticación
Todas las peticiones al API REST llevan un **token estático** entregado por canal privado:
```http
Authorization: Token <token>
```
Sin cabecera válida → **HTTP 401**.
En CertiMine el token se resuelve en este **orden**:
1. Variable de entorno **`CERTIMINE_DC3_TOKEN`** (recomendado en producción).
2. **`penasquito_dc3.static_token`** en `config/config.php`.
3. Archivo local **`config/token.php`** (copiar de `config/token.example.php`; está en **`.gitignore`**).
No leer el token desde documentación versionada. El ejemplo público del texto del PDF está en **`docs/DatosPdf.example.txt`** (línea del token redactada).
## Base URL
`https://penasquito.wotbi.com` (según la documentación en `docs/DatosPdf.example.txt`).
## Endpoint 1 — Crear solicitud de búsqueda
`POST /api/v1/dc3/competencies/passports/search/`
- `Content-Type: application/json`
- Body: `{ "passport": "E000055821" }`
- Respuesta si hay caché (~1 h): `status: "completed"` + `result` (name, company, competencies[]).
- Respuesta si encola: `status: "pending"` + `ticket_id` (+ opcional `posicion`).
## Endpoint 2 — Resultado del ticket (polling)
`GET /api/v1/dc3/competencies/passports/result/<ticket_id>/`
- Mientras trabaja el worker: `status` puede ser `pending` o `processing`.
- Al terminar: `status: "completed"` + `result`.
Flujo recomendado: llamar endpoint 1; si `pending`, consultar endpoint 2 cada pocos segundos hasta `completed` (implementado en `PenasquitoDc3Api::fetchResultForPassport`).
## Endpoint 3 — Estado de cola
`GET /api/v1/dc3/competencies/passports/status/`
- `queue_length`, `processing` — monitoreo / health.
## Estructura de `result`
| Campo | Uso |
|--------|-----|
| `passport` | ID consultado (coincide con búsqueda). |
| `name` | Nombre. |
| `company` | Empresa; CertiMine infiere contratista vs empleado con reglas heurísticas. |
| `competencies[]` | `activity`, `request_date`, `expiration_date` (null si no aplica), `status`. |
| `error` | Si no es null, mensaje de fallo. |
## Portal Mobilise-Me (scraping interno)
El documento describe además el login web (`testing.newmontpenasquito.mobilise-me.com`), cookies, CSRF, pas **`/Selection`** con `action=Administration Database`, etc. Eso lo ejecuta el **servidor** que alimenta el API anterior, no el navegador del usuario de CertiMine.
## Webhook CertiMine
CertiMine sigue aceptando `POST public/api/webhook.php` para sincronizar certificados desde otros sistemas (ver implementación). Es independiente del API Wotbi anterior.
## Configuración PHP
Rutas y tiempos de polling: `config/config.example.php` → sección `penasquito_dc3`.