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.
Borradores de pedido
Objetos
DraftOrder
idintegerobligatorioID del registro, único entre los registros de su tipo en la tienda.
versionintegerobligatorioRevisió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.
statusstringobligatorioopen — se puede cambiar y confirmar; completed — confirmado, el pedido está en order_id; cancelled — cancelado sin pedido.
- Valores:
opencompletedcancelled
customer_idinteger o nullobligatorioEl cliente del borrador (/v1/customers); null hasta elegirlo.
order_idinteger o nullobligatorioEl 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
idintegerobligatorioID de la línea en el borrador.
variant_idinteger o nullobligatorioVariante de la línea; null en una línea libre.
product_idinteger o nullobligatorioProducto de la línea; null en una línea libre.
product_namemapa de stringobligatorioNombre del producto al momento de la venta, por idioma.
variant_namemapa de stringobligatorioNombre de la variante al momento de la venta, por idioma; un objeto vacío si la variante no tenía nombre.
custom_namestring o nullobligatorioNombre de una línea libre que el personal agregó sin producto; null en una línea con variante.
quantitystringobligatorioCantidad como cadena decimal en unit: unidades en un ítem por unidad, la medida en un ítem por peso o volumen ("480" gramos).
unitstring o nullobligatorioUnidad de quantity: pcs, g o ml; null si la variante ya no conoce la unidad de su medida.
- Valores:
pcsgmlnull
unit_priceinteger o nullobligatorioPrecio de una unidad con sus adicionales; null en un borrador cerrado.
discountinteger o nullobligatorioRebaja de la línea; null en un borrador cerrado.
totalinteger o nullobligatorioImporte de la línea antes de la rebaja; null en un borrador cerrado.
modifiersarray de objectobligatorioAdicionales de la línea, como los toppings de un plato.
Campos · 2
option_idintegerobligatorioID de la opción del adicional.
quantityintegerobligatorioCuántas veces se agrega el adicional.
delivery_method_idinteger o nullobligatorioMétodo de envío (/v1/delivery-methods); null hasta elegirlo.
address_idinteger o nullobligatorioDirección de la libreta del cliente, para un método con envío; null hasta elegirla.
pickup_location_idinteger o nullobligatorioPunto 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 objectobligatorioFranjas de entrega elegidas para un método que trabaja con franjas.
Campos · 2
fromstringobligatorioInicio de la franja.
tostringobligatorioFin de la franja.
delivery_cost_overrideinteger o nullobligatorioPrecio 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 nullobligatorioMedio 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 nullobligatorioMedio de pago manual de la tienda cuando payment_method es manual; si no, null.
promocodestring o nullobligatorioCupón aplicado al borrador; null si no hay.
customer_commentstring o nullComentario del cliente al pedido. Solo con el scope customers:read.
notestring o nullobligatorioNota interna de la tienda: pasa al pedido, el cliente no la ve.
currencystringobligatorioMoneda de los importes, código ISO 4217: la moneda de la tienda.
items_totalintegerobligatorioSuma de las líneas antes del descuento del pedido.
discountintegerobligatorioDescuento del pedido.
delivery_costinteger o nullobligatorioEnvío a pagar; null si todavía no se puede calcular.
totalintegerobligatorioImporte a pagar.
issuesarray de objectobligatorioLo que impide confirmar el borrador; vacío si nada lo impide y en un borrador cerrado.
Campos · 2
codestringobligatoriocustomer_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 nullobligatorioLa línea a la que se refiere el problema; null en un problema de todo el borrador.
created_atstring (date-time)obligatorioCuándo se creó el registro.
updated_atstring (date-time)obligatorioCuá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
draftintegerobligatorioID del borrador de pedido.
Respuestas
200Éxito
Encabezados
ETagstringobligatorioVersió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-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/draft-orders/{draft}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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
draftintegerobligatorioID del borrador de pedido.
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
customer_idinteger o nullEl cliente del borrador (/v1/customers); null hasta elegirlo.
delivery_method_idinteger o nullMétodo de envío (/v1/delivery-methods); null hasta elegirlo.
address_idinteger o nullDirección de la libreta del cliente, para un método con envío; null hasta elegirla.
pickup_location_idinteger o nullPunto 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 nullFranjas de entrega elegidas para un método que trabaja con franjas.
- Máximo de elementos:
- 50
Campos · 2
fromstringobligatorioInicio de la franja.
tostringobligatorioFin de la franja.
delivery_cost_overrideinteger o nullPrecio 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 nullMedio 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 nullMedio de pago manual de la tienda cuando payment_method es manual; si no, null.
- Mínimo:
- 1
promocodestring o nullCupón aplicado al borrador; null si no hay.
- Largo máximo:
- 64
customer_commentstring o nullComentario del cliente al pedido. Solo con el scope customers:read.
- Largo máximo:
- 1000
notestring o nullNota 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
idintegerID de la línea en el borrador.
variant_idintegerobligatorioVariante de la línea; null en una línea libre.
quantitystringobligatorioCantidad 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 objectAdicionales de la línea, como los toppings de un plato.
- Máximo de elementos:
- 50
Campos · 2
option_idintegerobligatorioID de la opción del adicional.
quantityintegerCuántas veces se agrega el adicional.
- Mínimo:
- 1
- Máximo:
- 99
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 DraftOrder
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
draft_order_closedEl borrador de pedido está cerrado - 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/draft-orders/{draft}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @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
}
]
}
]
}{
"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
draftintegerobligatorioID del borrador de pedido.
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/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-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
customer_idinteger o nullEl cliente del borrador (/v1/customers); null hasta elegirlo.
delivery_method_idinteger o nullMétodo de envío (/v1/delivery-methods); null hasta elegirlo.
address_idinteger o nullDirección de la libreta del cliente, para un método con envío; null hasta elegirla.
pickup_location_idinteger o nullPunto 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 nullFranjas de entrega elegidas para un método que trabaja con franjas.
- Máximo de elementos:
- 50
Campos · 2
fromstringobligatorioInicio de la franja.
tostringobligatorioFin de la franja.
delivery_cost_overrideinteger o nullPrecio 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 nullMedio 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 nullMedio de pago manual de la tienda cuando payment_method es manual; si no, null.
- Mínimo:
- 1
promocodestring o nullCupón aplicado al borrador; null si no hay.
- Largo máximo:
- 64
customer_commentstring o nullComentario del cliente al pedido. Solo con el scope customers:read.
- Largo máximo:
- 1000
notestring o nullNota 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
idintegerID de la línea en el borrador.
variant_idintegerobligatorioVariante de la línea; null en una línea libre.
quantitystringobligatorioCantidad 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 objectAdicionales de la línea, como los toppings de un plato.
- Máximo de elementos:
- 50
Campos · 2
option_idintegerobligatorioID de la opción del adicional.
quantityintegerCuántas veces se agrega el adicional.
- Mínimo:
- 1
- Máximo:
- 99
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 DraftOrder
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
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
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/draft-orders" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @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
}
]
}
]
}{
"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
draftintegerobligatorioID del borrador de pedido.
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
modestringobligatorioinvoice — 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_totalintegerobligatorioEl 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
currencystringLa 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-Replayedstringtrue 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-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
draft_order_closedEl borrador de pedido está cerrado - 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 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{
"mode": "invoice",
"expected_total": 0,
"currency": "string"
}{
"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"
}