Addresses

Les objets Address représentent des adresses postales associées à un Customer. Chaque Customer peut posséder plusieurs adresses (livraison, facturation) avec une adresse marquée comme adresse par défaut.

Cas d’usage typiques : pré-remplir le formulaire de livraison lors du checkout, afficher l’adresse de facturation sur les factures PDF, gérer un carnet d’adresses multi-sites.

Adresse par défaut

Lorsque vous créez une adresse avec is_default: true, l’adresse par défaut précédente est automatiquement déclassée. Un Customer ne peut avoir qu’une seule adresse par défaut à la fois.

Endpoints

Méthode	Endpoint	Description
POST	`/customers/{id}/addresses/`	Ajouter une adresse à un Customer
GET	`/customers/{id}/addresses/`	Lister les adresses d'un Customer
GET	`/customers/{id}/addresses/{addr_id}/`	Récupérer une adresse par son ID
PATCH	`/customers/{id}/addresses/{addr_id}/`	Modifier une adresse
DELETE	`/customers/{id}/addresses/{addr_id}/`	Supprimer définitivement une adresse

Cette introduction est-elle claire ?

Schéma de l’objet

ResponseObjet Address

Structure complète retournée par tous les endpoints de cette ressource.

json

{
  "id": "addr_xxxxxxxxxxxx",
  "object": "address",
  "customer": "cust_xxxxxxxxxxxx",
  "line1": "Boulevard Triomphal Omar Bongo",
  "line2": "Immeuble Les Arcades, 3ème étage",
  "city": "Libreville",
  "state": "Estuaire",
  "postal_code": null,
  "country": "GA",
  "is_default": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Ajouter une adresse

Crée une nouvelle adresse et l’associe au Customer identifié par {id} dans l’URL. L’adresse est immédiatement disponible pour être utilisée dans un CheckoutSession ou une Invoice.

POSTCorps de la requête

line1Requis

string

Première ligne d’adresse — numéro et nom de rue, boîte postale, etc. Visible par l’acheteur sur les reçus et factures PDF.

line2Optionnel

string

Complément d’adresse — bâtiment, étage, appartement, zone industrielle, etc.

cityRequis

stringex :Libreville

Nom de la ville. Affiché sur les documents de facturation et les étiquettes de livraison.

stateOptionnel

stringex :Estuaire

Province, région ou État. Optionnel pour les pays qui n’utilisent pas de subdivisions administratives dans les adresses postales.

postal_codeOptionnel

string

Code postal. Peut être null pour les pays d’Afrique centrale où le système postal ne l’exige pas.

countryRequis

stringISO 3166-1 alpha-2ex :GA

Code pays au format ISO 3166-1 alpha-2. Doit correspondre à un pays couvert par votre App.

Exemples : GA (Gabon), CG (Congo-Brazzaville), CM (Cameroun), CI (Côte d’Ivoire). Les codes à deux lettres majuscules sont obligatoires — les noms de pays en clair sont rejetés.

is_defaultOptionnel

booleandéfaut :false

Marque cette adresse comme adresse par défaut du Customer. Si une adresse par défaut existe déjà, elle est automatiquement déclassée.

L’adresse par défaut est pré-sélectionnée dans les formulaires de paiement hébergés par Sangho. Elle est aussi utilisée comme adresse de facturation dans les Invoices quand aucune adresse n’est explicitement spécifiée.

Les paramètres de l'adresse sont-ils clairs ?

Ajouter une adresse

bash

curl -X POST https://api.sangho.ga/v1/customers/cust_xxx/addresses/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "Boulevard Triomphal Omar Bongo",
    "line2": "Immeuble Les Arcades, 3ème étage",
    "city": "Libreville",
    "state": "Estuaire",
    "country": "GA",
    "is_default": true
  }'

Response201 Created

L'adresse est créée et associée au Customer. Si is_default était true, l'ancienne adresse par défaut a été automatiquement déclassée.

json

{
  "id": "addr_xxxxxxxxxxxx",
  "object": "address",
  "customer": "cust_xxxxxxxxxxxx",
  "line1": "Boulevard Triomphal Omar Bongo",
  "line2": "Immeuble Les Arcades, 3ème étage",
  "city": "Libreville",
  "state": "Estuaire",
  "postal_code": null,
  "country": "GA",
  "is_default": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Lister les adresses

Retourne toutes les adresses associées au Customer, triées par date de création décroissante. L’adresse par défaut apparaît en premier.

Modifier une adresse

Met à jour un ou plusieurs champs d’une adresse existante. Seuls les champs fournis sont modifiés.

PATCHCorps de la mise à jour (PATCH)

line1Optionnel

string

Nouvelle première ligne d’adresse.

line2Optionnel

string

Nouveau complément d’adresse. Passez null pour supprimer le champ.

cityOptionnel

string

Nouvelle ville.

stateOptionnel

string

Nouvelle province/région. Passez null pour supprimer.

postal_codeOptionnel

string

Nouveau code postal. Passez null pour supprimer.

countryOptionnel

stringISO 3166-1 alpha-2

Nouveau code pays ISO 3166-1 alpha-2.

is_defaultOptionnel

boolean

Passer true pour promouvoir cette adresse comme adresse par défaut. L’ancienne adresse par défaut est automatiquement déclassée.

Supprimer une adresse

Supprime définitivement l’adresse. L’action est irréversible.

Suppression définitive

Contrairement aux Products, la suppression d’une Address est un hard delete — elle ne peut pas être restaurée. Si l’adresse supprimée était l’adresse par défaut, aucune autre adresse n’est automatiquement promue : vous devrez en désigner une nouvelle via PATCH.

Les opérations sur les adresses sont-elles bien documentées ?

Lister les adresses

bash

curl "https://api.sangho.ga/v1/customers/cust_xxx/addresses/" \
  -H "Authorization: Bearer sk_prod_xxxx"

Modifier une adresse

bash

curl -X PATCH https://api.sangho.ga/v1/customers/cust_xxx/addresses/addr_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "line2": "Appartement 4B",
    "is_default": true
  }'

Response200 OK — Adresse mise à jour

Retourne l'objet Address complet avec les champs modifiés.

json

{
  "id": "addr_xxxxxxxxxxxx",
  "object": "address",
  "customer": "cust_xxxxxxxxxxxx",
  "line1": "Boulevard Triomphal Omar Bongo",
  "line2": "Appartement 4B",
  "city": "Libreville",
  "state": "Estuaire",
  "postal_code": null,
  "country": "GA",
  "is_default": true,
  "updated_at": "2026-04-10T14:00:00Z"
}

Supprimer une adresse

bash

curl -X DELETE https://api.sangho.ga/v1/customers/cust_xxx/addresses/addr_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx"

Response204 No Content — Supprimée

La suppression a réussi. Aucun corps de réponse n'est retourné.