Webhooks

Buscar…
Webhooks
En esta sección contiene la documentación sobre los Webhooks que brinda Ventiapp. Qué son, cuales hay disponibles, cómo crearlos y eliminarlos
Que es un Webhook ?
Los webhooks son una herramienta para recuperar y almacenar datos de un evento determinado. Te permiten registrar una URL https:// a la cual Ventiapp estaría llamando cuando el evento registrado se dispare. Estos son los eventos que contamos con webhook:
Evento
Topics
Orders
orders/created, orders/updated, orders/cancelled, orders/billing, orders/returned
orders/shipment
Digital Orders
orders/redeemed
Bills
bills/created
Products
products/created, products/updated. products/deleted
(*) Más eventos próximamente
Métodos de API
get
https://ventiapi.azurewebsites.net
/api/webhooks/list
List Webhooks
post
https://ventiapi.azurewebsites.net
/api/webhooks/create
Create Webhook
Body Parameters
1
{
2
  "webhook": {
3
    "topic" : "orders/created", //REQUIRED
4
    "address" : "https://whatever.hostname.com/", //REQUIRED
5
    "authorization" :{  //OPTIONAL    
6
      "headers" : [{"header1":"value1"}, {"header2":"value2"}], // CUSTOM HEADERS
7
      "params" : [{"param1":"value1"} , {"param2":"value2"}], //CUSTOM URL PARAMS
8
      "addressLogin": "https://whatever.hostname.com/token", //CUSTOM URL ADDRESS LOGIN
9
      "body":{
10
        "customKey1":"value1",
11
      }, //CUSTOM BODY 
12
      "tokenKey": "auth_token", //OBJECT MAPPING FOR RESULT TOKEN
13
      "expiresKey": "expires_in", //OBJECT MAPPING FOR RESULT TOKEN
14
      "authType": "oauth", // TYPE OF TOKEN TO BE USED, CAN BE OAUTH OR API KEY
15
      "tokenType": "Bearer"
16
    }
17
  }
18
}
Copied!
Funcionamiento de Authorization (beta)
Actualmente el body de authorization tiene dos maneras distintas de operar, este campo se define en authType
oauth:
Esta funcionalidad generará un token contra el endpoint deseado, el token obtenido se utilizará para el posteo de todos los topics en el webhook definido
Headers: Contiene la información requerida para hacer login contra el endpoint OAuth que generará el token.
Params: Contiene los parámetros que deben ir a nivel de URL en el endpoint definido.
AddressLogin: URL del endpoint definido para generar tokens
Body: Cuerpo de la llamada que se enviará como POST al endpoint definido
TokenKey: Clave (nombre del objeto) donde se retornará el token OAUTH. Ej: "access_token"
ExpiresKey: Clave (nombre del objeto) donde se retornará la duración de vida en segundos del token
TokenType: Tipo de token y como se consumirá, ej: Bearer, Token, Basic.

Ejemplo
1
{
2
  "webhook": {
3
    "topic" : "orders/created",
4
    "address" : "https://whatever.hostname.com/", 
5
    "authorization" :{   
6
      "headers" : [
7
        {"Authorization":"Basic xxxxxxxxxxxxxxxxxx"},
8
        {"Content-Type":"application/x-www-form-urlencoded"}
9
      ],
10
      "params" : [],
11
      "addressLogin": "https://whatever.hostname.com/token", 
12
      "body":{
13
        "grant_type":"client_credentials",
14
      }, 
15
      "tokenKey": "auth_token", 
16
      "expiresKey": "expires_in",
17
      "tokenType": "Bearer",
18
      "authType": "oauth"
19
      
20
    }
21
  }
22
}
Copied!
​
api-key:
Esta funcionalidad utilizará un set de API-KEYs definido en el nivel Headers, estos mismos se almacenarán y utilizarán para consumir al webhook definido
Headers: Contiene la información requerida para autenticarse contra el URL definido. 
Ejemplo
1
{
2
  "webhook": {
3
    "topic" : "orders/created",
4
    "address" : "https://whatever.hostname.com/", 
5
    "authorization" :{   
6
      "headers" : [
7
        {"API-KEY" : "xxX12345xXxKey"},
8
        {"API-USER" : "username1"},
9
        {"API-X-FORMAT" : "json"},
10
      ],
11
      "params" : null, 
12
      "addressLogin": null, 
13
      "body":null, 
14
      "tokenKey": null, 
15
      "expiresKey": null, 
16
      "tokenType": null,
17
      "authType": "api-key"
18
    }
19
  }
20
}
Copied!
​
post
https://ventiapi.azurewebsites.net
/api/webhooks/delete
Delete Webhook
Body Parameters
1
{
2
  "webhook": {
3
    "id": 1047897671
4
  }
5
}
Copied!
Que envía el webhook ?
El webhook notificará a la URL que fue asignada un objeto de acuerdo al evento que se haya elegido.
Orders:
1
{
2
      "orderId": 1234,
3
      "channel": "meli",
4
      "dateAdded": "2018-10-29T00:00:00",
5
      "dateCreated":"2018-10-29T00:00:00",
6
      "dateModified": "2018-10-29T00:00:00",
7
      "externalId": "111444123",
8
      "total": 660.0,
9
      "currency": "MXN",
10
      "tax": 0.16,
11
      "comments": "Send it before tuesday",
12
      "itemsQuantity": 2,
13
      "title": "Order Title",
14
      "internalStatus": 1,
15
      "amazonFulfillment": "false",
16
      "cartId": "00000101110002",
17
      "externalNumber" : "12314512",
18
      "orderStatus" : "paid",
19
      "items": [
20
        {
21
          "itemExternalId": "MLM3312341",
22
          "title": "Item 1",
23
          "price": 460.0,
24
          "variationId": "13818313",
25
          "variationName": "Red",
26
          "itemQuantity": 1,
27
          "total": 460.0,
28
          "sku": "ITEM-RED001", //SKU DE VENTIAPP
29
          "channelSku": "765840002", //SKU DEL CANAL
30
          "erpId": null,
31
          "itemStatus": "returned"
32
        },
33
        {
34
          "itemExternalId": "MLM3317841",
35
          "title": "Item 2",
36
          "price": 200.0,
37
          "variationId": null,
38
          "variationName": null,
39
          "itemQuantity": 1,
40
          "total": 200.0,
41
          "sku": "PLAINITEM001", //SKU DE VENTIAPP
42
          "channelSku": "765840001", //SKU DEL CANAL
43
          "erpId": null,
44
          "itemStatus": null //ESTADO DEL ITEM EN CASO DE CANCELACIONES/DEVOLUCIONES PARCIALES
45
        }
46
      ],
47
      "buyer": {
48
      "name": "John",
49
        "lastname": "Doe",
50
        "email": "[email protected]",
51
        "state": "Distrito Federal",
52
        "address": "Street Address 123",
53
        "city": "Mexico City",
54
        "zipcode": "06700",
55
        "nickname": "JOHNDOEVENTI",
56
        "phone": "5584848152",
57
        "externalId": "551331413",
58
        "municipality": "cuahutemoc",
59
        "neigborhood":"roma sur",
60
        "billingInfo": { //INFORMACION FISCAL OPCIONAL(DEPENDE DEL CANAL)
61
           "docType": "DNI",
62
           "docValue": "123456789"
63
        }
64
      },
65
      "shipping": {
66
        "sellerInfo": "MYSELLERNAME",
67
        "sellerId": null,
68
        "shipmentType": "me2",
69
        "shippingStatus": "shipped",
70
        "shippingCourier": "drop_off",
71
        "shippingId": "27586098188",
72
        "shippingType": "me2",
73
        "ventiShipping": false,
74
        "ventiCourierId": null,
75
        "shippingTrackingId": "10003313132",
76
        "shippingCourierExternal": "Fedex Express",
77
        "shippingCost": 120.0,
78
        "shippingReceptor": "Juan Dominguez"
79
      },
80
      "paymentMethods": [
81
                {
82
                    "externalId": "5531048951",
83
                    "paymentMethod": "oxxo"
84
                }
85
            ],
86
      "accountName" : "MY_MELI_USER"
87
    }
Copied!
Digital Orders:
1
{
2
      "orderId":1234,
3
      "externalId": "111444123",
4
      "message":"Digital Order Redeemed"
5
      "redeemDate":"2021-10-29T00:00:00"
6
}
Copied!
Bills
1
{
2
      "orderId": 1234,
3
      "billingDate": "2018-06-06T00:00:00",
4
      "externalReference": "14124141",
5
      "externalDate": "2018-06-06T00:00:00",
6
      "message": "Billing message",
7
      "invoice": "0001",
8
      "total": 660.0,
9
      "cdfi": "04",
10
      "bankDigits": "1234",
11
      "paymentMethod": "03",
12
      "customer": {
13
        "name": "John",
14
        "businessName": "Doe",
15
        "rfc": "X3XXXXNNX0131",
16
        "email": "[email protected]",
17
        "phone": "1139992331",
18
        "billingAddress": "fake street 123 101",
19
        "billingStreet": "fake street",
20
        "billingInnerNumber": "101",
21
        "billingOuterNumber": "123",
22
        "billingNeighborhood": "Condesa",
23
        "billingCountry": "Mexico",
24
        "billingState": "CDMX",
25
        "billingMunicipality": "Cuahutemoc",
26
        "billingZipCode": "06700"
27
      }
28
    }
Copied!
Products:
1
{
2
    "productId": 3182093,
3
    "sku": "AA123",
4
    "price": 99.99,
5
    "title": "Olla a presion Gris",
6
    "ean": null,
7
    "upc": "41123123",
8
    "longDescription": "Descripcion larga de prueba",
9
    "shortDescription": "Descripción corta de prueba",
10
    "baseStock": 66,
11
    "images": ["url imagen 1","url imagen 2"],
12
    "brand": "Greycon",
13
    "weight": 2400,
14
    "height": 30,
15
    "width": 20,
16
    "depth": 20
17
}
Copied!
Notas importantes
Variación de la información
La información que viaja por los webhooks es completamente dinánica, es decir, es posible que varios campos cambien de información, inclusive los carritos de compra. Esto depende de la información que nos informa cada canal de ventas.
Es MUY RECOMENDADO que se implementen los webhooks de actualización de ordenes ya que en estos la información puede que tenga mucha variación. 
Ejemplos de cambios de información:
Cambios de información de Shipping
Cambios en el carrito (items)
Cambios en costos de envío
Cambios de estado de orden
Cambios de estado de shipping
Otro ejemplo muy importante, es cuando se generra la orden en primera instancia, es probable que no tenga guía de shipping ni información de shipping hasta unos varios minutos luego, en los cuales se disparará una actualización de orden.
Carrito de Mercado Libre
Mercado Libre hace separación de ordenes del mismo carrito en varias llamadas. Es por eso que viene el campo cartId para que se pueda adaptar una agrupación desde el lado del desarrollo.
Compras de Linio
Linio tiene 2 tipos de ID, uno que es el campo Id de la orden dentro de su canal, y otro que se llama Número de la orden. El que figura dentro de Linio Seller Center es el campo Número de la orden, en la API de Ventiapp este campo es externalNumber
Digital Orders
Este tipo de orden solamente aplica para productos digitales, en caso de que el usuario visite la URL que se le envía luego de utilizar el método AddDigitalRedeems se disparará el webhook de orders/redeemed
Orders/Returned
Este webhook actualmente se encuentra habilitado para Mercado Libre en caso de una devolución express. Cuando sucede este tipo de devolución ? Aquí podrás ver Devoluciones Express​
Orders/Shipment
Este webhook actualmente se encuentra habilitado para Mercado Libre en caso de asignación de un envío, al popularse el tracking code del envío este webhook se dispara por única vez
​
​
​
Ventas
Límite de Uso
Última actualización 6mo ago
Copiar enlace
Contenidos
Funcionamiento de Authorization (beta)
post
Delete Webhook
Que envía el webhook ?
Notas importantes