--- title: API´s ESP -Enterprise Service Platform slug: dev-en/apis-esp-enterprise-service-platform description: This document provides a comprehensive overview of a service request system's communication structure and APIs. It delves into various API requests like "GetOldest," "GetByCoordinates," and "GetById," explaining their parameters, fields, and corresponding docTags: createdAt: 2022-03-07T15:15:21.000Z --- This section is intended to describe the communication structure REST, established between applications and the back-end server. :::hint{type="danger"} "**CITSMART\_URL**": URL unalterable prefix, so that you can access the services made available to the mobile applications. *ALL API THAT REQUIRES A “**sessionID**” WILL NEED TO BE IN A SESSION PROVIDED BY THE “Login” API.* ::: *** ### Login "Login the user to use CITSmart Services." :::CodeblockTabs ```none POST ``` ```html /services/v2/login ``` ```JSON Request { "userName": "mobile", "password": "123456", "token": "API132654ASFE32132121­5412", "platform": "android" } ``` ```JSON Response { "sessionID": "2355A68BF75281B73607EEC1A7191645", "rangeAction": 10, "locationInterval": 10 } ``` ```none Request: userName: alphanumeric not empty and not null; password: alphanumeric not empty and not null; token: alphanumeric not empty and not null, referring to the device identifier for sending the push notification; platform: referring to the platform type (ios or android) from which the user will log in; Response: sessionID: cannot be null or empty. rangeAction: is integer, not null and can be zero. It represents the action radius of a field user in KM. locationInterval: is integer, not null, and greater than zero. Represents, in minutes, the time interval that the App must send the positioning of the attendant. ``` ::: ### ListContracts List the contracts accessible to the attendant." :::CodeblockTabs ```none POST ``` ```html /services/v2/contracts ``` ```JSON { "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1412101947000, "operationID": 65, "error": null, "contracts": [ { "id": 1, "description": "Test Name" } ] } ``` ```none Request : sessionID: alphanumeric not null and not empty; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; contracts: not empty and not null; id: numeric not empty and not null; description: alphanumeric not empty and not null ``` ::: ### ListDeniedReasons List the reasons when refusing a request, like in the check-in." :::CodeblockTabs ```none POST ``` ```html /services/v2/deniedReasons ``` ```JSON { "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1412101988000, "operationID": 666, "error": null, "reasons": [ { "id": 1, "description": "First Suspension Reason" }, { "id": 2, "description": "Second Suspension Reason" } ] } ``` ```none Request : sessionID: alphanumeric not null and not empty; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; reasons: not empty and not null; id: numeric not empty and not null; description: alphanumeric not empty and not null; ``` ::: ### ListSolicitationStatus List status of a request to be used, for example, in the checkout service." :::CodeblockTabs ```none POST ``` ```html /services/v2/status ``` ```JSON { "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1412101662000, "operationID": 64, "error": null, "status": [ { "id": 1, "description": "In progress" }, { "id": 2, "description": "Suspended", "justifications": [ { "id": 1, "description": "First Suspension Reason" }, { "id": 2, "description": "Second Suspension Reason" } ] }, { "id": 3, "description": "Canceled" }, { "id": 4, "description": "Solved", "justifications": [ { "id": 1, "description": "Reconfigured database user", "parentId": null }, { "id": 2, "description": "Any other solution here", "parentId": 1 } ] } ] } ``` ```none Request : sessionID: alphanumeric not null and not empty; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; status: not empty and not null; id: numeric not empty and not null; description: alphanumeric not empty and not null; ``` ::: ### ListUnits List the units of a contract" :::CodeblockTabs ```none POST ``` ```html /services/v2/units ``` ```JSON { "sessionID": "2355A68BF75281B73607EEC1A7191645" "contractID": 1233 } ``` ```JSON { "dateTime": 1412101988000, "operationID": 66, "error": null, "units": [ { "id": 1, "description": "Default" }, { "id": 2, "description": "Unit Test" } ] } ``` ```none Request : sessionID: alphanumeric not null and not empty; contractID: numeric not null Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; units: not empty and not null; id: numeric not empty and not null; description: alphanumeric not empty and not null; ``` ::: ### SendCoordinates Update the geographical coordinates of a unit." :::CodeblockTabs ```none POST ``` ```html /services/v2/coordinates ``` ```JSON { "unitID": 222, "sessionID": "2355A68BF75281B73607EEC1A7191645", "latitude": -19.369852147, "longitude": -49.369852147 } ``` ```JSON { "dateTime": 1412102841000, "operationID": 68, "error": null, "success": true } ``` ```none Request : unitID: numeric not null; sessionID: alphanumeric not empty and not null; latitude: numeric not null; longitude: numeric not null; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; success: boolean; ``` ::: ### DeviceDisassociate Disassociate a user from a device, so that when a user deletes a connection, the user no longer receives push notification from the deleted connection." :::CodeblockTabs ```none POST ``` ```html /services/v2/disassociate ``` ```JSON { "connection": "http://citsmart.centralit.com.br", "sessionID": "2355A68BF75281B73607EEC1A7191645", "token": "API132654ASFE32132121¬5412" } ``` ```JSON { "dateTime": 1412102841000, "operationID": 68, "error": null, "success": true } ``` ```none Request : connection: alphanumeric not empty and not null, referring to the connection deleted by the user; sessionID: alphanumeric not empty and not null; token: alphanumeric not empty and not null, referring to the token to be disassociated; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; success: boolean; ``` ::: ### GetNewest Recover the most recent request for the user in the group, from the latest (newestNumber) in the App " :::CodeblockTabs ```none POST ``` ```html /services/v2/getNewest ``` ```JSON { "notificationType": 0, "onlyApproval": 1, "newestNumber": 322, "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1377618318000, "operationID": 336, "error": null, "notifications": [ { "number": 95933, "taskId": 22737, "type": 1, "date": "27/08/2013", "timeFlag": 12345, "timeSLA": 12, "latitude": 32.9984730, "longitude": 29.9984730, "endSLA": "null", "task": "Validar requisição", "personal": true, "inService": true, "inCkeckin": 0, "typeRequest": 0, "waiting": 1, "service": "SERVICES AND PRODUCTS REQUEST", "contract": 1, "unit": 15, "priorityorder": 1 } ] } ``` ```none Request : notificationType: numeric not null; onlyApproval: numeric not null; sessionID: alphanumeric not null and not empty; newestNumber: numeric not null; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; notifications: not null; number: numeric not null; taskId: numeric not null; type: numeric not empty and not null; 0 - All 1 - Purchases 2 - Travels 3 - HR 4 - Incidents 5 - Others 6 - Waiting date: date string in dd/mm/yyyy format; timeFlag: Number that defines the period; 0 - In time 1 - Less than an hour 2 - Overdue timeSLA: numeric integer not null, in minutes; latitude: numeric; longitude: numeric; endSLA: date in alphanumeric in the patterns dd/MM/ yyyy HH:mm or MM/dd/yyyy HH:mm, depending on the locale, which may have null value. task: alphanumeric not empty and not null; personal: boolean that identifies whether the request is signed for the user or if it's from the group; inService: non-null boolean that identifies whether the request is in attendance; inCheckin: Flag that identifies whether a request is in Personal check (true or false); 0 – Waiting checkin 1 – In Cleckin service: alphanumeric not empty and not null; typeRequest: Flag that identifies the execution type of a request 0 - Request Execution 1 - Request Approval waiting: Flag that defines the status of the request. 0 - Monitoring 1 - Execution available contract: numeric not null; unit: numeric not null; priorityorder: numeric value that can present null value, sequence number that identifies if the manager ordered the attendance; ``` ::: ### GetOldest Recover the most recent request for the user in the group, from the oldest." :::CodeblockTabs ```none POST ``` ```html /services/v2/getOldest ``` ```JSON { "notificationType": 0, "onlyApproval": 1, "oldestNumber": 322, "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1377618318000, "operationID": 336, "error": null, "notifications": [ { "number": 95933, "taskId": 22737, "type": 1, "date": "27/08/2013", "timeFlag": 12345, "timeSLA": 12, "latitude": 32.9984730, "longitude": 29.9984730, "endSLA": "null", "task": "Validate request", "personal": true, "inService": true, "inCheckin": 1, "typeRequest": 0, "waiting": 1 "service": "SERVICES AND PRODUCTS REQUEST", "contract": 1, "unit": 15, "priorityorder": 1 } ] } ``` ```none Request : notificationType: numeric not null; onlyApproval: numeric not null; sessionID: alphanumeric not null and not empty; oldestNumber: numeric not null; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; notifications: not null; number: numeric not null; taskId: numeric not null; type: numeric not empty and not null; 0 - All 1 - Purchases 2 - Travels 3 - HR 4 - Incidents 5 - Others 6 - Waiting date: date string in the format dd/mm/yyyy; timeFlag: Number that defines the period; 0 - In time 1 - Less than an hour 2 - Overdue timeSLA: numeric integer not null, in minutes; latitude: numeric; longitude: numeric; endSLA: date in alphanumeric in the patterns dd/MM/ yyyy HH:mm or MM/dd/yyyy HH:mm, depending on the locale, which may have null value. task: alphanumeric not empty and not null; personal: boolean that identifies whether the request is signed for the user or if it's from the group; inService: non-null boolean that identifies whether the request is in service; inCheckin: Flag that identifies whether a request is in the checkin Personal (true or false); 0 – Waiting checkin 1 – In Cleckin service: alphanumeric not empty and not null; typeRequest: Flag that identifies the type of execution of a request 0 - Request Execution 1 - Request Approval waiting: Flag that defines the status of the request 0 - Monitoring 1 - Execution available contract: numeric not null; unit: numeric not null; priorityorder: numeric value that can present null value, sequence number that identifies if the manager ordered the service; ``` ::: ### GetByCoordinates Recover the most recent request for the user in the group, from the user's current coordinates." :::CodeblockTabs ```none POST ``` ```html /services/v2/getByCoordinates ``` ```JSON { "notificationType": 0, "onlyApproval": 1, "latitude": 32.9984730, "longitude": 29.9984730, "sessionID": "2355A68BF75281B73607EEC1A7191645", "pager": { "page": 1, "size": 10 } ``` ```JSON { "dateTime": 1377618318000, "operationID": 336, "error": null, "notifications": [ { "number": 95933, "taskId": 22737, "type": 1, "date": "27/08/2013", "timeFlag": 12345, "timeSLA": 12, "latitude": 32.9984730, "longitude": 29.9984730, "endSLA": "null", "task": "Validate request", "typeRequest": 0, "waiting": 1 "personal": true, "inService": true, "inCheckin": 1, "service": "SERVICES AND PRODUCTS REQUEST", "contract": 1, "unit": 15, "priorityorder": 1 } ], "paging": { "page": 1, "size": 1, "totalElements": 5, "totalPages": 5 } } ``` ```none Request : notificationType: numeric not null; onlyApproval: numeric not null; latitude: numeric not null; longitude: numeric not null; sessionID: alphanumeric not null and not empty; pager: pagination information: page: page number to be queried, starting from 1; size: number of elements to return; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; notifications: not null; number: numeric not null; taskId: numeric not null; type: numeric not empty and not null; 0 - All 1 - Purchases 2 - Travels 3 - HR 4 - Incidents 5 - Others 6 - Waiting date: date string in the format dd/mm/yyyy; timeFlag: Number that defines the period; 0 - In time 1 - Less than an hour 2 - Overdue timeSLA: numeric integer not null, in minutes; latitude: numeric not null; longitude: numeric not null; endSLA: date in alphanumeric in the patterns dd/MM/ yyyy HH:mm or MM/dd/yyyy HH:mm, depending on the locale, which may have null value. task: alphanumeric not empty and not null; personal: boolean that identifies whether the request is signed for the user or if it's from the group; inService: non-null boolean that identifies whether the request is in service; inCheckin: Flag that identifies whether a request is in the checkin Personal (true or false); 0 – Waiting checkin 1 – In Cleckin service: alphanumeric not empty and not null; typeRequest: Flag that identifies the type of execution of a request 0 - Request Execution 1 - Request Approval waiting: Flag that defines the status of the request. 0 - Monitoring 1 - Execution available contract: numeric not null; unit: numeric not null; priorityorder: numeric value that can present null value, sequence number that identifies if the manager ordered the service; paging: pagination information 1. page: number of the current page 2. size: size of the page returned 3. totalElements: total of elements according to the query totalPages: total of pages according to the query ``` ::: ### UpdateNotification Retrieve the tasks of a service." :::CodeblockTabs ```none POST ``` ```html /services/v2/update ``` ```JSON { number": 322, "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1377618318000, "operationID": 336, "error": null, "notifications": [ { "number": 95933, "taskId": 22737, "type": 1, "date": "27/08/2013", "timeFlag": 12345, "timeSLA": 12, "latitude": 32.9984730, "longitude": 29.9984730, "endSLA": "null", "task": "Validate request", "personal": true, "inService": true, "inCheckin": 1, "typeRequest": 0, "waiting": 1 "service: "SERVICES AND PRODUCTS REQUEST", "contract": 1, "unit": 15, "priorityorder": 1 } ] } ``` ```none Request : notificationType: numeric not null; onlyApproval: numeric not null; sessionID: alphanumeric not null and not empty; oldestNumber: numeric not null; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; notifications: not null; number: numeric not null; taskId: numeric not null; type: numeric not empty and not null; 0 - All 1 - Purchases 2 - Travels 3 - HR 4 - Incidents 5 - Others 6 - Waiting date: date string in format dd/mm/yyyy; timeFlag: Number that defines the period; 0 - In time 1 - Less than an hour 2 - Overdue timeSLA: numeric integer not null, in minutes; latitude: numeric; longitude: numeric; endSLA: date in alphanumeric in the patterns dd/MM/ yyyy HH:mm or MM/dd/yyyy HH:mm, depending on the locale, which may have null value. task: alphanumeric not empty and not null; personal: boolean that identifies whether the request is signed for the user or if it's from the group; inService: non-null boolean that identifies whether the request is in service; inCheckin: Flag that identifies whether a request is in the checkin Personal (true or false); 0 – Waiting checkin 1 – In Cleckin service: alphanumeric not empty and not null; typeRequest: Flag that identifies the type of execution of a request 0 - Request Execution 1 - Request Approval waiting: Flag that defines the status of the request. 0 - Monitoring 1 - Execution available contract: numeric not null; unit: numeric not null; priorityorder: numeric value that can present null value, sequence number that identifies if the manager ordered the service; ``` ::: ### GetById Retrieves details of a request, according to its identifier" :::CodeblockTabs ```none POST ``` ```html /services/v2/getById ``` ```JSON { "taskId": 22737, "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1377618392000, "operationID": 337, "error": null, "notification": { "endSLA": "null", "task": "Validate request", "service": "SERVICES AND PRODUCTS REQUEST", "description": " test", "status": "In progress", "taskStatus": "Available", "timeSLA": 12 } } ``` ```none Request : taskId: numeric not null; sessionID: alphanumeric not null and not empty; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; notification; not empty and not null; endSLA: date in alphanumeric by the patterns dd/MM/yyyy HH:mm or MM/dd/yyyy HH:mm, depending on the locale. task: alphanumeric not empty and not null; service: alphanumeric not empty and not null; description: alphanumeric not empty and not null; status: alphanumeric not empty and not null; taskStatus: alphanumeric not empty and not null; timeSLA: numeric integer not null, in minutes; ``` ::: ### GetReasons Recover motives to be used in the approval of a request, according to the request." :::CodeblockTabs ```none POST ``` ```html /services/v2/getReasons ``` ```JSON { "taskId": 22737, "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1377618482000, "operationID": 339, "error": null, "amount": 4, "reasons": [ { "id": 1, "desc": "Non-refundable authorization" }, { "id": 4, "desc": "Purchase necessary to the business" }, { "id": 6, "desc": "Purchase need supplied with another solution" }, { "id": 5, "desc": "Value of quotation above the budget of the contract" } ] } ``` ```none Request : taskId: numeric not null; sessionID: alphanumeric not null and not empty; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; amount: numeric not empty and not null; reasons; not empty and not null; id: numeric not empty and not null; desc: alphanumeric not empty and not null; ``` ::: ### AttendRequest Inform the beginning of attendance of a service request " :::CodeblockTabs ```none POST ``` ```html /services/v2/attendRequest ``` ```JSON { "number": 89647, "latitude": -19.369852147, "longitude": -49.369852147, "dateTime": 1377618517000, "sessionID": "2355A68BF75281B73607EEC1A7191645" } ``` ```JSON { "dateTime": 1377618517000, "operationID": 341, "error": null, "success": true } ``` ```none Request : number: numeric not null; latitude: numeric not null; longitude: numeric not null; dateTime: timestamp not empty and not null; sessionID: alphanumeric not null and not empty; Response : dateTime: timestamp not empty and not nul; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; success: boolean that identifies the successful completion of the operation; ``` ::: ### AttendantLocation Reports the automatic location of the attendant position." :::CodeblockTabs ```none POST ``` ```html /services/v2/ location ``` ```JSON { "sessionID": "2355A68BF75281B73607EEC1A7191645", "latitude": -19.369852147, "longitude": -49.369852147, "dateTime": 1412102841000 } ``` ```JSON { "dateTime": 1412102841000, "operationID": 68, "error": null, "success": true } ``` ```none N/A ``` ::: ### Feedback Register an approval or denial of a service request." :::CodeblockTabs ```none POST ``` ```html /services/v2/feedback ``` ```JSON { "taskId": 22736, "feedback": 0, "reasonId": 1, "comments": "Comments", "sessionID": "2355A68BF75281B73607EEC1A7191645} ``` ```JSON { "dateTime": 1377618517000, "operationID": 341, "error": null } ``` ```none Request : taskId: numeric not null; feedback: numeric not null: 0 - request rejection; 1 - request approval; reasonId: numeric not null; comments: alphanumeric not null and not empty; sessionID: alphanumeric not null and not empty; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; ``` ::: ### New Create a new request." :::CodeblockTabs ```none POST ``` ```html /services/v2/new ``` ```JSON { "description": "Teste mobile", "sessionID": "2355A68BF75281B73607EEC1A7191645", "latitude": -19.369852147, "longitude": -49.369852147} ``` ```JSON { "dateTime": 1377618543000, "operationID": 342, "error": null, "number": 95935 } ``` ```none Request : description: alphanumeric not null and not empty; sessionID: alphanumeric not null and not empty; latitude: numeric not null; longitude: numeric not null; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; number: alphanumeric not empty and not null; ``` ::: ### Check-In Check-in of the attendant in a request. In other words, it initiates the fulfillment of the request." :::CodeblockTabs ```none POST ``` ```html /services/v2/checkin ``` ```JSON { "taskId": 22778, "sessionID": "2355A68BF75281B73607EEC1A7191645", "latitude": -19.369852147, "longitude": -49.369852147, "startTime": 1377618543000} ``` ```JSON { "dateTime": 1377618543000, "operationID": 342, "error": null, "number": 95935 } ``` ```none Request : taskId: numeric not null; sessionID: alphanumeric not null and not empty; latitude: numeric not null; longitude: numeric not null; startTime: timestamp not empty and not null of the time that the attendant requests "Check-in" Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; number: alphanumeric not empty and not null; ``` ::: ### Check-Out Checks out an attendant in a request, updating their status ("Suspended", "Solved", etc.)." :::CodeblockTabs ```none POST ``` ```html /services/v2/checkout ``` ```JSON { "taskId": 22778, "sessionID": "2355A68BF75281B73607EEC1A7191645", "latitude": -19.369852147, "longitude": -49.369852147, "status": 5, "solution": 5, "descSolution": "Descrição da Solução" } ``` ```JSON { "dateTime": 1377618517000, "operationID": 342, "error": null, "number": 95935 } ``` ```none Request : taskId: numeric not null; sessionID: alphanumeric not null and not empty; latitude: numeric not null; longitude: numeric not null; status: numeric not null, according to return of service "ListNotivicationStatus" solution: numeric, informed only when a status of "Solved (4)" or "Suspended (2)" descSolution: alphanumeric, non-null and non-empty, reported only when status equal to "Solved (4)" or "Suspended (2)" Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; number: alphanumeric not empty and not null; ``` ::: ### Check-InDenied Register the denial of a request attendance by the attendant, in cases of refusal to the check-in. " :::CodeblockTabs ```none POST ``` ```html /services/v2/denied ``` ```JSON { "taskId": 22778, "sessionID": "2355A68BF75281B73607EEC1A7191645", "latitude": -19.369852147, "longitude": -49.369852147, "dateTime": 1377618543000, "reasonId": 1377618543000 } ``` ```JSON { "dateTime": 1377618543000, "operationID": 342, "error": null } ``` ```none Request : taskId: numeric not null; sessionID: alphanumeric not empty and not null; latitude: numeric not null; longitude: numeric not null; reasonId: numeric and not null. Obtained by calling the "GetDeniedReasons" service; Response : dateTime: timestamp not empty and not null; operationID: numeric not empty and not null; error: alphanumeric value that can be null but not empty; number: alphanumeric not empty and not null; ``` :::