Clientes

Clientes de la tienda con sus contactos, consentimiento de marketing y libreta de direcciones. Todo esto son datos personales bajo el scope customers:read.

Cargando el índice de búsqueda…

Clientes

Objetos

Customer

  • idintegerobligatorio

    ID del registro, único entre los registros de su tipo en la tienda.

  • external_idstring o nullobligatorio

    ID externo del cliente, su ID en tu sistema; null si no está definido. Después de fusionar dos clientes, el ID del fusionado también encuentra al que queda; la respuesta muestra el ID principal.

  • versionintegerobligatorio

    Versión del registro: crece con cada cambio. Para cambiar el registro, envíela como ETag en If-Match.

  • namestring o nullobligatorio

    Nombre del cliente; null si se desconoce.

  • phonestring o nullobligatorio

    Teléfono principal del cliente en formato E.164, por ejemplo +5491123456789; null si se desconoce.

  • emailstring o nullobligatorio

    Email del cliente; null si se desconoce.

  • languagestringobligatorio

    Idioma en el que la tienda le escribe al cliente: ru, en o es.

    Valores:
    ruenes
  • is_blockedbooleanobligatorio

    La tienda bloqueó al cliente: no puede ingresar a la tienda online.

  • marketing_consentsarray de objectobligatorio

    Consentimiento de publicidad por canal (email, telegram, whatsapp, instagram): una fila por cada canal donde el cliente aceptó (subscribed) o rechazó (unsubscribed) de forma explícita, con el momento del último consentimiento explícito. Si falta el canal, el consentimiento es implícito: una tienda con marketing_consent_mode opt_out escribe por ese canal, una con opt_in no. WhatsApp requiere subscribed.

    Campos · 3
    • channelstringobligatorio

      Canal de publicidad: email, telegram, whatsapp o instagram.

      Valores:
      emailtelegramwhatsappinstagram
    • statusstringobligatorio

      subscribed — el cliente aceptó la publicidad por el canal de forma explícita; unsubscribed — la rechazó.

      Valores:
      subscribedunsubscribed
    • consented_atstring (date-time) o nullobligatorio

      Cuándo el cliente aceptó por última vez la publicidad por el canal de forma explícita; el rechazo conserva este momento. null si no la aceptó.

  • accepts_marketingbooleanobligatorio

    Obsoleto, ver marketing_consents: el cliente no se dio de baja de la publicidad por email.

  • balanceintegerobligatorio

    Saldo del cliente en la tienda: con él se pueden pagar pedidos. En unidades mínimas de la moneda de la tienda.

  • addressesarray de objectobligatorio

    Libreta de direcciones del cliente; la tienda limita su tamaño. Una dirección eliminada simplemente no está en la lista.

    Campos · 15
    • 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.

  • group_idsarray de integerobligatorio

    Grupos del cliente por ID ascendente. La membresía la escriben los comandos del grupo: un cambio mueve al cliente en el feed y envía customer.updated, pero no cambia version ni updated_at.

  • wholesale_price_list_idinteger o nullobligatorio

    Lista de precios mayorista del cliente empresa: con ella se calculan sus ventas mayoristas. null — mayorista a precios base. La lista solo se ve con costs:read.

  • merged_into_customer_idinteger o nullobligatorio

    El cliente en el que se fusionó este: recibió sus contactos, direcciones y pedidos. null si no se fusionó.

  • created_atstring (date-time)obligatorio

    Cuándo se creó el registro.

  • updated_atstring (date-time)obligatorio

    Cuándo cambió el registro por última vez.

  • deleted_atstring (date-time) o nullobligatorio

    Cuándo se archivó el registro; null en un registro vigente.

Endpoints

Listar los clientes cambiados desde un momento dado: contactos, consentimiento de marketing, direcciones y grupos; búsqueda por teléfono, email y grupo

get/customers

Scope: customers:read

Parámetros

Query

  • limitinteger

    Tamaño de página: hasta 250 registros; 50 por defecto.

    Mínimo:
    1
    Máximo:
    250
  • cursorstring

    Cursor opaco: next_cursor de la página anterior, o sync_cursor de la última página guardado por la sincronización anterior. El listado va en orden de confirmación, así que el cursor de sincronización devuelve luego solo lo que cambió después de él.

    Largo máximo:
    4096
  • updated_sincestring (date-time)

    Solo los registros cambiados después de este momento, ISO 8601 con zona horaria. Un filtro de la primera sincronización; después se sigue con el cursor.

    Patrón:
    ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
  • include_deletedboolean

    true — devolver también los registros eliminados: los archivados con deleted_at y los borrados de la base como marcas de eliminación {id, deleted_at} en la continuación por el cursor de sincronización. Activalo para sincronizar.

  • phonestring

    Solo los clientes con este teléfono, en formato E.164.

    Largo máximo:
    32
  • emailstring

    Solo los clientes con este email.

    Largo máximo:
    254
  • group_idinteger

    Solo los clientes de este grupo: sus miembros actuales.

    Mínimo:
    1
  • wholesale_price_list_idinteger

    Solo los clientes con esta lista de precios mayorista asignada.

    Mínimo:
    1

Respuestas

200Éxito

application/json

  • dataarray de Customerobligatorio

    Registros de la página.

  • deletedarray de objectobligatorio

    Registros borrados de la base desde el cursor, como marcas de eliminación: solo con include_deleted=true en la continuación por el cursor de sincronización.

    Campos · 2
    • idintegerobligatorio

      ID del registro borrado.

    • deleted_atstring (date-time)obligatorio

      Cuándo se borró el registro.

  • next_cursorstring o nullobligatorio

    Cursor de la página siguiente; null en la última.

  • has_morebooleanobligatorio

    true si hay una página siguiente.

  • sync_cursorstring o nullobligatorio

    En la última página — el cursor desde el que continuar más tarde: con él llega solo lo que cambió después de esta página. null en las demás.

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

410El cursor de sincronización supera el plazo de conservación de eliminaciones o se emitió antes de restaurar la base de datos

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

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 "https://api.saleya.app/v1/customers" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "data": [
    {
      "id": 0,
      "external_id": "string",
      "version": 0,
      "name": "string",
      "phone": "string",
      "email": "string",
      "language": "ru",
      "is_blocked": true,
      "marketing_consents": [
        {
          "channel": "email",
          "status": "subscribed",
          "consented_at": "2026-01-15T12:00:00Z"
        }
      ],
      "accepts_marketing": true,
      "marketing_consent_at": "2026-01-15T12:00:00Z",
      "balance": 0,
      "addresses": [
        {
          "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"
        }
      ],
      "group_ids": [
        0
      ],
      "wholesale_price_list_id": 0,
      "merged_into_customer_id": 0,
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z",
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "deleted": [
    {
      "id": 0,
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": true,
  "sync_cursor": "string"
}

Crear un cliente: un nombre y al menos un contacto

post/customers

Scope: customers:write

Parámetros

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

  • namestringobligatorio

    Nombre del cliente; null si se desconoce.

    Largo máximo:
    120
    Patrón:
    \S
  • languagestring

    Idioma en el que la tienda le escribe al cliente: ru, en o es.

    Valores:
    ruenes
  • phonestring

    Teléfono principal del cliente en formato E.164, por ejemplo +5491123456789; null si se desconoce.

    Largo máximo:
    32
  • emailstring

    Email del cliente; null si se desconoce.

    Largo máximo:
    254
  • external_idstring o null

    ID externo del cliente, su ID en tu sistema; null si no está definido. Después de fusionar dos clientes, el ID del fusionado también encuentra al que queda; la respuesta muestra el ID principal.

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 Customer

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

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" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "name": "string",
  "language": "ru",
  "phone": "string",
  "email": "string",
  "external_id": "string"
}
Ejemplo de respuesta · 201
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "name": "string",
  "phone": "string",
  "email": "string",
  "language": "ru",
  "is_blocked": true,
  "marketing_consents": [
    {
      "channel": "email",
      "status": "subscribed",
      "consented_at": "2026-01-15T12:00:00Z"
    }
  ],
  "accepts_marketing": true,
  "marketing_consent_at": "2026-01-15T12:00:00Z",
  "balance": 0,
  "addresses": [
    {
      "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"
    }
  ],
  "group_ids": [
    0
  ],
  "wholesale_price_list_id": 0,
  "merged_into_customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Obtener un cliente

get/customers/{customer}

Scope: customers:read

Parámetros

Ruta

  • customerintegerobligatorio

    ID del cliente.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

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

    Ejemplo:
    "7"

application/json

Devuelve Customer

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}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "name": "string",
  "phone": "string",
  "email": "string",
  "language": "ru",
  "is_blocked": true,
  "marketing_consents": [
    {
      "channel": "email",
      "status": "subscribed",
      "consented_at": "2026-01-15T12:00:00Z"
    }
  ],
  "accepts_marketing": true,
  "marketing_consent_at": "2026-01-15T12:00:00Z",
  "balance": 0,
  "addresses": [
    {
      "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"
    }
  ],
  "group_ids": [
    0
  ],
  "wholesale_price_list_id": 0,
  "merged_into_customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Actualizar el nombre, el idioma y el ID externo de un cliente

patch/customers/{customer}

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
  • 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

  • namestring

    Nombre del cliente; null si se desconoce.

    Largo máximo:
    120
    Patrón:
    \S
  • languagestring

    Idioma en el que la tienda le escribe al cliente: ru, en o es.

    Valores:
    ruenes
  • external_idstring o null

    ID externo del cliente, su ID en tu sistema; null si no está definido. Después de fusionar dos clientes, el ID del fusionado también encuentra al que queda; la respuesta muestra el ID principal.

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 Customer

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}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "name": "string",
  "language": "ru",
  "external_id": "string"
}
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "name": "string",
  "phone": "string",
  "email": "string",
  "language": "ru",
  "is_blocked": true,
  "marketing_consents": [
    {
      "channel": "email",
      "status": "subscribed",
      "consented_at": "2026-01-15T12:00:00Z"
    }
  ],
  "accepts_marketing": true,
  "marketing_consent_at": "2026-01-15T12:00:00Z",
  "balance": 0,
  "addresses": [
    {
      "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"
    }
  ],
  "group_ids": [
    0
  ],
  "wholesale_price_list_id": 0,
  "merged_into_customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Obtener un cliente por su ID externo

get/customers/by-external-id/{external_id}

Scope: customers:read

Parámetros

Ruta

  • external_idstringobligatorio

    ID externo: el ID del registro en tu sistema.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

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

    Ejemplo:
    "7"

application/json

Devuelve Customer

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/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "name": "string",
  "phone": "string",
  "email": "string",
  "language": "ru",
  "is_blocked": true,
  "marketing_consents": [
    {
      "channel": "email",
      "status": "subscribed",
      "consented_at": "2026-01-15T12:00:00Z"
    }
  ],
  "accepts_marketing": true,
  "marketing_consent_at": "2026-01-15T12:00:00Z",
  "balance": 0,
  "addresses": [
    {
      "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"
    }
  ],
  "group_ids": [
    0
  ],
  "wholesale_price_list_id": 0,
  "merged_into_customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Crear o actualizar un cliente por su ID externo

patch/customers/by-external-id/{external_id}

Scope: customers:write

Parámetros

Ruta

  • external_idstringobligatorio

    ID externo: el ID del registro en tu sistema.

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-Matchstring

    ETag del registro de la última lectura. Es obligatorio si ya existe un registro con este ID externo (si no, 428) y no tiene que estar si no existe.

    Ejemplo:
    "7"
  • If-None-Matchstring

    * — solo crear: si ya existe un registro con este ID externo, la solicitud recibe 412.

    Valores:
    *

Cuerpo de la solicitud application/json

  • namestring

    Nombre del cliente; null si se desconoce.

    Largo máximo:
    120
    Patrón:
    \S
  • languagestring

    Idioma en el que la tienda le escribe al cliente: ru, en o es.

    Valores:
    ruenes
  • phonestring

    Teléfono principal del cliente en formato E.164, por ejemplo +5491123456789; null si se desconoce.

    Largo máximo:
    32
  • emailstring

    Email del cliente; null si se desconoce.

    Largo máximo:
    254

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 Customer

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 Customer

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

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/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "name": "string",
  "language": "ru",
  "phone": "string",
  "email": "string"
}
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "name": "string",
  "phone": "string",
  "email": "string",
  "language": "ru",
  "is_blocked": true,
  "marketing_consents": [
    {
      "channel": "email",
      "status": "subscribed",
      "consented_at": "2026-01-15T12:00:00Z"
    }
  ],
  "accepts_marketing": true,
  "marketing_consent_at": "2026-01-15T12:00:00Z",
  "balance": 0,
  "addresses": [
    {
      "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"
    }
  ],
  "group_ids": [
    0
  ],
  "wholesale_price_list_id": 0,
  "merged_into_customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Asignar a un cliente una lista de precios mayorista o quitársela

post/customers/{customer}/wholesale-price-list

Scope: customers:writeorders:wholesale

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
  • 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

  • price_list_idinteger o nullobligatorio

    Lista de precios mayorista del cliente; null quita la asignación: las ventas mayoristas al cliente van a precios base.

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 Customer

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 POST "https://api.saleya.app/v1/customers/{customer}/wholesale-price-list" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "price_list_id": 0
}
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "name": "string",
  "phone": "string",
  "email": "string",
  "language": "ru",
  "is_blocked": true,
  "marketing_consents": [
    {
      "channel": "email",
      "status": "subscribed",
      "consented_at": "2026-01-15T12:00:00Z"
    }
  ],
  "accepts_marketing": true,
  "marketing_consent_at": "2026-01-15T12:00:00Z",
  "balance": 0,
  "addresses": [
    {
      "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"
    }
  ],
  "group_ids": [
    0
  ],
  "wholesale_price_list_id": 0,
  "merged_into_customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}