Logo Image

Web Service

Αρχική  /  Doc  /  Documentation  /  Mysoho Εργαλεία  /  Web Service

Web Service

Web Service

Τι είναι το Web Service ή διαδικτυακή υπηρεσία;

Μια διαδικτυακή υπηρεσία είναι:
  • μια υπηρεσία που προσφέρεται από μια ηλεκτρονική συσκευή σε μια άλλη ηλεκτρονική συσκευή, που επικοινωνούν μεταξύ τους μέσω του Διαδικτύου
  • ή ένας διακομιστής που λειτουργεί σε μια συσκευή υπολογιστή και ακούει αιτήματα σε μια συγκεκριμένη θύρα μέσω δικτύου

Η πρώτη έκδοση που υποστηρίζει Web Service & Rest API είναι η 2.9.1.10

https://mysoftwarehouse.gr/topver/2.9/2.9.1/2.9.1.10/

 

Installation

  1. Στον ήδη υπάρχον φάκελο εγκατάσταση του Topvalue, αντιγράφουμε το TopValueSrv.exe όπου το έχουν κατεβάσει από τον παραπάνω σύνδεσμο.
  2. Ανοίγουμε ένα Command Prompt Line (cmd) με δικαιώματα διαχειριστή και πηγαίνουμε στον φάκελο εγκατάστασης του Topvalue.
  3. Δημιουργούμε ένα αρχείο service.ini Η σύνταξη του είναι όπως αναγράφεται και στην ενότητα Εισαγωγή Παραμέτρων στο Login
    Παράδειγμα:
    [APPLICATION]
C=test1
U=supervisor
apiUser=kostas
apiPass=@apo@123
ApiRoot=root
ApiPort=190
log=2

    log parameter can be=

    • 0 no log,
    • 1 log url string,
    • 2 log also in body

    Τα αρχεία καταγραφής (log) είναι ανά ημέρα, στον φάκελο LOG μέσα στον φάκελο εγκατάσταση του Topvalue.
    ****Στο prm αρχείο να προτιμάται ο sql χρήστης και password. Σε περίπτωση Windows authentication, θα πρέπει ο χρήστης των Windows που τρέχει το Service, να έχει δικαιώματα πρόσβασης στον Sql Server.

  4. Εκτελούμε την εντολή TopValueSrv.exe /install
  5. Ξεκινάμε το service.Έχουμε 2 επιλογές
    • Τρέχουμε την συντόμευση TopValueSrv
    • Ανοίγουμε τα services των Windows, βρίσκουμε από την λίστα το My Software House TopValue Service και κάνουμε Start.

Οποιοδήποτε σφάλμα προκύψει, καταγράφεται στο TopValue.log

Επικύρωση

Η επικύρωση των στοιχείων πρόσβασης γίνεται ως εξής:

  • Basic (Περίπτωση που κάνουμε request από Postman)
    username= ApiUsername   eg kostas
    password= ApiPassWord + #SerialNumber    eg @apo@123#301-00999
  • Base64 (Περίπτωση που κάνουμε request μέσα από script) eg a29zdGFzOkBhcG9AMTIzIzMwMS0wMDk5OQ== (Σχετικό παράδειγμα μπορείτε να βρείτε στην ενότητα Script Examples)

REST API Endpoint

Επιστρέφει πληροφορίες της εφαρμογής

return
{"AppName":"TopValue", "SN":"301-xxxxx", "AppVer":"2.0.0.1", "DBVer":"3.74","Company":"my 000000010", "BranchID":1, "UserName":"Supervisor", "VatNo":"000000010","LoginDate":"5/3/2025"}

Επιστρέφει τα δεδομένα ενός business object με όνομα = “bo” και key = “Keyvalues”

body
{
    "bo": "TCustomerbo",
    "Keyvalues": [
        1960027845
    ],
    "// or fromKey": "integer",
    "count": "integer optional default 50"
}

return:if result is many Array of Object(row) or Object(row) if one

{
    "ID": 1960027845,
    "RowType": 1,
    "Code": "json2",
    "Account_Type": 200,
    "Name": "json επωνυμία",
    "Profession": "a",
    "Vat_Type": 1,
    "Address1": "δεν",
    "City1": "no city",
    "Country1_ID": 1,
    "Discount_Perc": 0,
    "KEPYO_Type": 0,
    "KEPYO_Flag": 0,
    "Active": true,
    "Acc_Code": "30.00.01",
    "luCountry1Name": "ΕΛΛΑΔΑ",
    "BranchID": 99,
    "ValBehave": 0,
    "ValuerDays": 0,
    "CompType": 0,
    "HeadOffice": 1960027845,
    "CusHeadCode": "json2",
    "CusHeadName": "json επωνυμία",
    "Creation_Date": "2022-10-16T09:09:28",
    "GLCodeBuildType": 0,
    "CreditValAsPay": true,
    "ChqGrpCodeID": 1,
    "ChqType": 1,
    "ChqMove": 10,
    "calcChqAuto": false,
    "calcChqMoveTrn": false,
    "calcChqChoice": true,
    "calcChangeOwner": true,
    "calcChangeRemainAsIS": false,
    "calcChangePayDate": false,
    "isTransf": true,
    "isRetailFund": 0,
    "FundCreDeb": 0,
    "CoinCodeID": 1,
    "ValidFromDate": "2000-01-01",
    "ValidToDate": "9999-01-01",
    "BalancedTrn": false,
    "UpdateItemAllMaster": true,
    "DoOpenItem": 0,
    "OpenItemBehavior": false,
    "HandleFC": false,
    "MoveType": true,
    "Priority": 0,
    "BillToAmID": 1960027845,
    "BillToCode": "json2",
    "BillToName": "json επωνυμία",
    "PrPolicyUseShipTo": false,
    "DoEInvoice": false,
    "DeliveryPriority": 0,
    "eMarketing": 0,
    "BaseAGrpByID": 2,
    "MSH_Not_LogoURL_inLabels": false
}

Καταχωρεί δεδομένα σε ένα business object με όνομα “bo” και δεδομένα “data”

Παράδειγμα καταχώρησης τριών πελατών
body
{
    "bo": "TCustomerbo",
    "data": [
        {
            "code": "json2",
            "name": "json επωνυμία",
            "Profession": "a",
            "Address1": "δεν",
            "city1": "no city",
            "#echo": "e"
        },
        {
            "code": "json3",
            "name": "json επωνυμία",
            "Profession": "a",
            "Address1": "δεν",
            "city1": "no city"
        },
        {
            "code": "json4",
            "name": "json επωνυμία",
            "Profession": "a",
            "Address1": "δεν",
            "city1": "no city",
            "#echo": "d"
        }
    ]
}

return

[
    {
        "#echo": "e",
        "ID": 1960027845
    },
    {
        "ID": 1960027846
    },
    {
        "ID": 1960027847
    },
    {
        "ID": 1960027848
    },
    {
        "#echo": "d",
        "ID": 1960027849
    }
]
Παράδειγμα καταχώρησης πώλησης
{
{bo: "TSALESTRNBO",
 "doprint": 0,
 data:{"#echo":"e!",
       docprmid: 19, 
       SerieCode: "01Μ01",              
       "AMTRN_S1":{amid: 5965,
                   PayID: null},
        "Itetrn": {itemid: 20000164,
                    priqty: 3, "price":25}                    
        }
}
return

{"#echo":"e!","ID":2101600970}
Επιστρέφει τα δεδομένα ενός column σε Sql query. Αν περιέχονται περισσότερα από ένα επιστρέφει το πρώτο. Πάντα επιστρέφει array [] με το περιεχόμενο των columns.
body
{
    "sql": "select top 10 afm from customer where id>:0 order by id",
    "usenulls": true,
    "params": [
        3007
    ]
}
return always an array of values 
[
    "036611318",
    "0000000",
    "000000",
    "X-00.0002",
    "X-00.0003",
    "X-00.0004",
    "X-00.0005",
    "X-00.0006",
    "X-00.0007",
    "X-00.0008"
]

body

{
    "sql": "select top 10 id,code,name from customer where id>:0 order by id",
    "addnulls": false,
    "params": [
        3007
    ]
}

return always an array of objects (rows)

[
    {
        "id": 1960020580,
        "code": "30.0",
        "name": "ΜΕΝΤΖΕΛΙΔΗΣ ΜΙΛΤΟΣ ΑΕ"
    },
    {
        "id": 1960021364,
        "code": "301",
        "name": "Καραγκικας δημ"
    },
    {
        "id": 1960021365,
        "code": "302",
        "name": "Καραμολεγκος Τακης"
    },
    {
        "id": 1960021366,
        "code": "00.0002",
        "name": "ΑΓΡΙΟΓΙΑΝΝΗ ΕΛΕΝΗ ΤΟΥ ΝΙΚΟΛΑΟΥ"
    },
    {
        "id": 1960021367,
        "code": "00.0003",
        "name": "ΑΝΤΩΝΙΟΥ ΔΗΜΗΤΡΙΟΣ ΤΟΥ ΗΛΙΑ"
    },
    {
        "id": 1960021368,
        "code": "00.0004",
        "name": "ΦΟΥΦΑΣ ΠΑΝ/ΤΗΣ ΤΟΥ ΣΑΡΑΝΤΟΥ"
    },
    {
        "id": 1960021369,
        "code": "00.0005",
        "name": "SINGER PETER"
    },
    {
        "id": 1960021370,
        "code": "00.0006",
        "name": "ΕΥΘΥΜΙΟΥ ΔΗΜΗΤΡΙΟΣ & ΑΙΚΑΤΕΡΙΝΗa"
    },
    {
        "id": 1960021371,
        "code": "00.0007",
        "name": "ΤΣΙΟΥΛΟΣ ΔΗΜΟΣ"
    },
    {
        "id": 1960021372,
        "code": "00.0008",
        "name": "ΝΙΚΗΤΟΠΟΥΛΟΥ"
    }
]
Προσοχή στο DBFieldsRowValues υπάρχει s.
Επιστρέφει τα δεδομένα ενός Sql query ενός row ως object.
Αν dbfqr”:true τότε στο result δεν γίνεται format από το WebService επιστρέφεται αυτούσιο το result του SQL server.
Με αυτό τον τρόπο μπορούν να γίνουν με FOR Json nested results.
body
{
    "sql": "declare @x varchar(max)=(select top 2 
                                     id,code,name 
                                     from customer 
                                     where id>:0 
                                     order by id 
                                     for json auto) 
            select @x",
    "addnulls": false,
    "dbfqr": true,
    "params": [
        3007
    ]
}
  • dbFQR is optional
  • FQR (Format Query Result) If true means service not convert result to json because formated in db.Best practice in this case is to use it with “for json” clause.
return an object(if dbfqr<>true) 
[
   {"id":1960021371,"code":"00.0007","name":"ΤΣΙΟΥΛΟΣ ΔΗΜΟΣ"}, 
   {"id":1960021372,"code":"00.0008","name":"ΝΙΚΗΤΟΠΟΥΛΟΥ"}
]
Εκτελεί ένα report και επιστρέφει σε HTML,PDF
  • id = report guid
  • params = οι παράμετροι που αφορούν το report
  • exportDevice σε τι format θα επιστραφεί το report. Ως object property ενσωματώνονται επίσης επιπλέον παράμετροι που αφορούν το επιλεγμένο format και είναι ίδιες με τις επιλογές που έχει ο χρήστης όταν από την εφαρμογή γίνεται export ένα report
  • exportDevice ενα απο PDFExport, HTMLExport
μερικά properties του PDFExport
  • ExportNotPrintable: False
  • HTMLTags: True
  • Subject: A test
  • Keywords: test
  • Transparency: False
  • Author: Supervisor/my software house
  • HideToolbar: False
  • PDFStandard: one of “psNone, psPDFA_1a, psPDFA_1b, psPDFA_2a, sPDFA_2b, psPDFA_3a, psPDFA_3b”
  • PDFVersion: one of “pv14, pv15, pv16, pv17”
body
{
   "id":"{00000000-0000-0000-0000-000000002711}",
   "params":[
              {"amtrn.docdate.GT":"2024-01-20"}
            ],
   "exportDevice": {
                    "PDFExport": {"PDFStandard": "psNone"} 
                    }
}

καλείται ως runTemplate/xxx όπου xxx το όνομα αρχείου που θα αποσταλεί χωρίς το πρόθεμα html.
Παράδειγμα κλήσης http://localhost:190/root/runTemplate/index
το αρχείο index.html αναζητείται στο folder “TemplatesPath”, το οποίο έχει οριστεί στο service.ini ως TemplatesPath=c:\yyy\zzz

δεν χρειάζεται καμία παράμετρο.
Ανανεώνει όλα τα ενεργά cache dataset.

Επεξηγήσεις

  • Το property BO παίρνει το όνομα του Topvalue Business Object όπου θα γίνει καταχώρηση.
  • Τα data είναι array of rows (objects) ή object(row), χωρίς περιορισμούς. Μία καλή πρακτική είναι, το μέγεθος του body να μην ξεπερνάει το 1ΜΒ.
  • Κάθε γραμμή (ως Js object) περιέχει ζεύγος πεδίων (όνομα πεδίου – τιμή πεδίου) όπως περιγράφεται στο ΒΟ του Topvalue. Μπορεί επίσης να περιέχει ειδικά πεδία (#rus, #echo)
  • Προσοχή στη σειρά που εμφανίζονται. το πεδίο #rus πρέπει να είναι πρώτο, όλα τα πεδία του ΒΟ όπως εμφανίζονται στο JSON. Τα ένθετα σύνολα να είναι στο τέλος.
  • Πεδίο #rus (row update status)
    • 0=insert is default,
    • 1=update,
    • 2=delete.
  • Κάθε γραμμή (object) μπορεί να έχει το πεδίο #rus αλλά πρέπει να είναι πρώτο στη σειρά.
  • Πεδίο #echo. Είναι ένα πεδίο χρήστη που μπορεί να υπάρχει σε κάθε master σειρά, εάν υπάρχει θα επιστρέψει από το service όπως ελήφθη. Η βέλτιστη πρακτική είναι να το χρησιμοποιήσετε για να συγκρίνεται τα κλειδιά με αυτά του Topvalue
  • Η επιστροφή που λαμβάνουμε όταν κάνουμε request ApplyBOData είναι οι εξής:
    • #rus=0 (insert): Ένα object που περιέχει το #echo (εάν υπάρχει) και τα ID ή το σφάλμα σε περίπτωση λάθους.
    • #rus=1 (update): Ένα object που περιέχει το #echo (εάν υπάρχει) ή το σφάλμα σε περίπτωση λάθους.
    • #rus=2 (delete): Ένα object που περιέχει το #echo (εάν υπάρχει) ή το σφάλμα σε περίπτωση λάθους.
Was this article helpful to you? Yes No

How can we help?