Skip to main content
POST
Dar de alta a un cliente

Authorizations

​
Authorization
string
header
required

Clave del negocio. sk es una clave completa (todo lo que el rol de quien la creó puede dar) y rk una restringida a los permisos que se eligieron al crearla. Solo se usa desde un servidor: un pedido desde un navegador se rechaza con browser_not_allowed.

Scopes

​
clients:write

Crear, cambiar, dar de baja y reactivar clientes.

Headers

​
Craqui-Version
string

Versión de la API para este pedido (YYYY-MM-DD). Si no la mandas, se usa la versión fijada en la clave cuando se creó.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-12-01"

​
Idempotency-Key
string

Obligatorio en todo pedido que crea o cambia algo, salvo con dry_run=true. Un valor único por operación (por ejemplo un UUID). Si repites el pedido con la misma clave y el mismo cuerpo dentro de 24 horas, recibes la misma respuesta (con el header Idempotent-Replayed: true) sin que se repita el efecto, también la misma respuesta de error: para intentar de nuevo algo que se rechazó, usa una clave nueva. Con un dry_run=true la clave se ignora y no se guarda: el pedido real puede usar la misma. Pasadas las 24 horas, repetir una reserva con la misma clave y el mismo cuerpo sigue devolviendo la reserva que se hizo (como está ahora), y la misma clave con otro cuerpo responde idempotency_key_reused.

Required string length: 1 - 255

Query Parameters

​
dry_run
boolean

true para ver qué pasaría sin hacerlo: Craqui evalúa el pedido con las mismas reglas que el real y responde 200 con un objeto preview, sin escribir nada ni avisarle a nadie. Cuenta para el límite de escrituras. false (o sin el parámetro) hace el pedido real. Es el único parámetro de consulta de una escritura.

Body

application/json

Hace falta email o phone.

​
first_name
string
required
Required string length: 1 - 200
​
last_name
string | null
Maximum string length: 200
​
email
string<email> | null

Si ya es de un cliente activo del estudio, la respuesta es ese cliente (200, created: false). Si es de alguien que ya está en el estudio con otro rol, pasa a ser cliente también, con sus datos como están. Si es de una persona que no está en el estudio, 409 email_in_use; si es de un cliente dado de baja, 409 client_inactive.

Maximum string length: 255
​
phone
string | null

En E.164 (+59899123456), o como se marca en el país con phone_country_code (si no lo mandas, el país del estudio). Sin email, el teléfono distingue al cliente: el de un cliente activo con el mismo nombre devuelve ese cliente, y el de alguien de otro nombre responde 409 phone_in_use.

Maximum string length: 30
​
phone_country_code
string | null

El país del teléfono, en ISO 3166 (UY) o como código de discado (+598).

Maximum string length: 10
Example:

"UY"

​
center_id
string | null

La sede habitual del cliente.

Pattern: ^ctr_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example:

"ctr_01j65pdnq74qvnh0953pzvtczg"

​
metadata
object

Datos tuyos sobre el objeto (por ejemplo el id del cliente en tu sistema), que Craqui guarda y te devuelve sin mirarlos. Hasta 20 claves de 1 a 40 caracteres (a-z, 0-9 y _), con valores de texto de hasta 500. Solo los ve tu sistema, por la API: ni el estudio en su panel ni el cliente. No guardes datos sensibles.

​
notify
boolean
default:true

Al cliente no le llega ningún aviso por darlo de alta. false apaga el aviso «nuevo cliente» al panel del estudio, como una carga por planilla. Necesita el permiso notifications:suppress.

Response

Con dry_run=true, la vista previa (no se escribió nada). Sin él, el cliente que ya existía, con created: false.

Lo que haría un alta o un cambio de un cliente, sin hacerlo. Craqui lo evalúa con las mismas reglas que el pedido real: si el real se rechazaría, la vista previa responde el mismo error.

​
object
string
required
Allowed value: "preview"
​
livemode
boolean
required

false si la vista previa es de tu estudio de prueba (claves crq_test_); true con claves crq_live_.

​
action
enum<string>
required

client.create o client.update. La lista puede crecer.

Available options:
client.create,
client.update
​
result
object
required

El cliente como quedaría. En un alta nueva, id es null. En el alta de alguien que ya está en el estudio con otro rol, sus datos no cambian y no se muestran (first_name y last_name en null). El email y el teléfono, solo en un cambio y con clients.pii:read.

​
effects
object
required

Lo que la escritura de un cliente haría.

​
warnings
enum<string>[]
required

Lo que conviene saber, como códigos: already_client (ya es cliente del estudio: el alta no cambia nada), existing_person (ya está en el estudio con otro rol: pasa a ser cliente, con sus datos como están) y no_change (el cambio no cambia nada). La lista puede crecer.

Available options:
already_client,
existing_person,
no_change
​
summary
string
required

Lo mismo en una frase en español, para mostrarle a una persona. No nombra al cliente.