Direcciones de clientes

La libreta de direcciones de un cliente: agregar, cambiar, marcar como principal, eliminar.

Cargando el índice de búsqueda…

Direcciones de clientes

Objetos

CustomerAddress

  • idintegerobligatorio

    ID de la dirección.

  • customer_idintegerobligatorio

    ID del cliente al que pertenece la dirección.

  • labelstring o nullobligatorio

    Nombre de la dirección, como Casa o Trabajo; null si no se indicó.

  • streetstringobligatorio

    Calle.

  • housestring o nullobligatorio

    Número de la calle.

  • apartmentstring o nullobligatorio

    Departamento u oficina.

  • floorstring o nullobligatorio

    Piso.

  • entrancestring o nullobligatorio

    Entrada.

  • districtstring o nullobligatorio

    Barrio.

  • postal_codestring o nullobligatorio

    Código postal.

  • commentstring o nullobligatorio

    Comentario para el cadete, como la forma de entrar; null si no se indicó.

  • locationobject o nullobligatorio

    Ubicació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
    • latnumberobligatorio

      Latitud en grados.

    • lngnumberobligatorio

      Longitud en grados.

  • is_defaultbooleanobligatorio

    La dirección principal del cliente. Si se elimina la principal, pasa a serlo la más reciente.

  • created_atstring (date-time)obligatorio

    Cuándo se creó el registro.

  • updated_atstring (date-time)obligatorio

    Cuá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

  • customerintegerobligatorio

    ID del cliente.

  • addressintegerobligatorio

    ID de la dirección en la libreta del cliente.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

    Versió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-Authenticatestringobligatorio

    Esquema 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-Authenticatestring

    Esquema 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-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos 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

Ejemplo de solicitud
curl "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "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

  • customerintegerobligatorio

    ID del cliente.

  • addressintegerobligatorio

    ID de la dirección en la libreta del cliente.

Encabezado

  • Idempotency-Keystring

    Clave ú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-Matchstringobligatorio

    ETag 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 null

    Nombre de la dirección, como Casa o Trabajo; null si no se indicó.

    Largo máximo:
    64
  • streetstring

    Calle.

    Largo máximo:
    255
  • housestring o null

    Número de la calle.

    Largo máximo:
    32
  • apartmentstring o null

    Departamento u oficina.

    Largo máximo:
    32
  • floorstring o null

    Piso.

    Largo máximo:
    16
  • entrancestring o null

    Entrada.

    Largo máximo:
    16
  • districtstring o null

    Barrio.

    Largo máximo:
    64
  • postal_codestring o null

    Código postal.

    Largo máximo:
    16
  • commentstring o null

    Comentario para el cadete, como la forma de entrar; null si no se indicó.

    Largo máximo:
    500
  • locationobject

    Ubicació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
    • latnumber

      Latitud en grados.

      Mínimo:
      -90
      Máximo:
      90
    • lngnumber

      Longitud en grados.

      Mínimo:
      -180
      Máximo:
      180
  • is_defaultboolean

    La dirección principal del cliente. Si se elimina la principal, pasa a serlo la más reciente.

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true
  • ETagstringobligatorio

    Versió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-Authenticatestringobligatorio

    Esquema 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-Authenticatestring

    Esquema 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-Afterinteger

    Segundos 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-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
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
Cuerpo de la solicitud — 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
}
Ejemplo de respuesta · 200
{
  "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

  • customerintegerobligatorio

    ID del cliente.

  • addressintegerobligatorio

    ID de la dirección en la libreta del cliente.

Encabezado

  • Idempotency-Keystring

    Clave ú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-Matchstringobligatorio

    ETag 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-Replayedstring

    true 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-Authenticatestringobligatorio

    Esquema 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-Authenticatestring

    Esquema 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-Afterinteger

    Segundos 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-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
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

  • customerintegerobligatorio

    ID del cliente.

Encabezado

  • Idempotency-Keystring

    Clave ú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 null

    Nombre de la dirección, como Casa o Trabajo; null si no se indicó.

    Largo máximo:
    64
  • streetstringobligatorio

    Calle.

    Largo máximo:
    255
  • housestring o null

    Número de la calle.

    Largo máximo:
    32
  • apartmentstring o null

    Departamento u oficina.

    Largo máximo:
    32
  • floorstring o null

    Piso.

    Largo máximo:
    16
  • entrancestring o null

    Entrada.

    Largo máximo:
    16
  • districtstring o null

    Barrio.

    Largo máximo:
    64
  • postal_codestring o null

    Código postal.

    Largo máximo:
    16
  • commentstring o null

    Comentario para el cadete, como la forma de entrar; null si no se indicó.

    Largo máximo:
    500
  • locationobjectobligatorio

    Ubicació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
    • latnumberobligatorio

      Latitud en grados.

      Mínimo:
      -90
      Máximo:
      90
    • lngnumberobligatorio

      Longitud en grados.

      Mínimo:
      -180
      Máximo:
      180
  • is_defaultboolean

    La dirección principal del cliente. Si se elimina la principal, pasa a serlo la más reciente.

Respuestas

201Creado

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true
  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"
  • Locationstring (uri)obligatorio

    Direcció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-Authenticatestringobligatorio

    Esquema 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-Authenticatestring

    Esquema 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-Afterinteger

    Segundos 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-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
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
Cuerpo de la solicitud — 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
}
Ejemplo de respuesta · 201
{
  "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"
}