Rivile ERP — automatizavimo scenarijų API (nuoroda)

Rivile ERP — automatizavimo scenarijų API (nuoroda)

Projekto kontekstas: atstovų supažindinimas su automatizavimu ir pritaikymu; organizacija ir formatas — Tema 1 · Įvadas ir planas.

Susiję: trigeriai, įmonės apimtis, eilės ir auditas — rivile-erp-automatizavimo-konceptas.html. Pritaikymo sritys (UI, duomenys, ataskaitos ir kt.) — rivile-erp-customization-konceptas.html.

Viešasis REST API (Swagger UI)

Interaktyvi viešojo API specifikacija: https://erp.rivile.cloud/public-api/swagger-ui/index.html

Oficialus gidas (LT, API raktas, limitai, Postman): rivile-erp-guide-api.html.

Pilna OpenAPI schema (failas): rivile-erp-public-api.openapi.json · santrauka ir autentifikacija — rivile-erp-public-api-overview.html · atnaujinimas su X-SessionToken — fetch-public-openapi.sh.

GraphQL: serverio schema (apžvalga, callAutomation, SessionType, saga) — rivile-erp-graphql-overview.html.

Žemiau šiame faile — automatizavimo scenarijų (JavaScript) funkcijos ir pagalbinės API; išorinė integracija per HTTP dažnai remiasi Swagger aprašu.

---

1. Progresas ir būsena

1.1 Žurnalas (log)

Lygis	Sintaksė
Bendras	logMessage("{message}")
ERROR	log.error("{message}")
WARN	log.warn("{message}")
INFO	log.info("{message}")
DEBUG	log.debug("{message}")
TRACE	log.trace("{message}")

1.2 Automatizavimo užbaigimo būsena

output objekte:

output = {
  // ...
  executionStatus: "WARNING" // optional, default: "SUCCESS"
  // Galimos reikšmės: SUCCESS, WARNING, CANCELED
};

1.3 Apdorotų dokumentų skaičius

Tiesiogiai vykdymo metu:

await setDocumentsCount({integer});

Arba per užbaigimo output:

output = {
  // ...
  documentsCount: 1 // integer, optional
};

1.4 Sesijos likutis

Kiek sekundžių liko iki aktyvaus sesijos / prieigos žetono galiojimo pabaigos:

const remainingSeconds = await getRemainingSessionTime();

---

2. Kiti automatizavimai

const response = await callErpAutomation(
  "childAutomation",
  { param1: "param1", param2: true, param3: 3.14 }
);

Atsakymo struktūra:

• status: SUCCESS | FAILED | CANCELED — užbaigimo būsena
• data: Object arba String — automatizavimo atsakas

---

3. Gama integratorius

invokeGamaIntegrator(types[, filters][, integrationParameters])

3.1 Tipai (1-as parametras — masyvas)

Leidžiami tipai: DEPARTMENT, UOM, PRODUCT_GROUP, CLIENT, PRODUCT, TARE, INVENTORY_STOCK, RECEIPT.

CLIENT, PRODUCT, TARE, INVENTORY_STOCK gali būti perduoti su papildomu filtravimu (objektai su items).

Pavyzdžiai:

await invokeGamaIntegrator([
  "DEPARTMENT", "UOM", "PRODUCT_GROUP", "CLIENT", "PRODUCT",
  "TARE", "INVENTORY_STOCK", "RECEIPT"
]);

await invokeGamaIntegrator([{ type: "CLIENT", items: [123, 456, 789] }]);
await invokeGamaIntegrator([{ type: "PRODUCT", items: ["A1", "B2", "C3"] }]);

3.2 Filtrai (2-as parametras — neprivalomas)

Taikoma tik: CLIENT, PRODUCT, TARE, INVENTORY_STOCK.

Laukai objekte:

Laukas	Aprašymas
type	privaloma — duomenų tipas
lastDateTime	paskutinio atnaujinimo laikas; jei nenurodytas — iš SS-GAMA-INTEGRATOR
where	filtro sąlyga (string)
fromPage	pradinis puslapis (int)
updateLastDateTime	default true — ar atnaujinti sinchronizacijos žymą SS-GAMA-INTEGRATOR

3.3 Integracijos parametrai (3-as parametras — neprivalomas)

{ trimBarcode: Boolean } // default: false

---

4. DataExport paslauga

UI srautas (asinchroninis eksportas / ataskaita su užduotimi, Artemis, Data Mobility, failas): rivile-erp-data-export-async.html.

4.1 Schemų sąrašas

await getDataExportSchemas();

Atsakas: masyvas objektų su id, code, name, neprivaloma: filters, required, groupBy.

4.2 Duomenų eksportas

await fetchExportData("reportTypeId", {
  filters: Object,
  dataSelection: Array[String], // neprivaloma — laukų keliai
  groupBy: String               // neprivaloma
});

Atsakas:

{
  status: "SUCCESS" | "ERROR",
  data: {
    "{entityTypeName}": [ /* ... */ ]
  }
}

Trumpi pavyzdžiai: PRODUCT su filtru type: "SERVICE", LEDGER_ACCOUNT, PAYABLE_RECEIVABLES su datomis, tipais, klientais, valiutomis ir groupBy: "CLIENT".

---

5. Failai: įkėlimas parametruose, skaitymas, vieša nuoroda

5.1 Parametrų schema (failo įkėlimas)

[
  {
    "blockType": "FILEUPLOAD",
    "meta": {
      "fieldName": "fileName",
      "accept": ".xlsx,.json,.csv,.xml"
    }
  }
]

5.2 Duomenys iš failo (HTTP)

const fileDataResponse = await fetchData(undefined, {
  url: initial.fileName.publicLink,
  method: "GET",
  raw: Boolean // false, jei content-type application/**; default: true
});
// fileDataResponse: { body, headers, code }

5.3 Vieša nuoroda į vidinį failą (RQL)

const fileId = "ac7b21e8-2b0f-4f46-8889-c11615e42d1b";
let publicLink = await rql(`SELECT * FROM getPublicLink WITH id = ${fileId}`);
output = {
  message: "Sugeneruotas PublicLink failui",
  publicLink
};

---

6. Programų URL generavimas

Grąžinamos funkcijos, kurios priima neprivalomą konfigūraciją:

• getERPUrl(options) — ERP
• getPOSUrl(options) — POS
• getEmployeePortalUrl(options) — darbuotojų portalas

Parametras	Tipas	Default	Aprašymas
path	string	null	Kelias po baziniu URL
includeOrgCode	boolean	false	Organizacijos kodas kelyje
includeCompanyId	boolean	false	?c=...
queryParams	object	{}	Papildomi query parametrai

---

7. Duomenų parseriai (dataParser)

Formatas	Funkcija / naudojimas
JSON	JSON.parse(fileDataResponse.body)
CSV	dataParser.csvToJson(body, { valuesSeparator, rowsSeparator, firstRowHeaders })
XML	await dataParser.xmlToJson(body)
Excel	await dataParser.excelToJson(body) arba excelSheetToJson(body, sheetIndex, headersRow)
Base64	toBase64 / fromBase64; dvejetainiams: base64ToBuffer, bufferToBase64

---

8. FileManagement: įkėlimas ir atsisiuntimas

8.1 fileService.uploadFile(fileContent, fileName, options)

Svarbiausi laukai: fileType (ATTACHMENT | IMAGE), tags, association (companyId, entityTypeId, refId, refName, clientId, clientCode, clientName), isTemporary, generatePublicLink.

Atsakas turi tarp kitų: id, internalLink, publicLink, associations, ir kt.

Pavyzdžiai: tekstas, JSON.stringify į .json, CSVBuilder į .csv, XLSX (išplėstas dokumentacijoje).

8.2 Atsisiuntimas

const fileBinary = await fileService.getFileBinaryByLink(fileUrl);
// arba
const fileBinary = await fileService.getInternalFileBinaryById(fileId);
const fileContent = fileBinary.toString("UTF-8");

---

9. Telefono numeris

parsePhoneNumber(phoneNumber, defaultCountry?) // → PhoneNumber | undefined

Nuoroda: libphonenumber-js

---

10. El. paštas ir ataskaitos

10.1 El. laiško šablonas

await mutate(`prepareAndSendEmailTemplate`, {
  request: {
    companyId,           // UUID, privaloma
    templateCode,        // privaloma, jei nėra templateId
    templateId,          // privaloma, jei nėra templateCode
    placeId,             // neprivaloma
    fromEmail,           // neprivaloma
    initialData: {}
  }
});

10.2 Ataskaitos šablonas

• reportingService.prepareReportData({ templateId | templateCode, initialData }) → duomenų objektas
• reportingService.generateReport({ ... }) → { buffer, fileName, contentType }

Pastaba: naudojant generateReport, prepareReportData kviečiama automatiškai.

10.3 Word šablonas

const generatedWordBuffer = await fillWordTemplate(fileBuffer, sourceData?);

Tipinis srautas: getInternalFileBinaryById(templateId) → fillWordTemplate → uploadFile.

---

11. Išplėstiniai laukai

Klasifikatoriaus tipo laukui nustatyti ribojimus, pvz.: { "treeCode": "XX-CLASS" }.

---

Pastabos iš šaltinio

• Gama pavyzdyje lastDateTime formatas: ISO su laiko juosta (pvz. žiemos laikas LT).
• Dokumentacijoje pasitaiko rašybos klaidų (Tempalte ir pan.) — kode naudoti tikrus pavadinimus.