← Blog

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:

Structura tabelei custom din SQL Server

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:

Setarea automatizării 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:

Definirea parametrului Payload

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
}