This document describes the methods of data exchange between the Gosbi B2B platform and distributor information systems.

Synchronizations is based in 2 steps:

  • Scheduled (or forced) request for information (WebService B2B requests information from the Distributor WebService)

  • Order Shipping (the WebService B2B sends an order to the Distributor's WebService and the Distributor replies with the generated order ID)

1- Requests

It is required, in order to carry out the transfer of data in an agile and secure way of the following:

  • Fixed IP

  • Enabled WebService to exchange documents in JSON format

2- Communication Protocol

We establish the following communication requirements:

  • communications are made via HTTPS using documents “application/json”

  • User authentication will be using the HTTP 'Authorization' header on all document exchanges.

  • Requests are made using the HTTP verbs ‘GET’ and ‘POST’

3- Authentication

Communications will be validated using a specific token.

This token will be attached in all requests made in the Authorization header with a Bearer token as follows:

example 'GET':

> GET /gosbi/syncros HTTP/1.1

> Authorization: Bearer TaEpGVQeMdrypbLDVFnirUiKXiLlC9Xp4SMMt8CVztg

> POST /gosbi/documents HTTP/1.1

> Authorization: Bearer TaEpGVQeMdrypbLDVFnirUiKXiLlC9Xp4SMMt8CVztg

> Content-Type: application/json

3.1 - Authentication failed:

If the token is not attached, or is not valid, the system returns a 401 and the following document:

{

"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- Constants

For data synchronization between servers (distributor-B2B), is needed to set up constants for the fields: Commercial agent, client, product, province, taxes. For launching just like for each new Gosbi item that the distributor wants to market, an excel file will be provided where the B2B system ID must be related to the deales’s system ID. Below we detail the constants one by one specifying the name of the field to be transmitted in the requests

4.1- Commercial agents

agent_id

String field indicating the trading agent to which the customer belongs. Is considered a group of customers that will serve for the users assignment to client portfolio in the Gosbi CRM. There is no need to fill in with constants the Excel file

4.2- Customers

customer_id

String field indicating the customer. This code is the one that will be sent for the synchronization of each order. To boot, as we already have the client data in our system, it is important to square up Ids in the constant Excel file. New clients won’t do.

4.3 - Products

product_id

String field indicating the product. This code is the one that will be sent for the synchronization of each order. Before marketing a new product through the platform, the distributor shall indicate its unique ID to Gosbi in order for it to enter the constant in the system. To boot it will be done with the constants Excel file.

4.4- Provinces

address_admin2_code

String field indicating the province. To boot it will be done with the constants Excel file.

4.5- Taxes

tribute_customer_id

String field that should be indicated to the synchronization of each client. There are only three options:

  • VAT Value

  • Spain Customers with equivalence surcharge (ESP VAT + RecEq). Value

  • Customers without taxes. Value

5- Synchronization of customer information

Client synchronization will allow the Gosbi B2B platform to have the necessary data so that they have the possibility to place orders through it and so that merchants have access to the CRM with their (portfolio) already segmented.

This synchronisation will be performed with a scheduled task (e.g. daily through cron) or by a manual action via user interface (synchronisation button on the B2B management intranet).

The operation is as follows:

The B2B server sends a request to the distributor server using GET on the connection.

> GET /gosbi/syncros HTTP/1.1

> Authorization: Bearer TaEpGVQeMdrypbLDVFnirUiKXiLlC9Xp4SMMt8CVztg

The answer should be as in the following example:

< HTTP/1.1 200 Ok

< Content-Type: application/json

A similar document to the next one taking into account that the content data will correspond to the real ones for each case.

{

"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

}

]

}

Each model in the customer synchronization document is detailed below.

5.1- Agents

The agents section specifies the commercial agents corresponding to each of the customers specified in the customer section of the same document.

  • id - type: number. Refers to the agent ID in the dealer system.

  • name - type: string. Contains the name of the trading agent.

  • __leaving_date__ - type: date. By default null is required if there is no value. It refers to the unsubscribe date.

5.2 - Payment terms

Payment terms are detailed within payment_terms. These are framed under the following parameters.

  • id - type: number. Refers to the ID of the payment condition on the client system.

  • description - type: string. Description of the payment condition.

5.3 - Business

For the business section we have the following fields, which will refer to the tax figures of customers who may place orders. We differentiate between tax figures and customers (customers) to consider, for example, cases as a company with different points of sale.

  • name - type: string. The fiscal name of the company is indicated in this field.

  • __vat_number__ - type: string. This field indicates the fiscal identifier.

  • address - type: string. Address field.

  • address_admin2_code - type: number. Province ID: constant value to be indicated in the Excel file.

  • address_postal_code - type: string. Postal code field.

  • address_admin3 - type: string. Population field.

5.4 - Customers

For the customers section files are specified below. In this section we will indicate the order recipient data.

  • id - type: number. Refers to the ID of the client, which corresponds to that of the system that sends the documents to Gosbi.

  • name - type: string. The business name of the company is indicated in this field. If you do not have the fiscal name.

  • __vat_number__ - type: string. The fiscal identifier is indicated in this field.

  • address - type: string. The address of the client is indicated in this field. address_admin2_code - type: number. Province id: value -

  • constant to be indicated in the Excel file.

  • address_postal_code - type: string. Zip code field.

  • address_admin3 - type: string. Population field.

  • lat - type: number. Indicates the latidud of the GPS coordinates. If no null.

  • lng - type: number. Indicates length of GPS coordinates. if not available indicate null

  • agent_id - type: number. ID of the customer-related commercial agent.

  • discount_1 - type: number. Discount applicable to the customer.

  • discount_2 - type: number. Discount added, applicable to the customer.

  • leaving_date - type: date. The date of withdrawal of the customer is indicated. tribute_customer_id - type: number. Tax ID: constant value to be indicated in the Excel file. payment_term_id - type: number. Payment term ID.

NOTE: Users will be given access after configuration on the Intranet to which relevant access will be available. There may be more than one user for each customer to contemplate that, for example, different branches from the same company may place orders separately.

6 - Order synchronisation

Order notification will be done via POST requests in real time. The B2B server sends request to the distributor server using POST in connection with a JSON document such as the following:

> POST /gosbi/documents HTTP/1.1

> Authorization: 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"

}

The response must indicate that the document has been inserted correctly and return the generated ID to the system.

< HTTP/1.1 201 Created

< Content-Type: application/json

{"id":"234038"}

Important: Until this response ID is received, the B2B server will repeat the POST indefinitely from time to time (minutes). The distributor server must not duplicate this entry, simply return your ID.

6.1 - Order Document Detail

Below are details of the different elements that make up an order document.

  • document_date - type: date. Order creation date is sent.

  • gosbi_document_id - type: number. This identifier is the one that will have the order in the Gosbi B2B platform. It will serve to maintain a traceability and to be able to resolve possible conflicts.

  • customer_id - type: number. ID of the customer to whom the order corresponds. * document_lines - set of order lines.

  • global_discount_1 - type: number. Discount to be applied to the order if the figure contemplates it.

  • global_discount_2 - type: number. Added discount, which will apply to the product if the figure contemplates it.

  • payed - type: boolean. We will indicate if the order has been paid through the online payment platform.

  • doc_text - type: string. This text field corresponds to the field of observations that the user can fill in at the time of placing the order.

  • For each line will exist:

  • product_id - type: number. Correspond to product ID for this line. *

  • product_description - type: string. Corresponds to the product description.

  • quantity - type: number. Units corresponding to the product. In the case of boxes, the product ID will correspond to the box.

  • price - type: number. Price corresponding to the product.

  • line_discount_1 - type: number. Discount to be applied to the product if the figure so provides.

  • line_discount_2 - type: number. Added discount, which will be applied to the product if the figure contemplates it.

* The different IDs mentioned will correspond to the ID value of the client’s system.

7 - Formats

We refer to the formats that have to be preserved, for each of the transmitted data.

7.1 - Number

It is the numerical format, it can be integer or with fractions (4 or 4.1) being the fraction mark one point (.). Very importantly, when a number is expected, it does not have to be encapsulated in quotation marks, whether single or double.

7.2 - String

We indicate any string, delivered in quotation marks.

7.3 - Boolean

The values supported for attributes of this type will be true and false.

7.4 - Date

Dates shall be formatted in accordance with ISO 8601: e.g. for: 2020-01-20T15:39:29Z We will use the universal time variant (UTC) thus avoiding problems with summer/winter time.

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

ACEPTAR
Aviso de cookies