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

List Webhooks

GET https://ventiapi.azurewebsites.net/api/webhooks/list

Listado de webhooks, nos retornará una lista con los webhooks activos en Ventiapp

Headers

Name	Type	Description
Authorization	string	Bearer + token
Content-Type	string	application/json

Name

Type

Description

Authorization

string

Bearer + token

Content-Type

string

application/json

{
  "webhooks": [
    {
      "id": 1047897671,
      "address": "https://whatever.hostname.com/",
      "topic": "orders/created",
      "created_at": "2020-03-04T12:36:24-05:00",
      "api_version": "1.0.9"
    },
    {
      "id": 1047897673,
      "address": "https://whatever.hostname.com/",
      "topic": "orders/updated",
      "created_at": "2020-03-04T12:38:24-05:00",
      "api_version": "1.0.9"
    },
    {
      "id": 1047897678,
      "address": "https://whatever.hostname.com/",
      "topic": "bills/created",
      "created_at": "2020-03-04T12:39:24-05:00",
      "api_version": "1.0.9"
    },
  ]
}

Create Webhook

POST https://ventiapi.azurewebsites.net/api/webhooks/create

Creación de Webhook, aquí debemos enviar los siguientes datos para que se cree un webhook en Ventiapp. Es obligatorio que la url sea en https:// Este responderá con el ID del webhook, importante para poder eliminarlo.

Headers

Name	Type	Description
Authorization	string	Bearer + token
Content-Type	string	application/json

Name

Type

Description

Authorization

string

Bearer + token

Content-Type

string

application/json

{
  "webhook": {
    "id": 1047897671,
    "address": "https://whatever.hostname.com/",
    "topic": "orders/create",
    "created_at": "2020-03-04T12:38:24-05:00",
    "api_version": "1.0.9",
    "message": "Webhook created"
  }
}

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

Delete Webhook

POST https://ventiapi.azurewebsites.net/api/webhooks/delete

Eliminación de Webhook, aquí debemos el ID del webhook a eliminar Bearer + token

Headers

Name	Type	Description
Content-Type	string	application/json

Name

Type

Description

Content-Type

string

application/json

{
  "webhook": {
    "id": 1047897671,
    "address": "https://whatever.hostname.com/",
    "topic": "orders/create",
    "created_at": "2020-03-04T12:38:24-05:00",
    "api_version": "1.0.9",
    "message": "Webhook deleted"
  }
}

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@api.com",
        "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": "billing@test.com",
        "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.

AnteriorVentas SiguienteLímite de Uso

Última actualización hace 1 año