Entersoft Ecom Connector: Generic Web Hook API
Introducere
În mod tradițional, API-ul standard al Entersoft oferă două lucruri de bază:
- pe de o parte permite call-uri de tip GET, parametrizate, care să extragă datele din ERP pe baza unui scroller (de exemplu poate expune stocurile disponibile pentru un site);
- pe de altă parte permite importul de informații, pe baza unui XML/JSON (de exemplu importul de comenzi de la site).
Ambele mecanisme funcționează foarte bine și permit schimbul de informații într-un mod standardizat.
Pentru utilizatorii pretențioși, Entersoft a prevăzut și posibilitatea implementării unui mecanism mai avansat, de tip web hook, mecanism care, în principiu:
- permite prin call API (POST) apelul unei automatizări care să aibă drept parametru variabila PostData din call;
- automatizarea poate returna un parametru personalizat (request data).
Existența unui astfel de mecanism permite folosirea Entersoft Ecom Connector pentru funcționalități extraordinare.
Scenariu
Presupunem că dorim să implementăm următorul scenariu: de la o aplicație externă (un site, de exemplu) primim o comandă în următorul format:
{
"orderId": "1234",
"orderDate": "2023-01-05T12:37:56",
"customerData": {
"customerName": "Ion Vasile",
"deliveryAddress": "Bucuresti"
},
"orderNotes": "this is the demo order",
"shippingFee": 12,
"lineItems": [
{
"lineNumber": 1,
"sku": "BS001",
"quantity": 1,
"totalValue": 100
},
{
"lineNumber": 2,
"sku": "BS002",
"quantity": 2,
"totalValue": 200
}
]
}
În cazul procesării cu succes a informației, ne dorim ca API-ul să returneze ceva de genul:
{
"isError": false,
"headerError": [],
"lineError": [],
"erpDocument": {
"GID": "E39CD30B-0791-4292-8260-53489F7A53BD",
"ADCode": "COV-SED-00001",
"customerGID": "E1818D12-51DE-4246-AA98-D8D1A1CE6F10"
}
}
Iar în caz de eroare:
{
"isError": true,
"headerErrors": [
{
"errorCode": 1,
"errorDescription": "invalid customer"
}
],
"lineError": [
{
"lineNumber": 1,
"errorCode": 10,
"errorDescription": "SKU invalid"
},
{
"lineNumber": 3,
"errorCode": 11,
"errorDescription": "stock is missing"
}
],
"erpDocument": {
"GID": null,
"ADCode": null,
"customerGID": null
}
}
Setări de bază
Pentru a începe implementarea avem nevoie de câteva setări inițiale.
În primul rând vom avea nevoie de o tabelă custom în baza de date, pentru a salva informația primită. Structura și formatul sunt la alegerea dezvoltatorului; eu am preferat să am o singură tabelă de forma:

Observați că am pus acolo o coloană numită [sessionGID], pe care o voi folosi pentru a identifica înregistrările create la o rulare a automatizării.
Apoi avem nevoie de un scroller unde punem automatizarea. Nu are importanță ce este în scroller; eu am preferat să îl fac în zona ESGOCompany și să afișeze compania curentă. Astfel mă asigur că întotdeauna va afișa o singură linie.
Apoi am început să definesc automatizarea, care va avea câteva particularități.
În primul rând va trebui să ruleze ca scroller independent:

Apoi, la automatizare, este nevoie să definim un parametru de tip string numit „Payload” (case-sensitive), parametru care va prelua json-ul specificat în body la API:

Primul nod la automatizare: preluare JSON
Facem un nod nou la automatizare, mapat la o entitate oarecare, care are bifat „nu se afișează” și care nu are bifat „Salvare”. La nod adăugăm o acțiune de tip VB Script și începem să scriem codul necesar preluării JSON-ului:
#imports Newtonsoft.JSon
#references Newtonsoft.Json.dll
' stringul care va contine parametrul trimis de API (transmis apoi ca parametru catre automatizare)
' in cazul nostru
dim orderJSON as string = $PayloadParam
' pentru debuging salvam comanda intr-un fisier
System.IO.Directory.CreateDirectory("C:\Temp")
My.Computer.FileSystem.WriteAllText("C:\Temp\orderJSON.txt", orderJSON, false)
' pregatim query update
dim querySQL as string = "insert into demo_ApiOrder"
querySQL = querySQL + "(sessionGID, orderId, orderDate, customerName, deliveryAddress, orderNotes, shippingFee, lineNumber, sku, quantity, totalValue)"
querySQL = querySQL + " values (@sessionGID, @orderId, @orderDate, @customerName, @deliveryAddress, @orderNotes, @shippingFee, @lineNumber, @sku, @quantity, @totalValue)"
dim queryParams As Hashtable = ESResMngr.CreateCIHashTable
' serializam JSON-ul
dim orderObject as ApiOrder = JsonConvert.DeserializeObject(of ApiOrder)(orderJSON)
' incepem sa pregatim parametrii
queryParams("sessionGID") = $var_sessionGID
queryParams("orderId") = orderObject.orderId
queryParams("orderDate") = orderObject.orderDate
queryParams("customerName") = orderObject.customerData.customerName
queryParams("deliveryAddress") = orderObject.customerData.deliveryAddress
queryParams("orderNotes") = orderObject.orderNotes
queryParams("shippingFee") = orderObject.shippingFee
' avem nevoie sa parcurgem linie cu linie
for each li as lineItem in orderObject.lineItems
queryParams("lineNumber") = li.lineNumber
queryParams("sku") = li.sku
queryParams("quantity") = li.quantity
queryParams("totalValue") = li.totalValue
' avem parametrii completati, trimitem query SQL
Me.Session.ExecuteNonQuery(querySQL, queryParams)
next
' aici am terminat primul pas al automatizarii, si anume preluarea informatiei in baza de date
return nothing
' definim aici clasele necesare pentru a descrie JSON-ul
' putem folosi https://jsonutils.com/ pentru asta
#define{
Public Class CustomerData
Public Property customerName As String
Public Property deliveryAddress As String
End Class
Public Class LineItem
Public Property lineNumber As Integer
Public Property sku As String
Public Property quantity As decimal
Public Property totalValue As decimal
End Class
Public Class ApiOrder
Public Property orderId As String
Public Property orderDate As DateTime
Public Property customerData As CustomerData
Public Property orderNotes As String
Public Property shippingFee As decimal
Public Property lineItems As LineItem()
End Class
}