Aller au contenu
Essai gratuit de 14 jours, sans carte9 langues176 types d'activité · 50 applications
FR· USD
Essayer une démo en directEssai gratuit

Référence API v1

Chaque point d'accès de l'API REST avec sa méthode, son chemin et la portée requise, généré à partir du document OpenAPI servi par l'API.

GET https://<workspace>.zmle.com/api/v1/me

Démarrage rapide

  1. Ouvrez une démo instantanée : un espace de travail avec des données d'exemple
  2. Dans la démo, allez dans Admin → Intégrations et API et créez une clé
  3. Appelez GET /api/v1/me avec la clé (ci-dessous) pour voir à quel espace et à quelle personne elle appartient
  4. Ajoutez un point d'accès webhook et choisissez des événements ; dans une démo, les envois sont journalisés mais jamais envoyés

Document OpenAPI

La spécification complète est publique ; aucune clé n'est nécessaire pour la lire : https://zmle.com/api/v1/openapi.json

curl https://<your-demo>.zmle.com/api/v1/me \
  -H "Authorization: Bearer $ZMLE_API_KEY"

Adresse de base

Chaque espace de travail répond à sa propre adresse : https://<workspace>.zmle.com/api/v1 (ou son propre domaine). L'hôte API https://api.zmle.com/v1 retrouve l'espace à partir de la clé.

Authentification

Envoyez la clé dans Authorization: Bearer <key> (ou X-Api-Key). Les applications natives et connectées utilisent OAuth 2.1 avec PKCE et des jetons d'application de courte durée.

Listes et pagination

Les listes acceptent page et per (1 à 100, 25 par défaut), q pour la recherche et since pour les changements après une date. La réponse contient total et pages, plus les en-têtes Link et X-Total-Count.

Erreurs

Les erreurs sont en JSON : { error: { code, message } } avec le statut HTTP. Chaque réponse a un X-Request-Id. Les requêtes POST acceptent un en-tête Idempotency-Key. Chaque clé dispose d'un quota de 300 requêtes rechargé à 5 par seconde ; X-RateLimit-Remaining indique le reste, et 429 arrive avec Retry-After.

Versions et dépréciation

La v1 ne fait que grandir : de nouvelles routes et de nouveaux champs s'ajoutent, rien n'est supprimé ni renommé dans la v1. Une route appelée à disparaître est marquée dépréciée au moins 12 mois avant son arrêt ; d'ici là elle fonctionne sans changement et répond avec les en-têtes Deprecation et Sunset.

Client TypeScript

Un client TypeScript officiel généré à partir du document OpenAPI est en préparation (méthodes typées, nouvelles tentatives avec Retry-After, clés d'idempotence, pagination). En attendant sa publication, tout générateur OpenAPI fonctionne avec openapi.json.

Codes d'erreur

StatutCodeSignification
400invalid_jsonLe corps n'est pas un JSON valide
401unauthenticatedAucune clé ni jeton n'a été envoyé
401invalid_keyLa clé est inconnue, révoquée ou expirée, ou un jeton MCP a été utilisé sur l'API REST
401token_expiredLe jeton d'application a expiré : renouvelez-le
403insufficient_scopeLa clé n'a pas le droit requis par cette route
403forbiddenLa personne de la clé ne peut pas ouvrir cet espace ou cette fiche
403origin_not_allowedAppel navigateur depuis un site absent des origines autorisées de l'espace
403ip_not_allowedLa liste d'adresses IP autorisées de la clé ne contient pas cette adresse
403test_mode_read_onlyUne clé de test a tenté de modifier des données : les clés de test lisent seulement
404not_foundFiche ou route inexistante dans cet espace de travail
409conflictLa requête entre en conflit avec l'état actuel, par exemple un doublon
422validation_failedDes champs sont invalides ; la réponse liste les problèmes par champ
429rate_limitedTrop de requêtes : attendez le nombre de secondes indiqué par Retry-After
500internal_errorUne erreur s'est produite de notre côté : réessayez plus tard et citez le X-Request-Id si vous nous contactez

La référence ci-dessous est en anglais, comme le document OpenAPI.

Customers

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/customerscustomers:readList customers
GET/api/v1/customers/{id}customers:readRead a customer
POST/api/v1/customerscustomers:writeCreate a customer (an existing e-mail / phone returns that customer)
PATCH/api/v1/customers/{id}customers:writeUpdate a customer's contact details

Leads

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/inquiriesinquiries:readList leads
GET/api/v1/inquiries/{id}inquiries:readRead a lead
POST/api/v1/inquiriesinquiries:writeCreate a lead (contact, quote request, booking request, call-back) — notifies the team like the website form

Quotations

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/quotationsquotations:readList quotations
GET/api/v1/quotations/{id}quotations:readRead a quotation with its lines
POST/api/v1/quotationsquotations:writeCreate a DRAFT quotation (tax computed by the workspace's rules)

Invoices

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/invoicesinvoices:readList invoices
GET/api/v1/invoices/{id}invoices:readRead an invoice with lines and payments
POST/api/v1/invoicesinvoices:writeCreate a DRAFT invoice (numbered when issued in the back office)
GET/api/v1/paymentspayments:readList invoice payments (invoice=<id> to filter)
GET/api/v1/payments/{id}payments:readRead a payment

Orders

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/ordersorders:readList shop orders
GET/api/v1/orders/{id}orders:readRead a shop order

Catalog

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/productsproducts:readList products with price and stock (catalog:read also allows it)
GET/api/v1/products/{id}products:readRead a product
GET/api/v1/categoriescatalog:readList categories (type=product|service|post|project, locale=…) (espaces hébergés)
GET/api/v1/servicescatalog:readList published services (espaces hébergés)
GET/api/v1/services/{id}catalog:readRead a service (espaces hébergés)
GET/api/v1/products/lookupproducts:readExact barcode / SKU match (GTIN, SKU or an extra product barcode) — for scanners

Bookings

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/booking-servicescatalog:readList bookable services (online booking on) (espaces hébergés)
GET/api/v1/booking-services/{id}catalog:readRead a bookable service (espaces hébergés)
GET/api/v1/bookings/slotsbookings:readFree start times of a bookable service on a date (espaces hébergés)
GET/api/v1/bookingsbookings:readList appointments (espaces hébergés)
GET/api/v1/bookings/{id}bookings:readRead an appointment (espaces hébergés)
POST/api/v1/bookingsbookings:writeBook an appointment at a free time (409 when it was taken) (espaces hébergés)

Webhooks

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/eventswebhooks:readThe webhook event catalog
GET/api/v1/deliverieswebhooks:readWebhook delivery log
GET/api/v1/deliveries/{id}webhooks:readOne delivery with its payload
GET/api/v1/webhookswebhooks:readList webhook endpoints (no secrets) (espaces hébergés)
POST/api/v1/webhookswebhooks:writeCreate a webhook endpoint — the signing secret is returned once (espaces hébergés)
DELETE/api/v1/webhooks/{id}webhooks:writeDelete a webhook endpoint (espaces hébergés)

Account

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/me(any)Who is calling: the API key, or the person signed in to the app, with the workspace and the scopes

Stock

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/warehousesstock:readActive stock locations
GET/api/v1/stockstock:readStock levels per location (product=<id> for one product, all its rows)
POST/api/v1/stock/adjustmentsstock:writeAdd or remove stock (same rules as the admin: write-off reasons only remove)

Appointments

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/appointmentsappointments:readList appointments (from / to filter the start time)
GET/api/v1/appointments/{id}appointments:readRead an appointment

Point of sale

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/pos-salespos:readList till sales and refunds (since = created since)
GET/api/v1/pos-sales/{id}pos:readRead a till sale with its lines and payments

Tasks

MéthodeCheminPortéeCe qu'il fait
GET/api/v1/taskstasks:readList tasks (app sign-in without tasks.manage: only my tasks)
GET/api/v1/tasks/{id}tasks:readRead a task
POST/api/v1/taskstasks:writeCreate a task (assigned to the signed-in person by default)
PATCH/api/v1/tasks/{id}tasks:writeUpdate a task or change its status (DONE closes it; recurring tasks schedule the next one)

Files

MéthodeCheminPortéeCe qu'il fait
POST/api/v1/attachmentsattachments:writeUpload a photo or PDF (multipart: file, taskId?, folder?) — images are re-encoded, metadata such as GPS removed
GET/api/v1/attachments/{id}attachments:writeRead an uploaded file's record

Apps

MéthodeCheminPortéeCe qu'il fait
POST/api/v1/session/handoff(app)One-time URL (60 s) that signs the app's web view in to the workspace and opens `next` (jeton d'application uniquement)
GET/api/v1/devices(app)My app installations (jeton d'application uniquement)
POST/api/v1/devices(app)Register an app installation for push (FCM / APNs / Huawei Push Kit token; the same token again returns the same id) (jeton d'application uniquement)
DELETE/api/v1/devices/{id}(app)Remove an app installation (jeton d'application uniquement)
GET/api/v1/devices/{id}(app)One app installation with the alert categories it does not get pushes for (jeton d'application uniquement)
PATCH/api/v1/devices/{id}(app)Alert categories this installation does not get pushes for (tasks, sales, bookings, messages, stock, system) — they still appear in /notifications (jeton d'application uniquement)
GET/api/v1/account/deletion(app)Delete account (apps): which path applies — workspace owner closes the workspace, staff ask the administrators, customers use the website — with links and a pending request (jeton d'application uniquement)
POST/api/v1/account/deletion(app)Delete account (apps): mode request = ask the administrators to delete the staff account and remove the app data; mode app-data = only end every app sign-in and web session and remove devices / push tokens (jeton d'application uniquement)
POST/api/v1/session/sign-out-all(app)Sign out of all devices: ends every app sign-in and web session of the person and removes their app installations (jeton d'application uniquement)
GET/api/v1/rider/today(app)Rider mode: which duties I may start (rider = parcels.ride, tech = field.work, driver = fleet.drive), my duty, today's runs, delivery stops and pickups (jeton d'application uniquement)
POST/api/v1/rider/duty(app)Start duty (returns a duty token that can only post positions / end the duty) or end it; the workspace's live-location setting must be on (jeton d'application uniquement)
POST/api/v1/rider/positions(app)Post a batch of positions while on duty (app token or the duty token fx_dt_…); only the newest valid point is kept (latest position, no trail) and feeds the recipient ETA and the runs map; a driver's batch also moves their vehicle and, when the workspace keeps one, its short trail (jeton d'application uniquement)
GET/api/v1/apps(app)Home screen of the apps: the app grid I may open (name, area, icon as SVG nodes, waiting count), the workspace brand and unread alerts (jeton d'application uniquement)
GET/api/v1/search(app)Search records I may open (customers, invoices, orders, products …), grouped like the admin header search; also suggestion (did you mean), quick (prefilled create links such as a new invoice for a customer) and intent (jeton d'application uniquement)
GET/api/v1/notifications(app)Alerts for me since a time (the desktop app polls this) (jeton d'application uniquement)

Sensors

MéthodeCheminPortéeCe qu'il fait
POST/api/v1/sensors/readingssensors:writeUpload sensor readings (temperature, humidity, fuel_level, value) — up to 500 per request; the device is the key's own device or the serial in `device`; re-sent readings are skipped; send an Idempotency-Key

Suivant: Webhooks

Les événements métier envoyés à votre point d'accès HTTPS, signés, réessayés et journalisés.

Webhooks