Referencia · Compra

Crea un pedido como invitado

POST/checkout

Crea el pedido y devuelve su publicToken, con el que se opera después. Los rechazos no escriben nada: ni pedido, ni cliente, ni canje de cupón.

El stock se verifica acá, no se reserva: se descuenta recién al despachar o entregar. Dos compradores pueden pasar a la vez por la última unidad. Se verifica el stock online (la suma de las ubicaciones que despachan pedidos online).

No hay retiro en sucursal: un pedido con un método de tipo RETIRO se crea sin sucursal elegida y se verifica contra el mismo stock online.

Una tienda armada por una ráfaga exige ALTCHA: 403 ALTCHA_REQUIRED.

Está pensado para llamarse desde el navegador con pk_. Con sk_ se aceptan los mismos datos y se aplican los mismos límites, incluido el de IP y tienda: todos los compradores de un servidor son una sola IP, y Meta recibe la IP y el navegador de ese servidor. Una tienda armada le exige ALTCHA igual.

Encabezados

Idempotency-Keytextorequerido

Identificador único por intento de compra (se recomienda un UUID v4), con caracteres ASCII imprimibles y sin espacios. Reenviar la misma clave con el mismo cuerpo devuelve el pedido ya creado, sin repetir ningún efecto. Para comparar cuerpos cuentan los campos del contrato, sin importar su orden, y no cuentan altchaChallenge, altchaSolution ni metaContext. Solo se registra cuando se crea un pedido: un intento rechazado se puede repetir con la misma clave.

De 8 a 128 caracteres.

Cuerpo

application/json, requerido.

Se ignora cualquier total, y también storeId, isExistingCustomer y campos desconocidos. Qué campos del comprador son obligatorios lo define Store.checkout.fields, salvo tel, siempre obligatorio.

itemslista de objetosrequerido

De 1 a 100 elementos.

Campos de items (3)
productIdtextorequerido
skuIdtexto

Obligatorio en productos con variantes. En un producto simple se omite y el servidor usa su SKU por defecto.

quantityenterorequerido

De 1 a 100000.

teltextorequerido

Teléfono en cualquier forma legible (0981..., 981..., 595981..., +595...). Sin código de país se interpreta como Paraguay y se guarda en E.164.

emailtexto (email)

Opcional salvo que la tienda lo exija. Identifica al comprador junto con tel. Vacío equivale a ausente. Mal formado responde 400 INVALID_BODY, también si la tienda oculta el campo.

nametexto
lastNametexto
ructexto

Número de documento.

taxIdCountrytexto

País del documento. Hoy: PY. Va junto con taxIdType.

Valores:PY

taxIdTypetexto

Tipo de documento. Con el par presente, el servidor valida ruc, incluido el dígito verificador.

Valores:RUCCIPASSPORTFOREIGN_IDRESIDENCE_CARDDIPLOMATIC_CARDOTHERUNNAMED

rucNametexto

Razón social.

cityIdtexto

Código de GET /geo/cities. Desconocido o retirado responde 400. Gana sobre city.

citytexto

Texto libre, solo cuando no hay cityId. Si no coincide exactamente con una ciudad, el pedido sale igual, sin control de cobertura.

direction1texto
direction2texto

Referencia o apartado.

shippingMethodIdtexto

Id de un método activo de la tienda, o NINGUNO/ausente para «Retiro en local / Sin envío». Con un método de tipo RETIRO no se puede elegir la sucursal: el pedido se crea sin ella.

paymentMethodtextorequerido

Valores:TARJETAEFECTIVOTRANSFERENCIA

customPaymentMethodIdtexto

Solo en opciones manual. Tiene que ser un método activo de la tienda.

viaPagoparbooleanorequerido

Obligatorio, y hoy siempre false: Pagopar está retirado y true responde 400 PAGOPAR_NOT_ACTIVE.

viaStripebooleano

true si este pedido se paga con tarjeta (Stripe): la opción stripe de store.paymentOptions. Opcional; ausente equivale a false. Exige TARJETA, sin customPaymentMethodId y con viaPagopar: false (si no, 400 PAYMENT_METHOD_UNAVAILABLE). Si la tienda no lo tiene disponible, 400 STRIPE_NOT_AVAILABLE o STRIPE_CURRENCY_NOT_SUPPORTED; si el total supera stripe.maxTotal, 400 STRIPE_AMOUNT_NOT_ALLOWED. El pedido se paga después con POST /orders/{token}/pay.

couponCodetexto

Solo el código; el descuento lo calcula el servidor.

De 1 a 64 caracteres.

deliveryLocationobjeto

Punto de entrega opcional. Un valor inválido se descarta, nunca frena la venta.

Campos de deliveryLocation (4)
latnúmerorequerido

De -90 a 90.

lngnúmerorequerido

De -180 a 180.

sourcetextorequerido

Valores:GPSLINKMANUAL

accuracyMnúmero o nulo

Mínimo 0.

metaContextobjeto

Contexto opcional para la API de Conversiones de Meta. Nunca decide si se crea el pedido.

Campos de metaContext (6)
eventSourceUrltexto

Máximo 2048 caracteres.

fbclidtexto

Máximo 500 caracteres.

fbptexto

Valor de la cookie _fbp de la landing. Si es inválido, se descarta.

fbctexto

Valor de la cookie _fbc de la landing. Si es inválido, se descarta.

consenttexto

Valores:granteddeniedunknown

initiateCheckoutEventIdtexto (uuid)

UUID v4 con el que el navegador disparó InitiateCheckout. Si es inválido, el servidor no envía ese evento.

altchaChallengeobjeto

El desafío de GET /altcha/challenge, tal como se recibió.

altchaSolutionobjeto

La solución devuelta por altcha-lib.

Respuestas

EstadoCódigoQué significa
200—

Repetición de un pedido ya creado con esta clave.

201—

Pedido creado.

400
  • INVALID_QUERY
  • INVALID_BODY
  • IDEMPOTENCY_KEY_REQUIRED
  • SHIPPING_METHOD_INACTIVE
  • SHIPPING_METHOD_REQUIRED
  • PAYMENT_METHOD_UNAVAILABLE
  • STRIPE_NOT_AVAILABLE
  • STRIPE_CURRENCY_NOT_SUPPORTED
  • STRIPE_AMOUNT_NOT_ALLOWED
  • STRIPE_REJECTED
  • RETURN_URL_INVALID
  • PAGOPAR_NOT_ACTIVE
  • PAGOPAR_REJECTED
  • FILE_INVALID

Solicitud rechazada. Con code: INVALID_QUERY (un parámetro de una lectura está fuera de rango o mal formado), INVALID_BODY (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), IDEMPOTENCY_KEY_REQUIRED (ausente o mal formada), SHIPPING_METHOD_INACTIVE, SHIPPING_METHOD_REQUIRED, PAYMENT_METHOD_UNAVAILABLE (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o viaStripe/viaPagopar con algo distinto de TARJETA sin método manual), STRIPE_NOT_AVAILABLE (la tienda no tiene el pago con tarjeta disponible), STRIPE_CURRENCY_NOT_SUPPORTED (la tienda no vende en guaraníes), STRIPE_AMOUNT_NOT_ALLOWED (el total supera el máximo por venta), STRIPE_REJECTED (Stripe no aceptó iniciar el pago), RETURN_URL_INVALID (returnUrl ausente o que no es una URL https de un origen autorizado), PAGOPAR_NOT_ACTIVE (Pagopar está retirado: es lo que responde todo intento de usarlo), PAGOPAR_REJECTED (sin uso hoy), FILE_INVALID (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen message.

401
  • API_KEY_INVALID

Clave ausente, inválida o revocada: API_KEY_INVALID.

403
  • STOREFRONT_API_PLAN_REQUIRED
  • ORIGIN_NOT_ALLOWED
  • SECRET_KEY_IN_BROWSER
  • STORE_INACTIVE
  • ALTCHA_REQUIRED
  • ALTCHA_INVALID
  • ALTCHA_EXPIRED
  • ALTCHA_REPLAY

STOREFRONT_API_PLAN_REQUIRED (la tienda no está en el plan PRO; no aplica a GET /orders/{token} ni a GET /orders/by-payment-hash/{hash}), ORIGIN_NOT_ALLOWED, SECRET_KEY_IN_BROWSER, STORE_INACTIVE (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout ALTCHA_REQUIRED, ALTCHA_INVALID, ALTCHA_EXPIRED, ALTCHA_REPLAY.

409
  • INSUFFICIENT_STOCK
  • IDEMPOTENCY_KEY_REUSED
  • IDEMPOTENCY_IN_PROGRESS
  • ORDER_NOT_PAYABLE
  • ORDER_CHANGED
  • PROOF_NOT_ALLOWED
  • PROOF_ORDER_CANCELLED
  • PROOF_ALREADY_UPLOADED

INSUFFICIENT_STOCK (con details), IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS (el intento concurrente con esa clave no terminó a tiempo; reintentar), ORDER_NOT_PAYABLE, ORDER_CHANGED, PROOF_NOT_ALLOWED, PROOF_ORDER_CANCELLED, PROOF_ALREADY_UPLOADED. El tope de canjes de un cupón responde 409 solo con message.

422
  • SHIPPING_NOT_AVAILABLE_FOR_CITY
  • BUNDLE_COUPON_CONFLICT
  • PROOF_INVALID

SHIPPING_NOT_AVAILABLE_FOR_CITY, BUNDLE_COUPON_CONFLICT, PROOF_INVALID.

429
  • RATE_LIMITED

RATE_LIMITED. Respetar Retry-After. Sin datos para servir, también en una lectura de catálogo degradada.

500—

Error del servidor. En el checkout se puede reintentar con la misma Idempotency-Key.

503
  • SERVICE_UNAVAILABLE

SERVICE_UNAVAILABLE: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de Retry-After.