Customers

Los objetos Customer le permiten crear un perfil de cliente persistente al que puede asociar transacciones, métodos de pago, suscripciones y facturas.

Utilizar Customers le ofrece una vista consolidada de la actividad de cada cliente en su panel y permite enviar recibos automáticamente sin tener que indicar el correo electrónico en cada pago.

Customer frente a pago anónimo

Puede crear PaymentIntents sin Customer (pagos anónimos), pero asociar un Customer enriquece sus datos: historial completo, métodos de pago guardados, recibos automáticos y mejor detección de fraude.

Endpoints

Méthode	Endpoint	Description
POST	`/customers/`	Crear un nuevo Customer
GET	`/customers/`	Listar los Customers (paginado, filtrable)
GET	`/customers/{id}/`	Recuperar un Customer por su ID
PATCH	`/customers/{id}/`	Actualizar los datos de un Customer
DELETE	`/customers/{id}/`	Eliminar definitivamente un Customer
GET	`/customers/{id}/transactions/`	Listar las transacciones del Customer
GET	`/customers/{id}/payment-methods/`	Listar los métodos de pago del Customer

¿Le resulta útil esta introducción?

Esquema del objeto

ResponseObjeto Customer

Estructura completa devuelta por todos los endpoints de este recurso.

json

{
  "id": "cust_3Nx8mLKZ2eZvKYlo",
  "object": "customer",
  "app": "app_xxxxxxxx",
  "email": "[email protected]",
  "firstname": "Madeleine",
  "lastname": "Nguema",
  "phone": "+24177654321",
  "address": null,
  "status": "active",
  "is_blacklisted": false,
  "transactions_count": 14,
  "total_spent": 245000,
  "currency": "XAF",
  "metadata": {
    "internal_id": "USER-00123"
  },
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Crear un Customer

Crea un nuevo perfil de cliente asociado a su App. El correo electrónico es el identificador único del Customer: dos clientes de la misma App no pueden tener el mismo correo.

POSTCuerpo de la solicitud

emailRequis

stringemailex :[email protected]

Dirección de correo electrónico única del Customer dentro de su App. Se utiliza para el envío automático de recibos y como clave de deduplicación.

Si intenta crear un Customer con un correo ya existente para la misma App, la API devuelve un error 409 Conflict: no crea un duplicado. Utilice PATCH para actualizar un Customer existente.

nameRequis

stringex :Madeleine Nguema

Nombre completo del Customer. El backend descompone automáticamente este campo en firstname y lastname (división por el primer espacio). El objeto devuelto expone ambos campos por separado.

Para los nombres compuestos (p. ej. “Jean-Claude” o “Madeleine Nguema Obame”), la división se hace por el primer espacio. “Jean-Claude Ondo” → firstname: Jean-Claude, lastname: Ondo.

phoneOptionnel

stringE.164ex :+24177654321

Número de teléfono en formato internacional E.164. Obligatorio para los pagos con Mobile Money asociados a este Customer.

El formato E.164 empieza por + seguido del código de país y del número local sin espacios ni guiones. Ejemplos válidos: +24177000001 (Gabón), +237612345678 (Camerún). Los formatos locales (p. ej. 077 000 001) se rechazan.

metadataOptionnel

object

Diccionario clave/valor para almacenar sus propios identificadores: ID de usuario de su base de datos, número de contrato, segmento de cliente, etc.

Los metadatos se devuelven en todos los webhooks vinculados a este Customer. Máx. 50 claves, 500 caracteres por valor. No están indexados: no se pueden utilizar como criterio de búsqueda mediante la API.

¿Están claros los parámetros de creación?

Crear un Customer

bash

curl -X POST https://api.sangho.ga/v1/customers/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Madeleine Nguema",
    "phone": "+24177654321",
    "metadata": { "internal_id": "USER-00123" }
  }'

Response201 Created

El Customer se crea. Los campos firstname y lastname se derivan automáticamente del campo name indicado.

json

{
  "id": "cust_3Nx8mLKZ2eZvKYlo",
  "object": "customer",
  "app": "app_xxxxxxxx",
  "email": "[email protected]",
  "firstname": "Madeleine",
  "lastname": "Nguema",
  "phone": "+24177654321",
  "address": null,
  "status": "active",
  "is_blacklisted": false,
  "transactions_count": 0,
  "total_spent": 0,
  "metadata": { "internal_id": "USER-00123" },
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Response409 Conflict — Correo ya utilizado

Ya existe un Customer con este correo para esta App. Utilice GET /customers/?search={email} para encontrarlo y después PATCH para actualizarlo.

Sangho nunca crea duplicados. El conflicto se devuelve limpiamente para que pueda gestionar la deduplicación en el servidor.

json

{
  "error": {
    "type": "conflict_error",
    "code": "customer_email_exists",
    "message": "Un Customer avec cet email existe déjà.",
    "param": "email"
  }
}

Listar los Customers

GETParámetros de consulta (query)

searchOptionnel

string

Búsqueda de texto en el correo electrónico, el nombre y los apellidos del Customer. La búsqueda es parcial (contiene) e insensible a mayúsculas y minúsculas.

Ejemplo: search=madeleine devuelve todos los Customers cuyo correo, nombre o apellidos contengan “madeleine”.

statusOptionnel

string

Filtrar por estado. Valores: active, inactive, blocked.

orderingOptionnel

stringdéfaut :-created_at

Ordenación de los resultados. Campos disponibles: created_at, email, total_spent.

pageOptionnel

integerdéfaut :1

Número de página (paginación por offset, empieza en 1).

page_sizeOptionnel

integerdéfaut :20

Resultados por página. Mínimo: 1. Máximo: 100.

Actualizar un Customer

Modifica uno o varios campos de un Customer existente. Todos los campos son opcionales: solo se actualizan los campos indicados.

PATCHCuerpo de la actualización (PATCH)

emailOptionnel

stringemail

Nuevo correo electrónico. Debe ser único entre los Customers de la App. Devuelve 409 si ya está en uso.

nameOptionnel

string

Nuevo nombre completo. Se vuelve a descomponer en firstname / lastname en el backend.

phoneOptionnel

stringE.164

Nuevo número de teléfono en formato E.164. Pase null para eliminarlo.

metadataOptionnel

object

Combinación de metadatos. Las claves existentes no mencionadas se conservan. Pase una clave con valor null para eliminarla.

Ejemplo: si el Customer tiene { "a": "1", "b": "2" } y usted envía { "b": null, "c": "3" }, el resultado será { "a": "1", "c": "3" }.

Eliminar un Customer

Elimina definitivamente un Customer (hard delete). La acción es irreversible.

Eliminación definitiva

La eliminación de un Customer es permanente. Sus transacciones pasadas se conservan en los registros por razones de cumplimiento legal OHADA, pero el perfil del cliente en sí se destruye. Los PaymentIntents en curso asociados a este Customer siguen siendo válidos, pero pierden la referencia al Customer.

¿Están bien documentadas las operaciones CRUD sobre los Customers?

Buscar Customers

bash

curl "https://api.sangho.ga/v1/customers/?search=madeleine&status=active" \
  -H "Authorization: Bearer sk_prod_xxxx"

Actualizar un Customer

bash

curl -X PATCH https://api.sangho.ga/v1/customers/cust_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+24166000001",
    "metadata": { "plan": "premium", "legacy_id": null }
  }'

Response200 OK — Customer actualizado

Devuelve el objeto Customer completo con los campos modificados. Los metadatos reflejan la combinación (merge) aplicada.

json

{
  "id": "cust_3Nx8mLKZ2eZvKYlo",
  "object": "customer",
  "email": "[email protected]",
  "firstname": "Madeleine",
  "lastname": "Nguema",
  "phone": "+24166000001",
  "status": "active",
  "metadata": {
    "internal_id": "USER-00123",
    "plan": "premium"
  },
  "updated_at": "2026-03-15T14:00:00Z"
}

Eliminar un Customer

bash

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

Response204 No Content — Eliminado

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