Saltar al contenido
Qualth

Identificá o creá un cliente

Buscá primero un `customer`, crealo sólo cuando no exista y conservá su ID para continuar el recorrido.

Objetivo

Resolver una identidad de Qualth antes de registrar actividad. Al terminar este flujo tenés un customer.id válido para usar en la compra y en la lectura de estado.

Antes de empezar

  • Llamá a la Integration API desde tu backend o BFF.
  • Usá una X-API-Key del tenant correcto.
  • La búsqueda requiere customers.read; la creación requiere customers.write.
  • Tené disponible el programId que corresponde a la integración.

1. Buscá el cliente

Llamá a GET /api/customers/search con programId y email. Si data.customer contiene un cliente, reutilizá su id y no generes una segunda identidad.

Cuando no existe

Un cliente inexistente no se expresa como HTTP 404: la búsqueda devuelve HTTP 200 con data.customer = null y el warning customer_not_found. Ese resultado habilita el paso de creación.

2. Creá sólo después de un miss

Usá POST /api/customers. program_id y email son obligatorios; consultá la API Reference para los demás campos admitidos y su schema exacto.

Si el cliente ya existe

Un email duplicado devuelve HTTP 409 con customer_email_conflict. Volvé a ejecutar la búsqueda y continuá con el customer.id encontrado.

Si el resultado de create es ambiguo

POST /api/customers no define Idempotency-Key. Ante timeout, network failure o un 5xx donde no sabés si el write ocurrió, buscá nuevamente el mismo programId + email antes de crear otra vez.

Resultado esperado

Tanto el camino de búsqueda como el de creación terminan con un customer.id. Conservá ese ID en tu integración y usalo en el siguiente paso.

Registrá una compra y leé el estado resultante

Ejemplos probados

Los ejemplos que siguen se renderizan desde el bundle validado contra el mismo contrato que alimenta la API Reference.

TestedsearchCustomerByEmail

Buscar un customer existente

HTTP esperado
200
Última validación
2026-08-11
Evidencia
deterministic-ci

Customer resolves inside the credential tenant/program boundary.

cURL

curl --request GET \
  --url 'https://api.qualth.com/api/customers/search?programId={{program_id}}&email={{existing_customer_email}}' \
  --header 'X-API-Key: {{api_key}}' \
  --header 'X-Tenant-Subdomain: {{tenant_subdomain}}'

JavaScript

const response = await fetch("https://api.qualth.com/api/customers/search?programId={{program_id}}&email={{existing_customer_email}}", {
  method: "GET",
  headers: {
    "X-API-Key": "{{api_key}}",
    "X-Tenant-Subdomain": "{{tenant_subdomain}}"
  }
})
const data = await response.json()
TestedsearchCustomerByEmail

Interpretar un search miss

HTTP esperado
200
Última validación
2026-08-11
Evidencia
deterministic-ci

A miss is a successful 200 response with customer:null and customer_not_found warning.

cURL

curl --request GET \
  --url 'https://api.qualth.com/api/customers/search?programId={{program_id}}&email={{new_customer_email}}' \
  --header 'X-API-Key: {{api_key}}' \
  --header 'X-Tenant-Subdomain: {{tenant_subdomain}}'

JavaScript

const response = await fetch("https://api.qualth.com/api/customers/search?programId={{program_id}}&email={{new_customer_email}}", {
  method: "GET",
  headers: {
    "X-API-Key": "{{api_key}}",
    "X-Tenant-Subdomain": "{{tenant_subdomain}}"
  }
})
const data = await response.json()
TestedcreateCustomer

Crear después de un miss

HTTP esperado
201
Última validación
2026-08-11
Evidencia
deterministic-ci+controlled-smoke

Create is strict create semantics and returns 201 with created:true.

cURL

curl --request POST \
  --url 'https://api.qualth.com/api/customers' \
  --header 'X-API-Key: {{api_key}}' \
  --header 'X-Tenant-Subdomain: {{tenant_subdomain}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "program_id": {{program_id}},
  "email": "{{new_customer_email}}",
  "first_name": "Sales",
  "last_name": "Path"
}'

JavaScript

const response = await fetch("https://api.qualth.com/api/customers", {
  method: "POST",
  headers: {
    "X-API-Key": "{{api_key}}",
    "X-Tenant-Subdomain": "{{tenant_subdomain}}",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "program_id": Number("{{program_id}}"),
  "email": "{{new_customer_email}}",
  "first_name": "Sales",
  "last_name": "Path"
}),
})
const data = await response.json()
TestedcreateCustomer

Recuperar un duplicate create

HTTP esperado
409
Última validación
2026-08-11
Evidencia
deterministic-ci

A repeated create is not an upsert; duplicate email is an explicit 409 conflict and callers recover by search.

cURL

curl --request POST \
  --url 'https://api.qualth.com/api/customers' \
  --header 'X-API-Key: {{api_key}}' \
  --header 'X-Tenant-Subdomain: {{tenant_subdomain}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "program_id": {{program_id}},
  "email": "{{new_customer_email}}",
  "first_name": "Sales",
  "last_name": "Path"
}'

JavaScript

const response = await fetch("https://api.qualth.com/api/customers", {
  method: "POST",
  headers: {
    "X-API-Key": "{{api_key}}",
    "X-Tenant-Subdomain": "{{tenant_subdomain}}",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "program_id": Number("{{program_id}}"),
  "email": "{{new_customer_email}}",
  "first_name": "Sales",
  "last_name": "Path"
}),
})
const data = await response.json()

También te puede servir

Registrá una compra y leé el estado resultante