{"swagger":"2.0","info":{"description":"This is a simple API for a3box remote control and content management","version":"1.0.1","title":"a3box Backend API","contact":{"email":"support@egmenergo.cz"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"}},"securityDefinitions":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"tags":[{"name":"general","description":"User and unit information"},{"name":"normal box operations","description":"Box operations in normal manner (goods insertion, status)"},{"name":"service box operations","description":"Box operations in specific situation (failures, abnormal use cases)"},{"name":"log","description":"Log retrieval and manual log entry"}],"security":[{"APIKeyHeader":[]}],"paths":{"/user":{"get":{"tags":["general"],"summary":"gets current user and units info","operationId":"get","produces":["application/json"],"responses":{"200":{"description":"current user object","schema":{"$ref":"#/definitions/User"}}}}},"/units":{"get":{"tags":["general"],"summary":"gets units associated to current user / API key","operationId":"getUnits","parameters":[{"in":"query","name":"skip","description":"number of records to skip for pagination","type":"integer","format":"int32","minimum":0},{"in":"query","name":"limit","description":"maximum number of records to return","type":"integer","format":"int32","minimum":0,"maximum":50}],"produces":["application/json"],"responses":{"200":{"description":"array of associated units","schema":{"type":"array","items":{"$ref":"#/definitions/Unit"}}}}}},"/units/{id}":{"get":{"tags":["general"],"summary":"gets unit information and status of all boxes","operationId":"getUnit","parameters":[{"in":"path","required":true,"name":"id","description":"Unit id","type":"integer"}],"produces":["application/json"],"responses":{"200":{"description":"Unit information","schema":{"type":"object","properties":{"unit":{"$ref":"#/definitions/Unit"},"boxes":{"type":"array","items":{"$ref":"#/definitions/Box"}}}}},"400":{"description":"Bad id requested"}}}},"/units/{id}/freeboxes":{"get":{"tags":["normal box operations"],"summary":"Returns array of box ids available for a insertion of a package.","description":"Returns array of box ids available for a insertion of a package with defined size. Array is sorted in preference (smallest boxes at first). Returns empty array if not available.","parameters":[{"in":"path","required":true,"name":"id","description":"Unit id","type":"integer"},{"in":"query","required":true,"name":"width","description":"Min. box size in mm","type":"integer"},{"in":"query","required":true,"name":"height","description":"Min. box size in mm","type":"integer"},{"in":"query","required":true,"name":"depth","description":"Min. box size in mm","type":"integer"}],"produces":["application/json"],"responses":{"200":{"description":"List of available boxes","schema":{"type":"object","properties":{"boxId":{"type":"array","items":{"type":"integer"}}}}},"400":{"description":"Bad id requested"}}}},"/units/{id}/prepareinsertion":{"post":{"tags":["normal box operations"],"summary":"Prepare box for insertion","description":"Prepare box(es) for insertion, handle nested boxes if needed. Will generate transaction ID. Define packages to be inserted in call parameters. Used boxes array or error value is returned.","parameters":[{"in":"path","required":true,"name":"id","description":"Unit id","type":"integer"},{"in":"body","required":true,"name":"requestData","schema":{"type":"object","properties":{"boxlist":{"description":"Array of requested box IDs. First box will be *leadbox* if more than one box specified.","type":"array","items":{"type":"integer"}},"displayData":{"type":"string","format":"text/json","description":"Package/transaction-specific data to be shown to the customer. User-specific implementation."},"paymentRequestData":{"type":"string","format":"text/json","description":"Payment request specific data to be shown to the customer. User-specific implementation. If prepaid, keep empty. Deliveries divided into more boxes use one box as the *leadbox* (with normal use of *paymentRequestData* and *removalAccessData*), boxes that are to be opened in sequence after the first box use SEQUENCE *removalAccessData* authenticator and use the same transaction ID as the *leadbox*."},"insertAccessData":{"allOf":[{"$ref":"#/definitions/Authenticator"}],"description":"Authenticator specific for insertion into this box (courier access). Will use the same authenticator for all boxes in this transaction. If the provided authenticator has a value triggering authenticator value generator, a new value (non-conflicting to other boxes) is generated."},"removalAccessData":{"allOf":[{"$ref":"#/definitions/Authenticator"}],"description":"Authenticator specific for removal from the single box or  *leadbox* (customer access), will generate SEQUENCE authenticator for consequent boxes. If the provided authenticator has a value triggering authenticator value generator, a new value (non-conflicting to other boxes) is generated."},"transactionTimeoutTime":{"type":"string","format":"date-time","description":"Transaction (current state) timeout time (eg. open to remove goods until 7 days). Exact behavior depends on user-specific implementation, default behavior is to jump to *ServiceLocked* and populate *errorStatus*."}}}}],"produces":["application/json"],"responses":{"200":{"description":"Array of used/reserved boxes.","schema":{"type":"object","properties":{"boxId":{"type":"array","items":{"$ref":"#/definitions/Box"}}}}},"400":{"description":"Bad id requested"}}}},"/units/{id}/{boxid}":{"get":{"tags":["normal box operations"],"summary":"get current box status","parameters":[{"in":"path","required":true,"name":"id","description":"Unit id","type":"integer"},{"in":"path","required":true,"name":"boxid","description":"Box id","type":"integer"}],"produces":["application/json"],"responses":{"200":{"description":"Current box information","schema":{"$ref":"#/definitions/Box"}},"400":{"description":"Bad request, returned detailed error information","schema":{"type":"string","example":"Box does not exist."}}}}},"/units/{id}/{boxid}/setstate":{"post":{"tags":["service box operations"],"summary":"low-level operation, moves state machine to requested state if possible/allowed; uses all relevant data from","parameters":[{"in":"path","required":true,"name":"id","description":"Unit id","type":"integer"},{"in":"path","required":true,"name":"boxid","description":"Box id","type":"integer"},{"in":"body","name":"stateRequest","description":"New box state request, uses relevant not-null values.","schema":{"$ref":"#/definitions/Box"}}],"produces":["application/json"],"responses":{"200":{"description":"Updated box information","schema":{"$ref":"#/definitions/Box"}},"400":{"description":"Bad request, returned detailed error information","schema":{"type":"string","example":"Box does not exist."}}}}},"/log":{"post":{"tags":["log"],"summary":"adds manual log entry","operationId":"addLog","description":"Manual log entry for unit/box.","parameters":[{"in":"body","name":"logEntry","description":"New log entry. Entry originator will be overwritten to \"API\" + client IP address.","required":true,"schema":{"$ref":"#/definitions/LogEntry"}}],"produces":["application/json"],"responses":{"200":{"description":"success"},"400":{"description":"bad input parameter"}}},"get":{"tags":["log"],"summary":"searches log","operationId":"searchLog","description":"By passing in the appropriate options, you can search for available logs in the system","produces":["application/json"],"parameters":[{"in":"query","name":"searchString","description":"pass an optional search string for looking up the logs","required":false,"type":"string"},{"in":"query","name":"unitId","description":"pass an optional unit ID filter for looking up the logs","required":false,"type":"integer"},{"in":"query","name":"boxId","description":"pass an optional box ID filter for looking up the logs","required":false,"type":"integer"},{"in":"query","name":"skip","description":"number of records to skip for pagination; always sorted from latest to oldest","type":"integer","format":"int32","minimum":0},{"in":"query","name":"limit","description":"maximum number of records to return; always sorted from latest to oldest","type":"integer","format":"int32","minimum":0,"maximum":500}],"responses":{"200":{"description":"search results matching criteria","schema":{"type":"array","items":{"$ref":"#/definitions/LogEntry"}}},"400":{"description":"bad input parameter"}}}}},"definitions":{"User":{"type":"object","description":"API user account information object. Contains read-only list of assigned Units and user contact information, used for e-mail alert messages. User authetication to API uses API-keys, so this object is used only for information exchange about the currently authenticated user.","required":["alertPhone"],"properties":{"name":{"type":"string","example":"xsprague","readOnly":true,"description":"User account name, assigned by API/backend administrator."},"description":{"type":"string","example":"XShop Praha, a.s.","readOnly":true,"description":"User account description, assigned by API/backend administrator."},"alertPhone":{"type":"string","example":"+420 543 216 060","description":"User IT support phone for emergencies"},"alertEmail":{"type":"string","format":"email","example":"foo@bar.com","description":"E-mail address used for automatic e-mail alert messages. Keep empty to disable e-mails."},"units":{"type":"array","readOnly":true,"items":{"$ref":"#/definitions/Unit"}}}},"Unit":{"type":"object","description":"Described a unit - one physical control system, serving one or more boxes. Unit is identified by a unique unit id.","required":["name"],"properties":{"id":{"type":"integer","example":17,"readOnly":true,"description":"Unit is identified by a unit id. Unit ID is assigned by manufacturer."},"name":{"type":"string","example":"XShop Praha Nám. míru","description":"Unit description"},"supportWebsite":{"type":"string","format":"url","example":"https://www.acme-corp.com","description":"Customer support website (unit specific)"},"supportPhone":{"type":"string","example":"+420 543 216 060","description":"Customer support phone (unit specific)"},"unitConfig":{"type":"string","format":"text/json","example":{},"readOnly":true,"description":"Individual unit configuration, defined by manufaturer, readonly for API users."},"gpsCoordinates":{"type":"string","example":"41.40338, 2.17403","readOnly":true,"description":"Unit GPS coordinates, defined by manufaturer, readonly for API users."},"modelName":{"type":"string","readOnly":true,"example":"A3 BOX Model X-Mk2","description":"Unit model number, defined by manufaturer, readonly for API users. This is only for human use, model-specific configuration is stored in unitConfig."}}},"Box":{"description":"Object describes a single box of a unit *unitId*. Boxes use a unique *id* in a unit (so unique box identification is the pair (*id*, *unitId*)). There are physical properties defined (position in the unit, internal dimensions, ...) and operation status of the box.\n\nThe box uses a state machine to contain the status of the box loading / unloading, regardless of application. The load-unload process and its exceptions as defined by the state machine are still the same, moreless only the conditions for opening of the box are changing by application. As the authentication process of the courier and of the customer may vary deeply by unit user requirements and user specific implementations, these processes (or settings) are defined in separate JSON objects. The state machine uses these states. States are described in a normal flow sequence.\n- *Unused* ... box is available for use, is empty. The transaction UUID is cleared only in this state.\n- *InsertionReady* ... a courier is expected - box is empty but reserved for a package insertion. Box is locked. A transaction UUID is generated. (In a storage locker scenario, user selects a box for use.)\n- *InsertionOpened* ... a courier has authenticated (remotely or locally, using *insertAccessData*), unit opens the box\n- *InsertionFinished* ... a courier has entered the package into the box. This is a post-insertion guard interval to allow the courier to reopen the box (e.g. by re-authenticating; then moves back to *InsertionOpened*) in order to correct human errors.\n- *BoxInsideUnpaid* ... this state is skipped if the inserted box has no *paymentRequestData*; otherwise the box holds this state until the customer pays the goods (then the status moves to *RemovalReady*)\n- *RemovalReady* ... a customer is expected - box is full.\n- *RemovalOpened* ... a courier has authenticated (remotely or locally, using *removalAccessData*), unit opens the box\n- *RemovalFinished*  the customer has removed the package from the box. This is a post-insertion guard interval to allow the customer to reopen the box (e.g. by re-authenticating; then moves back to *RemovalOpened*) in order to correct human errors. After timeout, unit returns to *Unused* state.\n- Futher states are specific states with a special flow triggered by API user or administrator actions or by detected failures.\n- *ServiceOpen* ... a box was open remotely, using API, or other service access method defined by *serviceAccessData*. After closing, the box state changes to *ServiceLocked*\n- *ServiceLocked* ... this is a state after *ServiceOpen* and closing the box, or after intentional disabling of the box by API or operation timeouts. Administrator or API user must reset the box to *Unused* in order to continue with normal use or to *OutOfOrder* to disable the box (after removal of the package). API users should keep track of boxes in this state as these indicate abnormal conditions. Note that courier can open such box using *serviceAccessData*. User-case specific UI may allow the courier to reset box to *Unused* or *OutOfOrder* locally.\n- *OutOfOrder* ... this is a 'disable this box' state manually set by API user or using other service access method defined by *serviceAccessData*. This state can be reverted by API, or other service access method defined by *serviceAccessData*, to *Unused*, *ServiceLocked* or *ServiceOpen*.\n- *Failure* ... box enters this state automatically after detected failure, further described in *errorStatus*. This state can be reverted by API, or other service access method defined by *serviceAccessData*, to *Unused*, *ServiceLocked* or *ServiceOpen*. Value *errorStatus* is however kept intact until resetting the box to *Unused*.","properties":{"id":{"type":"integer","example":17,"readOnly":true},"unitId":{"type":"integer","example":4,"readOnly":true},"physicalProperties":{"type":"object","readOnly":true,"properties":{"posLeft":{"type":"integer"},"posTop":{"type":"integer"},"mmWidth":{"type":"integer"},"mmHeight":{"type":"integer"},"mmTop":{"type":"integer"},"hasDisinfection":{"type":"boolean"}}},"displayData":{"type":"string","example":{"OrderId":"123-2021"},"readOnly":true,"description":"Package/transaction-specific data to be shown to the customer. User-specific implementation."},"paymentRequestData":{"type":"string","example":{"PriceCZK":1755.14},"readOnly":true,"description":"Payment request specific data to be shown to the customer. User-specific implementation. If prepaid, keep empty. Deliveries divided into more boxes use one box as the *leadbox* (with normal use of *paymentRequestData* and *removalAccessData*), boxes that are to be opened in sequence after the first box use SEQUENCE *removalAccessData* authenticator and use the same transaction ID as the *leadbox*."},"insertAccessData":{"allOf":[{"$ref":"#/definitions/Authenticator"}],"readOnly":true,"description":"Authenticator specific for insertion into this box (courier access). More authenticators may share the same credentials thus allowing access to more boxes."},"removalAccessData":{"allOf":[{"$ref":"#/definitions/Authenticator"}],"readOnly":true,"description":"Authenticator specific for removal from this box (customer access). A nested access for deliveries divided into more boxes is possible using SEQUENCE authenticator."},"serviceAccessData":{"allOf":[{"$ref":"#/definitions/Authenticator"}],"readOnly":true,"description":"Authenticator specific for service access for this box. More authenticators may share the same credentials thus allowing access to more boxes."},"transactionUUID":{"type":"string","format":"uuid","example":"d290f1ee-6c54-4b01-90e6-d701748f0851","description":"This is a transaction UUID. UUID is used to identify single transaction (insertion to removal of package) and is used to link more boxes together for one-payment or one-authentication, more boxes user authentication."},"timestamp":{"type":"string","format":"date-time","readOnly":true,"example":"2025-04-12T23:20:50.52Z","description":"Timestamp of last state machine status change (ISO 8601)"},"disinfectionFinishTime":{"type":"string","format":"date-time","readOnly":true,"example":"2025-04-12T23:20:50.52Z","description":"Disinfection finish time. Empty if disinfection not used. Timer populated in InsertionOpened->InsertionFinished transition. If current time > disinfectionFinishTime, box is properly disinfected. Given by unit settings, the unit may not allow or may warn the customer in case the box is not disinfected properly."},"errorStatus":{"type":"string","readOnly":true,"example":"ERROR 21 Not-commanded box open detection on 2025-04-12T23:20:50.52Z","description":"Human-readable first error message that led the system to move into *Failure* or *ServiceLocked* state. Cleared upon entry to *Unused* state. Consequent errors are available only in log."},"status":{"type":"string","readOnly":true,"example":"Unused","enum":["Unused","InsertionReady","InsertionOpened","InsertionFinished","BoxInsideUnpaid","RemovalReady","RemovalOpened","RemovalFinished","ServiceOpen","ServiceLocked","OutOfOrder","Failure"]},"operationTimeoutTime":{"type":"string","readOnly":true,"format":"date-time","description":"Operation (current state) timeout time (eg. finish *RemovalOpened* in 10 minuts). Empty if not used in current state. Exact behavior depends on user-specific implementation, default behavior is to jump to *ServiceLocked* and populate *errorStatus*."},"transactionTimeoutTime":{"type":"string","readOnly":true,"format":"date-time","description":"Transaction (current state) timeout time (eg. open to remove goods until 7 days). Exact behavior depends on user-specific implementation, default behavior is to jump to *ServiceLocked* and populate *errorStatus*."},"oooRequested":{"readOnly":true,"type":"boolean","description":"This is used to disable the box after current transaction for maintenance. Set to true on all boxes to disable whole unit. State machine jumps to *OutOfOrder* with proper error message as soon as the state machine enters *Unused* state."}}},"Authenticator":{"description":"Authenticator specific for a box/transaction. Default is a numeric access code (method=CODE), other user-specific implementations (like remote authentication to a server) are possible. With method=SEQUENCE, box opens after opening of a *leadbox* with the same transaction ID in multi-box delivery scenario.","required":["method","accessCode"],"type":"object","properties":{"method":{"type":"string","enum":["CODE","SEQUENCE"],"example":"CODE","description":"Authenticator method. SEQUENCE is allowed only in *removalAuthenticator* role."},"value":{"description":"Numeric code in CODE method (including lead zeros, code length is defined by string length), eg. 001742. If sending the authenticator object into API, the value may be defined as sequence of dots, then the authenticator library created a numeric code in length according to the seqence length, unique among all codes (insertion, removal, service) in the unit. In SEQUENCE method assigns priority of opening sequence (*leadbox* first, then boxes from lower to upped values, in case the values are equal, sequence is not defined.)","type":"string","example":123456}}},"LogEntry":{"properties":{"id":{"type":"integer","example":17,"readOnly":true,"description":"Log item id."},"timestamp":{"type":"string","format":"date-time","readOnly":true,"example":"2025-04-12T23:20:50.52Z","description":"Timestamp of log entry"},"unitId":{"type":"integer","example":4147,"description":"Unit ID reference"},"boxId":{"type":"integer","example":27,"description":"Box ID reference. Value is -1 for unit-related events."},"severity":{"type":"string","enum":["DEBUG","INFORMATION","WARNING","ERROR","FATAL"]},"text":{"type":"string","example":"Disinfection on lock board 0 activated."},"originator":{"type":"string","example":"Backend v. 1.0.0, 172.0.14.1"}}}},"host":"virtserver.swaggerhub.com","basePath":"/EGMenergo/a3box/1.0.0","schemes":["https"]}