Rivile ERP API — gido santrauka (guide.rivile.cloud)

Rivile ERP API — gido santrauka (guide.rivile.cloud)

Šaltiniai (parsisiųsta / nuorodos):

Šaltinis URL
Pagrindinis API puslapis https://guide.rivile.cloud/api
Integracijos → API (analogiškas turinys) https://guide.rivile.cloud/integrative_solutions/api
API raktai https://guide.rivile.cloud/integrative_solutions/api/api_key
API naudojimo būdai https://guide.rivile.cloud/integrative_solutions/api/api_usage
Postman https://guide.rivile.cloud/integrative_solutions/api/api_postman

Techninė pastaba: gidas talpinamas GravCMS svetainėje; /api adresas grąžina HTML puslapį (ne atskirą JSON REST API), bet turinys aprašo Rivile ERP viešąjį REST API (erp.rivile.cloud/public-api).

Susiję projekto failai: rivile-erp-public-api-overview.html, rivile-erp-public-api.openapi.json (jei įkeltas), fetch-public-openapi.sh, GraphQL santrauka — rivile-erp-graphql-overview.html.

1. Paskirtis

Rivile ERP REST API skirta verslo procesų automatizavimui ir duomenų mainams su kitomis sistemomis (el. parduotuvės, finansų sistemos, trečiųjų šalių aplikacijos ir kt.).

2. Ką galima daryti (gido sąrašas)

  • Integracija su e. parduotuvėmis (PrestaShop, WooCommerce, Shopify, Amazon, eBay ir kt.).
  • Integracija su finansų sistemomis ir trečiųjų šalių aplikacijomis.
  • Automatinis užsakymų sinchronizavimas iš el. parduotuvių į Rivile ERP.
  • Sandėlio likučių sinchronizavimas su išorinėmis sistemomis.
  • Dokumentų kūrimas ir valdymas programiškai.
  • Realaus laiko duomenys apie atsargas, užsakymus, klientus.

3. Oficiali techninė dokumentacija (OpenAPI / Swagger)

(Gide kartais nuoroda rodoma kaip https://erp.rivile.cloud/public-api/ be swagger-ui — tas pats API bazinis kelias.)

  • Galima: peržiūrėti endpoint’us, testuoti užklausas naršyklėje, matyti schemas, parametrus ir pavyzdžius.

4. API rakto sukūrimas

Kelias sistemoje: Nustatymai → Bendrieji → API Raktai.

  1. Atidaryti API Raktai ir paspausti „Sukurti naują raktą“.
  2. Nurodyti pavadinimą (pvz. „Prestashop“).
  3. Įmonė — pasirinkti įmonę, kuriai skirtas raktas.
  4. Galioja iki — galiojimo data.
  5. Išsaugoti — sugeneruojamas raktas.

Svarbu:

  • Raktas matomas tik vieną kartą kuriant — išsisaugoti saugioje vietoje; sistemoje jis saugomas užšifruotas, kiti jo nemato.
  • Pergeneravus raktą senos integracijos su senu raktu nustoja veikti.
  • Deaktyvavimas: formoje pažymėti „Neaktyvus“ arba pakoreguoti Galioja iki datą.

5. Autentifikacija ir sauga

  • Kiekvienoje užklausoje naudoti antraštę X-SessionToken su API rakto reikšme.
  • API raktas suteikia plačią prieigą — elgtis kaip su slaptažodžiu.

6. Techninės ribos ir elgsena (iš „API naudojimo būdai“)

Sritis Aprašymas
GET sąrašai Iki 100 įrašų vienoje užklausoje — naudoti puslapiavimą didesniems kiekiams.
POST / PUT Užklausos dydis iki 5 MB.
Atsakymo laikas Maks. apie 5 min. — ilgiau grąžinama Read TimeOut klaida.
ID vs CODE Payload’e galima naudoti ID arba CODE laukus. Jei nurodyti abu, naudojamas ID (greičiau). Tik CODE — sistema validuoja ir suranda ID (šiek tiek lėčiau).
Privalomi laukai Kuriant įrašus dalis laukų gali būti neprivaloma (ERP užpildo pagal numatytuosius parametrus); privalomi laukai priklauso nuo įrašo tipo.

Kontekstas mokymams (kodėl ribos ir greitaveika): rivile-erp-infrastruktura-ribos-greitaveika.html.

Pavyzdinė užklausa (užsakymas / sąskaita — gido fragmentas)

{
  "clientCode": "000005",
  "lines": [
    {
      "itemCode": "000002",
      "uomAltCode": "VNT",
      "qtyAlt": 1,
      "departmentCode": "demo"
    }
  ]
}

Eilutėms (lines) privaloma (ID arba CODE pora):

  • itemId arba itemCode
  • uomAltId arba uomAltCode
  • qtyAlt
  • departmentId arba departmentCode

Numeracija, kainos, datos ir kt. gali būti užpildomos automatiškai pagal ERP nustatymus, jei neperduota.

7. GET filtravimas

  • Keli filtrai sujungiami logika AND.
  • Filtrų JSON užklausoje reikia URL užkoduoti (filter parametras).

Operatoriai: CONTAINS, NOT_CONTAINS, EQUAL, NOT_EQUAL, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, STARTS_WITH, ENDS_WITH.

Datos formatas (data): YYYY-MM-DD (pvz. 2025-09-01).

Data ir laikas (datetime): ISO 8601, pvz. 2025-09-01T00:00:00.000Z (Z = UTC).

8. HTTP atsakymai ir klaidos

  • 2xx — sėkmė.
  • 4xx — neteisingai suformuota užklausa.
  • 5xx — incidentas / techninė problema serveryje.

Klaidos struktūros pavyzdys (gidas):

{
  "code": "error.purchase-invoice.create.lines",
  "values": {
    "path": "createPurchaseInvoiceLine",
    "violations": {
      "lines[0].itemUomAltCode": "ItemUomAlt not found - Metras",
      "lines[3].itemCode": "Item not found - ABC123DEF"
    }
  }
}
  • Gali būti kelios validacijos klaidos; masyvai indeksuojami nuo 0.

9. Postman

  1. Įdiegti Postman; Import.
  2. Kolekcijos importas iš: https://erp.rivile.cloud/public-api/api-docs/v3

(Tai OpenAPI specifikacijos adresas Postman importui; skiriasi nuo swagger-ui URL.)

  1. Sukurti API raktą Rivile ERP.
  2. Kolekcijoje: Edit collection → Authorization → Type: API Key → Key: X-SessionToken, Value: gautas raktas (vietoj {{apiKey}}).
  3. Pasirinkti endpoint’ą, nustatyti parametrus, Send.

10. Kodo pavyzdžių kalbos (gido nuorodos)

Kalba Nuoroda
Java api_java (HttpClient)
Python api_python (requests)
JavaScript api_javascript (fetch)
PHP api_php (cURL)
Visual Basic api_visual_basic
Visual FoxPro api_visual_foxpro

11. Pagrindinės funkcinės sritys (gidas)

  • Dokumentai: pardavimo sąskaitos, pirkimai, užsakymai.
  • Sinchronizacija: klientai/tiekėjai, prekės/atsargos, kainos/nuolaidos.
  • Ataskaitos / analizė: realaus laiko duomenys, filtrai, puslapiavimas.

12. Greitieji patarimai (kartoja gido „API“ puslapį)

  • API raktą saugoti kaip slaptažodį.
  • ≤ 100 įrašų vienoje GET užklausoje — naudoti puslapiavimą.
  • Prieš gamybą testuoti Swagger arba Postman.

13. Skirtumai / patikslinimai vs šio projekto failai