service-finder/docs/kyc_eu_smart_address_implementation.md

KYC Wizard EU-Ready Smart Address Implementation

Overview

Enhanced the CompleteKycView.vue Step 2 (Address) with an EU-ready country selector and smart ZIP→City auto-fill using the zippopotam.us public API.

Changes Made

1. Frontend: frontend/src/views/CompleteKycView.vue

Template Changes (Step 2 - Address)

• Country selector added as the first field in Step 2 — a <select> bound to kycForm.region_code with options: HU, AT, SK, DE, RO (with flag emojis)
• City field now has a relative wrapper with a loading spinner (animated SVG) that appears when isCityLoading === true
• City input gets opacity-60 class during loading for visual feedback

Script Changes

• Import: Added watch from Vue
• New ref: isCityLoading (boolean, default false)
• Form state: Added region_code: 'HU' to kycForm reactive object
• Debounced watch on address_zip:
  • Clears previous timeout on each keystroke
  • Triggers only when ZIP length >= 3
  • 600ms debounce delay
  • Calls https://api.zippopotam.us/{country}/{zip} using the selected region_code
  • On success, auto-fills kycForm.address_city from data.places[0]['place name']
  • Error handling with console.error (silent fail, user can still type city manually)
  • isCityLoading reset in finally block
• Submit payload: Added region_code: kycForm.region_code to the API call

2. Backend Schema: backend/app/schemas/auth.py

• Added region_code: Optional[str] = "HU" to UserKYCComplete Pydantic model

3. Backend Service: backend/app/services/auth_service.py

• In complete_kyc(): Added if kyc_in.region_code: user.region_code = kyc_in.region_code to persist the selected country code to the user record

Data Flow

1. User selects country (default: HU) → kycForm.region_code
2. User types ZIP code → debounced 600ms → fetch(zippopotam.us/{country}/{zip})
3. If found → address_city auto-filled; if not → silent fail, manual entry
4. On submit → region_code sent in payload → backend updates users.region_code

EU Countries Supported

Code	Country
HU	Magyarország
AT	Ausztria
SK	Szlovákia
DE	Németország
RO	Románia

API Reference

• zippopotam.us: Free, no API key required. Returns JSON with places[] containing place name, state, etc.
• Endpoint format: https://api.zippopotam.us/{country_code}/{zip_code}