# 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 ``` 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 ``` **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// Authorization: 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 ``` **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//` 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*).