API public v1

API-ul REST public este destinat integrărilor server-la-server, de exemplu cu software CRM sau de facturare.

URL de bază: https://auto.manisma.com/api/v1

Nu utilizați direct API-ul Directus și nu plasați niciodată o cheie API în JavaScript frontend.

Crearea unei chei API

Deschideți ca Admin Administrare → Chei API. Dați cheii un nume recunoscut și alegeți scopes:

• read: marchează o cheie destinată citirii;
• write: creează sau modifică resurse inscriptibile și utilizează endpointuri de planificare.
• plan: solicită o propunere de planificare.

Pentru o integrare normală de citire/scriere, selectați ambele scopes. Atenție: backend-ul v1 actual verifică write explicit pentru POST/PATCH, dar permite GET pentru orice cheie activă validă; read este, așadar, în prezent doar o desemnare administrativă și nu o blocare tehnică separată. Cheia brută începe cu msk_, este afișată o singură dată și nu poate fi recuperată. În caz de pierdere, creați o cheie nouă și dezactivați sau ștergeți-o pe cea veche.

Autentificare

Utilizați unul dintre aceste headere:

Authorization: Bearer msk_...

X-API-Key: msk_...

Toate rezultatele sunt limitate server-side la organizația cheii. Un id al altui tenant returnează același 404 ca un id necunoscut.

Resurse și metode

În v1 nu există endpoint DELETE.

Liste și paginare

GET /clients?limit=50&page=1

• limit: 1 până la 100, implicit 50;
• page: începe de la 1.
• search: pentru listele de clienți și materiale, căutare parțială fără diferențiere între majuscule și minuscule, în text literal. Un semn procent caută un semn procent. Clienții corespund după nume, e-mail sau număr de client; materialele după SKU sau nume.

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

Un răspuns de detaliu sau de scriere folosește { "data": { ... } }.

Clienți

Câmpuri citibile: id, tenant_id, customer_number, name, client_type, email, phone, vat_number, status, created_at, updated_at.

POST /clients necesită name. Câmpurile de scriere permise sunt name, customer_number, client_type, email, phone, vat_number și status. La PATCH toate sunt opționale, dar trebuie să fie prezent cel puțin un câmp valid. Câmpurile necunoscute și un tenant_id furnizat sunt ignorate.

POST /addresses creează o adresă pentru un client și necesită client_id. Clientul trebuie să aparțină aceluiași 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"}'

Sarcini

Câmpurile citibile includ id, tenant, numărul sarcinii, id client, titlu, descriere, prioritate, stare, durată estimată, id tehnician principal, număr necesar de tehnicieni, planificare, id adresă de service, id tip de sarcină, competențe necesare și timestamp-uri. Notele interne și cele ale tehnicianului nu sunt expuse.

POST /jobs necesită title. Câmpuri permise:

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.

Când status lipsește, se folosește unplanned. Când job_number lipsește, Manisma generează un număr cu prefixul tenantului setat. La PATCH, job_number, status și assigned_technician_id nu pot fi modificate.

Cheile externe pentru client, adresa de service și tipul de sarcină trebuie să aparțină aceluiași tenant.

POST /jobs/:id/assign planifică o sarcină cu technician_id, scheduled_start și scheduled_end. POST /jobs/:id/unassign elimină atribuirea și readuce sarcina în coada neplanificată; nu șterge sarcina.

Propunere de planificare

POST /plan returnează o propunere de planificare și nu modifică nimic: nu creează și nu mută nicio sarcină. Necesită scope-ul separat plan și este limitat la 3 apeluri per organizație la fiecare 10 minute; apelurile următoare returnează o eroare 429 clară. Nu folosește AI-ul Manisma și nu consumă acțiunile AI incluse în planul dvs. Manisma, deoarece asistentul dvs. apelant face raționamentul.

Alte resurse

• assets: dispozitive instalate la un client; inscriptibile prin POST și PATCH.

• task_types: inscriptibile prin POST și PATCH.

• materials: inscriptibile prin POST și PATCH; prețul de achiziție și stocul pot fi citite și scrise.

• asset_models: doar pentru citire.

• technicians: nume, e-mail, telefon, statut activ și competențe. Orele de lucru, adresele și id-ul de utilizator nu sunt publice.

Erori și limite

API-ul este limitat la 600 de cereri pe minut per IP sursă. Construiți retry-uri cu backoff exponențial pentru 429, 502 și erori de rețea temporare. Nu reîncercați erorile de validare fără a corecta cererea.