Addresses

Los objetos Address representan direcciones postales asociadas a un Customer. Cada Customer puede tener varias direcciones (envío, facturación) con una dirección marcada como predeterminada.

Casos de uso típicos: rellenar previamente el formulario de envío durante el checkout, mostrar la dirección de facturación en las facturas en PDF, gestionar una libreta de direcciones de varios centros.

Dirección predeterminada

Cuando crea una dirección con is_default: true, la dirección predeterminada anterior deja de serlo automáticamente. Un Customer solo puede tener una dirección predeterminada a la vez.

Endpoints

Méthode	Endpoint	Description
POST	`/customers/{id}/addresses/`	Añadir una dirección a un Customer
GET	`/customers/{id}/addresses/`	Listar las direcciones de un Customer
GET	`/customers/{id}/addresses/{addr_id}/`	Recuperar una dirección por su ID
PATCH	`/customers/{id}/addresses/{addr_id}/`	Modificar una dirección
DELETE	`/customers/{id}/addresses/{addr_id}/`	Eliminar definitivamente una dirección

¿Está clara esta introducción?

Esquema del objeto

ResponseObjeto Address

Estructura completa devuelta por todos los endpoints de este recurso.

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"
}

Añadir una dirección

Crea una nueva dirección y la asocia al Customer identificado por {id} en la URL. La dirección está disponible de inmediato para utilizarla en una CheckoutSession o en una Invoice.

POSTCuerpo de la solicitud

line1Requis

string

Primera línea de la dirección: número y nombre de la calle, apartado de correos, etc. Visible para el comprador en los recibos y las facturas en PDF.

line2Optionnel

string

Complemento de la dirección: edificio, planta, apartamento, polígono industrial, etc.

cityRequis

stringex :Libreville

Nombre de la ciudad. Se muestra en los documentos de facturación y en las etiquetas de envío.

stateOptionnel

stringex :Estuaire

Provincia, región o Estado. Opcional para los países que no utilizan subdivisiones administrativas en las direcciones postales.

postal_codeOptionnel

string

Código postal. Puede ser null en los países de África Central en los que el sistema postal no lo exige.

countryRequis

stringISO 3166-1 alpha-2ex :GA

Código de país en formato ISO 3166-1 alpha-2. Debe corresponder a un país cubierto por su App.

Ejemplos: GA (Gabón), CG (Congo-Brazzaville), CM (Camerún), CI (Costa de Marfil). Los códigos de dos letras en mayúsculas son obligatorios: se rechazan los nombres de país escritos en claro.

is_defaultOptionnel

booleandéfaut :false

Marca esta dirección como la dirección predeterminada del Customer. Si ya existe una dirección predeterminada, deja de serlo automáticamente.

La dirección predeterminada aparece preseleccionada en los formularios de pago alojados por Sangho. También se utiliza como dirección de facturación en las Invoices cuando no se especifica ninguna dirección de forma explícita.

¿Están claros los parámetros de la dirección?

Añadir una dirección

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

La dirección se crea y se asocia al Customer. Si is_default era true, la anterior dirección predeterminada ha dejado de serlo automáticamente.

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"
}

Listar las direcciones

Devuelve todas las direcciones asociadas al Customer, ordenadas por fecha de creación descendente. La dirección predeterminada aparece la primera.

Modificar una dirección

Actualiza uno o varios campos de una dirección existente. Solo se modifican los campos indicados.

PATCHCuerpo de la actualización (PATCH)

line1Optionnel

string

Nueva primera línea de la dirección.

line2Optionnel

string

Nuevo complemento de la dirección. Pase null para eliminar el campo.

cityOptionnel

string

Nueva ciudad.

stateOptionnel

string

Nueva provincia/región. Pase null para eliminarla.

postal_codeOptionnel

string

Nuevo código postal. Pase null para eliminarlo.

countryOptionnel

stringISO 3166-1 alpha-2

Nuevo código de país ISO 3166-1 alpha-2.

is_defaultOptionnel

boolean

Pase true para promover esta dirección a dirección predeterminada. La anterior dirección predeterminada deja de serlo automáticamente.

Eliminar una dirección

Elimina definitivamente la dirección. La acción es irreversible.

Eliminación definitiva

A diferencia de los Products, la eliminación de una Address es un hard delete: no se puede restaurar. Si la dirección eliminada era la predeterminada, no se promueve automáticamente ninguna otra: tendrá que designar una nueva mediante PATCH.

¿Están bien documentadas las operaciones sobre direcciones?

Listar las direcciones

bash

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

Modificar una dirección

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 — Dirección actualizada

Devuelve el objeto Address completo con los campos modificados.

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"
}

Eliminar una dirección

bash

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

Response204 No Content — Eliminada

La eliminación se ha realizado correctamente. No se devuelve ningún cuerpo de respuesta.