Publiczne API v1

Publiczne REST API jest przeznaczone do połączeń serwer-serwer, na przykład z oprogramowaniem CRM lub fakturowania.

Podstawowy URL: https://auto.manisma.com/api/v1

Nie używaj bezpośrednio API Directus i nie umieszczaj klucza API w frontendowym JavaScript.

Tworzenie klucza API

Otwórz jako Admin Zarządzanie → Klucze API. Nadaj kluczowi rozpoznawalną nazwę i wybierz zakresy:

• read: oznacza klucz przeznaczony do odczytu;
• write: tworzenie lub zmienianie zapisywalnych zasobów i używanie endpointów planowania.
• plan: żądanie propozycji planowania.

Dla normalnego połączenia odczytu/zapisu wybierz oba zakresy. Uwaga: obecny backend v1 sprawdza write jawnie dla POST/PATCH, ale zezwala na GET dla każdego ważnego aktywnego klucza; read jest więc obecnie oznaczeniem administracyjnym, a nie osobnym technicznym blokowaniem. Surowy klucz zaczyna się od msk_, jest wyświetlany tylko raz i nie można go odzyskać. W razie utraty utwórz nowy klucz i dezaktywuj lub usuń stary.

Uwierzytelnianie

Użyj jednego z tych nagłówków:

Authorization: Bearer msk_...

X-API-Key: msk_...

Wszystkie wyniki są po stronie serwera ograniczane do organizacji klucza. Id innego tenanta zwraca ten sam 404 co nieznane id.

Zasoby i metody

W v1 nie ma endpointu DELETE.

Listy i paginacja

GET /clients?limit=50&page=1

• limit: od 1 do 100, domyślnie 50;
• page: zaczyna się od 1.
• search: dla list klientów i materiałów, wyszukiwanie częściowe bez rozróżniania wielkości liter w dosłownym tekście. Znak procentu wyszukuje znak procentu. Klienci są dopasowywani po nazwie, e-mailu lub numerze klienta, a materiały po SKU lub nazwie.

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

Odpowiedź szczegółowa lub zapisu używa { "data": { ... } }.

Klienci

Pola odczytu: id, tenant_id, customer_number, name, client_type, email, phone, vat_number, status, created_at, updated_at.

POST /clients wymaga name. Dozwolone pola zapisu to name, customer_number, client_type, email, phone, vat_number oraz status. W PATCH wszystkie są opcjonalne, ale musi być obecne co najmniej jedno prawidłowe pole. Nieznane pola oraz dostarczone tenant_id są ignorowane.

POST /addresses tworzy adres klienta i wymaga client_id. Klient musi należeć do tego samego tenanta.

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"}'

Zlecenia

Pola odczytu obejmują id, tenant, numer zlecenia, id klienta, tytuł, opis, priorytet, status, oczekiwany czas trwania, id technika głównego, wymaganą liczbę techników, planowanie, id adresu serwisowego, id typu zadania, wymagane umiejętności oraz znaczniki czasu. Notatki wewnętrzne i technika nie są udostępniane.

POST /jobs wymaga title. Dozwolone pola:

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.

Gdy status jest pominięty, używane jest unplanned. Gdy job_number jest pominięty, Manisma generuje numer z ustawionym prefiksem tenanta. W PATCH pola job_number, status oraz assigned_technician_id nie mogą być zmieniane.

Klucze obce dla klienta, adresu serwisowego i typu zadania muszą należeć do tego samego tenanta.

POST /jobs/:id/assign planuje zlecenie z użyciem technician_id, scheduled_start i scheduled_end. POST /jobs/:id/unassign usuwa przypisanie i zwraca zlecenie do kolejki niezaplanowanych; nie usuwa zlecenia.

Propozycja planowania

POST /plan zwraca propozycję planowania i niczego nie zmienia: nie tworzy ani nie przenosi żadnego zlecenia. Wymaga osobnego zakresu plan i jest ograniczony do 3 wywołań na organizację w ciągu 10 minut; kolejne wywołania zwracają jasny błąd 429. Nie używa AI Manisma ani nie zużywa akcji AI zawartych w Twoim planie Manisma, ponieważ Twój wywołujący asystent wykonuje pracę myślową.

Inne zasoby

• assets: urządzenia zainstalowane u klienta; zapisywalne przez POST i PATCH.

• task_types: zapisywalne przez POST i PATCH.

• materials: zapisywalne przez POST i PATCH; cena zakupu i stan magazynowy są dostępne do odczytu i zapisu.

• asset_models: tylko do odczytu.

• technicians: nazwa, e-mail, telefon, status aktywny i umiejętności. Godziny pracy, adresy i id użytkownika nie są publiczne.

Błędy i limity

API jest ograniczone do 600 żądań na minutę na źródłowy IP. Buduj retry z wykładniczym backoffem dla 429, 502 i tymczasowych błędów sieci. Nie ponawiaj błędów walidacji bez poprawienia żądania.