API publique v1

L’API REST publique est destinée aux connecteurs serveur-à-serveur avec, par exemple, un CRM ou un logiciel de facturation.

URL de base : https://auto.manisma.com/api/v1

N’utilisez pas directement l’API Directus et ne placez jamais une clé API dans du JavaScript frontend.

Créer une clé API

Ouvrez en tant qu’Admin Administration → Clés API. Donnez à la clé un nom reconnaissable et choisissez les scopes :

• read : marque une clé destinée à la lecture ;
• write : créer ou modifier les ressources inscriptibles et utiliser les endpoints de planification.
• plan : demande une proposition de planification.

Sélectionnez les deux scopes pour une connexion normale de lecture/écriture. Remarque : le backend v1 actuel vérifie explicitement write pour POST/PATCH, mais autorise GET pour toute clé active valide ; read est donc actuellement une indication administrative et pas encore un blocage technique distinct. La clé brute commence par msk_, s’affiche une seule fois et ne peut pas être récupérée. En cas de perte, créez une nouvelle clé et désactivez ou supprimez l’ancienne.

Authentification

Utilisez l’un de ces en-têtes :

Authorization: Bearer msk_...

X-API-Key: msk_...

Tous les résultats sont limités côté serveur à l’organisation de la clé. Un id d’un autre tenant renvoie le même 404 qu’un id inconnu.

Ressources et méthodes

Il n’y a pas d’endpoint DELETE en v1.

Listes et pagination

GET /clients?limit=50&page=1

• limit : 1 à 100, 50 par défaut ;
• page : commence à 1.
• search : pour les listes de clients et de matériaux, recherche partielle insensible à la casse sur du texte littéral. Un signe pourcentage recherche un signe pourcentage. Les clients correspondent par nom, e-mail ou numéro client ; les matériaux par SKU ou nom.

{
  "data": [],
  "meta": { "total": 0, "page": 1, "limit": 50 }
}

Une réponse de détail ou d’écriture utilise { "data": { ... } }.

Clients

Champs en lecture : id, tenant_id, customer_number, name, client_type, email, phone, vat_number, status, created_at, updated_at.

POST /clients exige name. Les champs inscriptibles autorisés sont name, customer_number, client_type, email, phone, vat_number et status. Pour PATCH, ils sont tous facultatifs, mais au moins un champ valide doit être présent. Les champs inconnus et un tenant_id fourni sont ignorés.

POST /addresses crée une adresse pour un client et exige client_id. Le client doit appartenir au même tenant.

curl -X POST 'https://auto.manisma.com/api/v1/clients' \
  -H 'Authorization: Bearer msk_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Bakkerij Peeters","client_type":"b2b","email":"info@example.com"}'

Ordres

Les champs en lecture comprennent id, tenant, numéro d’ordre, id client, titre, description, priorité, statut, durée prévue, id technicien principal, nombre requis de techniciens, planning, id adresse de service, id type de tâche, compétences requises et horodatages. Les notes internes et les notes du technicien ne sont pas exposées.

POST /jobs exige title. Champs autorisés :

job_number, client_id, title, description, priority, status, estimated_duration_minutes, required_technicians, scheduled_date, scheduled_start, scheduled_end, service_address_id, task_type_id, required_skills.

Lorsque status est absent, unplanned est utilisé. Lorsque job_number est absent, Manisma génère un numéro avec le préfixe de tenant configuré. Avec PATCH, job_number, status et assigned_technician_id ne sont pas modifiables.

Les clés étrangères pour le client, l’adresse de service et le type de tâche doivent appartenir au même tenant.

POST /jobs/:id/assign planifie un ordre avec technician_id, scheduled_start et scheduled_end. POST /jobs/:id/unassign supprime son affectation et le replace dans la file non planifiée ; il ne supprime pas l’ordre.

Proposition de planification

POST /plan renvoie une proposition de planification et ne modifie rien : il ne crée ni ne déplace aucun ordre. Il nécessite le scope distinct plan et est limité à 3 appels par organisation toutes les 10 minutes ; les appels suivants renvoient une erreur 429 claire. Il n’utilise pas l’IA de Manisma et ne consomme pas les actions IA incluses dans votre abonnement Manisma, car votre assistant appelant fournit le raisonnement.

Autres ressources

• assets : appareils installés chez un client ; inscriptibles avec POST et PATCH.

• task_types : inscriptibles avec POST et PATCH.

• materials : inscriptibles avec POST et PATCH ; le prix d’achat et le stock sont lisibles et inscriptibles.

• asset_models : en lecture seule.

• technicians : nom, e-mail, téléphone, statut actif et compétences. Les horaires, adresses et id utilisateur ne sont pas publics.

Erreurs et limites

L’API est limitée à 600 requêtes par minute par IP source. Implémentez des retries avec backoff exponentiel pour 429, 502 et les erreurs réseau temporaires. Ne relancez pas les erreurs de validation sans corriger la requête.