- 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>
5.1 KiB
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:
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
POST https://penasquito.wotbi.com/api/v1/dc3/competencies/passports/search/
Content-Type: application/json
Authorization: Token <token>
Cuerpo:
{ "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
{
"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:
{
"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
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
{
"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
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.
{
"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
- POST
/search/con el passport. - Si
status === "completed"→ usarresult. - Si
status === "pending"→ guardarticket_idy hacer GET/result/<ticket_id>/cada ~2 s hastastatus === "completed". - 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→ bloquepenasquito_dc3(base_url, rutas, timeout, intervalos de polling).