API Machine

12 endpoints — generated 2026-03-25 18:15

API_Machine — Qu'est-ce que c'est ?

API_Machine est l'API de synchronisation entre les machines physiques SmartLockers et le back-office. Elle est destinée exclusivement aux machines embarquées (pas aux applications mobiles).

Contrainte matérielle : les machines SmartLockers attendent toujours HTTP 200. L'API ne renvoie jamais de code d'erreur HTTP (4xx/5xx) — toutes les erreurs métier sont dans le tableau errors[] du JSON.

Authentification

Mode 1 — Login / Mot de passe

Envoyer login et passwd en POST à chaque requête.

POST /index.php
login=ML001&passwd=secret&action=GETSELECT

Mode 2 — Middleware (x-api-key)

Envoyer l'en-tête x-api-key et le paramètre POST uuid_machine.

POST /index.php
Header: x-api-key: YOUR_KEY
uuid_machine=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&action=GETSELECT

Mode 3 — Expire-based (POSTINSERT / PUTUPDATE / POSTEVENT)

Les routes d'écriture utilisent un mécanisme d'expiration intégré au JSON. Le champ expire est un timestamp Y-m-d H:i:s et uuid identifie de manière unique chaque requête (idempotence). 

data={"uuid":"req-uuid","expire":"2024-12-31 23:59:59","data":{"table":"...","uuid":"...","fields":{...}}}

Format de réponse

Toutes les requêtes répondent avec HTTP 200 et un corps JSON. Les erreurs ne provoquent jamais de code HTTP d'erreur. 

{
  "machines": [...],
  "lockers": [...],
  "errors": []
}

Les erreurs métier sont accumulées dans errors[]. Une réponse sans errors ou avec un tableau vide est un succès.

HTTPS obligatoire

Toutes les requêtes doivent utiliser HTTPS. Les requêtes HTTP non-sécurisées sont rejetées avec un code 403 immédiatement à l'entrée.

Tester avec Bruno

Télécharger la collection Bruno (.zip)

Importer la collection

  1. Télécharger et décompresser l'archive bruno-collection.zip.
  2. Ouvrir Bruno (application desktop open-source).
  3. Cliquer sur Open Collection et sélectionner le dossier décompressé.
  4. Sélectionner l'environnement prod (ou local / lab).
  5. Configurer les variables : machine_login, machine_passwd.

Bruno est disponible sur usebruno.com. Les fichiers .bru sont du texte brut versionnable avec Git.

Allocations

▶ POST MachineAllocateLocker none {{base_url}}/index.php?action=MachineAllocateLocker
Stable

Create an external locker allocation (Rent type) by ext_ref_locker.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Create an external locker allocation (Rent type).

Requires machine auth (login/passwd OR x-api-key + uuid_machine).

Required allocation JSON fields:
ext_ref_locker — external locker reference (must match a locker's ExtRefLocker)
ext_ref_user — external user reference (email or ID)
ext_ref_booking — external booking reference (unique per allocation)
start — allocation start datetime (Y-m-d H:i:s)
finish — allocation finish datetime (Y-m-d H:i:s)

Optional:
email — if set and valid, triggers notification
phone — user phone number

Response:
success: "Insert successfull"
code: <4-digit locker code>
allocation: <echo of input>

Errors:
"Ext parameters not renseigned"
"Start or finish date not renseigned"
"Start higher than finish"
"No locker founded for your Exts"
"No locker match to a transaction"
"Transaction found but there is an error in her"
"No ID customer found"
"Transaction expired and autorebill is off"
"Collision with another allocation"
"Start is inferior to the actual date : ... fin date"

Exemple de réponse

{
    "success": "Insert successfull",
    "code": "1234",
    "allocation": []
}
▶ POST MachineUpdateAllocateLocker none {{base_url}}/index.php?action=MachineUpdateAllocateLocker
Stable

Update an existing external locker allocation dates and user reference.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Update an existing external locker allocation.

Requires machine auth (login/passwd OR x-api-key + uuid_machine).

Looks up the allocation by ext_ref_booking and updates Start/Finish/ExtRefUser.
Also checks for collision with other bookings on the same locker (excludes
the current booking from the collision check).

Required allocation JSON fields:
ext_ref_locker — external locker reference
ext_ref_user — updated user reference
ext_ref_booking — booking to update (must already exist)
start — new start datetime (Y-m-d H:i:s)
finish — new finish datetime (Y-m-d H:i:s)

Response:
success: "successfull update"

Errors:
"No ExtRefLocker, ExtRefUser or ExtRefBooking found"
"Start higher than finish"
"Allocation not found"
"Collision with another allocation"
"No locker founded for your Exts"

Exemple de réponse

{
    "success": "successfull update"
}
▶ POST MachineCancelAllocateLocker none {{base_url}}/index.php?action=MachineCancelAllocateLocker
Stable

Soft-delete (cancel) an existing external locker allocation. Resets locker if currently active.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Soft-delete (cancel) an existing external locker allocation.

Requires machine auth (login/passwd OR x-api-key + uuid_machine).

Sets Type='Supp' on the matching lockersallocations row.
If the allocation is currently active (Start < NOW < Finish), also resets
the locker: restores the owner's code, clears ExtRefUser and ExtRefBooking.

Required allocation JSON fields:
ext_ref_locker — external locker reference
ext_ref_user — user reference
ext_ref_booking — booking to cancel

Response:
success: "successfull soft delete"
deallocation: "deallocation done" (only if allocation was currently active)

Errors:
"No ExtRefLocker, ExtRefUser or ExtRefBooking found"
"Allocation not found"

Exemple de réponse

{
    "success": "successfull soft delete"
}
▶ POST MachineAllocateLockerIntern none {{base_url}}/index.php?action=MachineAllocateLockerIntern
Stable

Create an internal locker allocation for staff use via lockers_tmp/lockersallocations_tmp tables.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Create an internal locker allocation (for staff / hotel internal use).

Requires machine auth (login/passwd OR x-api-key + uuid_machine).

Uses lockers_tmp and lockersallocations_tmp tables.
Finds or creates a user (by phone + IdEntreprise) and customer record, then
inserts the allocation.

Required allocation JSON fields:
phone — user phone number
email — user email (must be a valid email address)
ext_ref_locker — external locker reference (must match lockers_tmp.ExtRefLocker)
start — allocation start datetime (Y-m-d H:i:s)
finish — allocation finish datetime (Y-m-d H:i:s)

Optional:
ext_ref_booking — external booking reference

Response:
success: "Insert successfull"
allocation: <echo of input>

Errors:
"Phone and email are required"
"Start or finish date not renseigned"
"Oh no ! 😢" (invalid email)
"Start higher than finish"
"No locker found"
"No customer for this transaction"
"Collision with another allocation"
"Insert failed"

Exemple de réponse

{
    "success": "Insert successfull",
    "allocation": []
}

Auth

▶ POST Machine Login (login/passwd) none {{base_url}}/index.php?action=GETSELECT
Draft

Curl

curl -X POST "https://machines-api.smartlockers.io/"
▶ POST Middleware Auth (x-api-key) none {{base_url}}/index.php?action=GETSELECT
Draft

Headers

HeaderValue
x-api-key{{middleware_api_key}}

Curl

curl -X POST "https://machines-api.smartlockers.io/" \
  -H "x-api-key: {{middleware_api_key}}"

Sync

▶ POST GETSELECT (no filter) none {{base_url}}/index.php?action=GETSELECT
Draft

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Returns a full machine snapshot: machines, lockers, lockersbookings, envvars,
cyber* tables, users, transactions, credentials, translations, contexthelps.

Optional filters:
table=<tablename> — restrict to a single table
fieldname=<fieldname> — filter by field (combined with table)
fieldvalue=<value> — filter value
operator==|<|>|LIKE — comparison operator (default: =)

▶ POST GETACTION none {{base_url}}/index.php?action=GETACTION
Stable

Fetch the first pending action for this machine. Returns action payload or empty object.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Fetch the first pending action for this machine from machines_action.

If a pending action exists, $_JSON is replaced entirely with the action
payload (type, payload, expire, id) and the action is marked as Sent.

If no pending action exists, the response is an empty JSON object {}.

Requires machine authentication (x-api-key or login/passwd).

Exemple de réponse

{
    "type": "reboot",
    "payload": [],
    "expire": "2024-12-31 23:59:59",
    "id": 42
}
▶ POST POSTEVENT none {{base_url}}/index.php?action=POSTEVENT
Stable

Insert a machine event record into machines_event. Duplicate UUIDs are silently accepted.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Insert a machine event record into machines_event.

Valid types: exception, opened, closed, initialised, payement,
webhooks, notification, teamnotification

For exception type, valid levels: notice, warning, error, critical

Duplicate UUIDs are silently accepted (ignored with $_JSON.ignored set).

Required POST fields:
action = POSTEVENT
data = JSON { uuid, expire, data: { table, uuid,
fields: { type, datetime, payload, [level] } } }

Exemple de réponse

{
    "status": 200
}
▶ POST GETHELP none {{base_url}}/index.php?action=GETHELP
Stable

Returns field descriptors for every readable/writable table with access labels.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Returns a descriptor for every field in every readable/writable table.

Each field entry contains its access label:
[ReadOnly] — present in the sync map, not writable
[ReadWrite] — writable and updatable (WRITABLES value = true)
[AppendOnly] — writable on insert only (WRITABLES value = false)

UUID foreign-key fields (from CONVERTABLES) show the target table name.

Requires machine authentication (x-api-key or login/passwd).

Exemple de réponse

{
    "help": {
        "machines": {
            "Login": "[ReadOnly]"
        },
        "lockers": {
            "flag": "[ReadWrite]"
        }
    },
    "errors": []
}

Write

▶ POST POSTINSERT none {{base_url}}/index.php?action=POSTINSERT
Stable

Insert a new record into a writable table by UUID. Duplicate UUIDs are promoted to PUTUPDATE.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Insert a new record into a writable table by UUID.

If the UUID already exists, the request is silently promoted to PUTUPDATE
and $_JSON.warning = 'duplicate_uuid_go_update' is set.

Required POST fields:
action = POSTINSERT
data = JSON { uuid, expire, data: { table, uuid, fields: { ... } } }

Exemple de réponse

{
    "status": 200,
    "uuid": "...",
    "table": "machines_event",
    "action": "insert"
}
▶ POST PUTUPDATE none {{base_url}}/index.php?action=PUTUPDATE
Stable

Update an existing record by UUID. AppendOnly fields are silently skipped.

Curl

curl -X POST "https://machines-api.smartlockers.io/"

Description

Update an existing record by UUID.

Only fields declared as updatable (true) in WRITABLES are applied.
AppendOnly fields (false) are silently skipped.

Required POST fields:
action = PUTUPDATE
data = JSON { uuid, expire, data: { table, uuid, fields: { ... } } }

Exemple de réponse

{
    "status": 200,
    "uuid": "...",
    "table": "lockers",
    "action": "update"
}