Borradores de pedido

Un pedido que prepara la aplicación: se calcula en vivo según catálogo, descuentos y envío, muestra qué impide confirmarlo y al confirmarse es un pedido.

Cargando el índice de búsqueda…

Borradores de pedido

Objetos

DraftOrder

  • idintegerobligatorio

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

  • versionintegerobligatorio

    Revisión del borrador: cualquier cambio la mueve, también uno del personal en el panel. Bajo ella el borrador se cambia, se elimina y se confirma.

  • statusstringobligatorio

    open — se puede cambiar y confirmar; completed — confirmado, el pedido está en order_id; cancelled — cancelado sin pedido.

    Valores:
    opencompletedcancelled
  • customer_idinteger o nullobligatorio

    El cliente del borrador (/v1/customers); null hasta elegirlo.

  • order_idinteger o nullobligatorio

    El pedido confirmado desde el borrador; null hasta confirmarlo.

  • linesarray de objectobligatorio

    Ítems del borrador. Un borrador abierto se calcula en vivo según el catálogo, los descuentos y el envío; uno cerrado guarda sus ítems sin precios.

    Campos · 12
    • idintegerobligatorio

      ID de la línea en el borrador.

    • variant_idinteger o nullobligatorio

      Variante de la línea; null en una línea libre.

    • product_idinteger o nullobligatorio

      Producto de la línea; null en una línea libre.

    • product_namemapa de stringobligatorio

      Nombre del producto al momento de la venta, por idioma.

    • variant_namemapa de stringobligatorio

      Nombre de la variante al momento de la venta, por idioma; un objeto vacío si la variante no tenía nombre.

    • custom_namestring o nullobligatorio

      Nombre de una línea libre que el personal agregó sin producto; null en una línea con variante.

    • quantitystringobligatorio

      Cantidad como cadena decimal en unit: unidades en un ítem por unidad, la medida en un ítem por peso o volumen ("480" gramos).

    • unitstring o nullobligatorio

      Unidad de quantity: pcs, g o ml; null si la variante ya no conoce la unidad de su medida.

      Valores:
      pcsgmlnull
    • unit_priceinteger o nullobligatorio

      Precio de una unidad con sus adicionales; null en un borrador cerrado.

    • discountinteger o nullobligatorio

      Rebaja de la línea; null en un borrador cerrado.

    • totalinteger o nullobligatorio

      Importe de la línea antes de la rebaja; null en un borrador cerrado.

    • modifiersarray de objectobligatorio

      Adicionales de la línea, como los toppings de un plato.

      Campos · 2
      • option_idintegerobligatorio

        ID de la opción del adicional.

      • quantityintegerobligatorio

        Cuántas veces se agrega el adicional.

  • delivery_method_idinteger o nullobligatorio

    Método de envío (/v1/delivery-methods); null hasta elegirlo.

  • address_idinteger o nullobligatorio

    Dirección de la libreta del cliente, para un método con envío; null hasta elegirla.

  • pickup_location_idinteger o nullobligatorio

    Punto de retiro para un método de retiro. Un método con un solo punto lo usa por su cuenta; con varios, el borrador debe nombrar uno.

  • delivery_slotsarray de objectobligatorio

    Franjas de entrega elegidas para un método que trabaja con franjas.

    Campos · 2
    • fromstringobligatorio

      Inicio de la franja.

    • tostringobligatorio

      Fin de la franja.

  • delivery_cost_overrideinteger o nullobligatorio

    Precio de envío fijado a mano en lugar del cálculo del método; null — según las reglas del método.

  • payment_methodstring o nullobligatorio

    Medio de pago con el que se confirmará el borrador: de él dependen los descuentos por medio de pago y la compatibilidad con el envío.

    Valores:
    cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
  • manual_payment_method_idinteger o nullobligatorio

    Medio de pago manual de la tienda cuando payment_method es manual; si no, null.

  • promocodestring o nullobligatorio

    Cupón aplicado al borrador; null si no hay.

  • customer_commentstring o null

    Comentario del cliente al pedido. Solo con el scope customers:read.

  • notestring o nullobligatorio

    Nota interna de la tienda: pasa al pedido, el cliente no la ve.

  • currencystringobligatorio

    Moneda de los importes, código ISO 4217: la moneda de la tienda.

  • items_totalintegerobligatorio

    Suma de las líneas antes del descuento del pedido.

  • discountintegerobligatorio

    Descuento del pedido.

  • delivery_costinteger o nullobligatorio

    Envío a pagar; null si todavía no se puede calcular.

  • totalintegerobligatorio

    Importe a pagar.

  • issuesarray de objectobligatorio

    Lo que impide confirmar el borrador; vacío si nada lo impide y en un borrador cerrado.

    Campos · 2
    • codestringobligatorio

      customer_required — sin cliente; phone_required — el cliente no tiene teléfono; items_empty — sin líneas; import_lines_pending, import_parse_running — las líneas importadas aún no están listas; items_unavailable — un producto no está a la venta; modifier_invalid — un adicional no corresponde al ítem; price_missing — un producto no tiene precio; measure_required — un ítem por peso o volumen necesita su medida; insufficient_stock — no alcanza el stock; presale_not_ready, presale_plan_short — un producto en preventa no está listo o le quedan menos que lo pedido; gift_card_sales_disabled — la tienda no vende tarjetas de regalo; delivery_method_required — sin método de envío; address_required — el envío necesita una dirección; branch_required — el método necesita una sucursal del transportista; pickup_location_required — el método tiene varios puntos de retiro, nombre uno; pickup_location_none — el método no tiene un punto disponible; pickup_location_mismatch — el método no atiende ese punto; slot_required — el método necesita una franja de entrega; slot_invalid — la franja no está disponible; delivery_not_applicable — el método no entrega este pedido; delivery_cost_required — el método necesita un precio de envío a mano; promocode_invalid — el cupón no aplica; payment_delivery_incompatible — el medio de pago no funciona con ese método de envío.

      Valores:
      customer_requiredphone_requireditems_emptyimport_lines_pendingimport_parse_runningitems_unavailablemodifier_invalidprice_missingmeasure_requiredinsufficient_stockpresale_not_readypresale_plan_shortgift_card_sales_disableddelivery_method_requiredaddress_requiredbranch_requiredpickup_location_requiredpickup_location_nonepickup_location_mismatchslot_requiredslot_invaliddelivery_not_applicabledelivery_cost_requiredpromocode_invalidpayment_delivery_incompatible
    • line_idinteger o nullobligatorio

      La línea a la que se refiere el problema; null en un problema de todo el borrador.

  • 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 un borrador de pedido: ítems, totales y lo que impide confirmarlo

get/draft-orders/{draft}

Scope: orders:read

Parámetros

Ruta

  • draftintegerobligatorio

    ID del borrador de pedido.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

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

    Ejemplo:
    "7"

application/json

Devuelve DraftOrder

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/draft-orders/{draft}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "id": 0,
  "version": 0,
  "status": "open",
  "customer_id": 0,
  "order_id": 0,
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "custom_name": "string",
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "discount": 0,
      "total": 0,
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 0
        }
      ]
    }
  ],
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "delivery_cost": 0,
  "total": 0,
  "issues": [
    {
      "code": "customer_required",
      "line_id": 0
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Cambiar un borrador de pedido: cliente, entrega, medio de pago e ítems

patch/draft-orders/{draft}

Scope: orders:write

Parámetros

Ruta

  • draftintegerobligatorio

    ID del borrador de pedido.

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

  • customer_idinteger o null

    El cliente del borrador (/v1/customers); null hasta elegirlo.

  • delivery_method_idinteger o null

    Método de envío (/v1/delivery-methods); null hasta elegirlo.

  • address_idinteger o null

    Dirección de la libreta del cliente, para un método con envío; null hasta elegirla.

  • pickup_location_idinteger o null

    Punto de retiro para un método de retiro. Un método con un solo punto lo usa por su cuenta; con varios, el borrador debe nombrar uno.

  • delivery_slotsarray de object o null

    Franjas de entrega elegidas para un método que trabaja con franjas.

    Máximo de elementos:
    50
    Campos · 2
    • fromstringobligatorio

      Inicio de la franja.

    • tostringobligatorio

      Fin de la franja.

  • delivery_cost_overrideinteger o null

    Precio de envío fijado a mano en lugar del cálculo del método; null — según las reglas del método.

    Mínimo:
    0
    Máximo:
    10000000000
  • payment_methodstring o null

    Medio de pago con el que se confirmará el borrador: de él dependen los descuentos por medio de pago y la compatibilidad con el envío.

    Valores:
    cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
  • manual_payment_method_idinteger o null

    Medio de pago manual de la tienda cuando payment_method es manual; si no, null.

    Mínimo:
    1
  • promocodestring o null

    Cupón aplicado al borrador; null si no hay.

    Largo máximo:
    64
  • customer_commentstring o null

    Comentario del cliente al pedido. Solo con el scope customers:read.

    Largo máximo:
    1000
  • notestring o null

    Nota interna de la tienda: pasa al pedido, el cliente no la ve.

    Largo máximo:
    1000
  • linesarray de object

    Ítems del borrador. Un borrador abierto se calcula en vivo según el catálogo, los descuentos y el envío; uno cerrado guarda sus ítems sin precios.

    Máximo de elementos:
    200
    Sin repetidos
    Campos · 4
    • idinteger

      ID de la línea en el borrador.

    • variant_idintegerobligatorio

      Variante de la línea; null en una línea libre.

    • quantitystringobligatorio

      Cantidad como cadena decimal en unit: unidades en un ítem por unidad, la medida en un ítem por peso o volumen ("480" gramos).

      Largo máximo:
      32
    • modifiersarray de object

      Adicionales de la línea, como los toppings de un plato.

      Máximo de elementos:
      50
      Campos · 2
      • option_idintegerobligatorio

        ID de la opción del adicional.

      • quantityinteger

        Cuántas veces se agrega el adicional.

        Mínimo:
        1
        Máximo:
        99

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 DraftOrder

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/draft-orders/{draft}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "customer_id": 0,
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 1,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "quantity": "string",
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 1
        }
      ]
    }
  ]
}
Ejemplo de respuesta · 200
{
  "id": 0,
  "version": 0,
  "status": "open",
  "customer_id": 0,
  "order_id": 0,
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "custom_name": "string",
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "discount": 0,
      "total": 0,
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 0
        }
      ]
    }
  ],
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "delivery_cost": 0,
  "total": 0,
  "issues": [
    {
      "code": "customer_required",
      "line_id": 0
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Eliminar un borrador de pedido

delete/draft-orders/{draft}

Scope: orders:write

Parámetros

Ruta

  • draftintegerobligatorio

    ID del borrador de pedido.

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/draft-orders/{draft}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'

Crear un borrador de pedido para un cliente

post/draft-orders

Scope: orders: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

  • customer_idinteger o null

    El cliente del borrador (/v1/customers); null hasta elegirlo.

  • delivery_method_idinteger o null

    Método de envío (/v1/delivery-methods); null hasta elegirlo.

  • address_idinteger o null

    Dirección de la libreta del cliente, para un método con envío; null hasta elegirla.

  • pickup_location_idinteger o null

    Punto de retiro para un método de retiro. Un método con un solo punto lo usa por su cuenta; con varios, el borrador debe nombrar uno.

  • delivery_slotsarray de object o null

    Franjas de entrega elegidas para un método que trabaja con franjas.

    Máximo de elementos:
    50
    Campos · 2
    • fromstringobligatorio

      Inicio de la franja.

    • tostringobligatorio

      Fin de la franja.

  • delivery_cost_overrideinteger o null

    Precio de envío fijado a mano en lugar del cálculo del método; null — según las reglas del método.

    Mínimo:
    0
    Máximo:
    10000000000
  • payment_methodstring o null

    Medio de pago con el que se confirmará el borrador: de él dependen los descuentos por medio de pago y la compatibilidad con el envío.

    Valores:
    cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
  • manual_payment_method_idinteger o null

    Medio de pago manual de la tienda cuando payment_method es manual; si no, null.

    Mínimo:
    1
  • promocodestring o null

    Cupón aplicado al borrador; null si no hay.

    Largo máximo:
    64
  • customer_commentstring o null

    Comentario del cliente al pedido. Solo con el scope customers:read.

    Largo máximo:
    1000
  • notestring o null

    Nota interna de la tienda: pasa al pedido, el cliente no la ve.

    Largo máximo:
    1000
  • linesarray de object

    Ítems del borrador. Un borrador abierto se calcula en vivo según el catálogo, los descuentos y el envío; uno cerrado guarda sus ítems sin precios.

    Máximo de elementos:
    200
    Sin repetidos
    Campos · 4
    • idinteger

      ID de la línea en el borrador.

    • variant_idintegerobligatorio

      Variante de la línea; null en una línea libre.

    • quantitystringobligatorio

      Cantidad como cadena decimal en unit: unidades en un ítem por unidad, la medida en un ítem por peso o volumen ("480" gramos).

      Largo máximo:
      32
    • modifiersarray de object

      Adicionales de la línea, como los toppings de un plato.

      Máximo de elementos:
      50
      Campos · 2
      • option_idintegerobligatorio

        ID de la opción del adicional.

      • quantityinteger

        Cuántas veces se agrega el adicional.

        Mínimo:
        1
        Máximo:
        99

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 DraftOrder

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/draft-orders" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "customer_id": 0,
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 1,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "quantity": "string",
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 1
        }
      ]
    }
  ]
}
Ejemplo de respuesta · 201
{
  "id": 0,
  "version": 0,
  "status": "open",
  "customer_id": 0,
  "order_id": 0,
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "custom_name": "string",
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "discount": 0,
      "total": 0,
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 0
        }
      ]
    }
  ],
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "delivery_cost": 0,
  "total": 0,
  "issues": [
    {
      "code": "customer_required",
      "line_id": 0
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Confirmar el pedido desde un borrador: cobrarle al cliente o registrar el pago como recibido

post/draft-orders/{draft}/complete

Scope: orders:write

Parámetros

Ruta

  • draftintegerobligatorio

    ID del borrador de pedido.

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

  • modestringobligatorio

    invoice — el pedido espera el pago, los datos de pago van al cliente por los canales de la tienda, la página de pago está en payment_url del pago; after_picking — el cliente recibe la cuenta por el total exacto después de preparar el pedido, para mercadería por peso; mark_paid — el dinero ya se recibió por un medio manual, necesita el scope payments:write.

    Valores:
    invoiceafter_pickingmark_paid
  • expected_totalintegerobligatorio

    El total que leíste en el borrador: precios, descuentos o envío pueden cambiar después de leerlo. Si es distinto, la solicitud recibe 422 y no se crea el pedido.

    Mínimo:
    0
    Máximo:
    100000000000000
  • currencystring

    La moneda en la que leíste el total: el campo currency del borrador. Una tienda sin pedidos puede cambiar de moneda, y el cambio no toca los números de los precios; si la moneda es distinta, la solicitud recibe 422 y no se crea el pedido. Sin el campo la moneda no se verifica.

    Largo mínimo:
    3
    Largo máximo:
    3

Respuestas

201Creado

Encabezados

  • Idempotent-Replayedstring

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

    Valores:
    true

application/json

Devuelve Order

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/draft-orders/{draft}/complete" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "mode": "invoice",
  "expected_total": 0,
  "currency": "string"
}
Ejemplo de respuesta · 201
{
  "id": 0,
  "number": "string",
  "channel": "web",
  "app_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "status": "string",
  "status_group": "pos_open",
  "payment_status": "unpaid",
  "sale_type": "retail",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "applied_discounts": [
    {
      "id": 0,
      "source": "promocode",
      "kind": "promo",
      "name": {},
      "code": "string",
      "reason": "string",
      "order_item_id": 0,
      "amount": 0
    }
  ],
  "delivery_cost": 0,
  "delivery_discount": 0,
  "delivery_discounts": [
    {
      "id": 0,
      "source": "promocode",
      "kind": "promo",
      "name": {},
      "code": "string",
      "amount": 0
    }
  ],
  "delivery_tax_lines": [
    {
      "regime": "vat",
      "kind": "taxed",
      "rate_bps": 0,
      "base": 0,
      "amount": 0,
      "jurisdiction": "string"
    }
  ],
  "platform_discount": 0,
  "platform_service_fee": 0,
  "platform_delivery_fee": 0,
  "total": 0,
  "tax_lines": [
    {
      "regime": "vat",
      "kind": "taxed",
      "rate_bps": 0,
      "base": 0,
      "amount": 0,
      "jurisdiction": "string"
    }
  ],
  "gift_card_issue_amount": 0,
  "reservation_deposit_amount": 0,
  "account_payment_amount": 0,
  "service_package_issue_amount": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "delivery_method_id": 0,
  "fulfilment_type": "self_pickup",
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "shipment": {
    "carrier": "andreani",
    "carrier_name": "string",
    "tracking_number": "string",
    "tracking_url": "string",
    "status": "accepted",
    "status_at": "2026-01-15T12:00:00Z",
    "events": [
      {
        "status": "accepted",
        "description": "string",
        "occurred_at": "2026-01-15T12:00:00Z"
      }
    ],
    "label_available": true
  },
  "previous_shipments": [
    {
      "carrier": "andreani",
      "carrier_name": "string",
      "tracking_number": "string",
      "tracking_url": "string",
      "status": "accepted",
      "status_at": "2026-01-15T12:00:00Z",
      "events": [
        {
          "status": "accepted",
          "description": "string",
          "occurred_at": "2026-01-15T12:00:00Z"
        }
      ]
    }
  ],
  "shipment_attempt": {
    "state": "queued",
    "started_at": "2026-01-15T12:00:00Z",
    "error": {
      "code": "no_carrier",
      "message": "string"
    }
  },
  "merged_into_order_id": 0,
  "cancel_reason": "payment_init_failed",
  "items": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "total": 0,
      "discount": 0,
      "discount_allocations": [
        {
          "applied_discount_id": 0,
          "amount": 0
        }
      ],
      "is_gift": true,
      "tax_lines": [
        {
          "regime": "vat",
          "kind": "taxed",
          "rate_bps": 0,
          "base": 0,
          "amount": 0,
          "jurisdiction": "string"
        }
      ],
      "cost_amount": 0,
      "cost_basis": "variant"
    }
  ],
  "customer": {
    "id": 0,
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "delivery_address": {
    "kind": "address",
    "recipient": "string",
    "phone": "string",
    "street": "string",
    "house": "string",
    "apartment": "string",
    "floor": "string",
    "entrance": "string",
    "district": "string",
    "city": "string",
    "province": "string",
    "postal_code": "string",
    "address_line": "string",
    "comment": "string",
    "location": {
      "lat": 0,
      "lng": 0
    },
    "branch": {
      "external_id": "string",
      "name": "string"
    }
  },
  "customer_comment": "string",
  "fiscal_receptor": {
    "id_type": "tax_id",
    "id_number": "string",
    "name": "string",
    "tax_status": "registered",
    "address": "string"
  },
  "external_fiscal_document": {
    "issuer": "string",
    "status": "pending",
    "number": "string"
  },
  "placed_at": "2026-01-15T12:00:00Z",
  "confirmed_at": "2026-01-15T12:00:00Z",
  "completed_at": "2026-01-15T12:00:00Z",
  "cancelled_at": "2026-01-15T12:00:00Z",
  "refunded_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}