Direcciones de clientes
La libreta de direcciones de un cliente: agregar, cambiar, marcar como principal, eliminar.
Direcciones de clientes
Objetos
CustomerAddress
idintegerobligatorioID de la dirección.
customer_idintegerobligatorioID del cliente al que pertenece la dirección.
labelstring o nullobligatorioNombre de la dirección, como Casa o Trabajo; null si no se indicó.
streetstringobligatorioCalle.
housestring o nullobligatorioNúmero de la calle.
apartmentstring o nullobligatorioDepartamento u oficina.
floorstring o nullobligatorioPiso.
entrancestring o nullobligatorioEntrada.
districtstring o nullobligatorioBarrio.
postal_codestring o nullobligatorioCódigo postal.
commentstring o nullobligatorioComentario para el cadete, como la forma de entrar; null si no se indicó.
locationobject o nullobligatorioUbicación de la dirección en el mapa; null si la dirección vino de otro sistema y aún no se ubicó.
Campos · 2
latnumberobligatorioLatitud en grados.
lngnumberobligatorioLongitud en grados.
is_defaultbooleanobligatorioLa dirección principal del cliente. Si se elimina la principal, pasa a serlo la más reciente.
created_atstring (date-time)obligatorioCuándo se creó el registro.
updated_atstring (date-time)obligatorioCuándo cambió el registro por última vez.
Endpoints
Obtener una dirección de la libreta del cliente
get/customers/{customer}/addresses/{address}
Scope: customers:read
Parámetros
Ruta
customerintegerobligatorioID del cliente.
addressintegerobligatorioID de la dirección en la libreta del cliente.
Respuestas
200Éxito
Encabezados
ETagstringobligatorioVersión del registro. Mandala en If-Match para cambiar el registro.
- Ejemplo:
"7"
application/json
Devuelve CustomerAddress
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Actualizar una dirección del cliente
patch/customers/{customer}/addresses/{address}
Scope: customers:write
Parámetros
Ruta
customerintegerobligatorioID del cliente.
addressintegerobligatorioID de la dirección en la libreta del cliente.
Encabezado
Idempotency-KeystringClave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.
- Largo mínimo:
- 1
- Largo máximo:
- 255
- Ejemplo:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringobligatorioETag del registro de la última lectura, por ejemplo "7". El cambio se aplica solo si nadie cambió el registro desde entonces; si no, 412. Sin él, 428.
- Ejemplo:
"7"
Cuerpo de la solicitud application/json
labelstring o nullNombre de la dirección, como Casa o Trabajo; null si no se indicó.
- Largo máximo:
- 64
streetstringCalle.
- Largo máximo:
- 255
housestring o nullNúmero de la calle.
- Largo máximo:
- 32
apartmentstring o nullDepartamento u oficina.
- Largo máximo:
- 32
floorstring o nullPiso.
- Largo máximo:
- 16
entrancestring o nullEntrada.
- Largo máximo:
- 16
districtstring o nullBarrio.
- Largo máximo:
- 64
postal_codestring o nullCódigo postal.
- Largo máximo:
- 16
commentstring o nullComentario para el cadete, como la forma de entrar; null si no se indicó.
- Largo máximo:
- 500
locationobjectUbicación de la dirección en el mapa; null si la dirección vino de otro sistema y aún no se ubicó.
Campos · 2
latnumberLatitud en grados.
- Mínimo:
- -90
- Máximo:
- 90
lngnumberLongitud en grados.
- Mínimo:
- -180
- Máximo:
- 180
is_defaultbooleanLa dirección principal del cliente. Si se elimina la principal, pasa a serlo la más reciente.
Respuestas
200Éxito
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
ETagstringobligatorioVersión del registro. Mandala en If-Match para cambiar el registro.
- Ejemplo:
"7"
application/json
Devuelve CustomerAddress
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve ConflictProblem
412El registro cambió después de leerlo: la versión de If-Match no es la actual
application/problem+json
Devuelve Problem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
428La solicitud necesita If-Match con el ETag del registro
application/problem+json
Devuelve Problem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 412
precondition_failedEl registro cambió - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida - 428
precondition_requiredFalta If-Match
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl -X PATCH "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true
}{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Eliminar una dirección de la libreta del cliente
delete/customers/{customer}/addresses/{address}
Scope: customers:write
Parámetros
Ruta
customerintegerobligatorioID del cliente.
addressintegerobligatorioID de la dirección en la libreta del cliente.
Encabezado
Idempotency-KeystringClave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.
- Largo mínimo:
- 1
- Largo máximo:
- 255
- Ejemplo:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringobligatorioETag del registro de la última lectura, por ejemplo "7". El cambio se aplica solo si nadie cambió el registro desde entonces; si no, 412. Sin él, 428.
- Ejemplo:
"7"
Respuestas
204Éxito
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
Sin cuerpo
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve ConflictProblem
412El registro cambió después de leerlo: la versión de If-Match no es la actual
application/problem+json
Devuelve Problem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
428La solicitud necesita If-Match con el ETag del registro
application/problem+json
Devuelve Problem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 409
in_use_conflictRegistro en uso - 412
precondition_failedEl registro cambió - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida - 428
precondition_requiredFalta If-Match
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl -X DELETE "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Agregar una dirección a la libreta del cliente
post/customers/{customer}/addresses
Scope: customers:write
Parámetros
Ruta
customerintegerobligatorioID del cliente.
Encabezado
Idempotency-KeystringClave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.
- Largo mínimo:
- 1
- Largo máximo:
- 255
- Ejemplo:
8e03978e-40d5-43e8-bc93-6894a57f9324
Cuerpo de la solicitud application/json
labelstring o nullNombre de la dirección, como Casa o Trabajo; null si no se indicó.
- Largo máximo:
- 64
streetstringobligatorioCalle.
- Largo máximo:
- 255
housestring o nullNúmero de la calle.
- Largo máximo:
- 32
apartmentstring o nullDepartamento u oficina.
- Largo máximo:
- 32
floorstring o nullPiso.
- Largo máximo:
- 16
entrancestring o nullEntrada.
- Largo máximo:
- 16
districtstring o nullBarrio.
- Largo máximo:
- 64
postal_codestring o nullCódigo postal.
- Largo máximo:
- 16
commentstring o nullComentario para el cadete, como la forma de entrar; null si no se indicó.
- Largo máximo:
- 500
locationobjectobligatorioUbicación de la dirección en el mapa; null si la dirección vino de otro sistema y aún no se ubicó.
Campos · 2
latnumberobligatorioLatitud en grados.
- Mínimo:
- -90
- Máximo:
- 90
lngnumberobligatorioLongitud en grados.
- Mínimo:
- -180
- Máximo:
- 180
is_defaultbooleanLa dirección principal del cliente. Si se elimina la principal, pasa a serlo la más reciente.
Respuestas
201Creado
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
ETagstringobligatorioVersión del registro. Mandala en If-Match para cambiar el registro.
- Ejemplo:
"7"
Locationstring (uri)obligatorioDirección del registro creado; en una solicitud aceptada (202), la dirección donde seguir su resultado.
application/json
Devuelve CustomerAddress
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve ConflictProblem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
address_book_fullLa libreta de direcciones del cliente está llena - 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl -X POST "https://api.saleya.app/v1/customers/{customer}/addresses" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true
}{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}