- 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>
162 lines
5.1 KiB
Markdown
162 lines
5.1 KiB
Markdown
# 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*).
|