Proceso de autorización

• Esta optimizado para aplicaciones del lado del servidor.
• El código fuente no se expone públicamente.
• Mantiene la confidencialidad del Client Secret.

¿Qué es OAuth2?

Es un marco de autorización que permite a las aplicaciones obtener acceso limitado a cuentas de usuario en un servicio HTTP como Google, Facebook, GitHub, entre otros. 

¿Cómo funciona?

Funciona delegando  la  autenticación  del usuario (Merchant) al servicio que aloja la cuenta (Multivende) y autorizando a las aplicaciones de terceros a  acceder  a  los  datos  de  la  cuenta  del Merchant seleccionando los permisos que desea otorgar.

Roles

• Propietario del recurso - Merchant
• Cliente - Aplicación
• Servidor de recursos - Multivende 
• Servidor de autorización - Multivende

• Proceso de Autorización

1. El Merchant ingresa al sitio web de la aplicación y genera la solicitud de autorización a Multivende.

2. Aplicación redirecciona al Merchant a Multivende enviando por parámetro en la URL:

• "response_type" = code.
• "client_id" = Client ID.
• "redirect_uri" = redirect_uri (Ingresada previamente al crear la aplicación en Multivende).
• "scope"= scopes (Ingresado(s) previamente al crear la aplicación en Multivende).

Ejemplo:

https://app.multivende.com/apps/authorize?response_type=code&client_id=00000000000&redirect_uri=asd&scope=read:checkouts

3. El Merchant selecciona los permisos (scopes) a autorizar para la aplicación. Mas detalles en el artículo Scopes.

4. Multivende genera el código de autorización y redirige al redirect_uri. Enviando:

• code(Código de autorización)

5. Aplicación solicita el access token a Multivende por el endpoint Authenticate OAuth2 Enviando: 

• • client_id.
  • client_secret.
  • grant_type: 'authorization_code'.
  • code.

6. Multivende valida que el authorization code entregado no haya expirado y retornar el access token. La aplicación recibe:

• • token
  • expiresAt
  • refreshToken
  • refreshTokenExpiresAt
  • scopes
  • MerchantId
  • OauthClientId

Response:

  {
    "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status": "created",
    "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "scopes": {
      "read:products": true,
      "write:products": true,
      "read:stocks": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:stocks": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "read:prices": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:prices": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "read:checkouts": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:checkouts": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "read:product_links": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:product_links": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "manage:checkouts": true,
      "manage:product_links": true
    },
    "expiresAt": "2021-03-03T01:45:34.958Z",
    "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "refreshTokenExpiresAt": "2021-03-04T19:45:34.958Z",
    "updatedAt": "2021-03-02T19:45:34.000Z",
    "createdAt": "2021-03-02T19:45:34.000Z",
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }

Se ilustra a continuación en el diagrama del proceso de autorización:

Diagrama del proceso de autorización

• Proceso para actualizar el token

 Para generar un nuevo token se debe solicitar el endpoint Refresh token OAuth2 enviando:

• refresh_token: Generado en el paso anterior. (Proceso de Autorización)
• client_id.
• client_secret.
• grant_type: 'refresh_token'.

Retorna dentro del response:

• token.
• expiresAt.
• refreshToken.
• refreshTokenExpiresAt.
• scopes.
• MerchantId.
• OauthClientId.
  
  

Response:

  {
    "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status": "created",
    "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "scopes": {
      "read:products": true,
      "write:products": true,
      "read:stocks": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:stocks": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "read:prices": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:prices": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "read:checkouts": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:checkouts": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "read:product_links": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "write:product_links": {
        "all": false,
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": true
      },
      "manage:checkouts": true,
      "manage:product_links": true
    },
    "expiresAt": "2021-03-03T01:45:34.958Z",
    "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "refreshTokenExpiresAt": "2021-03-04T19:45:34.958Z",
    "updatedAt": "2021-03-02T19:45:34.000Z",
    "createdAt": "2021-03-02T19:45:34.000Z",
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }

Diagrama proceso de refrescado del token:

Diagrama proceso de refrescado

Importante

• Cada vez que el Merchant otorgue permisos a la aplicación se genera una nueva conexión entre la aplicación y la cuenta del Merchant la cual no sustituye las conexiones anteriores. Por lo que si tu aplicación solo permite una conexión, el Merchant deberá eliminar las conexiones que no de desean usar.
• Se debe encriptar con un algoritmo de clave simétrica el token y refresh token antes de almacenarlo en la base de datos.
  • Y se debe seguir los protocoles establecidos en nuestra sección de Seguridad.
• Tiempos de caducidad:

Equipo Integraciones API Multivende

Cuando se produce un evento en Multivende, se envía una solicitud HTTPS POST a la URL de devolución de llamada (Callback URL) por cada una de las apps de integración que están suscritas a los webhooks. A partir de las notificaciones se puede usar para desencadenar reglas o procesos específicos de la aplicación.

De esta manera, las apps resultan más eficientes, porque identifican cuando se produce un cambio en tiempo real, y, entonces, puede hacer las solicitudes periódicas en un rango de tiempo más amplio a la API para obtener el contenido actualizado.

Los webhooks disponibles son los siguientes:

• Stock: Se notificará los cambios del stock de una versión de un producto por bodega.
• Products: Se notificará que hay un cambio en los detalles o un nuevo producto y sus versiones.
• Product links: Se notificará que hay un cambio en el estado de sincronización del producto con el canal.
• Checkouts: Se notificará que hay una nueva venta, cambios de estados, cambio en el detalle de la venta.*
• Prices: Se notificará los cambios en los precios de una versión de un producto por lista de precio.
• Delivery Orders: Se notificará los cambios de estados en las entregas con despacho a domicilio de una venta.
• Pick Up Orders: Se notificará los cambios de estados en las entregas con retiro en tienda de una venta.

Ejemplo de notificación cambio de checkouts:

{
   "CheckoutId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "MerchantId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "MarketplaceConnectionId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "MerchantAppId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "OauthClient":{
      "_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "client_id":"99631xxxxxxx"
   },
   "resource":"checkouts",
   "attemps":1,
   "received":"2021-04-08T19:55:07.061Z"
}

Más ejemplos de notificaciones (link)

Importante:

• Recomendamos no procesar la notificación (Webhooks) cuando esta se recibe en tu sistema, sino realizarlo de forma asíncrona, implementando un sistema de colas para el procesamiento de las notificaciones.
• Guarda el JSON directamente en algún lugar.
  • Por ejemplo Redis o alguna BBDD.
• El Callback URL se registra al momento de crear la aplicación (Crear tu aplicación).
  • El Callback URL debe poseer certificado SSL válido (HTTPS).
  • El Callback URL no debe poseer validación de token.
  • El tiempo de respuesta de la CallbackURL debe ser menor a 6 segundos.
• Los Webhooks son infinitos, los costos de su operación es por parte de ustedes como desarrolladores.
• Por seguridad deben agregar que solo reciban Request de nuestra IP como Multivende.
• Los webhooks se deben complementar con un polling para disminuir la probabilidad de pérdida de datos.

Equipo Integraciones API Multivende

• “all”: La aplicación tendrá permiso a todos los recursos asociados a ese scope.
• “xxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx”: La aplicación tendrá permiso al _id del recurso asociado al alcance.

Por ejemplo:

El Merchant otorga el alcance “read: stock”. Como el stock varia según la bodega, el Merchant puede seleccionar otorgar acceso a todas sus bodegas o a una/varias bodegas específicas. 

• Permiso encendido para leer el Stock de Todas las sucursales y bodegas:

Response:

{
  "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "created",
  "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantAppId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "scopes": {
    "read:stocks": {
      "all": true
    }
  },
  "expiresAt": "2024-10-15T19:57:26.468Z",
  "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "refreshTokenExpiresAt": "2024-10-17T13:57:26.468Z",
  "updatedAt": "2024-10-15T13:57:26.000Z",
  "createdAt": "2024-10-15T13:57:26.000Z",
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXX........."
}

Si el merchant otorga permisos "all", deberá consultar el endpoint correspondiente según sea el caso para obtener el listado de todos los recursos.

• Permiso para acceder solo a una bodega o sucursal:

Response:

{
  "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "created",
  "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantAppId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "scopes": {
    "read:stocks": {
      "all": false,
      "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": false,
      "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX1234": true // Bodega con acceso
    }
  },
  "expiresAt": "2024-10-15T19:57:26.468Z",
  "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "refreshTokenExpiresAt": "2024-10-17T13:57:26.468Z",
  "updatedAt": "2024-10-15T13:57:26.000Z",
  "createdAt": "2024-10-15T13:57:26.000Z",
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXX........."
}

En este caso en el json del scope el valor del campo “all” es “false” por lo que la aplicación no tiene acceso a todas las bodegas. Pero tiene acceso a la bodega con id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX1234".

• Sin permiso para leer stock de ninguna sucursal o bodega:

Response:

{
  "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "created",
  "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantAppId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "scopes": {
    "read:stocks": {
      "all": false // Ninguna bodega con acceso.
    }
  },
  "expiresAt": "2024-10-15T19:57:26.468Z",
  "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "refreshTokenExpiresAt": "2024-10-17T13:57:26.468Z",
  "updatedAt": "2024-10-15T13:57:26.000Z",
  "createdAt": "2024-10-15T13:57:26.000Z",
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXX........."
}

Tipos de scope:

• Read: Otorga permisos de solo lectura para el scope seleccionado.
• Write: Otorga permisos de escritura para el scope seleccionado.
• Manage: Otorga permisos para administrar(lectura/escritura) los recursos del scope seleccionado de forma global, no permite seleccionar por recurso.

Los diferentes scopes que tenemos disponibles son los siguientes:

• Permisos para consultar/escribir los productos, sus versiones, categorías, color, talla, entre otros. Se otorga acceso global. 
  • •  read:products
    • write:products

• Permisos para consultar/escribir el stock de los productos según las bodegas. Se puede otorgar acceso a global o segmentado.
  • • read:stocks
    • write:stocks

• Permisos para consultar/escribir el precio de los productos según las listas de precios. Se puede otorgar acceso a global o segmentado.
  • • read:prices
    • write:prices

• Permisos para consultar/escribir/administrar las ventas de los diferentes canales de venta. Se puede otorgar acceso a global o segmentado.
  • •  read:checkouts
    • write:checkouts
    • manage:checkouts Este scope se debe habilitar solo para las aplicaciones que son canales de venta.

• Permisos para consultar/escribir/administrar la asociación de una versión de un producto a los diferentes canales de venta. Se puede otorgar acceso a global o segmentado por canal.
  • • read:product_links
    • write:product_links
    • manage:product_links 
      • Este scope se debe habilitar solo para las aplicaciones que son canales de venta.

• Permisos para consultar/escribir/administrar las bodegas que tiene creadas el merchant. Se puede otorgar acceso a global o segmentado.
  • • read:warehouses
    • write:warehouses
    • manage:warehouses
      
      
• Permisos para consultar/escribir/administrar los clientes que tiene creados el merchant. Se puede otorgar acceso a global.
  • • read:clients
    • write:clients
    • manage:clients
      
      
• Permisos para consultar/escribir en las conexiones con couriers que tiene el merchant creada . Se puede otorgar acceso a global o segmentado.
  • • read:couriers
    • write:couriers
      
      
• Permisos para consultar los canales que tiene creados el merchant. Se puede otorgar acceso a global o segmentado.
  
  • • read:channels

• Permisos para generar etiquetas de despacho desde los canales de ventas que permiten esta funcionalidad.
  • • read:channels
    • read:checkouts
    • write:checkouts

Equipo Integraciones API Multivende

Equipo Integraciones API Multivende