MONEO API integrācija - darba plūsma

POST pieprasījuma adrese ir https://api.moneo.lv/[KOMPĀNIJAS ID LIELAJIEM BURTIEM]/api/v2/[TableName], kur:

• [KOMPĀNIJAS ID LIELAJIEM BURTIEM] vietā ir Jūsu Kompānijas ID
• [TableName] vietā ir nolasāmā tabula, piemēram, items.items vai sales.invoices

Biežāk lietoto tabulu kodi.

Piemēram, zemāk redzamais pieprasījums nolasīs un atgriezīs visus kompānijas rēķinus, kuri izveidoti klientam 1003.

POST ar JSON struktūru: https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/sales.invoices

{
  "filter":{"custcode":"1003"},
  "fieldlist":["custcode","sernr", "custname"],
  "request":{
    "compuid":"53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6",
  }
}

Piemērs ar curl:

curl -d '{"filter":{"custcode":"1003"}, "fieldlist":["custcode","sernr","custname"], "request":{"compuid":"53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6"}}' -H "Authorization: {{api_key}}" https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/sales.invoices

• request tiek formēts vienādi - tas saturēs compuid
• fieldlist ļauj atlasīt tikai tos laukus, kurus vēlamies iegūt. Ja ir liels datu pieprasījums, vēlams samazināt lauku sarkastu izmatojot šo parametru. Ja parametru neizmanto, tiks nosūtīts pilns lauku saraksts, bet jāņem vērā, ka par katru apakštabulu (subtable) galvas rindu saraksts tiek daudzkāršots, tādēļ pieprasot piemēram rēķina rindas ar galvu vēlams norādīt, kuru subtable tieši nepieciešams, jo rēķinos ir vairāki subtable (artikuli, kredītrēķini, priekšapmaksas, aģenti)
• filter ļauj filtrēt datus. Pamatpierakstā lauka un lauka vērtības key-value pāris.
  

  Pieprasot datus, iespējams izmantot MONEO datu filtrēšanas izteiksmes. Par izteiksmēm vairāk lasīt šeit.

  Filtrācija ar chainfield: tas nozīmē sekojošas izteiksmes esam paredzējuši __gte, __gt, __lte, __lt, __eq, __ne, __gteon, __lteon, __set, kur gte -> greater than or equal, lt -> less than, eq -> equal, lteon -> less than or equal or none. Šī filtrācija var noderēt piemēram, ja nepieciešams atlasīt datus, kur vērtība ir tukša, jo vienkārši tukšs filtrs nozīmēs atlasīt visu, bet lai norā'ditu, ka nepieciešamas tikai tukšas vērtības, jānorāda field__eq: "".
  
  • Piemēram, nepieciešams nolasīt artikulu kodus un nosaukumus, ja ārējais kods (externalid) ir tukšs

    {
      "filter":{},
      "fieldlist":["code","name","externalid"],
      “filter”: {"externalid__eq": ""},
      "request":{
        "compuid":{{comp_id}}
      },
    }

atbildes piemērs uz POST https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/sales.invoices

{
 "result": {
   "records": [
     {
       "custcode": "1003",
       "sernr": 200001,
       "custname": "Testa firma"
     },
     {
       "custcode": "1003",
       "sernr": 200002,
       "custname": "Testa firma"
     },
     {
       "custcode": "1003",
       "sernr": 200003,
       "custname": "Testa firma"
     },
     {
       "custcode": "1003",
       "sernr": 200004,
       "custname": "Testa firma"
     }
   ]
 }
}

• result saturēs records elementu, kur katrs elements ir viens ieraksts, ja ieraksts satur sevī vēl apakštabulu ar rindām, tad būs elements sub_table, kurš saturēs apakštabulas nosaukumu un tajā esošos laukus (piemērs zemāk).

Piemērs, JSON pieprasījums, nolasīt rēķinu numur 352, un atgriezt informāciju par tā datumu un artikulu rindām: artikula kodu un daudzumu.

{
  "filter":{"sernr": 352},
  "fieldlist":["sernr","invdate","items.itemcode","items.quant"],
  "request":{
    "compuid":{{comp_id}}
  },
}

atbilde:

{
"result": {
  "records": [
    {
      "sernr": 352,
      "invdate": "2021-06-01",
      "sub_table": {
        "items": [
          {
            "itemcode": "8431034004726",
            "quant": "1",
            "_sernr": 352,
            "_rownr": 0
          },
          {
            "itemcode": "8431034000469",
            "quant": "1",
            "_sernr": 352,
            "_rownr": 1
           }]}}]}}

• result saturā redzams, ka parādas papildus lauki _sernr un _rownr, tie informē par rindas piederību, pie ieraksta id (primārais atslēgas lauks rēķinam ir sernr) un apakštabulas rindas indeks numurs - _rownr - sākas ar 0.

Gadījumā, ja Jums nepieciešams nolasīt tikai rindas datus, tad var formēt pieprasījumu uz rindas tabulu, t.i. iepriekš aprakstītajā gadījumā, ja jāiegūst rēķina 352 rindas informācija artikula kods un daudzums, tad tabulas sales.invoices vietā jānorāda tabula sales.invoices_items_rows

POST ar JSON struktūru: https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/sales.invoices_items_rows

{
  "filter":{"_sernr":"352"},
  "fieldlist":["itemcode","quant"],
  "request":{
    "compuid":{{comp_id}}
  }
}

 atbilde:

{
  "result": {
    "records": [
    {
      "itemcode": "8431034004726",
      "quant": "1",
      "_sernr": 352,
      "_rownr": 0
    },
    {
      "itemcode": "8431034000469",
      "quant": "1",
      "_sernr": 352,
      "_rownr": 1
    }]
  }
}

Ja integrācijas nodrošināšanai svarīgi noskaidrot lauku datu tipus un datu struktūru, tad veidojot pieprasījumu var norādīt parametru include_field_list, rezultātā, kopā ar atbildi par datiem, tiks atgriezts papildus elementi: field_list, field_types, sub_field_list, sub_field_types.

JSON pieprasījums ar include_field_list:

{
  "filter":{"sernr":"352"},
  "fieldlist":["sernr","invdate","items.itemcode","items.quant"],
  "request":{
    "compuid":{{comp_id}}
  },
  "include_field_list": true
}

atbilde:

{
  "result": {
    "records": [
    {
      "sernr": 352,
      "invdate": "2021-06-01",
      "sub_table": {
      "items": [
      {
        "itemcode": "8431034004726",
        "quant": "1",
        "_sernr": 352,
        "_rownr": 0
      },
      {
        "itemcode": "8431034000469",
        "quant": "1",
        "_sernr": 352,
        "_rownr": 1
      }]
    }
    }],
    "field_list": [
      "sernr",
      "invdate"
    ],
    "field_types": {
      "sernr": {"__callable": "builtins::int"},
      "invdate": {"__callable": "datetime::date"}
    },
    "sub_field_list": {
      "items": [
        "itemcode",
        "quant",
        "_sernr",
        "_rownr"
      ]
    },
    "sub_field_types": {
      "items": {
        "itemcode": {"__callable": "builtins::str"},
        "quant": {"__callable": "bin.moneodecimal::Decimal"},
        "_sernr": {"__callable": "builtins::int"},
        "_rownr": {"__callable": "builtins::int"}
      }
    }
  }
}

row_count - atgriežamo ierakstu skaits

Lai ierobežotu atgriežamo ierakstu skaitu, piemēram, lai atgriež tikai 5 ierakstus

JSON pieprasījums ar row_count:

{
  "filter":{"custcode":"1003"},
  "request":{
    "compuid":{{comp_id}}
  },
  "row_count": "5"
}

sort_direction un keyname - atgriežamo ierakstu secība

Nolasāmos datu tabulas ierakstus var sakārtot pēc noteikta lauka (keyname), pašu sarakstu var sakārtot dilstoši (sort_direction - "up"/"down").

Lai nolasītu pēdējo ierakstu (pēc datuma lauka "transdate") tabulā var lietot kombināciju no atslēgvārdiem: sort_direction="down", keyname="transdate" un row_count="1"

{
  "filter":{"custcode":"1003"},
  "request":{
    "compuid":{{comp_id}}
  },
  "keyname": "transdate",
  "sort_direction": "down",
  "row_count": "1"
}

join_tables - datu nolasīšana pievienojot datus no citām tabulām

Piemēram, pieprasot datus par rēķiniem (sales.invoices), to rindām (sales.invoices_items_rows), nepieciešams papildus pie rēķina rindas saņemt arī artikula svītrkodu (barcode) vai artikula ārējo id (externalid). Standartā šie lauki nav rēķinu ierakstos, tie ir atrodami artikulu kartiņās (tabula items.items), tas nozīmē ka būtu jāveic rēķinu rindu nolasīšana, pēc tam atrastos artikulus nolasīt no artikulu tabulas.

Ar join_tables var veikt šo datu savienošanu uzreiz, tādā veidā ar vienu pieprasījumu saņemot arī saistītot informāciju.

Piemērs, nolasītu konkrēta rēķina 220095 rindu artikulus, artikula svītrkodu un pārdodamo daudzumu

POST ar JSON struktūru: https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/sales.invoices_items_rows

{
  "filter":{"_sernr":"220095"},
  "fieldlist":["itemcode","items.items.barcode","quant"],
  "join_tables": [["items.items", {"items.items.code": "itemcode"}]],
  "request":{
    "compuid":{{comp_id}}
  }
}

join_tables var saturēt vairākus joinus, tāpēc norādāms dubults [], katrs elements satur tabulas savienošanas informāciju

["tablename", {"pievienojamās tabulas sasaistes lauks": "esošās tabulas sasaistes lauks"}]

["items.items", {"items.items.code": "itemcode"}]

Pastāv iespēja izsaukt metodi, kas atgriež vērtības, kuras nav tiešs tabulas saturs. Metodes izsaukšana notiek ar sekojošu pieprasījumu: https://api.moneo.lv/[KOMPĀNIJAS ID LIELAJIEM BURTIEM]/api/method/[app_name].[method name]

{“params”:[“arg1”,“arg2”,“arg3”…], “request”:{“compuid”:[compuid]}}

piemēram: https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/method/stock.getstockquantforitemlist

{
  "params":[
    ["013G4155" ,"013G4156" ,"013G4190" ,"0600-02.000" ,"0600-02.553" ,"0600-03.000" ,"0600-03.553"],
    "MWH"
  ],
  "request":{
    "compuid":"130C0585-60605033-D3BEEE44-5505ECA5-2B107BD8"
  }
}

atbilde:

"result":[
  ["12.00", "48.00", "0.00", …]
]

• result elements saturēs method funkcijas atbildi. redzamajā piemērā, artikulu atlikums noliktavā MWH

Šobrīd pieejamās metodes:

• stock.getStockQuantForItemList - noliktavas atlikums artikulu sarakstam. Parametri: artikulu saraksts (list elements) un noliktavas kods
• stock.getStockQuant - noliktavas atlikums vienam artikulam. Parametri: artikula kods (obligāts), partijas numurs (optional), noliktava (optional), datums (optional)
• stock.getItemDeficiencyInfo - noliktavas atlikums artikulu sarakstam mīnus rezervētie daudzumi saistītajās tabulās, piemēram, neizpildītos klientu pasūtījumos, negrāmatotajās norakstīšanās un citur. Metodes parametri sakrīt ar atskaites Iztrūkstošo preču pārskats atlases parametriem.
  • Par IncludeInStock:
    0 - Tikai ar iztrūkumu (With Deficiency Only)
    1 - Visus artikulus, kuriem bijusi vēsture (All Items With History)
    2 - Ar iztrūkumu vai piegādātāju pasūtījumiem (With Deficiency Or Purchase Orders)
    3 - Artikuli no avota ieraksta (Items From Source Record) - jānorāda klientu pasūtījuma numurs
    4 - Tikai ar pārpalikumu (With Surplus Only)
    5 - Tikai ar neizpildāmu iztrūkumu (With Missing Deficiency Only)
• porders.webGetPurchseOrderRows - plānotās saņemšanas (preces kuras ir pasūtītas, bet vēl nav saņemtas) -> tas pats ko iespējams redzēt veidojot saņemšanas dokumentu un izvēloties kuru pasūtījumu šobrīd izpilda (nesaņemto rindu saraksts).
  • detailedflag - pārskats vai detalizēts variants (0, 1, noklusēti 0 - pārskats)
  • keyname - kārtošanas lauks, pēc noklusējuma tukšs, ja vajag var norādīt lauku no pasūtījuma piegādātājiem pēc kura kārtot (galvenes laukiem liek prefix porders.orders, piemēram, kārtot pēc piegādātāja nosaukuma šeit norādītu porders.orders.suppliername, svarīgi nesajaukt atbildes lauku kodus ar pasūtījuma piegādātājiem laukiem (tie atšķiras))
  • supplier - norāda vienu konkrētu piegādātāju, noklusētā vērtība ir tukšs - visi
  • itemlist - norāda ar komatu atdalītus artikulus, kurus atlasīt, noklusētā vērtībā ir tukšs - visi

Piemēram: POST https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/method/stock.getItemDeficiencyInfo

Piemēram: POST http://127.0.0.1:15000/api/v2/method/porders.webGetPurchseOrderRows

{
  'params': [{
    'detailedflag': 1,
    'supplier': '1026',
    'itemlist': 'K10001,K10002'
  }],
  "request":{
    "compuid": {{comp_id}}
  }
} 

atbilde:

{
  'jsonrpc': '2.0',
  'id': '59601485-f367bfc8-0e235789-6032e971-837aa115',
  'result': [
    [{
      'OrderRowID': '2dd092d9-b2ee21e6-3ba1a1e7-556cf4dc-f6bfc582',
      'Order': 200003,
      'OrdDate': '2020-02-11',
      'Item': 'K10001',
      'ItemName': 'Tapas koka 5x20',
      'PurchItemCode': 'LK10001',
      'Quant': '1990.00',
      'RequisitionRowID': '',
      'RequisitionNr': null,
      'ReqQuant': null,
      'Comment': '',
      'ManufacturerItemCode': '',
      'Reference': '',
      'PlanReceiveDate': '2020-02-16',
      'Supplier': '1026',
      'SupplierName': 'Moneo Sup'
    },
    {
      'OrderRowID': '0df5eda6-459c8100-3a3cf7ad-24d7b19c-43df0cb9',
      'Order': 200003,
      'OrdDate': '2020-02-11',
      'Item': 'K10002',
      'ItemName': 'Tapas koka 5x15',
      'PurchItemCode': 'LK10002',
      'Quant': '1980.00',
      'RequisitionRowID': '',
      'RequisitionNr': null,
      'ReqQuant': null,
      'Comment': '',
      'ManufacturerItemCode': '',
      'Reference': '',
      'PlanReceiveDate': '2020-02-16',
      'Supplier': '1026',
      'SupplierName': 'Moneo Sup'
    }]
  ],
  'trans_state': null
}

REST API ļauj veikt arī datu rakstīšanu .

Pieprasījuma formāts ir sekojošs:

https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/[table name]/create/

{
  "data":{
    "tablename":{
      "fieldlist":["field1","field2","field3","field4"],
      "data":[ ["value1","value2","value3","value4"] ]
    },
    "row_tablenname:{
      "fieldlist":["rowfield1","rowfield2"],
      "data":[ ["row1value1","row1value2"] , ["row2value1","row2value2"]]
    }
  },
  "request":{
    "compuid":"130C0585-60605033-D3BEEE44-5505ECA5-2B107BD8"}
}

Piemērs: https://api.moneo.lv/53F98A26-041ECDF6-4CF71DCD-0474B2B3-B7C42FD6/api/v2/sorders.orders/create/

Izveidot jaunu klientu pasūtījumu, klientam 2001 ar cenu lapu VIP un komentāru Test comment.

Pasūtījums saturēs divas rindas, artikuls 001 ar daudzumu 13.1 un artikuls 101 ar daudzumu 10.99

{
  "data":{
    "sorders.orders":{
      "fieldlist":["custcode","pricelist","currency","comment"],
      "data":[ ["2001", "VIP", "EUR", "Test comment"] ]
    },
    "sorders.orders_items_rows":{
      "fieldlist":["itemcode","quant"],
      "data":[ ["001","13.1"] , ["101","10.99"]]
    }
  },
  "request":{
    "compuid":"130C0585-60605033-D3BEEE44-5505ECA5-2B107BD8"}
}