certimine/docs/mobiliseme-api.md
remaster ff0fd6a89d API Peñasquito: ticket persistente, company y mejor flujo de búsqueda
- Renombrado «DC3» a «API Peñasquito» (URL base del documento) en UI/docs;
  rutas y claves de config conservadas por compatibilidad.
- Persistencia de ticket_id en nueva tabla `penasquito_tickets`:
  POST /search/ guarda el ticket y los siguientes requests retoman
  GET /result/<ticket_id>/ sin reencolar.
- Polling acotado por request HTTP (~6 s) con `PenasquitoPendingException`
  y caja «reintentar» en lookup; ticket queda válido 1 h.
- `users_cache.company` nuevo (con migración idempotente); persistResult
  guarda empresa + competencias en transacción y aplica source distinto.
- Mensajes HTTP específicos (400/401/403/404/408/429/5xx) y `/` final
  forzado en rutas (DRF), FOLLOWLOCATION habilitado.
- Vista de perfil muestra «Empresa» y aviso cuando no hay competencias.
- Auth::login evita doble fetch cuando ya tenemos el `result` del API.
- i18n ES/EN actualizados; lookup_pending_*; limpieza de archivos lang.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-13 19:43:37 -06:00

162 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# API REST Peñasquito (Wotbi) — tres endpoints principales — CertiMine
Este documento refleja el contrato descrito en el PDF de proceso (p. ej. `DatosPdf.txt` / `docs/DatosPdf.example.txt`). CertiMine consume **solo** estos tres endpoints sobre la URL base; el scraping de Mobilise-Me ocurre **en el servidor Wotbi**, no en el navegador del usuario.
**No versionar tokens.** Usar `CERTIMINE_PENASQUITO_TOKEN`, `config.php` (`penasquito_dc3.static_token`) o `config/token.php`.
---
## 1.1 Autenticación
Todas las peticiones requieren un header de autorización con un **token estático** entregado por canal privado:
```http
Authorization: Token <token>
```
Petición sin header o con token inválido → **HTTP 401**.
En CertiMine el valor se resuelve en este orden: `CERTIMINE_PENASQUITO_TOKEN` → `CERTIMINE_DC3_TOKEN` (alias) → `penasquito_dc3.static_token` → `config/token.php`.
---
## 1.2 Endpoint 1 — Crear solicitud de búsqueda
```http
POST https://penasquito.wotbi.com/api/v1/dc3/competencies/passports/search/
Content-Type: application/json
Authorization: Token <token>
```
**Cuerpo:**
```json
{ "passport": "E000055821" }
```
**Comportamiento:** La API valida el passport, **encola** la tarea de scraping y responde de inmediato con un **ticket**. El scraping corre en segundo plano.
### Respuesta estándar encolada
```json
{
"status": "pending",
"ticket_id": "2cf364bebf16",
"posicion": 1
}
```
El cliente debe **guardar `ticket_id`** y consultar el endpoint 1.3 hasta que termine el trabajo.
### Respuesta con caché (última hora, mismo passport)
Si ya se consultó ese passport en la ventana de caché (~1 h), la API devuelve **directamente** el resultado **sin encolar**:
```json
{
"status": "completed",
"result": {
"passport": "E000055821",
"name": "…",
"company": "…",
"competencies": [
{
"activity": "FRM - CONFINED SPACES",
"request_date": "30/07/2025",
"expiration_date": null,
"status": "Received"
}
],
"error": null
}
}
```
**Recomendación:** siempre llamar primero a este endpoint; si `status === "completed"` usar `result`; si `status === "pending"` hacer *polling* en 1.3.
---
## 1.3 Endpoint 2 — Estado y resultado del ticket
```http
GET https://penasquito.wotbi.com/api/v1/dc3/competencies/passports/result/<ticket_id>/
Authorization: Token <token>
```
**Comportamiento:** Devuelve el estado del ticket. Mientras el worker no termina, `status` puede ser **`pending`** o **`processing`**. Al terminar, `status` es **`completed`** y viene el objeto **`result`**.
### Ejemplo completado
```json
{
"status": "completed",
"result": {
"passport": "E000055821",
"name": "…",
"company": "…",
"competencies": [ … ],
"error": null
}
}
```
### Estructura de `result`
| Campo | Descripción |
|--------|-------------|
| `passport` | Passport consultado. |
| `name` | Nombre (extraído del portal por el backend). |
| `company` | Empresa. |
| `competencies` | Lista de ítems con `activity`, `request_date`, `expiration_date` (puede ser `null`), `status`. |
| `error` | `null` si todo bien; si hubo fallo (sesión, passport no encontrado, etc.) trae mensaje y `competencies` puede ir vacío. CertiMine rechaza estos casos vía excepción para mostrar el mensaje al usuario. |
---
## 1.4 Endpoint 3 — Estado de la cola
```http
GET https://penasquito.wotbi.com/api/v1/dc3/competencies/passports/status/
Authorization: Token <token>
```
**Monitoreo / health:** estado de la cola (p. ej. Redis) y si el worker está ocupado.
```json
{
"queue_length": 0,
"processing": false
}
```
| Campo | Significado |
|--------|-------------|
| `queue_length` | Tickets esperando procesamiento. |
| `processing` | `true` si el worker está ejecutando un scraping ahora. |
En PHP: `PenasquitoDc3Api::queueStatus()`.
---
## 1.5 Caché de resultados (lado servidor)
Los resultados exitosos se guardan en caché **~1 hora** por passport. Durante ese tiempo, una nueva solicitud del mismo passport responde al instante con datos cacheados y **no encola** trabajo nuevo.
---
## 1.6 Flujo recomendado del cliente
1. **POST** `/search/` con el passport.
2. Si `status === "completed"` → usar `result`.
3. Si `status === "pending"` → guardar `ticket_id` y hacer **GET** `/result/<ticket_id>/` cada **~2 s** hasta `status === "completed"`.
4. Presentar `result.competencies` (y demás campos según la UI).
Tiempo típico sin caché: **unos 5–15 s**, según carga del portal externo. Por eso en `config.example.php` se configuran `poll_interval_seconds` y `poll_max_attempts` con margen.
**Implementación en CertiMine:** `PenasquitoDc3Api::fetchResultForPassport()` (búsqueda + *polling*).
---
## Otros
- **Webhook CertiMine** (`public/api/webhook.php`): distinto; sincronización desde otros sistemas.
- **Configuración PHP:** `config/config.example.php` → bloque `penasquito_dc3` (`base_url`, rutas, timeout, intervalos de *polling*).