Referencia · Compra
Crea un pedido como invitado
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-KeytextorequeridoIdentificador ú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,altchaSolutionnimetaContext. 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 objetosrequeridoDe 1 a 100 elementos.
Campos de items (3)
productIdtextorequeridoskuIdtextoObligatorio en productos con variantes. En un producto simple se omite y el servidor usa su SKU por defecto.
quantityenterorequeridoDe 1 a 100000.
teltextorequeridoTelé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 400INVALID_BODY, también si la tienda oculta el campo.nametextolastNametextoructextoNúmero de documento.
taxIdCountrytextoPaís del documento. Hoy:
PY. Va junto contaxIdType.Valores:
PYtaxIdTypetextoTipo de documento. Con el par presente, el servidor valida
ruc, incluido el dígito verificador.Valores:
RUCCIPASSPORTFOREIGN_IDRESIDENCE_CARDDIPLOMATIC_CARDOTHERUNNAMEDrucNametextoRazón social.
cityIdtextoCódigo de
GET /geo/cities. Desconocido o retirado responde 400. Gana sobrecity.citytextoTexto libre, solo cuando no hay
cityId. Si no coincide exactamente con una ciudad, el pedido sale igual, sin control de cobertura.direction1textodirection2textoReferencia o apartado.
shippingMethodIdtextoId de un método activo de la tienda, o
NINGUNO/ausente para «Retiro en local / Sin envío». Con un método de tipoRETIROno se puede elegir la sucursal: el pedido se crea sin ella.paymentMethodtextorequeridoValores:
TARJETAEFECTIVOTRANSFERENCIAcustomPaymentMethodIdtextoSolo en opciones
manual. Tiene que ser un método activo de la tienda.viaPagoparbooleanorequeridoObligatorio, y hoy siempre
false: Pagopar está retirado ytrueresponde 400PAGOPAR_NOT_ACTIVE.viaStripebooleanotruesi este pedido se paga con tarjeta (Stripe): la opciónstripedestore.paymentOptions. Opcional; ausente equivale afalse. ExigeTARJETA, sincustomPaymentMethodIdy conviaPagopar: false(si no, 400PAYMENT_METHOD_UNAVAILABLE). Si la tienda no lo tiene disponible, 400STRIPE_NOT_AVAILABLEoSTRIPE_CURRENCY_NOT_SUPPORTED; si el total superastripe.maxTotal, 400STRIPE_AMOUNT_NOT_ALLOWED. El pedido se paga después conPOST /orders/{token}/pay.couponCodetextoSolo el código; el descuento lo calcula el servidor.
De 1 a 64 caracteres.
deliveryLocationobjetoPunto de entrega opcional. Un valor inválido se descarta, nunca frena la venta.
Campos de deliveryLocation (4)
latnúmerorequeridoDe -90 a 90.
lngnúmerorequeridoDe -180 a 180.
sourcetextorequeridoValores:
GPSLINKMANUALaccuracyMnúmero o nuloMínimo 0.
metaContextobjetoContexto opcional para la API de Conversiones de Meta. Nunca decide si se crea el pedido.
Campos de metaContext (6)
eventSourceUrltextoMáximo 2048 caracteres.
fbclidtextoMáximo 500 caracteres.
fbptextoValor de la cookie
_fbpde la landing. Si es inválido, se descarta.fbctextoValor de la cookie
_fbcde la landing. Si es inválido, se descarta.consenttextoValores:
granteddeniedunknowninitiateCheckoutEventIdtexto (uuid)UUID v4 con el que el navegador disparó InitiateCheckout. Si es inválido, el servidor no envía ese evento.
altchaChallengeobjetoEl desafío de
GET /altcha/challenge, tal como se recibió.altchaSolutionobjetoLa solución devuelta por
altcha-lib.
Respuestas
| Estado | Código | Qué significa |
|---|---|---|
| 200 | — | Repetición de un pedido ya creado con esta clave. |
| 201 | — | Pedido creado. |
| 400 |
| Solicitud rechazada. Con |
| 401 |
| Clave ausente, inválida o revocada: |
| 403 |
|
|
| 409 |
|
|
| 422 |
|
|
| 429 |
|
|
| 500 | — | Error del servidor. En el checkout se puede reintentar con la misma |
| 503 |
|
|