Costa Rica · El Salvador · Honduras · Guatemala
Cómo integrar Boxful con Tiendli
Tiendli usa un único conector regional BOXFUL para Costa Rica, El Salvador, Honduras y Guatemala. La cuenta se autentica contra la API oficial; el comercio elige el origen; el checkout consulta los couriers disponibles para la ruta, cotiza en vivo y vuelve a validar la tarifa en servidor; y el envío puede crearse desde el pedido con tracking sincronizado por API y webhook.
¿Qué permite hacer?
- Conectar una cuenta Boxful con correo y contraseña.
- Validar las credenciales directamente contra la API oficial antes de activar el operador.
- Mantener el accessToken temporal únicamente del lado servidor.
- Consultar desde el conector los catálogos autenticados de direcciones de recolección y estados/ciudades.
- Seleccionar la dirección de recolección real guardada en la cuenta Boxful.
- Usar en checkout los IDs oficiales de estado y ciudad que devuelve Boxful.
- Consultar los couriers disponibles para cada ruta y cotizar en vivo con POST /quoter usando parcels reales del catálogo.
- Volver a cotizar en servidor antes de crear el pedido para no confiar en el precio enviado por el navegador.
- Crear el envío desde el pedido con protección contra despachos duplicados.
- Guardar tracking e historial y sincronizar estados por consulta manual o webhook.
- Consultar couriers y lockers desde el cliente servidor sin crear integraciones separadas por país.
Antes de empezar
- Cuenta activa de Boxful para el país del comercio.
- Correo y contraseña de la cuenta Boxful.
- El comercio debe estar configurado en Costa Rica, El Salvador, Honduras o Guatemala. Nicaragua requiere confirmar la disponibilidad comercial con Boxful.
- Boxful exige usar sus identificadores de estado/ciudad obtenidos desde GET /states para los flujos automáticos.
- Los productos que vayan a cotizarse automáticamente deben tener peso, ancho, alto y largo cargados en Tiendli.
Cómo conectar la cuenta
- 1
Ingresá a Panel de Tiendli → Logística → Operadores logísticos.
- 2
Abrí la tarjeta Boxful.
- 3
Ingresá el correo y la contraseña de tu cuenta Boxful.
- 4
Tiendli autentica la cuenta y valida una lectura protegida antes de guardar la conexión.
- 5
Elegí la dirección de recolección que Tiendli carga directamente desde GET /addresses.
- 6
Opcionalmente elegí un courier preferido. Tiendli igualmente consulta los couriers disponibles para cada ruta antes de cotizar.
- 7
Si Boxful rechaza credenciales u origen, el método no queda habilitado en checkout.
Durante el checkout
Tiendli consulta al operador desde el servidor. El importe se vuelve a validar al crear el pedido para evitar que un precio modificado en el navegador sea aceptado.
- Cuando Boxful está completamente configurado, el checkout carga provincia/departamento y ciudad desde GET /states y conserva sus IDs.
- Tiendli consulta los couriers disponibles para la ruta y llama a POST /quoter por cada alternativa con destino, origen y parcels; si Boxful no devuelve una tarifa válida, el método se muestra como no disponible y nunca como envío gratis.
- La opción elegida lleva únicamente identificadores de cotización/courier/servicio. Al crear el pedido, el servidor vuelve a cotizar y toma ese precio como autoritativo.
- Costa Rica conserva además el distrito; Guatemala puede conservar zona/localidad cuando corresponda.
Preparar y despachar el pedido
- La conexión de cuenta no despacha pedidos por sí sola: el comercio crea el envío cuando el paquete está listo.
- Desde Pedidos → Despachar pedido, Tiendli llama a POST /shipment usando el origen, courier elegido, destino y parcels guardados. El peso de Tiendli se convierte de kg a libras al enviar a Boxful.
- El despacho usa un bloqueo idempotente para impedir que dos clics o dos procesos creen dos envíos cobrables.
- El mismo flujo está disponible para la API móvil de comerciantes.
Etiquetas
- La documentación pública de Boxful confirma cotización, creación de envíos, tracking, lockers y webhooks.
- No anunciamos etiquetas porque la documentación pública revisada no confirma todavía un endpoint específico de impresión de etiquetas.
Seguimiento
- El tracking de Boxful se persiste en el pedido y en ShippingTracker.
- El vendedor puede forzar una actualización desde el pedido mediante GET /tracking/{shipmentNumber}.
- Cada comercio tiene una URL de webhook con secreto propio; ante un evento, Tiendli vuelve a consultar el tracking a Boxful antes de actualizar SHIPPED o DELIVERED.
- Si el alta automática del webhook no está permitida por la cuenta, la URL queda visible en la configuración para registrarla manualmente.
Recomendaciones
Cargá peso, ancho, alto y largo en todos los productos físicos. Los operadores utilizan esos datos para calcular la tarifa y preparar el envío.
Antes de comenzar a vender con un operador nuevo, realizá un pedido de prueba completo: cotización, compra, creación del envío, etiqueta y tracking.
Preguntas frecuentes
¿Tengo que configurar Boxful por separado en cada país?
No. Tiendli utiliza un único conector BOXFUL y toma el país de la configuración del comercio.
¿En qué países aparece la integración?
Los países publicados por Boxful son Costa Rica, El Salvador, Honduras y Guatemala. La configuración de Nicaragua está preparada, pero su habilitación comercial debe confirmarse con Boxful.
¿Ya aparece Boxful con precio en el checkout?
Sí, cuando la cuenta tiene dirección de recolección y los productos poseen peso y dimensiones. Tiendli consulta los couriers disponibles para la ruta, cotiza con Boxful y vuelve a validar la tarifa al crear el pedido.