Bienvenido a la documentación de Picker Express API.

Picker te permitirá conectar tus plataformas y/o comercios a distintos proveedores de delivery de la región en la que te encuentras. La integración con Picker a través de su API te ofrece las siguientes capacidades:

• Administración de locales.
• Automatizar la creación de pedidos desde tu plataforma.
• Realizar consultas de tarifas.
• Recibir en tiempo real las actualizaciones de tu pedido.

La siguiente guía te permitirá saber los primeros pasos, buenas practicas y las referencias de la API que debes de tomar en cuenta en tu desarrollo.

En esta página podrás ver cuales son los primeros pasos y que cosas se deben tener en cuenta antes de desarrollar la integración. Si tienes alguna duda acerca de algún concepto de nuestra plataforma, puedes visitar la página de Glosario donde tendrás información mas detallada.

Para entender un poco la lógica que maneja Picker, una cuenta se la denomina Empresa. Cada empresa puede tener N locales (que pueden representar tiendas, restaurantes, puntos de despacho). Cada local obligatoriamente debe estar referenciado con una dirección y una geolocalización (se las requiere al momento de crearlas). Por ejemplo: Si tu empresa va a manejar 2 sucursales, deberás crear 2 locales.

Para poder identificar tu empresa o local, nuestra API utiliza dos tipos de keys:

• API Key de Local: Permite hacer operaciones sobre cada local (actualizaciones) y permite realizar operaciones de pedidos (crear, consultar estado, consultar precio)
• Master Key de Empresa: Permite consultar y hacer operaciones sobre mi empresa (crear locales, consultar locales).

API KEY

Al tener acceso al dashboard podrás obtener los api keys de cada local que vayas creando en la opción de Locales.

En la esquina superior derecha de cada local, podrás visualizar el api key del local.

MASTER KEY

Para poder acceder al Master Key de tu tienda, debes ingresar a la opción de Configuraciones (representado por el engrane).

En configuraciones, podrás encontrar el key de tu empresa.

La autenticación que maneja Picker API para cada enpoint es una autenticación de tipo Bearer; y usar como key el api key de tu local o el master key de tu empresa de acuerdo al endpoint que estes usando.

BASH

Select...
curl --location 'https://dev-api.pickerexpress.com/api/createBooking' \
--header 'content-language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiKey}}' \

BASH

Select...
curl --location 'https://dev-api.pickerexpress.com/api/createStore' \
--header 'content-language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{masterKey}}' \

Todo pedido creado en la plataforma de Picker es determinado por un estado. El estado de un pedido es una parte importante del ciclo de vida del mismo. Estos estados pueden indicar si el pedido esta terminado, cancelado o aun en proceso. Es importante que en la integración que se vaya a desarrollar se mapeen todos los estados posibles, para que el cliente tenga muy claro lo que significa cada estado.

Un booking es la representación o entidad de un pedido dentro de la plataforma de Picker. Cada booking o pedido va a tener los siguientes elementos:

• Local: Es la representación del negocio/restaurante en Picker. Representa el punto de despacho con una dirección y una geolocalización.
• Cliente: Es el consumidor final del pedido. Representa un punto de entrega con una dirección y una geolocalización.
• Estado: Representa la fase en que esta el pedido actualmente.
• Conductor: Es la representación de la persona que se encargará de entregar el pedido al cliente. Contiene datos como número de teléfono para poder contactarse.
• Proveedor: Nombre del proveedor que atiende el pedido.
• Método de Pago: Indicará si este pedido requiere un pago contra entrega o no.
• Órdenes: Son todos los llamados que hace Picker hacia cada uno de los proveedores durante un pedido. Si un pedido al crearse no tiene respuesta de ningún proveedor o no hay proveedores que puedan atender sus pedidos, el pedido se guarda con el estado PROVIDER_NOT_FOUND

Flujo de un pedido

• Pedido se crea en Picker vía Dashboard o API. Los datos de entrada determinarán que proveedores podrán atender el pedido. Ejemplo: Si el pedido es en efectivo, solo va a ser atendido por proveedores que pueden recibir el efectivo.
• Picker, de acuerdo a los parámetros del pedido y la configuración de proveedores que tiene el local, crea las ordenes en los proveedores.

• Los proveedores procesan el pedido y confirman si pueden atender el pedido o no. Si no pueden atender el pedido, su respectiva orden se anula.

• Cuando un proveedor asigna un conductor para el pedido, las órdenes en los demás proveedores automáticamente se cancelan.

• El proveedor que esta asignado al pedido será el encargado de operarlo con su conductor. De aquí en adelante el proveedor me indicará los estados del pedido.

Al crear un pedido mediante el endpoint de Create Booking, el primer estado con el que va a nacer el pedido dependerá si manejas o no tiempo de preparación (en el API es representado por el campo cookTime). Este cookTime puede ser configurado a nivel de local, empresa o puede ser enviado individualmente por cada pedido. A partir de esto, puede suceder lo siguiente:

• Si el pedido contiene cookTime, este nace con el estado ON_HOLD. Una vez cumplido el tiempo de preparación, pasa automáticamente a READY_FOR_PICKUP
• Si el pedido no tiene cookTime o es 0, este nace con el estado READY_FOR_PICKUP

Una vez que el pedido este en READY_FOR_PICKUP, el ciclo de vida de un pedido exitoso es muy lineal:

• Cuando el pedido esta en READY_FOR_PICKUP, esta buscando un conductor ideal para tu pedido.
• Cuando es aceptado por un conductor de alguna flota o proveedor, pasa al estado ACCEPTED.
• De ACCEPTED, pasa a ARRIVED_AT_PICKUP una vez que el conductor indica que ha llegado al local.
• De ARRIVED_AT_PICKUP pasa a WAY_TO_DELIVER si el conductor indica que ya abandono el local y va al punto de entrega.
• El pedido pasa a ARRIVED_AT_DELIVERY si el conductor indica que ya esta donde el cliente y esta presto a terminar el pedido.
• El pedido termina con el estado COMPLETED cuando el conductor entrega satisfactoriamente el pedido.

Un pedido en proceso puede sufrir cancelaciones o retornos de todo tipo. Desde escenarios en que el local no requiere ya un motorizado, o cancelaciones desde el proveedor. Los escenarios de cancelación son los siguientes:

Cancelado por Negocio

En este escenario, un pedido es creado exitosamente. Pero durante el transcurso del pedido el negocio desea cancelarlo (puede ser vía API o via Dashboard). Cuando esto sucede, el pedido se guarda bajo el estado de CANCELLED_BY_BUSINESS. Esta cancelación puede efectuarse mientras el pedido este en:

• ON_HOLD
• READY_FOR_PICKUP
• ACCEPTED
• ARRIVED_AT_PICKUP

En los 2 últimos estados (ACCEPTED y ARRIVED_AT_PICKUP), esta cancelación incurre en un costo del 50% del delivery.

Cancelado por Admin

En este escenario, durante el ciclo de un pedido si este esta en un estado superior a ARRIVED_AT_PICKUP, el local no podrá cancelar el pedido. Para poder cancelarlo, el usuario deberá consultar a soporte para proceder con la cancelación. En este flujo, el estado con el que se guarda el pedido es CANCELLED_BY_ADMIN.

Cancelado por Proveedor

Existen ocasiones en que el proveedor, ya teniendo el pedido en curso, no puede despachar o terminar el pedido. En estos escenarios, el proveedor cancela el pedido y se guarda con el estado CANCELLED_BY_DELIVERY_PROVIDER.

Provider Not Found

Este estado se dispara al momento en que se crea un pedido, pero ningún proveedor esta disponible para poder atender tu pedido. Para entender como se registra este estado, seguimos el siguiente flujo:

1. Se crea un pedido en la plataforma de Picker (via API o Dashboard).
2. Picker intenta solicitar a los proveedores activos del local si pueden efectuar la orden.
3. Si al menos un proveedor accede a atender la orden, se efectúa la búsqueda.
4. Si ningún proveedor puede atender el pedido, se da por finalizado el pedido y se lo guarda con el estado PROVIDER_NOT_FOUND.

La disponibilidad de un proveedor va a depender distintos criterios:

• El método de pago del pedido (algunos proveedores no manejan el pago contra entrega o efectivo).
• La ubicación de entrega esta fuera de la cobertura de los proveedores.
• Proveedores no pueden atender el pedido por alta demanda en sus respectivas plataformas.

No Entrega (Not Delivered)

Este escenario sucede cuando el conductor esta intentando entregar al pedido al cliente, pero por alguna razón no puede completar el pedido. Esto puede suceder por distintas razones:

• Conductor no encuentra con la dirección de entrega (Dirección errónea o incompleta)
• Cliente no recibe pedido o lo rechaza.
• Conductor no puede contactar con cliente para coordinar la entrega (Número de teléfono o datos de contacto erróneos).

Hay que tener en consideración que cuando se dispara este escenario, el pedido pasará al estado NOT_DELIVERED si este no es requerido de retorno al local.

Retornado

Si el pedido no pudo ser entregado al cliente (bajo los escenario descritos en No Entrega), y este requiere que sea retornado al local o comercio, para al estado RETURNING, el cual indica que el pedido va de regreso al local. Una vez que el pedido sea retornado satisfactoriamente al local, pasa al estado final RETURNED.

A continuación presentamos un glosario de todos los estados que se tienen en Picker.

Previo a la salida a producción, es imperativo que se coordine una reunión para poder certificar tu integración con Picker. Dentro de esta certificación se van a revisar los siguientes puntos, dependiendo de las funcionalidades que tengas integradas:

• Bookings:
  • Pre Checkout
  • Create Booking
    • Datos correctos y concretos del cliente
    • Valores a cobrar
    • Uso correcto de métodos de pago
    • Uso de cook time (Opcional)
  • Cancel Booking (Opcional)
• Webhooks
  • Registro de Webhooks
  • Interpretación de estados en su sistema
• Stores
  • Create Store
  • Get Store (Opcional)
• Pre Booking
  • Create Pre Booking
    • Datos del cliente y del negocio sea correcto
    • Flujo de envió de link para confirmar dirección
  • Cancel Pre Booking (Opcional)
• Interacción con Usuario Final
  • Visualización de Estados
  • Visualización de datos de pedido
  • Visualización de Tracking de Picker

Para acordar una reunión de certificación, se la puede agendar mediante este link.

• ¿Es necesario usar el endpoint de pre-checkout para usar el API?
  • No es imperativo usar el endpoint de pre-checkout; sin embargo lo recomendamos para que puedas saber con anterioridad el precio de un pedido antes de crearlo.
• ¿Para que me sirve el Dashboard?
  • El Dashboard de Picker es una herramienta visual donde podrás:
    • Visualizar, administrar y crear pedidos.
    • Visualizar y administrar tus locales.
    • Manejar tus configuraciones generales.
    • Consultar los keys para la integración.
• ¿En que escenario debo enviar CASH o CARD en paymentMethod al crear un booking?
  • CASH: Cuando el pedido requiere un pago contra entrega en efectivo.
  • CARD: Cuando unicamente requieres que el conductor recoja el pedido y lo entregue en sitio. Esto funciona si de tu lado de la integración ya estas realizando el cobro al cliente (Por transferencia, pasarela de pagos, etc).
• ¿Qué valor debo ingresar en el campo orderAmount?
  • Nosotros recomendamos fuertemente que se coloque el valor en bruto del pedido (sin delivery fee, descuentos u otros rubros), inclusive si el pedido tiene como método de pago CASH. Esto es necesario para la auditoría de los proveedores en el caso que suceda alguna incidencia con el pedido en curso.
• Acabo de crear mi pedido, pero no esta buscando en ningún proveedor. ¿Qué me esta haciendo falta?
  • Es muy probable que tu pedido tenga cooktime y este en estado ON_HOLD. Cuando un pedido se inicia con cooktime, tiene un tiempo de espera hasta antes de iniciar una búsqueda en los proveedores. Para iniciar una búsqueda, hay las siguientes opciones:
    • Esperar que se cumpla el tiempo de espera
    • Iniciar la búsqueda manualmente mediante la opción de Iniciar Búsqueda en el menu del pedido en Dashboard
    • Usar endpoint de Start Search.
• Me aparece que mi workspace esta suspendido. ¿Qué debo hacer?
  • Si tu empresa esta suspendida, puedes contactar a soporte mediante la opción de chat que existe en Dashboard para conocer mas del asunto.

• Empresa: Espacio de trabajo que representa la empresa o marca, el cual puede tener 1 o mas locales asociados. Tiene un master key único, el cual es utilizado para las operaciones vía API. También es conocido como Workspace en algunas nomenclaturas.
• Local: Es la representación de un comercio/local/restaurante/punto de despacho en la plataforma de Picker. Cada local tiene un identificativo único (Api Key); y tiene asociado una dirección y una geolocalización necesarias para la operación.
• Master Key: Es el identificador único de cada empresa. Es obligatorio usarlo en cada operación vía API que requiere la identificación del empresa. Ejemplo: En el endpoint Create Store, es necesario para poder indicar a que empresa se debe asociar la tienda recién creada.
• Api Key: Es el identificador único de cada tienda. Es obligatorio usarlo en las operaciones vía API en que se requiere la identificación del local. Ejemplo: En el endpoint Create Booking, es necesario para poder identificar la tienda a donde el conductor tiene que recoger el pedido.
• Booking: Es la representación del pedido como tal en la plataforma de Picker. Cada booking o pedido tiene un identificador único interno (id), público (bookingNumericId) y un estado (statusText). Este ultimo campo representa en que estado del proceso se encuentra el pedido.
• Orden: Es la representación de cada llamado a un proveedor. Cuando un booking se crea, este llama a todos los proveedores que tiene activado el local; cada uno de estos llamados es una orden. Un booking puede tener de N ordenes de acuerdo al número de proveedores que puede atenderlo.
• Dashboard: Es la plataforma visual de Picker. Desde esta web se podrán administrar y configurar la empresa como sus locales. Para acceder al dashboard de producción haz click aquí.
• Restart Search: Se lo conoce también como una rebúsqueda. Sucede cuando un pedido ya con conductor ejecuta una nueva busqueda de conductor en cada proveedor debido a que el conductor asignado no puede cumplir con el pedido antes de llegar al local. Restart Search se puede disparar en estos escenarios:
  • Proveedor cancela pedido antes de llegar al local
  • Proveedor desasigna un conductor antes de llegar al local
  • Soporte lo ejecuta manualmente en el caso que exista alguna novedad con el conductor del pedido