Estados, soporte y recuperación
La web confirma la recepción del registro en el servicio. Para comprobar entrega o importación en BC, el operador consulta los metadatos del mismo receiptId. El recibo por sí solo no es una credencial y no permite leer datos de huéspedes.
Estados de entrega
state |
Significado | Acción |
|---|---|---|
held |
Registro anterior a la migración de outbox, retenido para revisión | Aprobar y liberar individualmente mediante retry |
pending |
Espera de entrega o de un nuevo intento | Comprobar que BC está habilitado, tiene ruta y llegó nextAttemptAt |
processing |
Worker con lease activo de cinco minutos | Esperar; tras caída el lease caducado permite recuperación |
blocked |
Error permanente o destino cambiado | Corregir causa y programar retry; no modificar el payload |
inbox_received |
BC guardó el recibo; todavía Pending |
Importar desde Guest Check-in Inbox; el servicio vuelve a consultar |
import_error |
BC informa Error al importar |
Corregir/reintentar en BC y luego solicitar revisión al servicio |
imported |
BC informa importación de negocio completada | Terminal; verificar la referencia en la bandeja BC |
No confundir state del servicio con importStatus de BC (Pending, Error, Imported). El errorCode de metadatos del servicio informa errores de transporte/entrega; el código de fallo del adapter se consulta en la bandeja de BC.
El worker toma entradas pendientes con bloqueo FOR UPDATE SKIP LOCKED, libera la transacción antes de llamadas HTTP y solo confirma el resultado si conserva el identificador de su lease. Un proceso antiguo no puede sobrescribir la confirmación de otro. Los recibos nuevos generan outbox aunque la entrega esté apagada.
Consultar un recibo
Desde una terminal autorizada, con el secreto administrativo del entorno ya configurado:
$api = 'https://api.example.com'
$site = 'las-torres'
$receiptId = '<UUID-del-recibo>'
$headers = @{ 'X-Checkin-Admin-Token' = $env:CHECKIN_ADMIN_TOKEN }
Invoke-RestMethod -Uri "$api/v1/checkin/sites/$site/deliveries/$receiptId" -Headers $headers
La respuesta tiene receiptId, state, attempts, nextAttemptAt, errorCode, receivedAt, importStatus y bcSystemId. No incluye huésped, documento, payload, token ni credenciales. attempts también aumenta al consultar un recibo conocido; no cuenta exclusivamente inserciones POST en BC. receivedAt indica cuándo el servicio confirmó la recepción en BC.
GET /deliveries devuelve hasta 100 entradas ordenadas por nextAttemptAt descendente, sin filtros ni paginación. No es un historial completo ordenado por alta del huésped: para localizar un caso usa el endpoint del recibo. La consulta de un recibo inexistente o de otro sitio devuelve 404 delivery_not_found.
Reintentar o liberar histórico
Tras revisar causa, sitio y destino:
Invoke-WebRequest -Method Post -Uri "$api/v1/checkin/sites/$site/deliveries/$receiptId/retry" -Headers $headers
204 programa el trabajo; no confirma importación ni espera a BC. Admite held, blocked, pending, inbox_received e import_error. Un recibo desconocido, processing o imported devuelve 409 delivery_not_retryable. Conserva payload, recibo BC y destino capturado.
Si ya hay recibo BC conocido, retry consulta estado y no reinserta. Un import_error no se arregla pulsando retry únicamente en el servicio: corrige el adapter y ejecuta Import / Retry en BC, luego programa la consulta. Sin revisión explícita, import_error no entra en el polling automático de inbox_received.
Los recibos de bandeja pendientes se consultan cada cinco minutos. Una operación está limitada a 100 segundos, con timeout HTTP de 30 segundos hasta cabeceras y cuerpos limitados a 128 KiB. Fallos temporales de red/timeout/408/429/5xx usan espera exponencial con variación aleatoria; Retry-After se respeta hasta un día. Un 401 invalida el token OAuth en caché y reintenta; vigila fallos persistentes de credenciales. No se guarda el cuerpo de error remoto en metadatos ni logs del módulo.
Cambio de destino BC
El primer intento fija una huella de tenant, entorno, empresa y versión API. Cambiar ese destino para un recibo ya intentado produce blocked con bc_route_changed. La rotación de credenciales en el mismo destino es diferente y no cambia esa huella.
No borres la huella ni uses retry esperando reenviar a otra empresa. Restaura la ruta original o prepara una migración revisada tras comprobar la existencia y estado del recibo en ambas empresas. De lo contrario puede duplicarse una importación o entregarse información al destino incorrecto.
Incidencias frecuentes
| Síntoma | Comprobación / recuperación |
|---|---|
/health funciona, rutas check-in devuelven 404 |
Revisión de backend correcta y CHECKIN_ENABLED=true; la salud no prueba que el módulo esté activo |
| API no arranca tras activar | Conexión/permisos de migración, zona horaria, sitios y formato/rutas BC; si activaste BC sin rutas válidas, corrige o deja entrega apagada |
| Web muestra sitio no disponible | Coincidencia exacta entre marca frontend, URL y CHECKIN_SITE_SLUGS |
| Web intenta llamar a localhost en un móvil | Nueva build con URL API pública o proxy mismo origen; localhost es el teléfono |
| CORS o respuesta HTML | Origen exacto de web, HTTPS, proxy /v1, URL incrustada y headers; /v1 no debe devolver index.html |
| Enlace pierde token al recargar | Comportamiento de memoria; reabrir el original. Si hubo envío incierto, conciliar antes de volver a registrar |
reservation_exists después de un timeout de provisión |
Token de primera respuesta no recuperable actualmente; no crear otro cupo cambiando referencia |
| Resultado de huésped incierto | Mantener página abierta y reintentar el envío capturado; no crear otro UUID |
pending no avanza |
BC apagado, sitio sin ruta, próxima fecha aún futura, worker detenido o error de conectividad |
bc_authentication_failed o HTTP 401 |
Tenant/client ID/valor y caducidad del secreto, consentimiento y autorización de aplicación en BC |
bc_http_403, bc_http_404 o rechazo permanente |
Permisos de empresa, app instalada, entorno/company ID y ruta de API; el código preciso depende de la respuesta |
bc_receipt_conflict o bc_invalid_response |
Comprobar coincidencia de recibo/sitio/versión/hash/SystemId y JSON; no dar por recibido por un simple 2xx |
BC queda Pending, adapter_not_configured |
Implementar/publicar el suscriptor real y ejecutar Import / Retry |
BC queda Error, business_import_failed |
Revisar adapter/permisos/reglas de negocio; las escrituras de ese intento se revierten |
En soporte utiliza sitio, recibo, momento, código seguro y X-Trace-Id; no pegues nombres, documentos, tokens o cuerpos completos en tickets públicos. La API administrativa no permite recuperar una persona por su documento ni reconstruir un intento perdido del navegador.
Retirada y rollback
Para detener solo exportaciones, establece CHECKIN_BC_ENABLED=false y redespliega el backend. Los nuevos registros siguen guardándose con outbox pending. Si el backend se detiene durante un intento, el lease permite recuperación posterior y BC podría haber recibido ya el registro: no deduzcas ausencia por interrupción local.
Para cerrar también la entrada pública, retira los enlaces web o publica un aviso y desactiva CHECKIN_ENABLED; al reiniciar no se registran rutas/contexto ni se aplican migraciones check-in. Conserva la base y sus backups para conciliación y reactivación. No borres esquema, recibos, tokens/hash, huellas ni volúmenes como procedimiento de rollback.
Antes de volver a una imagen anterior, verifica compatibilidad con la base migrada y las firmas del host compartido en un entorno de ensayo. Para restaurar la web conserva el artefacto anterior y su URL API de compilación. Retirar fuentes/imagen no revierte personas ya importadas en BC; cualquier corrección necesita el proceso de negocio acordado.
Evidencia de pruebas y pendientes
Las fuentes incluyen pruebas de backend y web. Los registros de trabajo del 23 de octubre de 2026 informan 180 pruebas backend superadas y seis PostgreSQL omitidas, 33 pruebas unitarias web, build TypeScript/Vite y escenarios de navegador con respuestas simuladas. Esta documentación no vuelve a ejecutar ni convierte esa evidencia en validación de producción.
Para comprobar el backend desde la raíz:
dotnet test backend.sln
# Solo contra una base dedicada de prueba, nunca producción:
$env:CHECKIN_TEST_DATABASE_URL = 'Host=127.0.0.1;Database=baltoya_checkin_tests;Username=postgres;Password=<test-password>'
dotnet test backend.sln --filter FullyQualifiedName~CheckIn
La base de integración debe terminar en _checkin_tests. Las pruebas usan conexiones independientes para concurrencia; SQLite y mocks no prueban los bloqueos PostgreSQL. Desde checkin-web/, npm test y npm run build comprueban unidad/tipos/build. Sus scripts de navegador están descritos en checkin-web/README.md y requieren Vite y Playwright disponibles.
Siguen pendientes el PostgreSQL real de destino, la compilación/runtime AL con símbolos del cliente, el adapter de negocio, entrega en sandbox, dispositivos físicos y el despliegue productivo. Para check-in no hay afirmación de certificación de accesibilidad ni cumplimiento normativo; acuerda privacidad, retención, acceso, documentos de menores y reporting oficial con el establecimiento.