Repositorio y runtime

• Referencia local revisada: ips-lacpass-backend.
• El stack backend incluye IPS Lacpass API, Keycloak, PostgreSQL y MailCatcher.
• Herramientas requeridas: Docker. Go 1.24 solo es necesario si se ejecuta la API sin Docker. JQ solo es necesario para scripts helper.
• Puertos por defecto del README: API http://localhost:9081, Keycloak http://localhost:9083, Swagger UI http://localhost:9999, MailCatcher HTTP http://localhost:1080.

cp .env.sample .env
docker compose up
docker compose up --detach
docker compose down
docker compose up swagger-ui

Checklist de variables backend

• API_PORT controla el puerto del contenedor API. El sample usa 3000 internamente y expone la API mediante el puerto host definido en compose.
• KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID y KEYCLOAK_ADMIN_CLIENT_SECRET deben coincidir con la configuración de realm/client en Keycloak.
• KC_BOOTSTRAP_ADMIN_USERNAME y KC_BOOTSTRAP_ADMIN_PASSWORD se usan para la consola admin de Keycloak.
• KEYCLOAK_DEFAULT_USER y KEYCLOAK_DEFAULT_USER_PASSWORD se usan por scripts/auth.sh para solicitar tokens.
• FHIR_BASE_URL, FHIR_MEDIATOR_BASE_URL, VHL_BASE_URL e ICVP_VALIDATOR_URL deben apuntar a los servicios participantes usados por el backend.
• La integracion de wallet usa WALLET_ENABLED, WALLET_URL, WALLET_IDENTIFIER y WALLET_API_KEY.

Configuración de Keycloak

• Abrir Keycloak en http://localhost:9083 e iniciar sesion con KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD.
• Usar el realm lacpass creado por el import.
• Habilitar autenticación en el client admin-cli, copiar el client secret y configurar KEYCLOAK_ADMIN_CLIENT_SECRET en .env.
• Asignar service account roles a admin-cli para que el backend pueda registrar usuarios y ejecutar operaciones contra Keycloak.
• Crear un usuario de prueba en el realm lacpass y completar campos requeridos; si faltan, la obtención de token puede fallar con invalid_grant / Account is not fully set up.
• Para pruebas locales con HTTP o IP, configurar Frontend URL del realm. Para acceso desde emulador Android, usar 10.0.2.2 en vez de localhost.

docker compose up auth auth-db
sh scripts/auth.sh access-token
sh scripts/auth.sh refresh-token
sh scripts/auth.sh logout

Documentacion API y smoke checks

• La especificacion OpenAPI vive en api/openapi/api.yaml.
• Ejecutar el contenedor Swagger UI y abrir http://localhost:9999 para inspeccionar endpoints.
• Los endpoints protegidos requieren un JWT válido de Keycloak. Usar scripts/auth.sh después de crear/configurar un usuario de prueba.

curl -X POST "${APP_BACKEND_URL}/users" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"document_type":"passport","email":"patient@example.org","first_name":"Test","identifier":"PATIENT-001","last_name":"Patient","locale":"en","password":"ChangeMe123!","password_confirm":"ChangeMe123!"}'

curl -X GET "${APP_BACKEND_URL}/ips" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

curl -X POST "${APP_BACKEND_URL}/qr" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{"content":"{}","expires_on":"2026-12-31T23:59:59","pass_code":"0000"}'