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,
orders/tracking
Digital Orders
orders/redeemed
Bills
bills/created
Products
products/created, products/updated. products/deleted
Invoice
invoice/created
(*) 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
{
  "webhook": {
    "topic" : "orders/created", //REQUIRED
    "address" : "https://whatever.hostname.com/", //REQUIRED
    "authorization" :{  //OPTIONAL    
      "headers" : [{"header1":"value1"}, {"header2":"value2"}], // CUSTOM HEADERS
      "params" : [{"param1":"value1"} , {"param2":"value2"}], //CUSTOM URL PARAMS
      "addressLogin": "https://whatever.hostname.com/token", //CUSTOM URL ADDRESS LOGIN
      "body":{
        "customKey1":"value1",
      }, //CUSTOM BODY 
      "tokenKey": "auth_token", //OBJECT MAPPING FOR RESULT TOKEN
      "expiresKey": "expires_in", //OBJECT MAPPING FOR RESULT TOKEN
      "authType": "oauth", // TYPE OF TOKEN TO BE USED, CAN BE OAUTH OR API KEY
      "tokenType": "Bearer"
    }
  }
}
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
{
  "webhook": {
    "topic" : "orders/created",
    "address" : "https://whatever.hostname.com/", 
    "authorization" :{   
      "headers" : [
        {"Authorization":"Basic xxxxxxxxxxxxxxxxxx"},
        {"Content-Type":"application/x-www-form-urlencoded"}
      ],
      "params" : [],
      "addressLogin": "https://whatever.hostname.com/token", 
      "body":{
        "grant_type":"client_credentials",
      }, 
      "tokenKey": "auth_token", 
      "expiresKey": "expires_in",
      "tokenType": "Bearer",
      "authType": "oauth"
      
    }
  }
}
​
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
{
  "webhook": {
    "topic" : "orders/created",
    "address" : "https://whatever.hostname.com/", 
    "authorization" :{   
      "headers" : [
        {"API-KEY" : "xxX12345xXxKey"},
        {"API-USER" : "username1"},
        {"API-X-FORMAT" : "json"},
      ],
      "params" : null, 
      "addressLogin": null, 
      "body":null, 
      "tokenKey": null, 
      "expiresKey": null, 
      "tokenType": null,
      "authType": "api-key"
    }
  }
}
​
post
https://ventiapi.azurewebsites.net
/api/webhooks/delete
Delete Webhook
Body Parameters
{
  "webhook": {
    "id": 1047897671
  }
}
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:
{
      "orderId": 1234,
      "channel": "meli",
      "dateAdded": "2018-10-29T00:00:00",
      "dateCreated":"2018-10-29T00:00:00",
      "dateModified": "2018-10-29T00:00:00",
      "externalId": "111444123",
      "total": 660.0,
      "currency": "MXN",
      "tax": 0.16,
      "comments": "Send it before tuesday",
      "itemsQuantity": 2,
      "title": "Order Title",
      "internalStatus": 1,
      "amazonFulfillment": "false",
      "cartId": "00000101110002",
      "externalNumber" : "12314512",
      "orderStatus" : "paid",
      "items": [
        {
          "itemExternalId": "MLM3312341",
          "title": "Item 1",
          "price": 460.0,
          "variationId": "13818313",
          "variationName": "Red",
          "itemQuantity": 1,
          "total": 460.0,
          "sku": "ITEM-RED001", //SKU DE VENTIAPP
          "channelSku": "765840002", //SKU DEL CANAL
          "erpId": null,
          "itemStatus": "returned"
        },
        {
          "itemExternalId": "MLM3317841",
          "title": "Item 2",
          "price": 200.0,
          "variationId": null,
          "variationName": null,
          "itemQuantity": 1,
          "total": 200.0,
          "sku": "PLAINITEM001", //SKU DE VENTIAPP
          "channelSku": "765840001", //SKU DEL CANAL
          "erpId": null,
          "itemStatus": null //ESTADO DEL ITEM EN CASO DE CANCELACIONES/DEVOLUCIONES PARCIALES
        }
      ],
      "buyer": {
      "name": "John",
        "lastname": "Doe",
        "email": "[email protected]",
        "state": "Distrito Federal",
        "address": "Street Address 123",
        "city": "Mexico City",
        "zipcode": "06700",
        "nickname": "JOHNDOEVENTI",
        "phone": "5584848152",
        "externalId": "551331413",
        "municipality": "cuahutemoc",
        "neigborhood":"roma sur",
        "billingInfo": { //INFORMACION FISCAL OPCIONAL(DEPENDE DEL CANAL)
           "docType": "DNI",
           "docValue": "123456789"
        }
      },
      "shipping": {
        "sellerInfo": "MYSELLERNAME",
        "sellerId": null,
        "shipmentType": "me2",
        "shippingStatus": "shipped",
        "shippingCourier": "drop_off",
        "shippingId": "27586098188",
        "shippingType": "me2",
        "ventiShipping": false,
        "ventiCourierId": null,
        "shippingTrackingId": "10003313132",
        "shippingCourierExternal": "Fedex Express",
        "shippingCost": 120.0,
        "shippingReceptor": "Juan Dominguez"
      },
      "paymentMethods": [
                {
                    "externalId": "5531048951",
                    "paymentMethod": "oxxo"
                }
            ],
      "accountName" : "MY_MELI_USER"
    }
Digital Orders:
{
      "orderId":1234,
      "externalId": "111444123",
      "message":"Digital Order Redeemed"
      "redeemDate":"2021-10-29T00:00:00"
}
Bills
{
      "orderId": 1234,
      "billingDate": "2018-06-06T00:00:00",
      "externalReference": "14124141",
      "externalDate": "2018-06-06T00:00:00",
      "message": "Billing message",
      "invoice": "0001",
      "total": 660.0,
      "cdfi": "04",
      "bankDigits": "1234",
      "paymentMethod": "03",
      "customer": {
        "name": "John",
        "businessName": "Doe",
        "rfc": "X3XXXXNNX0131",
        "email": "[email protected]",
        "phone": "1139992331",
        "billingAddress": "fake street 123 101",
        "billingStreet": "fake street",
        "billingInnerNumber": "101",
        "billingOuterNumber": "123",
        "billingNeighborhood": "Condesa",
        "billingCountry": "Mexico",
        "billingState": "CDMX",
        "billingMunicipality": "Cuahutemoc",
        "billingZipCode": "06700"
      }
    }
Products:
{
    "productId": 3182093,
    "sku": "AA123",
    "price": 99.99,
    "title": "Olla a presion Gris",
    "ean": null,
    "upc": "41123123",
    "longDescription": "Descripcion larga de prueba",
    "shortDescription": "Descripción corta de prueba",
    "baseStock": 66,
    "images": ["url imagen 1","url imagen 2"],
    "brand": "Greycon",
    "weight": 2400,
    "height": 30,
    "width": 20,
    "depth": 20
}
Invoice:
{
    "invoice_type": "factura",
    "folio": "99999",
    "url_pdf": "https://url/qmxbyo8bkm0e_factura_meli_99999.pdf",
    "url_xml": "https://url/qmxbyo8bkm0e_factura_meli_99999.xml",
    "guid": "1234ABC5-D6EF-7C8F-9G90-01H23I456J7K",
    "serie": "ML",
    "receptor": {
        "rfc": "ABCD01012020XX",
        "razon_social": "S.A DE CV"
    },
    "ventas_asociadas": [
        "2000021321456"
    ]
}
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 en caso de asignación de un envío, al popularse la información del envío este webhook se dispara por única vez. Las órdenes que contengan el estado buffered también se notificarán.
Orders/Tracking
Este webhook actualmente se encuentra habilitado en caso de que la información de tracking de una órden esté completa. En el caso de envíos que tengan información retrasada (ej. Mercado Libre con estado buffered) la notificación se disparará hasta que se complete dicha información. Es recomendable utilizar este webhook para saber en que momento la guía de envío se encuentra disponible para impresión
Invoice/Created
Este webhook se encuentra habilitado para los casos donde se genera un documento fiscal relacionado con la orden. 
​
​
Ventas
Límite de Uso
Última actualización 10d ago
Evento	Topics
Orders	orders/created, orders/updated, orders/cancelled, orders/billing, orders/returned, orders/shipment, orders/tracking
Digital Orders	orders/redeemed
Bills	bills/created
Products	products/created, products/updated. products/deleted
Invoice	invoice/created