Gosbi Sincro B2B vía WebService

En este documento se describen los métodos de intercambio de datos entre la plataforma B2B Gosbi y los sistemas de información de los distribuidores.

La sincronización se basa en 2 pasos:

  • Petición programada (o forzada) de información (el WebService B2B pide información al WebService del distribuidor)
  • Envío de pedido (el WebService B2B envía un pedido al WebService del distribuidor y este contesta con la ID de pedido generada)

1 - Requisitos

Se requiere, para poder realizar la transferencia de datos de forma ágil y segura de lo siguiente:

  • IP fija
  • WebService habilitado para intercambiar documentos en formato JSON.

2 - Protocolo de comunicación

Establecemos para la comunicación los siguientes requisitos:

  • Las comunicaciones son vía HTTPS usando documentos 'application/json'
  • La autenticación de usuario será mediante la cabecera HTTP 'Authorization' en todos los intercambios de documentos.
  • Las peticiones son usando los verbos HTTP 'GET' y HTTP 'POST'. Esto implica la necesidad de un servidor web con IP fija pública capaz de gestionar conexiones SSL.

3 - Autenticación

Se validarán las comunicaciones mediante un token específico.

Este token estará adjunto en todas las peticiones que se realicen en la cabecera Authorization con un Bearer token de la siguiente forma:

ejemplo 'GET':

> GET /gosbi/syncros HTTP/1.1
> Authentication: Bearer TaEpGVQeMdrypbLDVFnirUiKXiLlC9Xp4SMMt8CVztg
> POST /gosbi/documents HTTP/1.1
> Authentication: Bearer TaEpGVQeMdrypbLDVFnirUiKXiLlC9Xp4SMMt8CVztg
> Content-Type: application/json

3.1 - Autenticación fallida

En el caso de no adjuntar el token , o uno no válido, el sistema devuelve un 401 y el siguiente documento.

{
  "msg": "The server could not verify that you are authorized to access the URL requested. You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required.",
  "code": 401
}

4 - Constantes

Para la sincronización de datos entre servidores (distribuidor - B2B), es necesario un establecimiento de constantes para los campos: Agente comercial, cliente, producto, provincia, impuestos. Para la arrancada igual que para cada artículo nuevo de Gosbi que el distribuidor quiera comercializar, se facilitará un archivo excel dónde debe casarse la ID del sistema B2B con la ID del sistema del distribuidor. A continuación detallamos las constantes una a una especificando el nombre del campo que debe transmitirse en las peticiones:

4.1 - Agentes comerciales

agent_id

Campo tipo string que indica el agente comercial al que "pertenece" el cliente. Se considera una agrupación de clientes que servirá para la asignación de usuarios a carteras de clientes en el CRM de Gosbi. No hace falta rellenar el fichero Excel de constantes.

4.2 - Clientes

customer_id

Campo tipo string que indica el cliente. Dicho código es el que se enviará para la sincronización de cada pedido. Para arrancar, cómo ya tenemos los datos de clientes en nuestro sistema, es importante cuadrar Ids en el fichero Excel de constantes. Por clientes nuevos no hará falta.

4.3 - Productos

product_id

Campo tipo string que indica el producto. Dicho código es el que se enviará para la sincronización de cada pedido. Antes de comercializar un producto nuevo a través de la plataforma, el distribuidor deberá indicar su ID único a Gosbi para que este entre la constante en el sistema. Para arrancar se hará con el fichero Excel de constantes.

4.4 - Provincias

address_admin2_code

Campo tipo string que indica la província. Para arrancar se hará con el fichero Excel de constantes.

4.5 - Impuestos

tribute_customer_id

Campo tipo string que se debe indicar a la sincronización de cada cliente. Sólo dos opciones:

  • IVA España
  • Clientes con recargo de equivalencia (IVA ESP + RecEq)

5 - Sincronización de información de clientes

La sincronización de clientes permitirá que la plataforma Gosbi B2B disponga de los datos necesarios para que éstos, tengan la posibilidad de realizar los pedidos a través de ella y para que los comerciales tengan acceso al CRM con su cartera ya segmentada.

Esta sincronización se realizará con una tarea programada (p. ej.: diariamente mediante cron) o bien mediante una acción manual vía interfaz de usuario (botón de sincronización en la intranet de gestión B2B). El funcionamiento es el siguiente:

El servidor B2B envia petición al servidor des distribuidor utilizando GET en la conexión.

> GET /gosbi/syncros HTTP/1.1
> Authentication: Bearer TaEpGVQeMdrypbLDVFnirUiKXiLlC9Xp4SMMt8CVztg

La respuesta debe ser como en el siguiente ejemplo.

< HTTP/1.1 200 Ok
< Content-Type: application/json

Un documento igual que el siguiente teniendo en cuenta que los datos de contenido corresponderán a los reales para cada caso.

    {
        "agents": [
            {
                "id": 1,
                "name": "AGENTE COMERCIAL 1",
                "leaving_date": null
            },
            {
                "id": 2,
                "name": "AGENTE COMERCIAL 2",
                "leaving_date": null
            }
        ],
        "payment_terms": [
            {
                "id": 1,
                "description": "Recibo bancario 10 días"
            },
            {
                "id": 2,
                "description": "Transferencia 10,20"
            }
        ],
        "business": [
            {
                "name": "NOMBRE FISCAL EMPRESA 1",
                "vat_number": "B17777777",
                "address": "C. FEERMIN BURUBUGA 3",
                "address_admin2_code": 28,
                "address_postal_code": "28034",
                "address_admin3": "Madrid"
            },
            {
                "name": "NOMBRE FISCAL EMPRESA 1",
                "vat_number": "B17777779",
                "address": "C. FONCALADA, 19",
                "address_admin2_code": 788,
                "address_postal_code": "33002",
                "address_admin3": "Oviedo"
            }
        ],
        "customers": [
            {
                "id": 2500,
                "name": "NOMBRE COMERCIAL (EN SU DEFECTO NOMBRE FISCAL)  1",
                "vat_number": "B17777777",
                "address": "C. PLANETA VENUS (LOCAL 2), 10",
                "address_admin2_code": 28,
                "address_postal_code": "28983",
                "address_admin3": "Parla",
                "lat": 41.62144937,
                "lng": 2.29290548,
                "agent_id": 2,
                "discount_1": 5,
                "discount_2": 0,
                "leaving_date": null,
                "tribute_customer_id": 1,
                "payment_term_id": 1
            },
            {
                "id": 3518,
                "name": "NOMBRE COMERCIAL (EN SU DEFECTO NOMBRE FISCAL) 2",
                "vat_number": "B17777779",
                "address": "Pl. ANTONIO BELO, 4",
                "address_admin2_code": 28,
                "address_postal_code": "28707",
                "address_admin3": "San Sebastián de los Reyes",
                "lat": null,
                "lng": null,
                "agent_id": 1,
                "discount_1": 0,
                "discount_2": 0,
                "leaving_date": "2017-11-27T00:00:00Z",
                "tribute_customer_id": 1,
                "payment_term_id": 2
            }
        ]
    }

A continuación se detallan cada uno de los modelos del documento de sincronización de clientes.

5.1 - Agents

En el apartado agents se especifican los agentes comerciales correspondientes a cada uno de los clientes especificados en el aparado de customers del mismo documento .

  • id - tipo: number. Hace referencia a la ID del agente en el sistema del distribuidor.
  • name - tipo: string. Contiene el nombre del agente comercial.
  • __leaving_date__ - tipo: fecha. Por defecto se requiere null si no hay valor. Hace referencia a la fecha de baja.

5.2 - Payment terms

Dentro de payment_terms se detallan las condiciones de pago. Estas quedan enmarcadas bajo los siguientes parámetros.

  • id - tipo: number. Hace referencia a la ID de la condición de pago en el sistema cliente.
  • description - tipo: string. Descripción de la condición de pago.

5.3 - Business

Para el apartado business disponemos de los siguientes campos, los cuales harán referencia a las figuras fiscales de los clientes que podrán realizar pedidos. Diferenciamos entre figuras fiscales y clientes (customers) para contemplar, por ejemplo, casos como una empresa que disponga de distintos puntos de venta.

  • name - tipo: string. Se indica en este campo el nombre fiscal de la empresa.
  • __vat_number__ - tipo: string. Se indica en este campo el identificador fiscal.
  • address - tipo: string. Campo de dirección.
  • address_admin2_code - tipo: number. ID de provincia: valor constante que se nos indicará en el fichero Excel.
  • address_postal_code - tipo: string. Campo de código postal.
  • address_admin3 - tipo: string. Campo de población.

5.4 - Customers

Para el bloque customers se especifican los campos a continuación. En esta sección indicaremos los datos del destinatario del pedido.

  • id - tipo: number. Hace referencia a la ID del cliente, que se corresponde a la del sistema que envía los documentos a Gosbi.
  • name - tipo: string. Se indica en este campo el nombre comercial de la empresa. Si no tiene indicaremos el nombre fiscal.
  • __vat_number__ - tipo: string. Se indica en este campo el identificador fiscal.
  • address - tipo: string. Se indica en este campo la dirección del cliente.
  • address_admin2_code - tipo: number. ID de provincia: valor - constante que se nos indicará en el fichero Excel.
  • address_postal_code - tipo: string. Campo de código postal.
  • address_admin3 - tipo: string. Campo de población.
  • lat - tipo: number. Indica la latidud de las coordenadas de GPS. Si no se dispone indicar null.
  • lng - tipo: number. Indica la longitud de las coordenadas de GPS. si no de dispone indicar null.
  • agent_id - tipo: number. ID del agente comercial relacionado con el cliente.
  • discount_1 - tipo: number. Descuento aplicable al cliente.
  • discount_2 - tipo: number. Descuento añadido, aplicable al cliente.
  • leaving_date - tipo: fecha. Se indica la fecha de baja del cliente.
  • tribute_customer_id - tipo: number. ID de impuestos: valor constante que se nos indicará en el fichero Excel.
  • payment_term_id - tipo: number. ID de término de pago.

    NOTA: Se dará acceso a los usuarios previa configuración en la Intranet a la que se dispondrá del acceso pertinente. Podrá existir más de un usuario para cada customer para contemplar que por ejemplo, que distintos ATV's puedan realizar pedidos por separado.

6 - Sincronización de pedidos

La notifiación de pedidos se realizará mediante peticiones POST en tiempo real.

El servidor B2B envia petición al servidor del distribuidor utilizando POST en la conexión con un documento json como el siguiente:

> POST /gosbi/documents HTTP/1.1
> Authentication: Bearer TaEpGVQeMdrypbLDVFnirUiKXiLlC9Xp4SMMt8CVztg
{
    "document_date": "2019-12-13T15:59:27Z",
    "gosbi_document_id": 15,
    "customer_id": "3437",
    "document_lines": [
        {
            "product_id": "4457",
            "product_description": "GOSBI EXCLUSIVE GRAIN FREE PUPPY 500g",
            "quantity": 1,
            "price": 2.92,
            "line_discount_1": 5,
            "line_discount_2": 0
        },
        {
            "product_id": "3730",
            "product_description": "GOSBI EXCLUSIVE GRAIN FREE PUPPY 3Kg",
            "quantity": 168,
            "price": 13.8,
            "line_discount_1": 5,
            "line_discount_2": 0
        }
    ],
    "global_discount_1": 0,
    "global_discount_2": 0,
    "payed": false,
    "doc_text": "por favor, servir durante la mañana que esta semana no estamos por las tardes"
}

La respuesta debe indicar que se ha insertado el documento correctamente y devolver la ID generada en el sistema.

< HTTP/1.1 201 Created
< Content-Type: application/json
{"id":"234038"}

Importante: Mientras no se reciba este ID de respuesta, el servidor B2B repetirá el POST indefinidamente cada cierto tiempo (minutos). El servidor distribuidor no debe duplicar esta entrada, simplemente devolver su ID.

6.1 - Detalle del documento de pedido

A continuación se detallan los distintos elementos que conforman un documento de pedido.

  • document_date - tipo: fecha. Se envía la fecha de creación de pedido.
  • gosbi_document_id - tipo: number. Este identificador es el que tendrá el pedido en la plataforma Gosbi B2B. Servirá para mantener una trazabilidad y poder resolver posibles conflictos.
  • customer_id - tipo: number. ID del cliente al que corresponde el pedido. *
  • document_lines - conjunto de líneas de pedido.
  • global_discount_1 - tipo: number. Descuento que se aplicará al pedido si la figura lo contempla.
  • global_discount_2 - tipo: number. Descuento añadido, que se aplicará al producto si la figura lo contempla.
  • payed - tipo: boolean. Indicaremos si el pedido se ha pagado a través de la plataforma de pago online.
  • doc_text - tipo: string. Este campo de texto corresponde al campo de observaciones que el usuario puede rellenar en el momento de realizar el pedido.

Para cada línea existirá:

  • product_id - tipo: number. Corrsesponde a la ID del producto para esta línea. *
  • product_description - tipo: string. Corresponde a la descripción de producto.
  • quantity - tipo: number. Unidades correspondiente al producto. Si se tratan de cajas, la ID de producto corresponderá a la caja.
  • price - tipo: number. Precio correspondiente al producto.
  • line_discount_1 - tipo: number. Descuento que se aplicará al producto si la figura lo contempla.
  • line_discount_2 - tipo: number. Descuento añadido, que se aplicará al producto si la figura lo contempla.

* Las distintas ID mencionadas corresponderán al valor ID del sistema del cliente.

7 - Formatos

Nos referimos a los formatos que se tienen que preservar, para cada uno de los datos transmitidos.

7.1 - Number

Es el formato numérico, puede ser entero o con fracciones (4 o 4.1) siendo la marca de fracción un punto (.). Muy importante, cuando se espere un número, no se tiene que encapsular dentro de comillas, sean simples o dobles.

7.2 - String

Indicamos string cualquier cadena de caracteres, entregada entre comillas.

7.3 - Boolean

Los valores admitidos para los atributos de este tipo serán true y false.

7.4 - Fecha

Las fechas tendrán el formato siguiendo la norma ISO 8601: p. ej.: 2020-01-20T15:39:29Z Utilizaremos la variante de hora universal (UTC) evitando así problemas con el horario de verano/invierno.

Al utilizar nuestros servicios aceptas el uso que hacemos de las cookies

ACEPTAR
Aviso de cookies