Entregas

Un producto físico puede habilitar pickup, delivery y shipping en fulfillmentMethods. El método también debe estar activo en el negocio. Sin métodos habilitados no se exige información de entrega por ese motivo.

Cuando corresponde una entrega, el checkout ofrece las opciones efectivas y la alternativa de acordar con el negocio. Para un carrito, los demás métodos deben ser compatibles con todos los productos físicos.

Registrar una guíaCopiar enlace

{"number": "GUIA_EJEMPLO"}

El envío nacional se realiza a una oficina del transportista que el cliente selecciona. Enviar una guía no confirma su aceptación; consulta el estado de verificación.

La guía debe ser válida antes de trackingDueAt (2 días hábiles desde el pago). Si no, la entrega se cancela (cancellationReason: "not_shipped") y tu negocio le debe al cliente lo que pagó: un reembolso pendiente que devuelves desde tu banco.

Retiro en la oficinaCopiar enlace

Cuando Zoom reporta el paquete en la oficina, la entrega pasa a ready_for_pickup y readyAt dice desde cuándo; el cliente recibe un correo. Si no lo retira, Billete se lo recuerda a los 3 y a los 7 días, y el día 7 le avisa a tu negocio (bandeja y correo, tema Problemas y plazos de entregas) para que lo contactes antes de que Zoom lo devuelva. Al retirarlo, la entrega pasa a received (receivedBy: "carrier"); si Zoom lo devuelve, pasa a problem y Billete lo revisa.

Entregar con el código del clienteCopiar enlace

Mientras el negocio no entrega una compra (salvo un envío por agencia), la página del pedido del cliente muestra un código QR. Escanearlo es la prueba de que el cliente estuvo ahí. El QR lleva una dirección que termina en el código; puedes enviar la dirección completa o solo el código.

Para encontrar la entrega de un código escaneado, filtra la lista con GET /v1/fulfillments?handoverCode= y el valor codificado para URL: un código que Billete no dio no encuentra nada. Luego entrégala con el mismo valor:

{"code": "VALOR_ESCANEADO"}

Un código que no es el de esa entrega responde handover_code_invalid; uno de un envío por agencia, fulfillment_shipped_by_carrier. Si no tienes el código (por ejemplo, un delivery que sale con un motorizado), usa deliver, con un reason opcional:

{"reason": "Lo llevó un motorizado"}

handover dice cómo se entregó: {"method": "code"} con el código o {"method": "manual", "reason": …} sin él.

Confirmar recepciónCopiar enlace

Entregarla con el código da al cliente 24 horas para confirmar o reportar un problema; marcarla sin el código, 48. A mitad del plazo le recordamos que confirme. La confirmación del cliente usa su enlace privado; el negocio no debe realizarla en su nombre.

Un problema que reporta el cliente es un reclamo sobre el pago de la compra: mientras la espera, la entrega pasa a problem y Billete lo revisa. Termina de una de estas formas:

• El cliente confirma que la recibió.
• Billete lo resuelve a favor de tu negocio: la entrega pasa a received con receivedBy: "billete".
• Billete lo resuelve a favor del cliente, o tu negocio reembolsa el pago completo: la entrega se cancela (cancellationReason: "refunded"). Si lo decidió Billete, tu negocio le debe el pago: un reembolso pendiente que devuelves desde tu banco. Billete solo decide; no mueve el dinero.

receivedBy dice cómo terminó una entrega recibida: customer (confirmó), timeout (venció confirmBy), carrier (el transportista la entregó) o billete (Billete resolvió el problema a favor de tu negocio).

Escucha fulfillment.created, fulfillment.shipped, fulfillment.ready_for_pickup, fulfillment.delivered, fulfillment.received, fulfillment.problem_reported y fulfillment.canceled.

Devolución al clienteCopiar enlace

Mientras tu negocio le debe el pago a tu cliente, la página de su entrega (GET /v1/client/fulfillments/:token) trae refund: el monto, status (needs_destination mientras espera dónde enviarlo, processing mientras tu negocio lo envía y paid), el destino enmascarado (Banesco · 0414 •••• 567), reference y paidAt al registrarse, y problem si el destino anterior no funcionó. Sin un reembolso pendiente o pagado desde tu banco es null.

El cliente indica su Pago Móvil desde esa página o desde la de su reembolso; si construyes la tuya, es client.fulfillments.setRefundDestination(token, input) en el cliente del navegador, con las mismas reglas que la página del reembolso:

{ "bank": "0134", "phone": "0414 1234567", "holderId": "V-12345678" }