Hvordan får man standardkontakt-/adresseoplysninger for installationssted/udstyr på en ordre?
Hvilke felter er mindstekravene for at oprette en ordre i Handyman med API?
Teknisk minimumseksempel for et kald til endpointet 'Orders'
Hvordan får man alle åbne/aktive ordrenumre for en bestemt kunde?
Hvilke vedhæftningsformater er mulige, og hvordan kan vi uploade disse (TIFF, JPG, PNG osv.)?
Hvordan får vi de ordrer, vi har brug for, med en eller flere statusser (f.eks. 1 og 2)?
Hvilke filtre virker for de API'er, vi planlægger at bruge?
Hvordan får man standardkontakt-/adresseoplysninger for installationssted/udstyr på en ordre?
Der er ingen standardkontakt for et installationssted, du kan indsamle de vedhæftede kontakter for et ordreinstallationssted med følgende endpoint: api/installations/{site-id}/contacts. Installationssted-id'en kan indsamles gennem følgende endpoint: api/orders/{order-id}/installations?installationType=1 --> Id-property for den/de returnerede objekt(er).
Er der nogen måde at opdatere "OrderHead's CustomerReference" eller "OrderHead's Rekvisition"-felt via API-kald for en åben ordre?
Begge feltopdateringer bør virke på api/orders-endpointet (POST)
Dette gælder også for api/weboffice/orders-endpointet (POST), men da dette endpoint bruger en anden POST-model (OrderCreateModel), er de tilsvarende felter: CustomerReferenceText og Rekvisition
Hvilke felter er mindstekravene for at oprette en ordre i Handyman med API?
Det tekniske minimumseksempel for et kald til Orders-endpointet:
Eksempel på JSON:
[
{
"CustomerReference":
{
"ExternalId": "910478658"
},
"OrderHead":
{
"EstimatedHours": 32,
"OrderDate": "2023-03-13T12:46:42.329Z",
"OrderName": " Testing "
}
}
]
The Json above is a technical minimum for the Api call, meaning that the API will not respond with an Error. Fra et forretningsmæssigt synspunkt er disse data ikke en meningsfuld ordre.
Forretningsminimumsopkaldseksempel:
[
{
"OrderHead": {
"OrderDate": "{{$isoTimestamp}}",
"OrderName": "Bence Testing CW Export 17",
"EstimatedHours": 32,
"Requsition": "Ekstern reference til ordren.",
"IsInternalOrder": false,
"DoNotSetAsPassive": false,
"CustomerReference": "Kundereference for ordren.",
"Message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
"ContactName": "Hr. Kontakt",
"Telephone1": "+36419871234",
"Telephone2": "+3612045406",
"ContactEmail": "mr.contact@email.com",
"FixedPrice": 12345,
"ManagerReference": {
"ExternalId": "10"
},
"DepartmentReference": {
"ExternalId": "400"
},
"StartDate": "{{Order_start_date}}",
"FinishDate": "{{Order_end_date}}",
"ActualStartDate": "{{Actual_start_date}}",
"ActualFinishDate": "{{Actual_end_date}}",
"CategoryList": [
{
"CategoryBackOfficeId": "12",
"CategoryType": 1
},
{
"CategoryBackOfficeId": "2",
"CategoryType": 0
}
],
"Location": {
"Latitude": 47.563660,
"Longitude": 19.093232,
"AddressName": "HQ",
"BoligmappaEdokNumber": "Lebstück",
"BoligmappaPlantID": 1534,
"Address1": "Lebstück Mária",
"StreetNo": "63",
"Address2": "utca",
"PostalCode": "1041",
"PostalArea": "Budapest",
"Country": "Hu"
},
"KB_ValueList": [
{
"Level": 0,
"Value": "12345678910111",
"Description": "Test med lang id",
"Parent": null,
"FixedPrice": null
},
{
"Level": 0,
"Value": "Kan det være tekst",
"Description": "Test med enda lengre id",
"Parent": null,
"FixedPrice": null
},
{
"Level": 1,
"Value": "1",
"Description": "Kontrakt",
"Parent": null,
"FixedPrice": null
},
{
"Level": 1,
"Value": "2",
"Description": "Additional work",
"Parent": null,
"FixedPrice": null
},
{
"Level": 2,
"Value": "1",
"Description": "Indoor work",
"Parent": null,
"FixedPrice": null
},
{
"Level": 2,
"Value": "2",
"Description": "Outdoor work",
"Parent": null,
"FixedPrice": 5000.0
}
]
},
"Status": 12,
"CustomerReference": {
"ExternalId": "31"
},
"ParticipantList": [
{
"EmployeeReference": {
"ExternalId": "10"
},
"MainParticipant": true
}
]
}
]
The sample Json creates an Order which is valid for some businesss cases.
How to get all open/active order# for a specific customer?
- only the active orders:
["Status", "<>", 14]
- s the "Passive" state in HMO, every order with other value is considered as "Active"
Which attachment formats are possible and how can we upload these (TIFF, JPG, PNG..)?
You can add any type of attachment using document-adding endpoints. For example, in case of orders you can use the api/orders/{order-id}/documents POST endpoint and pass the data like this (you should specify the extension in the “FilePath” property and in the “FileExtension”. The image should be passed as a byte array):
[
{
"HSDocumentID": "99",
"DocumentID": "178",
"Date": "2022-10-12T17:04:43.133",
"ChecklistRegistrationReference": null,
"EmployeeReference": {
"Id": 4,
"ExternalId": "2"
},
"Name": "test",
"Comment": "",
"SendToClient": false,
"FilePath": "test.jpg",
"DocumentData": "000000000000000000000000000000000011000000000000000000000000000000011000000100000100000000000000000000000000000000000000000000000000111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
"FileExtension": "jpg",
"KB1": "String",
"KB2": "",
"Phase": "",
"AssetID": null,
"AssetPropertyID": null,
"BoligmappaID": null,
"BoligmappaUploadDate": null,
"SyncStatus": 0,
"SiteReference": null,
"EquipmentReference": null,
"DocumentType": 0,
"ResetSyncStatus": null,
"HSId": 99,
"BackOfficeId": "178",
"IsAvailableOnWeb": null
}
]
How do we get the orders that we need, with one or more Status (ex. 1 and 2)?
- Can we use: GET /api/orders
- Can we do one call to get this or do we need to do multiple calls?
It depends on what kind of status we look for. If it’s about the Status of the order eg. ny ordre, ændret på mobil osv. Så er der ikke sådan en filter, men der er mulighed for at filtrere på aktive og afsluttede ordre. Med Status forespørgselsparameter kan du bruge følgende værdier:
Alle = 0,
Aktive = 1,
Afsluttede = 2
Hvad er forskellen mellem disse:
- Handyman, Swagger (Netel): https://api.netelgroup.com/swagger/ui/index#/
- Handyman, Swagger (Ny): https://api.gsgroup.io/swagger/index.html
Dette er swaggeren for Common Api. Ældre version til Handyman Api. Den blev designet til at få adgang til flere Gsgroup-produkter med én Api. Har mindre funktionalitet end Handyman Api. Vi anbefaler ikke Handyman-kunder at bruge den!
Hvilke filtre virker for de API'er, vi planlægger at bruge?
Det afhænger altid af selve slutpunktet. Nogle af GET (liste) slutpunkterne har en ExternalId forespørgselsparameter, som kan bruges til at filtrere elementer (f.eks. Ordre) efter deres ERP (IdBackoffice) identifikator.
Paging understøttes også for forskellige slutpunkter med pageSize og startIndex forespørgselsparametre
Bemærk: QA swagger har en bredere parameterliste af en eller anden grund
Filteret er en forespørgselsparameter, den har et array-indhold, kan indeholde filterklausuler og logiske relationer.
Hver filterklausul skal selv være en array med følgende struktur:
["felt","operator","værdi"]
Filtre til de nødvendige operationer:
- kun de aktive ordrer:
["Status", "<>", 14]
- så er "Passive"-tilstanden i HMO, enhver ordre med en anden værdi betragtes som "Aktiv"
- ændret inden for en tidsramme
["SidstÆndret", ">", "2023-04-13 00:00:00"]
Datoen kan være i går
- har en specifik kategori
[["OrderCategory", "contains", "Dette er en ordrekategori"], "eller", ["OrderCategory", "contains", "En anden ordrekategori"]]
eller-operatører kan bruges til forskellige mulige værdier
Den fulde filter forespørgselsstreng er følgende:
Filter=[["Status", "<>", 14], "og", ["LastChanged", ">", "2023-04-13 00:00:00"], "og", [["OrderCategory", "contains", "Dette er en ordrekategori"], "eller", ["OrderCategory", "contains", "En anden ordrekategori"]]]
For at reducere "støj" i JSON-svaret er der en mulighed for at projicere resultatet med Vælg forespørgselsparameter.
Vi kan have en JSON med OrderId, OrderCategory (til bagtjek) og Sekundær kunde med værdien af forespørgselsparameteren:
["OrderId", "SecondaryCustomer", "OrderCategory"]
En fuld forespørgselsstreng for denne tilgang ser sådan ud:
api/weboffice/orders?Filter=[["Status","<>",14], "og", ["LastChanged", ">", "2023-04-13 00:00:00"], "og", [["OrderCategory", "contains", "Dette er en ordrekategori"], "eller", ["OrderCategory", "contains", "En anden ordrekategori"]]]&Vælg=["OrderId", "SecondaryCustomer", "OrderCategory"]
Hvilken operation skal vi bruge til at sende FinancialTransactionId, POST /api/orders/{orderId}/materials?
Det afhænger af, hvad FinancialTransactionId er til.
Hvilken operation kan vi bruge til at sende til logfilen i Handyman: POST /api/orders/{orderId}/descriptions
Beskrivelses-endepunktet er ikke det samme som loggene for ordren. Sidstnævnte kaldes messagelog og endepunktet er tilgængeligt under samme navn.