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

5.1 KiB
Raw Blame History

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

  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).