DOCS

Suggérer et valider des adresses

Complétez les adresses pendant la saisie de vos clients et confirmez une adresse avant d’y expédier.

GraphQL

Utilisez locationSuggest pour proposer des adresses complètes pendant la saisie d’un client, et locationValidate pour vérifier une adresse et la récupérer sous une forme normalisée. Lorsqu’une adresse est validée, vous pouvez transmettre le résultat à partyCreate ou partyCreateWorkflow afin que l’adresse soit enregistrée comme vérifiée.

Suggérer des adresses pendant la saisie 

Envoyez l’adresse partielle saisie par le client ainsi que le pays dans lequel effectuer la recherche. locationSuggest renvoie les adresses complètes correspondantes, dans le même format que l’entrée de localisation de partyCreate, ce qui vous permet de remplir le reste du formulaire d’adresse à partir de celle que le client sélectionne.

1query LocationSuggest($input: LocationSuggestInput!) {
2 locationSuggest(input: $input) {
3 line1
4 line2
5 locality
6 administrativeArea
7 administrativeAreaCode
8 postalCode
9 countryCode
10 latitude
11 longitude
12 }
13}

Champs d’entrée des suggestions

Champ↕Obligatoire↕Description↕
countryCodeLe code ISO 3166-1 alpha-2 du pays dans lequel effectuer la recherche.
limitLe nombre maximal de suggestions à renvoyer, de 1 à 20. Valeur par défaut : 10.
queryL’adresse partielle et libre saisie par le client, par exemple 22382 Avenida Emp.

Les suggestions constituent un point de départ, et non une adresse vérifiée. Validez l’adresse finalement retenue par le client avant de créer une partie avec celle-ci.

Valider une adresse 

Envoyez l’adresse complète à locationValidate. Le résultat indique le niveau de vérification de l’adresse, l’adresse sous sa forme normalisée et un verificationToken lorsque l’adresse est vérifiée.

1query LocationValidate($input: LocationValidateInput!) {
2 locationValidate(input: $input) {
3 status
4 verificationToken
5 address {
6 line1
7 line2
8 locality
9 administrativeArea
10 administrativeAreaCode
11 postalCode
12 countryCode
13 latitude
14 longitude
15 propertyType
16 }
17 }
18}

Champs d’entrée de la validation

Champ↕Obligatoire↕Description↕
administrativeAreaLe nom de l’État, de la province ou de la région.
administrativeAreaCodeLe code de l’État, de la province ou de la région, par exemple CA.
countryCodeLe code ISO 3166-1 alpha-2 du pays.
line1La première ligne de l’adresse.
line2 – line4Lignes d’adresse supplémentaires, le cas échéant.
localityLa ville, la commune ou le village.
postalCodeLe code postal.

Envoyez autant d’éléments de l’adresse que possible. Un code postal, ou une localité accompagnée d’une division administrative, donne les meilleurs résultats.

Statuts de validation

Statut↕Signification↕Étape suivante suggérée↕
VERIFIEDL’adresse a été vérifiée jusqu’au bâtiment ou jusqu’à l’unité exacte.Utilisez l’adresse normalisée.
PARTIALLY_VERIFIEDSeule une partie de l’adresse a été vérifiée, comme la rue ou la ville, mais pas le bâtiment.Demandez au client de vérifier des détails comme le numéro de rue ou d’unité.
UNVERIFIEDL’adresse n’a pas pu être vérifiée. address vaut null.Demandez au client de vérifier l’adresse.

L’adresse normalisée

Lorsque l’adresse est VERIFIED ou PARTIALLY_VERIFIED, address contient sa forme normalisée. Elle peut différer de ce que vous avez envoyé : des informations manquantes comme la ville peuvent être ajoutées, le code postal peut être complété, et les majuscules ainsi que les abréviations sont corrigées. Présentez l’adresse normalisée au client ou utilisez-la à la place de ce qu’il a saisi.

  • latitude et longitude sont incluses lorsqu’elles sont disponibles.
  • propertyType vaut RESIDENTIAL ou COMMERCIAL lorsque l’adresse est vérifiée et que son type est connu, et null dans le cas contraire. Il n’est pas appliqué automatiquement. Transmettez-le dans l’entrée de localisation lors de la création de la partie si vous souhaitez l’utiliser.

Enregistrer une adresse vérifiée sur une partie 

Un résultat VERIFIED inclut un verificationToken. Transmettez-le dans l’entrée location de partyCreate ou partyCreateWorkflow, avec l’adresse normalisée exactement telle que locationValidate l’a renvoyée. La localisation de la partie est alors enregistrée comme vérifiée, sans que l’adresse soit vérifiée à nouveau.

1mutation PartyCreate($input: PartyCreateInput!) {
2 partyCreate(input: $input) {
3 id
4 type
5 location {
6 id
7 line1
8 locality
9 administrativeAreaCode
10 postalCode
11 countryCode
12 propertyType
13 }
14 }
15}

Gardez ces règles à l’esprit lorsque vous transmettez un jeton :

  • Un jeton est valable un jour. Un jeton expiré est ignoré, et la partie est tout de même créée.
  • Les champs d’adresse doivent correspondre à l’adresse normalisée. Si le client modifie l’adresse après l’avoir validée, le jeton est ignoré et la partie est tout de même créée. Validez l’adresse modifiée pour obtenir un nouveau jeton.
  • latitude, longitude, propertyType et metadata peuvent être modifiés sans affecter le jeton.
  • Traitez le jeton comme une valeur opaque. Ne l’analysez pas et ne le modifiez pas. Un jeton altéré, ou émis pour une autre organisation, fait échouer la requête.

Erreurs 

Message↕Cause↕Que faire↕
Address verification is unavailableLes suggestions ou la validation n’ont pas pu aboutir pour le moment.Réessayez plus tard. Laissez le client continuer avec l’adresse qu’il a saisie.
Invalid location verification tokenLe verificationToken a été altéré ou a été émis pour une autre organisation.Transmettez le jeton exactement tel que locationValidate l’a renvoyé, ou omettez-le.
limit must be between 1 and 20La valeur de limit transmise à locationSuggest était hors de la plage autorisée.Transmettez une valeur de limit comprise entre 1 et 20, ou omettez-la pour obtenir 10 suggestions.
GraphQL API ReferenceTypes, inputs, and operations used in this guide
Réserver une démo

Cette page vous a-t-elle été utile?