Wiki source code of get_ddd_details.php

Last modified by YellowFox_RD on 2024/12/19 10:11
Show last authors
1 (% class="box" %)
2 (((Table of Contents)))
3 {{toc/}}
4
5 Offers access to parsed data of a digitacho file. **Only supports driver files.**
6 = Description =
7 (% class="green mark" %)GET(%%)//** /get_ddd_details.php?company**=RTI_COMPANYKEY**&import**=RTI_IMPORTKEY**&file**=UUID//
8
9 = Parameter =
10 |=Parameter|=Description|=Type|=Note|=Mandatory
11 |company|RTI company key|string||yes
12 |import|RTI import key|string||yes
13 |file|UUID of requested file|string|You can get this value via [[get_file_list.php>>doc:YellowFox Remote Tracking Interface.Funktionen.Abfrageseiten.get_file_list\.php.WebHome]]|yes
14
15 = Return =
16 A **string** in Json format is returned. Returns "(% class="error" %)**ERROR:description**(%%)" on error.
17
18 == General ==
19 A digitacho file consists of different data blocks. Not all blocks are always set. This RTI function will only return blocks that are available. Additionally you have to ditinct between data block of generation 1 data and generation 2 data. A potential block is therefore described as an object with the possible attributes //G1// and //G2//. These might contain similar data. Generation 2 data can also hold additional information. This function only returns the raw data. You need to merge this data by yourself if needed.
20 The following block are returned if available:
21 (((
22 * information for driver identification (//Identification//)
23 * activity records(//DriverActivityData//)
24 * driver licence information (//DriverLicenceInfo//)
25 * country codes(//Places//)
26 * used vehicles (//VehiclesUsed//)
27 * only for generation 2 cards: GPS data (//GNSSPlaces//)
28 )))
29
30 You can find official information about the structure of digitacho files [[here>>https://eur-lex.europa.eu/legal-content/DE/TXT/?uri=CELEX:32016R0799]]. The return value of this function is based on this. Some data is already processed. For example you will receive countries as country codes, all data is encoded as UTF-8 and time values are formatted according to ISO 8601.
31
32 == JSON ==
33 You can access the specification as a JSON Schema file [[here>>https://map.yellowfox.de/rti/schema/get_ddd_details_schema.json]].
34 **example of return value**
35 {{code language="java"}}{
36     "Identification": {
37         "G1": {
38             "cardIdentification": {
39                 "cardIssuingMemberState": "PL",
40                 "cardNumber": "123456789",
41                 "cardIssuingAuthorityName": "PWPW S.A.",
42                 "cardIssueDate": "2021-03-24T00:00:00+00:00",
43                 "cardValidityBegin": "2021-04-11T00:00:00+00:00",
44                 "cardExpiryDate": "2026-04-10T23:59:59+00:00"
45             },
46             "driverCardHolderIdentification": {
47                 "cardHolderName": "Mustermann, Max",
48                 "cardHolderBirthDate": "08.06.1979",
49                 "cardHolderPreferredLanguage": "PL"
50             },
51             "certState": true
52         }
53     },
54     "DriverActivityData": {
55         "G1": {
56             "cardDriverActivity": {
57                 "cardActivityDailyRecords": [
58                     {
59                         "cardActivityDailyRecord": {
60                             "activityRecordDate": "2021-03-14T00:00:00+00:00",
61                             "activityDayDistance": 0,
62                             "activityChangeInfos": [
63                                 {
64                                     "activityChangeInfo": {
65                                         "slot": 0,
66                                         "drivingStatus": 1,
67                                         "cardStatus": 1,
68                                         "activity": 0,
69                                         "time": 0
70                                     }
71                                     [...]
72                                 }
73                             ]
74                         }
75                     }
76                     [...]
77                 ]
78             },
79             "certState": true
80         }
81     },
82     "DriverLicenceInfo": {
83         "G1": {
84             "cardDrivingLicenceInformation": {
85                 "drivingLicenceIssuingAuthority": "Testamt",
86                 "drivingLicenceIssuingNation": "D",
87                 "drivingLicenceNumber": "12345789 "
88             },
89             "certState": true
90         }
91     },
92     "Places": {
93         "G1": {
94             "cardPlaceDailyWorkPeriod": {
95                 "placeRecords": [
96                     {
97                         "placeRecord": {
98                             "entryTime": "2021-04-11T04:26:45+00:00",
99                             "entryTypeDailyWorkPeriod": 0,
100                             "dailyWorkPeriodCountry": "D",
101                             "dailyWorkPeriodRegion": 0,
102                             "vehicleOdometerValue": 422050
103                         }
104                     }
105                 ]
106             },
107             "certState": true
108         }
109     },
110     "VehiclesUsed": {
111         "G1": {
112             "cardVehiclesUsed": {
113                 "cardVehicleRecords": [
114                     {
115                         "vehicleOdometerBegin": 422050,
116                         "vehicleOdometerEnd": 422050,
117                         "vehicleFirstUse": "2021-04-11T04:26:45+00:00",
118                         "vehicleLastUse": "2021-04-11T23:59:59+00:00",
119                         "vehicleRegistration": {
120                             "vehicleRegistrationNation": "D",
121                             "vehicleRegistrationNumber": "YF 101"
122                         }
123                     }
124                 ]
125             },
126             "certState": true
127         }
128     }
129 }{{/code}}
130
131 == Possible error values ==
132 |=Error|=Description
133 |MISSING_COMPANY|company key is missing
134 |INVALID_COMPANY|Company not found. Company key or import key might be faulty.
135 |ERROR_MAINTENANCE|Your company is under maintenance, no RTI request are possible at the moment.
136 |MISSING_IMPORT|import key is missing
137 |MISSING_FILE|No UUID was given.
138 |NO_FILE_FOUND|Could not find any digitacho file with this UUID.
139 |FILE_PARSING_FAILED|An error occured while trying to parse this file.
140 |FILE_TYPE_NOT_SUPPORTED|File type not supported. Only access for driver files.
141