View source for Module DoliPostal

= Module DoliPostal =

{| class="wikitable"
|-
! Nom du module
| DoliPostal
|-
! Éditeur
| InCréation
|-
! Statut
| Stable
|-
! Version
| 1.0.2
|-
! Identifiant du module
| 207621
|-
! Compatibilité
| Dolibarr 17 à 24
|-
! Licence
| GNU GPL v3 ou ultérieure
|-
! Langues
| Français et anglais
|}

== Présentation ==

DoliPostal ajoute une assistance à la saisie des adresses françaises dans les champs natifs de Dolibarr.

Après la saisie d’un code postal français à cinq chiffres, le module recherche les communes correspondantes. L’utilisateur peut sélectionner la commune souhaitée et, si l’option est activée, DoliPostal renseigne automatiquement le champ natif « Département / Canton ».

Le module ne modifie aucun fichier du cœur de Dolibarr et n’ajoute aucun champ métier propriétaire.

== Fonctionnalités ==

* Recherche des communes à partir d’un code postal français à cinq chiffres.
* Proposition de toutes les communes correspondant au code postal.
* Sélection de la commune dans le champ natif « Ville ».
* Remplissage automatique optionnel du champ natif « Département / Canton ».
* Prise en charge de la Corse (2A et 2B).
* Prise en charge des départements et régions d’outre-mer.
* Conservation d’une ville déjà saisie.
* Possibilité de continuer à saisir une ville manuellement.
* Cache navigateur configurable afin de limiter les appels réseau.
* Messages explicites pendant la recherche ou si le service est indisponible.
* Interface disponible en français et en anglais.

== Écrans pris en charge ==

DoliPostal intervient sur les formulaires Dolibarr utilisant les champs natifs d’adresse, notamment :

* création et modification d’un tiers ;
* création et modification d’un contact ou d’une adresse ;
* autres formulaires natifs exposant un couple « Code postal / Ville » compatible.

Le module complète uniquement les champs présents sur le formulaire affiché.

== Prérequis ==

* Dolibarr 22.x ou 23.x.
* PHP 7.4 ou version ultérieure.
* Extension PHP cURL recommandée.
* Accès HTTPS sortant vers <code>geo.api.gouv.fr</code>.

== Installation ==

Télécharger <code>module_dolipostal-1.0.2.zip</code> depuis [https://www.dolistore.com/product.php?id=3311 DoliStore].

# Télécharger l’archive <code>module_dolipostal-1.0.1.zip</code>.
# Dans Dolibarr, ouvrir « Accueil > Configuration > Modules/Applications ».
# Utiliser l’outil de déploiement d’un module externe.
# Importer l’archive sans la décompresser manuellement.
# Rechercher puis activer le module « DoliPostal ».
# Ouvrir la page de configuration du module.

L’archive contient le répertoire <code>dolipostal/</code> à sa racine, conformément aux règles de conditionnement des modules externes Dolibarr.

== Configuration ==

La page de configuration permet de régler :

; Remplissage automatique du département
: Active ou désactive la mise à jour automatique du champ natif « Département / Canton » après la sélection d’une commune.

; Durée du cache
: Définit le nombre de jours pendant lesquels les résultats peuvent être conservés dans le navigateur afin de limiter les appels à l’API.

== Utilisation ==

# Ouvrir un formulaire Dolibarr contenant une adresse.
# Sélectionner « France (FR) » comme pays si le formulaire propose un pays.
# Saisir un code postal français complet à cinq chiffres.
# Attendre l’affichage de la liste des communes.
# Sélectionner la commune souhaitée.
# Vérifier le département proposé, puis poursuivre normalement la saisie du formulaire.

Lorsque plusieurs communes utilisent le même code postal, elles sont toutes proposées. La saisie manuelle de la ville reste possible.

== Confidentialité ==

DoliPostal utilise l’API géographique officielle française.

Seul le code postal à cinq chiffres est transmis à <code>geo.api.gouv.fr</code>. Le module ne transmet notamment pas :

* le nom du tiers ;
* le nom d’un contact ;
* l’adresse complète ;
* un numéro de téléphone ou une adresse électronique ;
* une référence de devis, commande, facture ou projet ;
* un identifiant de document métier.

Le module n’ajoute aucune table métier et ne modifie aucun document commercial.

== Fonctionnement en cas d’indisponibilité ==

Si l’API ne répond pas ou si la connexion HTTPS est indisponible :

* un message informe l’utilisateur ;
* les champs Dolibarr restent accessibles ;
* la ville et le département peuvent être saisis manuellement ;
* aucune donnée déjà saisie n’est supprimée.

== Désinstallation ==

La désactivation ou la désinstallation du module ne supprime aucune adresse et aucune donnée métier. DoliPostal utilisant les champs natifs de Dolibarr, les valeurs enregistrées restent disponibles.

== Support ==

Pour faciliter le diagnostic, indiquer :

* la version de Dolibarr ;
* la version de PHP ;
* le navigateur utilisé ;
* la version de DoliPostal ;
* le code postal ayant provoqué le problème ;
* le formulaire concerné.

Ne pas transmettre de données personnelles ni de document métier réel dans une demande de support.

== Informations techniques ==

* Nom technique : <code>dolipostal</code>
* Classe du module : <code>modDoliPostal</code>
* Identifiant Dolibarr : <code>207621</code>
* Version : <code>1.0.1</code>
* Modification du cœur Dolibarr : aucune
* Table métier ajoutée : aucune
* API utilisée : <code>https://geo.api.gouv.fr</code>

[[Category:Modules complémentaires]]
[[Category:DocUtilisateur]]
[[Category:DocUtilisateurFR]]