Brief – Backend WhatsApp (Cloud API Meta) para Check-In / Check-Out multi-empresa 1) Objetivo Desarrollar un backend en PHP/Laravel en whatsapp.timhr.es que gestione la mensajería de WhatsApp usando WhatsApp Cloud API de Meta (Graph API), para que usuarios registrados puedan hacer Check-in / Check-out con botones, y que el sistema llame al backend correspondiente de cada empresa (https://xxxx.timhr.es/api). Importante: no se usará Twilio ni pasarelas/BSP. Integración directa con WhatsApp Cloud API. 2) Concepto general El usuario escribe cualquier mensaje por WhatsApp (“hola”, “fichar”, etc.). El backend identifica al usuario por su número de teléfono (E.164). Cada usuario tiene configurado manualmente un api_base_url (ej. https://empresa1.timhr.es/api) porque cada empresa tiene su propio backend. El backend consulta a esa API el último registro del usuario (IN/OUT). Según el estado, responde con un botón único: Si el último estado es OUT → mostrar botón Entrar Si el último estado es IN → mostrar botón Salir Al pulsar el botón: Entrar → llamar a check_in en el backend empresa y devolver confirmación + botón contrario. Salir → llamar a check_out en el backend empresa + llamar a worked_time y devolver confirmación + “Has trabajado Xh Ym” + botón informativo con ese texto (“ Has trabajado Xh Ym”). 3) Requisitos funcionales (casos) 3.1 Usuario no registrado Si el teléfono no existe en BD o está inactivo → responder: “Tu número no está registrado. Contacta con administración.” 3.2 Usuario registrado (flujo normal) Usuario escribe cualquier texto. Backend obtiene su api_base_url. Backend llama a la API empresa para obtener last_status (IN/OUT + timestamp). Responde por WhatsApp con mensaje + botón correcto (Entrar o Salir). Usuario pulsa botón: Entrar → se ejecuta check_in y se confirma. Salir → se ejecuta check_out, luego worked_time, se confirma y se muestra tiempo trabajado. 3.3 Respuestas esperadas (ejemplos) Check-in OK: “Check-in registrado a las 08:12. Último estado: IN.” Botón: “ Salir” Check-out OK: “ Check-out registrado a las 17:05. Hoy has trabajado: 8h 53m.” Botón informativo: “ Has trabajado 8h 53m” (y opcionalmente botón “ Entrar” para el próximo fichaje) 4) Requisitos de integración con APIs xxxx.timhr.es/api Los endpoints exactos y payloads se entregarán en documentación, pero el sistema debe soportar: GET last_status (último estado IN/OUT del usuario) POST check_in POST check_out GET worked_time (tiempo trabajado; puede ser del día o del último turno según doc) Condición clave: El base_url es dinámico por usuario (api_base_url). Autenticación: Puede ser por token/cabecera o lo que indique la documentación. Debe ser configurable por usuario (o por empresa si se decide agrupar más adelante). 5) Datos / Base de datos (mínimo viable) Se requiere una BD propia en whatsapp.timhr.es. Tabla wa_users id phone_e164 (único) api_base_url (string) api_token (nullable, si aplica) active (boolean) timestamps Tabla wa_processed_messages (idempotencia) id provider_message_id (único) timestamps Objetivo: evitar dobles fichajes si WhatsApp reintenta el webhook. Alta/baja de usuarios: manual vía panel admin (CRUD simple). 6) WhatsApp Cloud API (Meta) Webhook Endpoint: POST /webhooks/whatsapp Implementar verificación de webhook (challenge) según Meta. Parsear: Mensajes de texto Respuestas a botones (interactive reply) Envío de mensajes Enviar mensajes interactivos con reply buttons (máx 3). Usar Graph API con token configurado en .env. Respetar ventana de 24h: el usuario normalmente inicia, por lo que la respuesta es válida sin templates. 7) Estructura técnica sugerida (Laravel) WhatsAppWebhookController (recepción webhook, verificación, parseo) Servicios: UserResolver (normaliza teléfono y busca usuario en wa_users) CompanyApiClient (HTTP client con api_base_url dinámico) AttendanceOrchestrator (lógica de estado → botones → llamadas check_in/out → worked_time) WhatsAppSender (envío de mensajes y botones con Graph API) Logging: Loggear teléfono, action, api_base_url, status, errores. Timeouts / errores: Si la API empresa falla, responder: “No he podido fichar ahora. Inténtalo más tarde.” 8) Panel admin (mínimo) CRUD básico (puede ser Laravel Breeze/Nova/Filament o simple): Alta usuario: teléfono + api_base_url (+ token si aplica) Editar usuario Desactivar usuario 9) Entregables Código fuente del backend whatsapp.timhr.es. Webhook operativo con WhatsApp Cloud API. Envío de botones (Entrar/Salir) y respuestas completas. Integración dinámica con api_base_url por usuario. Panel admin para gestión de usuarios. Idempotencia (no duplicar por retries) + logs. Instrucciones de despliegue (env vars, configuración de webhook en Meta). 10) Criterios de aceptación (tests) Teléfono no registrado → devuelve mensaje de no registrado. Teléfono registrado con last_status OUT → muestra botón “ Entrar”. Pulsar “ Entrar” → ejecuta check_in → confirma → muestra botón “Salir”. Teléfono registrado con last_status IN → muestra botón “ Salir”. Pulsar “ Salir” → ejecuta check_out → obtiene worked_time → muestra “Has trabajado Xh Ym” + botón informativo con ese valor. Reenvío del mismo webhook (mismo message_id) → no duplica fichaje.