Saltar al contenido principal

Localizacion y Pais (LATAM)

La plataforma opera para paises de LATAM hispanohablante. En primer acceso se sugiere pais por IP, pero el usuario siempre puede elegir manualmente.

1. Flujo UX​

  1. Deteccion automatica (GeoIP o CF-IPCountry).
  2. Confirmacion de pais detectado si pertenece a catalogo soportado.
  3. Selector manual obligatorio cuando no hay deteccion valida.
  4. Persistencia en perfil autenticado y cookie/localStorage para anonimos.
  5. Propagacion en requests con X-Country-Code.

2. Fuente unica de paises y niveles​

  • El selector se alimenta de /api/v1/meta/countries (solo enabled=true).
  • Los niveles geograficos se alimentan de /api/v1/meta/location-levels?country_code=XX.
  • Ambos endpoints salen del mismo catalogo admin (Catalogs), no de listas estaticas en frontend.

3. Estrategia multi-pais para niveles​

Modelo tecnico fijo:

  • level=0, node_type=country
  • level=1, node_type=region
  • level=2, node_type=locality

Modelo visual por pais:

  • GT: Region = Departamento, Localidad = Municipio
  • MX: Region = Estado, Localidad = Municipio
  • AR: Region = Provincia, Localidad = Municipio/Partido

Conclusión: no se crean columnas por pais; se usa metadata de labels por pais.

4. Contrato API esperado​

  • GET /api/v1/meta/countries
  • GET /api/v1/meta/location-levels?country_code=XX
  • POST /api/v1/admin/catalogs/geo/countries
  • POST /api/v1/admin/catalogs/geo/departments
  • POST /api/v1/admin/catalogs/geo/departments/bulk
  • POST /api/v1/admin/catalogs/geo/municipalities
  • POST /api/v1/admin/catalogs/geo/municipalities/bulk
  • PATCH /api/v1/admin/catalogs/geo/{id}
  • DELETE /api/v1/admin/catalogs/geo/{id} (solo sin hijos/referencias)

5. Reglas de negocio​

  • country_code debe ser ISO 3166-1 alpha-2.
  • Si un pais pasa a enabled=false, el usuario debe reconfirmar pais en siguiente sesion.
  • No bloquear por mismatch de IP cuando usuario selecciona manualmente un pais soportado.

6. Seguridad y privacidad​

  • GeoIP solo para sugerencia; no persistir IP en perfil.
  • Registrar eventos: country_detected, country_confirmed, country_changed, country_rejected.
  • Validar X-Country-Code contra whitelist en backend.

7. QA minimo​

  • IP soportada -> preseleccion y continuar.
  • IP no soportada -> selector manual obligatorio.
  • Cambio manual de pais -> se actualiza X-Country-Code en siguiente request.
  • Usuario autenticado -> pais de perfil prevalece sobre cookie.