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.

En este apartado podrás encontrar los endpoints usados para la administración de los locales de tu empresa. Podrás encontrar los endpoints de:

• Create Store
• Update Store
• Get Store
• Get Stores

En este apartado encontraras los endpoints a utilizar para el manejo de webhooks. Podrás encontrar los endpoints de:

• Get Webhooks
• Add Webhooks

Así mismo, podrás encontrar los detalles de los payloads que se envian a los webhooks registrados según cada evento. Los eventos que se devuelven en los webhooks son:

• Driver Assigned
• Update Booking Status

Un Pre-booking es denominada a una plantilla con datos preliminares de un pedido sin los datos del punto final de entrega. Para poder convertirlo en un booking, es necesario que se pueda ingresar la dirección de entrega mediante una url que es retornado al momento de crear o consultar un pre-booking. Una vez ingresada la dirección final, el booking se crea y se inicia automáticamente la búsqueda de un conductor.

En este apartado podrás encontrar todos los endpoints utilizados para poder crear un pre-booking:

• Create Pre-Booking
• Get Pre-Booking
• Cancel Pre-Booking

En este apartado encontrarás todos los endpoints relacionados a los pedidos o bookings. Podras encontrar desde consultas de precios, creación de bookings, consultas y cancelaciones. Los endpoints que puedes encontrar en esta sección son:

• Pre Checkout
• Create Booking
• Get Booking Details
• Get Cancel Reasons
• Cancel Booking
• Start Search

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