Integracje i wymiana danych

Zakres wymienianych danych

MetronQ przechowuje cennik zakładu jako jedną konfigurację: materiały, maszyny, wykończenia i reguły cenowe. Konfigurację można odczytać i zapisać poza panelem, więc dane prowadzone w systemie ERP, CRM albo w arkuszu nie muszą być wpisywane ręcznie ani uzgadniane z drugą kopią. Konfiguracja zawiera:

• Materiały - nazwa, oznaczenie EN i DIN, gęstość, cena za kilogram, wydajność obróbki zgrubnej, wydajność toczenia, wydajność wykańczania, naddatek na półfabrykat, prędkość skrawania.
• Maszyny - nazwa, technologia, stawka godzinowa, przestrzeń robocza, liczba osi, moc i maksymalne obroty wrzeciona, liczba gniazd narzędziowych, minimalna partia oraz producent, model, sterowanie, rok produkcji, numer seryjny i numer inwentarzowy.
• Wykończenia - nazwa, rodzaj, koszt za kilogram, koszt za decymetr kwadratowy, stała opłata za partię, liczba dni roboczych dodawanych do terminu realizacji oraz widoczność operacji dla klienta.
• Reguły cenowe - marża, minuty przezbrojenia i obsługi, minimalny cykl, terminy realizacji, mnożnik ekspresu, dostawa, stawka VAT oraz tabele mnożników dla klas tolerancji, klas geometrii i klas chropowatości powierzchni.

Dostępne są dwa formaty:

• CSV - osobny arkusz dla każdego katalogu. Format odpowiada eksportom większości systemów ERP i można go poprawiać ręcznie.
• JSON - jeden dokument z całą konfiguracją. Format dla integracji, w której system zewnętrzny sam utrzymuje aktualność danych w MetronQ.

Import i eksport w panelu

1. 1Otwórz w panelu zakładkę Zasady wyceny.
2. 2W menu po lewej stronie wybierz Import i eksport.
3. 3Eksport CSV i Eksport JSON pobierają plik w formacie opisanym niżej. Import CSV i Import JSON przyjmują plik w tym samym formacie.

Format CSV

Każdy katalog (materiały, maszyny, wykończenia) to osobny plik. Pierwszy wiersz zawiera nazwy kolumn. Nazwy kolumn są angielskimi identyfikatorami pól, niezależnie od języka panelu, ponieważ na nich opiera się mapowanie w systemie zewnętrznym i tylko je rozpoznaje import.

• Wiersze są dopasowywane wyłącznie po kolumnie key. Wiersz ze znanym kluczem aktualizuje istniejącą pozycję. Wiersz z nieznanym kluczem dodaje nową pozycję.
• Import odczytuje wyłącznie kolumny obecne w pliku. Pole, którego kolumny nie ma w pliku, zachowuje dotychczasową wartość we wszystkich wierszach.
• Pusta komórka oznacza „pozostaw bez zmian”, a nie „wyczyść”. Dzięki temu możesz importować eksport częściowy, np. tylko materiały dostępne na stanie albo tylko stawki z bieżącego kwartału.
• Import niczego nie usuwa. Materiał albo maszynę usuwa się w panelu.
• Separator kolumn określa znak dziesiętny: średnik występuje z przecinkiem dziesiętnym (1234,56), przecinek z kropką dziesiętną (1234.56). Import odczytuje oba warianty. Eksport używa separatora ustawionego na koncie zakładu.
• Kodowanie: UTF-8 z sygnaturą BOM lub bez niej albo Windows-1250, czyli środkowoeuropejska strona kodowa zapisywana przez Excel w systemie Windows.
• Plik może zawierać najwyżej 20 000 wierszy i mieć najwyżej 2 MB.

Arkusz maszyn nie zawiera biblioteki narzędzi, ponieważ lista narzędzi nie mieści się w jednym wierszu. Import arkusza zachowuje bibliotekę narzędzi maszyny, więc nie zmienia zakresu detali, które maszyna przyjmuje do wyceny. Bibliotekę narzędzi przenosi dokument JSON oraz wywołania /machines/{key}/tools opisane niżej.

Format JSON

Eksport JSON zawiera całą konfigurację wyceny w postaci, w jakiej przechowuje ją panel. Import JSON przyjmuje dokument w tej samej postaci. Dokument zawiera trzy katalogi, wszystkie parametry wyceny, ustawienia bezpieczników, strategię doboru maszyny, strategię doboru półfabrykatu i walutę. Używaj tego formatu, gdy system zewnętrzny prowadzi własną kopię cennika zakładu. Pole Jak zastosować wybiera tryb importu:

• „Scal - tylko to, co podaje plik” (tryb domyślny) stosuje wyłącznie wartości, które dokument zawiera. Plik z trzema materiałami i jedną marżą zmienia trzy materiały i jedną marżę. Pozostałe pola zachowują wartości ustawione w panelu.
• „Zastąp - plik wygrywa, łącznie z usunięciami” stosuje dokument w całości, łącznie z usunięciem pozycji, których w nim nie ma. Używaj tego trybu, gdy system zewnętrzny jest nadrzędnym rejestrem danych, a nie tylko ich źródłem.
• Katalogi są scalane po tym samym polu key co w arkuszu, więc oba formaty rozpoznają tę samą pozycję po tym samym kluczu.

Podgląd importu

Każdy import zaczyna się od podglądu, który niczego nie zapisuje. Podgląd pokazuje:

• liczbę pozycji dodanych i zaktualizowanych,
• różnice pole po polu między obecnym cennikiem a cennikiem po imporcie,
• wiersze, których nie udało się odczytać,
• kolumny, których MetronQ nie rozpoznał.

Import zapisuje się dopiero po wybraniu Zastosuj. Obowiązują następujące reguły:

• Jeden wiersz, którego cennik nie przyjmuje (np. brak gęstości albo cena, która nie jest liczbą), blokuje cały plik. Import nie jest stosowany częściowo.
• Podgląd wymienia z nazwy każdą nierozpoznaną kolumnę. Import niczego z niej nie odczytuje. Nierozpoznana kolumna oznacza zwykle literówkę w nagłówku albo eksport z przesuniętymi kolumnami; bez tego ostrzeżenia taki plik zostałby przyjęty jako brak zmian.
• Jeśli cennik zostanie zapisany, gdy podgląd jest otwarty, import zostaje odrzucony, ponieważ podgląd nie odpowiada już wynikowi. Uruchom import ponownie.

Każdy zastosowany import jest zapisywany w historii zmian ustawień konta: każde zmienione pole osobno, ze źródłem „import”. Dzięki temu każdą zmianę ceny można przypisać do importu, który ją wprowadził.

Klucze API

Import i eksport są dostępne także przez API, bez otwierania panelu. System ERP, CRM albo narzędzie automatyzacji uwierzytelnia się kluczem API zakładu. Dostęp do API włączamy indywidualnie dla każdego zakładu: napisz do nas, z jakim systemem chcesz się połączyć. Klucz należy do zakładu, a nie do osoby, która go utworzyła, więc działa także pod jej nieobecność.

1. 1Otwórz w panelu Ustawienia, zakładkę Integracje. Zakładka jest dostępna wyłącznie dla właściciela konta.
2. 2Wybierz Nowy klucz. W polu Do czego służy wpisz nazwę systemu, który będzie używał klucza. W sekcji Co może robić zaznacz zakresy uprawnień. Wybierz Utwórz klucz.
3. 3Skopiuj klucz od razu. Klucz jest wyświetlany tylko raz i nie jest przechowywany. Jeśli go zgubisz, cofnij go przyciskiem Cofnij i utwórz nowy.

Pierwsza integracja krok po kroku

Sześć podstawowych wywołań w typowej kolejności implementacji. Wszystkie używają tego samego nagłówka Authorization: Bearer z kluczem API. Serwer: https://app.metronq.com, prefiks ścieżek: /api/v1/integration. Odpowiedzi są w formacie JSON, z wyjątkiem plików (.csv, PDF, plik wyceny, podgląd .glb).

1. Sprawdź klucz

GET /whoami nie wymaga zakresu uprawnień. Zwraca zakład, do którego należy klucz, zakresy i datę wygaśnięcia klucza oraz limity zapytań. Odpowiedź 200 oznacza, że klucz jest ważny.

curl https://app.metronq.com/api/v1/integration/whoami \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "tenant": { "name": "Zakład Mechaniczny Kowalski", "slug": "zaklad-kowalski", "currency": "PLN" },
  "key": {
    "name": "ERP sync",
    "prefix": "a1b2c3d4",
    "scopes": ["config:read", "quotes:read"],
    "expires_at": "2027-09-16T10:12:00+00:00"
  },
  "rate_limit": {
    "requests_per_minute": 120,
    "requests_per_day": 20000,
    "day_resets": "00:00 UTC",
    "requests_total": 1000,
    "requests_total_used": 3,
    "requests_total_remaining": 997
  }
}

2. Odczytaj katalog

GET /catalog/{name} zwraca jeden katalog: materials, machines albo treatments. GET /config zwraca cały dokument cennika.

curl https://app.metronq.com/api/v1/integration/catalog/materials \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "catalog": "materials",
  "count": 12,
  "items": [
    {
      "key": "alu_6061",
      "name": "Aluminium 6061",
      "kind": "metal",
      "en_number": "EN AW-6061",
      "din_number": "3.3211",
      "density_g_cm3": 2.7,
      "price_per_kg": 6.4,
      "mrr_rough_cm3_min": 50.0,
      "mrr_turning_cm3_min": 60.0,
      "finishing_rate_cm2_min": 90.0,
      "stock_allowance_mm": 3.0,
      "cutting_speed_m_min": 250.0
    }
  ]
}

3. Odpytaj o nowe zapytania

Parametr since= zwraca zapytania utworzone w podanej chwili lub później. API nie przechowuje kursora: zapisuj po swojej stronie najnowszy odczytany created_at i przekazuj go w since=. Wynik obejmuje także zapytanie z tym samym created_at, więc pomijaj już odczytane id. limit przyjmuje wartości od 1 do 200 (domyślnie 100), offset przesuwa stronę wyników.

curl "https://app.metronq.com/api/v1/integration/quotes?since=2026-09-16T00:00:00Z&limit=50" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "items": [
    {
      "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
      "number": 1042,
      "ref": "WID-1042",
      "status": "priced",
      "created_at": "2026-09-16T08:41:12+00:00",
      "filename": "bracket.step",
      "material_key": "alu_6061",
      "quantity": 25,
      "unit_price": 178.5,
      "total_price": 4462.5,
      "discount_pct": null,
      "customer_unit_price": 178.5,
      "currency": "PLN",
      "customer_email": "zakupy@example.com",
      "customer_data_visible": true,
      "external_ref": "",
      "source": "widget"
    }
  ],
  "limit": 50,
  "offset": 0
}

4. Odczytaj, co zmierzyła analiza

GET /quotes/{id}/metrics zwraca wyniki analizy geometrii detalu, bez cen. Jedno wywołanie dotyczy jednej wyceny.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/metrics \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "analyzed_at": "2026-09-16T08:41:29+00:00",
  "file_extension": ".step",
  "status": "priced",
  "gate_status": "instant",
  "gate_reasons": [],
  "complexity": 34.2,
  "material_key": "alu_6061",
  "quantity": 25,
  "tolerance_class": "m",
  "surface_finish": "ra_3_2",
  "confirmed_threads": ["M8"],
  "geometry_metrics": {
    "bounding_box": { "x": 120.0, "y": 80.0, "z": 18.0 },
    "volume": 74210.5,
    "surface_area": 31890.2,
    "face_count": 46,
    "holes": [
      { "diameter": 8.2, "depth": 18.0, "through": true, "direction": [0, 0, 1] }
    ],
    "pockets": [
      { "depth": 6.0, "floor_area": 1840.0, "corner_radius": 5.0, "open": false }
    ],
    "min_wall_thickness": 3.1,
    "derived": { "volume_ratio": 0.43, "area_ratio": 1.71 }
  },
  "parts": []
}

5. Zapisz własny numer i zmień status zamówienia

PATCH /orders/{id} zmienia wyłącznie pola podane w treści żądania.

curl -X PATCH https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "WO-2026-0912", "status": "in_production"}'

{
  "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
  "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "status": "in_production",
  "payment_status": "unpaid",
  "external_ref": "WO-2026-0912",
  "quantity": 25,
  "unit_price": 178.5,
  "total_price": 4462.5,
  "currency": "PLN",
  "customer": { "name": "Anna Kowalska", "email": "zakupy@example.com", "city": "Warszawa", "...": "..." },
  "...": "..."
}

6. Zaktualizuj cennik z ERP

Aktualizacja wymaga dwóch wywołań: podglądu (POST /config/import/preview albo POST /config/import/preview-json) i zatwierdzenia (POST /config/import). Podgląd niczego nie zapisuje i zwraca base_hash. Wyślij base_hash w wywołaniu zatwierdzającym.

Zakresy uprawnień

• config:read - odczyt katalogów i reguł cenowych.
• config:write - aktualizacja katalogów i reguł cenowych przez podgląd i zatwierdzenie, tak jak w panelu.
• quotes:read - odczyt wycen i zamówień: detal, materiał, ilość, cena i odczyt analizy. Nie obejmuje danych kontaktowych klienta (patrz customers:read). Klucz z tym zakresem odczytuje wszystkie zapytania i zamówienia zakładu. Nadawaj go tylko systemowi, który potrzebuje zleceń.
• customers:read - odczyt danych kontaktowych klienta w zapytaniach i zamówieniach. Działa tylko razem z quotes:read. Bez tego zakresu wiersze są zwracane, ale customer_email, cały blok customer i notatka klienta (note) mają wartość null. Nie nadawaj go systemowi, któremu wystarczą detal, ilość i cena: klucz bez tego zakresu nie ujawni bazy klientów.
• quotes:write - zapis własnego numeru (external_ref), zmiana statusu zamówienia i znacznika płatności. Nie pozwala niczego wycenić ani zatwierdzić.
• quotes:create - wysyłanie plików detali do wyceny i zmiana parametrów dowolnej wyceny zakładu, dopóki nie zdecyduje o niej technolog. Cenę liczy silnik. Klucz nie może wpisać ceny, zatwierdzić ani odrzucić wyceny ani udzielić rabatu. Każdy plik to wycena w ramach planu zakładu. Zakres nie obejmuje quotes:read: system, który tylko wysyła pliki, nie potrzebuje odczytu zapytań.
• files:read - pobieranie plików wgranych przez klientów i podglądów 3D oraz odczyt kodu dostępu wyceny. Działa tylko razem z quotes:read, tak jak customers:read. Zakres jest oddzielony od quotes:read, ponieważ odczyt analizy zawiera tylko liczby, z których nie da się odtworzyć detalu, a plik zawiera projekt klienta.

Klucz API nie może tworzyć ani cofać kluczy ani zmieniać ich zakresów. Klucze tworzy i cofa wyłącznie właściciel zalogowany w panelu, więc przejęty klucz nie przedłuży sobie ważności. Klucz wygasa 365 dni po utworzeniu; panel nie oferuje innego terminu, a datę wygaśnięcia pokazuje kolumna Wygasa. Cofnięty klucz przestaje działać od następnego żądania.

Dane dostępne do odczytu

API zwraca dane katalogu i zapytań zakładu, do którego należy klucz: te same, które panel pokazuje temu zakładowi. Dane innych zakładów nie są dostępne. Endpointy odczytu:

• Materiały (GET /catalog/materials) - cały katalog: numer EN i numer DIN (Werkstoffnummer), gęstość, cena za kilogram, wydajności skrawania i prędkość skrawania.
• Maszyny (GET /catalog/machines) - park maszynowy: technologia, stawka godzinowa, przestrzeń robocza, liczba osi, moc i maksymalne obroty wrzeciona, liczba gniazd narzędziowych, maksymalna masa detalu oraz dane identyfikacyjne (producent, model, sterowanie, rok produkcji, numer inwentarzowy).
• Narzędzia (GET /tools) - biblioteka narzędzi jako płaska lista. Każdy wiersz podaje maszynę, do której należy narzędzie, i promień naroża wyznaczony z narzędzia przez silnik.
• Dane skrawania (GET /cutting-data) - dla materiału prędkość skrawania i wydajności używane w wycenie, dla maszyny parametry wrzeciona, które skalują te wydajności.
• Wykończenia (GET /catalog/treatments) - obróbka powierzchniowa i cieplna z kosztami i czasami realizacji.
• Zapytania i zamówienia (GET /quotes, GET /orders) - od najnowszych, z parametrem since= do odpytywania. Pojedyncza wycena zawiera rozbicie ceny, pojedyncze zamówienie - dane klienta do faktury i wysyłki.
• Odczyt pliku (GET /quotes/{id}/metrics) - wyniki analizy: gabaryt, objętość, powierzchnia, otwory, kieszenie, gwinty, ścianki i tolerancje, osobno dla każdej części złożenia.

Narzędzie zawsze należy do jednej maszyny, dlatego każdy wiersz GET /tools podaje maszynę. Arkusz CSV katalogu maszyn nie przenosi narzędzi, ponieważ wiersz nie mieści listy. GET /cutting-data nie jest tabelą parametrów skrawania: MetronQ nie przechowuje posuwu na ząb ani głębokości skrawania, ponieważ model czasu obróbki opiera się na wydajności usuwania materiału. Endpoint zwraca liczby, z których liczona jest cena: wartości wpisane przez zakład i wartości wyprowadzone z nich przez silnik. Dzięki temu podłączony system ma te same dane o materiale co silnik wyceny.

Opis pól

Jednostka jest częścią nazwy pola wszędzie tam, gdzie mogłaby budzić wątpliwość: _mm, _kg, _cm3_min, _m_min. Wartości są liczbami albo tekstem JSON; kwoty nie są formatowane. Ceny katalogu są w walucie zakładu, którą zwraca GET /whoami. Wycena i zamówienie podają w polu currency walutę, w której zostały policzone.

Materiał (GET /catalog/materials)

• key - identyfikator materiału. Wycena odwołuje się do niego w polu material_key. Po tym kluczu Twój system i MetronQ identyfikują ten sam materiał. Zmiana klucza tworzy nowy materiał; nie zmienia nazwy istniejącego.
• name - nazwa materiału widoczna dla klienta w widgecie i w ofercie. API zwraca ją w postaci zapisanej w cenniku zakładu, bez tłumaczenia.
• kind - metal albo plastic. Określa, które tolerancje, pasowania i wykończenia są oferowane klientowi.
• en_number, din_number - oznaczenia normowe (EN AW-6061, 1.0503). Widget pokazuje en_number obok nazwy materiału. Silnik nie używa tych pól w obliczeniach.
• density_g_cm3 - gęstość w g/cm3. Na jej podstawie liczona jest masa detalu, a z masy koszt materiału.
• price_per_kg - cena zakupu za kilogram, w walucie zakładu. Pole najczęściej aktualizowane przez ERP.
• mrr_rough_cm3_min - wydajność obróbki zgrubnej w cm3/min dla wrzeciona referencyjnego 15 kW. Od tej wartości zależy, o ile dłużej lub krócej obrabia się materiał w porównaniu z innymi.
• mrr_turning_cm3_min - wydajność toczenia w cm3/min. null oznacza, że używana jest wydajność obróbki zgrubnej.
• finishing_rate_cm2_min - wydajność obróbki wykańczającej: powierzchnia obrabiana w ciągu minuty, w cm2/min.
• stock_allowance_mm - naddatek w mm dodawany z każdej strony detalu przy doborze półfabrykatu.
• cutting_speed_m_min - prędkość skrawania vc w m/min. null oznacza, że wartość jest wyprowadzana z wydajności obróbki zgrubnej. Wartość faktycznie użytą zwraca GET /cutting-data.

Maszyna (GET /catalog/machines)

Pola, które wpływają na cenę albo na odrzucenie detalu:

• key, name - identyfikator maszyny i nazwa używana w zakładzie.
• technology - milling, turning, bar_turning albo mill_turn. Określa, jakie detale maszyna przyjmuje i która wydajność skrawania obowiązuje.
• hourly_rate - stawka godzinowa maszyny w walucie zakładu. Wybór modelu z katalogu maszyn nigdy nie ustawia tego pola; stawkę wpisuje zakład.
• envelope_mm - przestrzeń robocza. Dla frezarki trzy wartości (x, y, z). Dla tokarki pierwsza wartość to średnica toczenia, druga to długość toczenia.
• axes - liczba osi, od 3 do 5 przy frezowaniu. Przy więcej niż 3 osiach detal wymaga mniejszej liczby zamocowań.
• spindle_power_kw - moc wrzeciona w kW. Przy mocy poniżej referencyjnych 15 kW wydajności są proporcjonalnie zmniejszane. Przy mocy powyżej 15 kW nie są zwiększane, więc podanie mocy może cenę tylko podnieść.
• max_spindle_rpm - maksymalne obroty wrzeciona. Wpływają na wycenę tylko przy małych narzędziach, dla których nie da się osiągnąć obrotów wymaganych przez prędkość skrawania.
• min_tool_radius_mm - najmniejszy promień naroża wewnętrznego, jaki wykona maszyna. Pole przestaje być używane, gdy biblioteka narzędzi maszyny zawiera frezy palcowe (na tokarce: płytki tokarskie). Wtedy obowiązuje najmniejszy promień z tych narzędzi.
• tool_stations, max_workpiece_kg, through_spindle_coolant - liczba gniazd w magazynie narzędzi, maksymalna masa detalu na stole, chłodziwo przez wrzeciono.
• datasheet - maker, model, control, year, serial, inventory_no, notes. Dane identyfikacyjne. Silnik nie używa żadnego pola z tego bloku.

Narzędzie (GET /tools)

{
  "count": 2,
  "items": [
    {
      "key": "e12",
      "kind": "endmill",
      "name": "frez 12 mm, węglik, 4 ostrza",
      "diameter_mm": 12.0,
      "nose_radius_mm": null,
      "flute_length_mm": 45.0,
      "designation": "",
      "machine_key": "dmu50",
      "machine_name": "DMU 50",
      "cut_radius_mm": 6.0
    }
  ]
}

• machine_key, machine_name - maszyna, do której należy narzędzie. Każde narzędzie należy do jednej maszyny.
• kind - drill, endmill, tap, thread_mill, reamer albo turning_insert.
• diameter_mm - średnica skrawania: dla wiertła i rozwiertaka średnica wykonywanego otworu, dla frezu palcowego średnica frezu, dla gwintownika średnica nominalna gwintu.
• nose_radius_mm - promień naroża płytki tokarskiej, czyli najmniejsze zaokrąglenie, jakie płytka zostawia na toczonym profilu.
• flute_length_mm - użyteczna długość robocza w mm. null oznacza brak ograniczenia; silnik wtedy żadnego nie stosuje.
• cut_radius_mm - najmniejszy promień wewnętrzny, jaki zostawia narzędzie, wyliczany przez MetronQ: połowa średnicy albo promień naroża płytki. Ograniczeniem naroża maszyny jest najmniejsza z tych wartości wśród narzędzi, które wykonują naroże: frezów palcowych na frezarce i płytek tokarskich na tokarce. Wiertła, gwintowniki, frezy do gwintów i rozwiertaki nie są brane pod uwagę.

Dane skrawania (GET /cutting-data)

Odpowiedź zawiera wartości wpisane przez zakład i obok nich wartości wyprowadzone przez silnik:

{
  "reference": { "spindle_power_kw": 15.0, "cutting_speed_m_min": 250.0 },
  "materials": [
    {
      "key": "steel_c45",
      "name": "Stal C45",
      "kind": "metal",
      "en_number": "1.0503",
      "din_number": "",
      "density_g_cm3": 7.85,
      "cutting_speed_m_min": null,
      "cutting_speed_effective_m_min": 156.2,
      "machinability_factor": 1.6,
      "mrr_rough_cm3_min": 19.5,
      "mrr_turning_cm3_min": null,
      "mrr_turning_effective_cm3_min": 19.5,
      "finishing_rate_cm2_min": 40.0,
      "stock_allowance_mm": 3.0
    }
  ],
  "machines": [
    {
      "key": "dmu50",
      "name": "DMU 50",
      "technology": "milling",
      "spindle_power_kw": 13.0,
      "max_spindle_rpm": 10000.0,
      "spindle_power_factor": 0.867,
      "min_tool_radius_mm": 1.0,
      "tool_radius_effective_mm": 6.0,
      "tool_count": 2
    }
  ]
}

• reference - moc wrzeciona i prędkość skrawania odniesienia dla całego cennika: 15 kW i 250 m/min. Pozwalają sprawdzić poniższe obliczenia.
• cutting_speed_effective_m_min - prędkość skrawania użyta w wycenie: wartość wpisana przez zakład, a gdy jej nie ma, reference / machinability_factor.
• machinability_factor - skrawalność materiału względem aluminium: 1,0 aluminium, około 1,6 zwykła stal, około 3 stal nierdzewna. Wartość to pierwiastek kwadratowy ze stosunku wydajności obróbki zgrubnej aluminium (bazy) do wydajności obróbki zgrubnej materiału.
• mrr_turning_effective_cm3_min - wydajność toczenia użyta w wycenie: mrr_turning_cm3_min, a gdy ma wartość null, mrr_rough_cm3_min.
• spindle_power_factor - współczynnik skalowania wydajności na tej maszynie: spindle_power_kw / 15, nie więcej niż 1,0 i nie mniej niż 0,25. Gdy moc nie jest podana, wynosi 1,0.
• tool_radius_effective_mm - obowiązujący promień naroża: wpisany min_tool_radius_mm albo, gdy biblioteka zawiera narzędzia wykonujące naroże (frezy palcowe na frezarce, płytki tokarskie na tokarce), najmniejszy z ich promieni. Wiertła, gwintowniki, frezy do gwintów i rozwiertaki nie zmieniają tej wartości.

Zapytanie i zamówienie (GET /quotes, GET /orders)

• id - identyfikator wyceny, przyjmowany przez wszystkie pozostałe wywołania. number - numer czytelny dla człowieka. ref - pełny numer widoczny w zakładzie, z prefiksem źródła: WID-1042, WYC-1042 albo API-1042.
• status - etap zapytania: created, uploaded, analyzing, analyzed, priced, approved, rejected, ordered, analysis_failed. Cenę mają zapytania o statusie priced, approved i ordered.
• unit_price, total_price, currency - cena za sztukę, cena za partię i waluta wyceny. Wycena, która nie została policzona, ma w polach cen null.
• discount_pct, customer_unit_price - rabat udzielony przez zakład temu klientowi, w procentach, i cena za sztukę po rabacie. Bez rabatu discount_pct ma wartość null. unit_price pozostaje ceną zatwierdzoną; zamówienie zawiera już cenę po rabacie.
• min_order_top_up, delivery_cost - tylko w zamówieniu: dopłata do minimalnej wartości zamówienia i koszt dostawy. Oba są wliczone w total_price zamówienia, tak jak klient widział je w widgecie i w ofercie PDF. Zamówienia złożone przed wprowadzeniem tych pól mają w obu wartość 0.
• material_key, quantity - materiał i ilość wybrane przez klienta. material_key wskazuje pozycję katalogu materiałów.
• external_ref - numer nadany przez Twój system. Pole jest puste, dopóki Twój system go nie zapisze. Zlecenie z tym numerem znajdziesz przez ?external_ref=.
• source - źródło zapytania: widget (strona zakładu), panel (plik wgrany przez technologa) albo api (plik wysłany przez system zakładu). Pole jest puste w zapytaniach utworzonych przed jego wprowadzeniem.
• customer_email - jedyna dana kontaktowa w zapytaniu. Pozostałe dane klienta są dostępne dopiero w zamówieniu.
• customer_email, customer, note - mają wartość null, jeśli klucz nie ma zakresu customers:read. Pole customer_data_visible rozróżnia oba przypadki: false oznacza brak zakresu, true z pustym polem oznacza, że klient nie podał danych.
• Zamówienie zawiera dodatkowo: status (new, confirmed, in_production, shipped, cancelled), payment_status (unpaid, paid) oraz customer z pełnym adresem do faktury i wysyłki.
• breakdown - tylko w GET /quotes/{id}: zapisane rozbicie kosztów, z którego wynika cena. Służy do uzgodnienia ceny z danymi w systemie zakładu.

Odczyt pliku (GET /quotes/{id}/metrics)

Pola używane przy przygotowaniu produkcji:

• geometry_metrics.bounding_box - gabaryt w mm. derived.bbox_sorted_dims - te same trzy wymiary posortowane malejąco; na ich podstawie silnik sprawdza wykonalność.
• geometry_metrics.volume, surface_area - objętość detalu w mm3 i pole powierzchni w mm2. derived.volume_ratio - objętość detalu podzielona przez objętość gabarytu; niska wartość oznacza dużo materiału do usunięcia.
• holes[] - każdy policzony otwór: średnica, głębokość, informacja, czy jest przelotowy, i oś. Otwór jest liczony na podstawie pełnego okręgu ścianki, a nie wielkości średnicy.
• pockets[] - głębokość, pole dna, promień naroża oraz informacja, czy kieszeń jest otwarta albo przelotowa.
• min_wall_thickness - grubość najcieńszej znalezionej ścianki w mm albo null, gdy nie zmierzono żadnej dostatecznie cienkiej ścianki.
• gate_status, gate_reasons - wynik bramek bezpieczeństwa (np. instant, pending_review) i powody zatrzymania wyceny w formacie code:machine:field:actual:limit, z pomiarem, który spowodował zatrzymanie.

Wysyłanie detalu do wyceny

System zakładu może wysłać plik detalu do wyceny przez API. Plik przechodzi tę samą analizę i wycenę co plik wgrany przez klienta w widgecie. Obsługiwane pliki: model STEP albo IGES, kontur DXF, rysunek PDF albo jego zdjęcie. Wymagany zakres: quotes:create. Kolejność: utwórz wycenę, wgraj plik, potwierdź wgranie, odczytaj wynik.

1. Utwórz wycenę

Wyślij POST /quotes z nazwą i rozmiarem pliku oraz parametrami wyceny. Pola:

• wymagane: filename, file_size_bytes;
• opcjonalne: quantity (domyślnie 1), material_key, tolerance_class, geometric_class, surface_finish, treatments, lead_time, thickness_mm i units_mm (dla DXF), process, customer_email, locale, external_ref, label. process określa, jak powstaje płaski detal w zakładzie, który ma maszynę do cięcia blach: machining (frezarka albo tokarka), sheet_cutting albo auto. auto, a także zapytanie bez process, to wybór silnika: każdy detal, który maszyna do cięcia blach zakładu może wyciąć, jest wyceniany jako cięty. W zakładzie bez maszyny do cięcia blach auto wycenia tak jak dotąd.

Pole, którego to wywołanie nie zna, powoduje odpowiedź 422; nie jest pomijane. Dzięki temu literówka w nazwie pola nie powoduje wyceny z materiałem domyślnym. Nieznany materiał jest odrzucany od razu, a nie dopiero po analizie pliku.

curl -X POST https://app.metronq.com/api/v1/integration/quotes \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "bracket.step", "file_size_bytes": 482113, "quantity": 25,
       "material_key": "alu_6061", "tolerance_class": "f", "external_ref": "RFQ-2026-0455"}'

{
  "quote": {
    "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
    "number": 1043,
    "ref": "API-1043",
    "status": "created",
    "filename": "bracket.step",
    "quantity": 25,
    "unit_price": null,
    "external_ref": "RFQ-2026-0455",
    "source": "api",
    "...": "..."
  },
  "release": { "state": "waiting", "customer_may_see_price": false },
  "upload": {
    "method": "PUT",
    "url": "https://OBJECT_STORAGE/...",
    "headers": {
      "x-amz-server-side-encryption-customer-algorithm": "AES256",
      "x-amz-server-side-encryption-customer-key": "...",
      "x-amz-server-side-encryption-customer-key-MD5": "..."
    },
    "content_length": 482113,
    "expires_at": "2026-09-25T10:15:00+00:00"
  }
}

2. Wgraj plik żądaniem PUT na upload.url

Plik trafia bezpośrednio do magazynu obiektów. Nie przechodzi przez serwer aplikacji MetronQ.

• Wyślij wszystkie nagłówki z upload.headers w niezmienionej postaci, ponieważ nagłówki szyfrowania są objęte podpisem adresu.
• Content-Length musi być równy rozmiarowi zadeklarowanemu w kroku 1 (file_size_bytes).
• Adres jest ważny do expires_at, czyli przez 15 minut.
• Plik jest szyfrowany w chwili zapisu własnym, osobnym kluczem.
• Jeśli Twoja sieć przepuszcza ruch wychodzący tylko do znanych hostów, dopuść host magazynu obiektów z upload.url.

curl -X PUT "UPLOAD_URL" \
  -H "x-amz-server-side-encryption-customer-algorithm: AES256" \
  -H "x-amz-server-side-encryption-customer-key: ..." \
  -H "x-amz-server-side-encryption-customer-key-MD5: ..." \
  --data-binary @bracket.step

3. Potwierdź

POST /quotes/{id}/confirm-upload umieszcza analizę w kolejce. Po analizie silnik wycenia detal z parametrami z kroku 1. Serwer odpowiada 202. To wywołanie uruchamia pracę, dlatego limit planu i limit pięciu plików API w analizie są sprawdzane ponownie. Błędy:

• 409 file_not_uploaded - żądanie PUT nie dotarło. Wgraj plik ponownie, dopóki adres jest ważny.
• 409 upload_expired - od utworzenia wyceny minęło ponad 45 minut (15 minut ważności adresu i 30 minut zapasu). Utwórz wycenę od nowa.
• 409 quote_not_awaiting_upload - wycena została już potwierdzona. Powtórne potwierdzenie niczego nie zmienia.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/confirm-upload \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "quote": { "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33", "ref": "API-1043", "status": "uploaded", "...": "..." },
  "release": { "state": "waiting", "customer_may_see_price": false },
  "poll_after_seconds": 10
}

4. Poczekaj na cenę

Odpytuj GET /quotes/{id} (krótka odpowiedź) co około 10 sekund (poll_after_seconds w odpowiedzi potwierdzenia), dopóki status ma wartość uploaded albo analyzing. Następnie odczytaj jeden raz pełną wycenę z GET /quotes/{id}/detail (opis niżej). Odczyt wymaga zakresu quotes:read, oddzielnego od quotes:create: system, który tylko wysyła pliki, nie musi mieć dostępu do wszystkich zapytań zakładu.

• Każdy plik to wycena. Liczy się do limitu planu tak samo jak wycena z widgetu albo z panelu i podlega dziennemu limitowi wycen zakładu. Odpowiedź 403 quoting_blocked:<reason> wskazuje, który limit został osiągnięty. Wycena jest rozliczana dopiero wtedy, gdy silnik poda cenę.
• W analizie może być jednocześnie najwyżej 5 plików zakładu wysłanych przez API. Wyceny z widgetu i z panelu nie są wliczane. Szósty plik jest odrzucany odpowiedzią 429 analysis_backlog z nagłówkiem Retry-After: 30. Wycena, której adres do wgrania wygasł bez użycia, przestaje być wliczana.
• Limity pól: plik do 50 MB; quantity od 1 do 100 000; treatments najwyżej 10 pozycji; thickness_mm do 200, units_mm do 1000; external_ref do 80 znaków, label do 200 znaków; filename do 255 znaków, bez znaków sterujących. W drawing-inputs: scale_ratio od 0,02 do 50, thickness_mm od 0,2 do 500 mm.
• Pliki wysłane przez API mają w kolejce analiz niższy priorytet niż pliki wgrane w widgecie i w panelu. Analiza pojedynczego detalu trwa zwykle kilka sekund, dużego złożenia kilka minut.
• Numer wyceny ma prefiks API (API-1043). Panel pokazuje nazwę klucza, który wysłał wycenę, więc wyceny z API są odróżnione od zapytań klientów.
• Jeśli wycena ma customer_email, zatwierdzenie jej w panelu wysyła temu klientowi e-mail z linkiem, tak samo jak przy wycenie utworzonej w panelu. Bez customer_email MetronQ nie wysyła żadnej wiadomości poza zakład.
• Jeśli POST /quotes przekroczy czas oczekiwania, wycena mogła mimo to zostać utworzona. Wysyłaj external_ref. Po przekroczeniu czasu sprawdź GET /quotes?external_ref=, zanim utworzysz wycenę ponownie. Wycena, do której plik nie dotarł, nie jest rozliczana, a częściowo wgrany plik jest usuwany po 6 godzinach. Pusta wycena pozostaje na liście i jest wliczana do dziennego limitu wycen zakładu.

Ponowna wycena

POST /quotes/{id}/reprice (zakres quotes:create) zmienia parametry wyceny, a silnik liczy ją od nowa. Działa dla każdej wyceny zakładu, niezależnie od źródła. Wyjątki:

• 409 quote_closed - wycena została zatwierdzona albo odrzucona albo klient ją zamówił.
• 409 quote_in_review - technolog wpisał cenę dla wyceny albo dla jednej z jej części. Ponowna wycena usunęłaby tę cenę.

Każde pole jest opcjonalne; pominięte pole zachowuje dotychczasową wartość. Pola: quantity, material_key, tolerance_class, geometric_class, surface_finish, confirmed_threads, confirmed_external_threads, hole_fits, face_tolerances, treatments, lead_time, process, countersinks. process przyjmuje te same wartości co w POST /quotes. countersinks zaznacza otwory przelotowe detalu ciętego do pogłębienia: klucz otworu z choices.sheet_holes i kąt z choices.countersink_angles ({"6.0": 90}); w rozkroju klucz danej części (2:8.0). {} usuwa wszystkie zaznaczenia. Dla detalu obrabianego skrawaniem pole jest pomijane. Dopuszczalne wartości gwintów i pasowań podaje blok choices wyceny. W złożeniu confirmed_threads, confirmed_external_threads i hole_fits mogą wskazywać jedną część: "<indeks>:<oznaczenie>" dla gwintu (1:M16), "<indeks>:<średnica>" dla pasowania (2:80.0). Klucze każdej części zwraca GET /quotes/{id}/parts. Oznaczenie albo średnica bez indeksu dotyczy każdej części, która je ma. confirmed_threads, confirmed_external_threads i face_tolerances przyjmują najwyżej po 200 pozycji. face_tolerances wskazuje powierzchnie po ich nazwach z podglądu 3D (face_3), więc wymaga klucza, który może ten podgląd odczytać (files:read).

Rysunki

Rysunek, z którego silnik nie odtworzył modelu 3D, pozostaje w statusie analyzed z release.state równym needs_input. Pole drawing.reconstruction_declined podaje, czego zabrakło. Dla rysunku wysłanego przez API są dwie możliwości:

• POST /quotes/{id}/drawing-inputs - uzupełnia material_key, scale_ratio (skala 1:2 na arkuszu to 2.0) albo thickness_mm. Analiza rusza ponownie, a po niej silnik wycenia detal.
• POST /quotes/{id}/submit-drawing - przekazuje rysunek technologowi, który wycenia go ręcznie.

Rysunek wgrany w widgecie uzupełnia klient w widgecie. Dla takiej wyceny oba wywołania zwracają 409 not_an_api_quote.

Szczegóły wyceny

GET /quotes/{id}/detail (zakres quotes:read) zwraca dane, które technolog widzi na ekranie wyceny w panelu. Służy do założenia zlecenia w systemie zakładu bez przepisywania danych. Odpowiedź zawiera wszystkie pola GET /quotes/{id}, z tymi samymi nazwami i znaczeniem, oraz pola opisane niżej. Odczyt niczego nie zmienia: wycena nie zostaje oznaczona w panelu jako otwarta.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/detail \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "ref": "API-1043",
  "status": "priced",
  "unit_price": 41.5,
  "source": "api",
  "...": "...",
  "breakdown": { "machine_name": "DMU 50", "...": "..." },
  "release": { "state": "needs_review", "customer_may_see_price": false },
  "pricing": {
    "engine_unit_price": 41.5,
    "adjusted_unit_price": null,
    "customer_total": 1037.5,
    "min_order_top_up": 0.0,
    "delivery_cost": 25.0,
    "order_total": 1062.5,
    "vat_rate_pct": 19.0,
    "order_vat": 201.88,
    "order_gross": 1264.38,
    "lead_days": 10
  },
  "material": { "key": "alu_6061", "name": "Aluminium 6061", "en_number": "EN AW-6061", "din_number": "3.3211", "density_g_cm3": 2.7 },
  "part_mass_kg": 0.2004,
  "specification": {
    "tolerance_class": "f",
    "geometric_class": "K",
    "surface_finish": "ra_3_2",
    "lead_time": "standard",
    "treatments": [ { "key": "anodising", "name": "Anodising", "customer_visible": true } ],
    "confirmed_threads": null,
    "hole_fits": {},
    "...": "..."
  },
  "choices": {
    "thread_candidates": [ { "designation": "M8", "count": 4, "total_depth_mm": 72.0, "hole_key": "6.8" } ],
    "external_thread_candidates": [],
    "hole_fit_options": [ { "key": "8.0", "diameter": 8.0, "count": 2 } ],
    "section_candidate": null
  },
  "outcome": {
    "gate_status": "pending_review",
    "gate_reasons": [
      {
        "raw": "part_exceeds_envelope:vf2:part_size_y:350:310",
        "code": "part_exceeds_envelope",
        "machine_key": "vf2",
        "machine_name": "Haas VF-2",
        "field": "part_size_y",
        "actual": 350.0,
        "limit": 310.0
      }
    ],
    "dfm_reasons": [],
    "complexity": 34.2,
    "thresholds": { "complexity": 60.0, "thin_wall_mm": 1.0 },
    "analysis_error": null,
    "upload_abandoned": false,
    "review": { "note": null, "reviewed_at": null, "reviewed_by": null }
  },
  "drawing": { "is_drawing": false, "fallback": false, "reconstruction_declined": null },
  "readout": { "...": "exactly what GET /quotes/{id}/metrics returns" },
  "items": [],
  "order": null,
  "files": {
    "deleted_at": null,
    "original": { "available": true, "size_bytes": 482113, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/file" },
    "preview": { "available": true, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/preview.glb" },
    "readable": false
  },
  "customer_link": "https://quoting.metronq.com/precision-works/quote/1043?lang=en",
  "customer_link_shared_at": null,
  "access_code": null,
  "created_by_key": { "name": "PDM", "prefix": "a1b2c3d4" },
  "timestamps": { "analysis_queued_at": "...", "analyzed_at": "...", "billable_at": "...", "...": "..." }
}

• release.state - etap ceny: waiting (jeszcze bez ceny), abandoned (plik nie dotarł), needs_input (rysunek czeka na uzupełnienie), failed (pliku nie udało się odczytać), instant (cena policzona, nic jej nie wstrzymuje), needs_review (cena policzona, technolog musi ją zatwierdzić, zanim zobaczy ją klient), manual (silnik nie wycenił detalu, cenę podaje technolog), approved, rejected, ordered.
• release.customer_may_see_price - czy strona klienta pokazuje w tej chwili tę cenę; wartość wynika z tej samej reguły, której używa strona klienta. Sprawdź to pole, zanim Twój system wyśle komuś cenę: unit_price jest wypełnione w każdej wycenie z policzoną ceną, także w wycenie, która czeka na technologa.
• pricing.engine_unit_price - cena policzona przez silnik. unit_price to cena obowiązująca: kwota technologa (pricing.adjusted_unit_price), jeśli ją skorygował, w przeciwnym razie cena silnika.
• pricing.order_total, order_vat, order_gross - kwota, na jaką zostałoby złożone zamówienie: cena detali po rabacie klienta, dopłata do minimalnej wartości zamówienia zakładu i wysyłka, a następnie VAT według stawki zakładu. Obliczenie jest takie samo jak w widgecie i w ofercie PDF.
• material, part_mass_kg - materiał z katalogu zakładu i masa detalu (objętość detalu razy gęstość materiału).
• specification - parametry, z którymi detal jest wyceniany. confirmed_threads równe null oznacza, że nikt nie odpowiedział na pytanie o gwinty; pusta lista oznacza odpowiedź „brak”. Wykończenie z customer_visible równym false jest wliczone w cenę, ale jego nazwa nie jest pokazywana klientowi. price_overrides to korekty technologa dla tej wyceny; API je zwraca, a zmienić je można tylko w panelu. process to proces wybrany dla wyceny, null oznacza wybór silnika; technologies mówi, jak powstaje wyceniony detal: milling, turning, laser, plasma albo waterjet. Detal cięty z blachy ma też edge_quality (oznaczenie ISO 9013 i odchyłkę graniczną) oraz countersinks. Klasy ISO 2768, surface_finish, hole_fits i face_tolerances nie dotyczą detalu ciętego.
• choices - wartości przyjmowane przez POST /quotes/{id}/reprice dla tego detalu, wyznaczone z jego analizy: oznaczenia gwintów, gwinty zewnętrzne, otwory, którym można nadać pasowanie ISO 286, oraz profil walcowany rozpoznany w detalu, jeśli występuje. part_kind ma wartość sheet dla detalu wycenianego jako cięty z blachy, a processes podaje wartości process dopuszczalne dla detalu (dwie, gdy zakład może go i wyciąć, i obrobić). Dla detalu ciętego: sheet_threads (gwinty, na które wystarcza grubość blachy), sheet_countersinks (pogłębienia narysowane w modelu), sheet_holes i countersink_angles (wartości przyjmowane przez countersinks). W złożeniu choices opisuje cały model, a otwory wszystkich części są liczone razem; opcje każdej części zwraca GET /quotes/{id}/parts.
• outcome.gate_reasons - powody zatrzymania wyceny przez bramki. Każdy powód jest podany jako surowy tekst (raw) i rozłożony na pola: code, machine_key z machine_name, field, actual i limit. Nie parsuj surowego tekstu samodzielnie, ponieważ klucz maszyny może zawierać dwukropek. dfm_reasons - kody powodów wynikających z trudności wykonania detalu, a nie z reguły ustawionej przez zakład. outcome.review - notatka technologa, czas decyzji i osoba, która ją podjęła.
• readout - to samo, co zwraca GET /quotes/{id}/metrics, albo null przed analizą.
• items - części złożenia, każda z własną ceną, statusem bramek, powodami i rozbiciem kosztów. Geometria części jest w readout.parts pod tym samym indeksem. label ma wartość null, gdy plik nie nazywa części.
• files - ścieżki API do wgranego pliku i podglądów 3D. Pobranie wymaga zakresu files:read; pole readable informuje, czy klucz ma ten zakres. Odpowiedź nie zawiera linków do pobrania, więc logi Twojego systemu nie zawierają adresu, który otwiera plik klienta.
• customer_link, access_code - adres strony klienta dla tej wyceny i kod dostępu, o który prosi ta strona. access_code jest zwracany tylko z zakresem files:read, ponieważ strona pokazuje rysunek i model 3D klienta.
• created_by_key - nazwa i prefiks klucza, który wysłał wycenę, jeśli wycena pochodzi z API.

Pozostałe dane ekranu wyceny zwracają cztery wywołania:

• GET /quotes/{id}/similar - trzy najbardziej podobne detale zakładu, już sprawdzone przez technologa, z zatwierdzoną ceną i odchyleniem ceny silnika od tej ceny.
• GET /quotes/{id}/machine-options - cena tej wyceny na każdej maszynie parku, powody, dla których maszyna nie przyjmie detalu, oraz maszyna, którą silnik wybiera sam. Przypięcie maszyny jest możliwe tylko w panelu.
• GET /quotes/{id}/parts - części złożenia, każda z własnymi opcjami gwintów i pasowań oraz z maszyną, materiałem i sposobem zakupu formatki wybranymi dla niej przez technologa.
• GET /quotes/{id}/pdf - dokument wyceny w języku zakładu albo w jednym z języków oferowanych przez zakład (?locale=). Bez zakresu customers:read dokument nie zawiera wiersza „Dla” z adresem e-mail klienta.

Lista wywołań z przykładami

Serwer: https://app.metronq.com, prefiks ścieżek: /api/v1/integration. Klucz w nagłówku Authorization: Bearer. Żądania i odpowiedzi w formacie JSON, z wyjątkiem plików (ścieżki zakończone na .csv, PDF, plik wyceny i podgląd .glb). Opis każdego wywołania zaczyna się od zakresu, który musi mieć klucz; GET /whoami nie wymaga żadnego.

GET /whoami

Zakres: brak. Zwraca zakład, do którego należy klucz, nazwę, prefiks, zakresy i datę wygaśnięcia klucza oraz limity zapytań. Użyj go do sprawdzenia klucza i do ustalenia przyczyny odpowiedzi 403.

curl https://app.metronq.com/api/v1/integration/whoami \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /config

Zakres: config:read. Zwraca cały dokument cennika: trzy katalogi, wszystkie parametry, bramki bezpieczeństwa, strategie doboru i walutę. POST /config/import/preview-json przyjmuje ten dokument bez zmian i bez opakowania; stosuje wtedy tryb merge. Tryb replace, który usuwa także pozycje nieobecne w dokumencie, wymaga opakowania: {"config": ..., "mode": "replace"}.

curl https://app.metronq.com/api/v1/integration/config \
  -H "Authorization: Bearer mq_live_YOUR_KEY" > pricing.json

GET /catalog/{name}

Zakres: config:read. Zwraca jeden katalog w formacie JSON. {name}: materials, machines albo treatments. Odpowiedź: {catalog, count, items}. Nieznany katalog: 404 unknown_catalog.

curl https://app.metronq.com/api/v1/integration/catalog/materials \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /catalog/{name}.csv

Zakres: config:read. Zwraca katalog jako plik CSV, taki sam jak przycisk Eksport CSV w panelu: z sygnaturą BOM dla Excela, z separatorem ustawionym na koncie zakładu, jeden wiersz na pozycję. Plik maszyn nie zawiera listy narzędzi, ponieważ wiersz nie mieści listy.

curl https://app.metronq.com/api/v1/integration/catalog/machines.csv \
  -H "Authorization: Bearer mq_live_YOUR_KEY" > machines.csv

key;name;technology;hourly_rate;min_quantity;envelope_mm.1;envelope_mm.2;...
dmu50;DMU 50;milling;280,00;1;500,0;450,0;400,0;...

GET /tools

Zakres: config:read. Zwraca wszystkie narzędzia zakładu jako płaską listę; każdy wiersz podaje maszynę. Parametr ?machine= ogranicza listę do jednej maszyny. Nieznana maszyna: 404 unknown_machine.

curl https://app.metronq.com/api/v1/integration/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY"
curl "https://app.metronq.com/api/v1/integration/tools?machine=dmu50" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /machines/{key}/tools

Zakres: config:read. Zwraca bibliotekę narzędzi jednej maszyny, wpisany min_tool_radius_mm i wynikający z biblioteki promień naroża tool_radius_effective_mm.

curl https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "machine_key": "dmu50",
  "machine_name": "DMU 50",
  "count": 3,
  "min_tool_radius_mm": 1.0,
  "tool_radius_effective_mm": 6.0,
  "items": [
    {
      "key": "e12",
      "kind": "endmill",
      "name": "frez 12 mm, węglik",
      "diameter_mm": 12.0,
      "nose_radius_mm": null,
      "flute_length_mm": 45.0,
      "designation": "",
      "machine_key": "dmu50",
      "machine_name": "DMU 50",
      "cut_radius_mm": 6.0
    },
    { "key": "d6.8", "kind": "drill", "diameter_mm": 6.8, "cut_radius_mm": 3.4, "...": "..." },
    { "key": "m8", "kind": "tap", "diameter_mm": 8.0, "designation": "M8", "...": "..." }
  ]
}

PUT /machines/{key}/tools

Zakres: config:write. Zastępuje całą bibliotekę narzędzi maszyny listą z treści żądania (najwyżej 500 narzędzi). Wywołanie jest idempotentne, więc synchronizacja może wysłać listę, którą ma, bez sprawdzania poprzedniej zawartości. Dwa narzędzia z tym samym kluczem: 422 duplicate_tool_key.

curl -X PUT https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tools": [
        {"key": "e12", "kind": "endmill", "name": "frez 12 mm, węglik",
         "diameter_mm": 12.0, "flute_length_mm": 45.0},
        {"key": "d6.8", "kind": "drill", "diameter_mm": 6.8},
        {"key": "m8", "kind": "tap", "diameter_mm": 8.0, "designation": "M8"}
      ]}'

POST /machines/{key}/tools

Zakres: config:write. Dodaje jedno narzędzie albo zastępuje narzędzie o tym samym kluczu. Użyj go do zgłaszania pojedynczych zmian zamiast wysyłania całej biblioteki.

curl -X POST https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "r8h7", "kind": "reamer", "diameter_mm": 8.0}'

DELETE /machines/{key}/tools/{tool}

Zakres: config:write. Usuwa jedno narzędzie. Gdy narzędzia o tym kluczu nie ma: 404 unknown_tool, dzięki czemu synchronizacja odróżni usunięcie od błędu we własnym mapowaniu.

curl -X DELETE https://app.metronq.com/api/v1/integration/machines/dmu50/tools/r8h7 \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /cutting-data

Zakres: config:read. Zwraca dla każdego materiału prędkość skrawania i wydajności, z których liczona jest cena, a dla każdej maszyny parametry wrzeciona, które skalują te wydajności. To nie jest tabela parametrów skrawania (patrz wyżej).

curl https://app.metronq.com/api/v1/integration/cutting-data \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

POST /config/import/preview

Zakres: config:write. Podgląd importu pliku CSV jednego katalogu. Parametry: catalog (materials, machines albo treatments) i csv_base64 (plik zakodowany w base64). Niczego nie zapisuje. Odpowiedź: dokument wynikowy (config), klucze dodane (added) i zmienione (updated), wiersze, których nie udało się odczytać (errors), nierozpoznane kolumny (ignored_columns), lista zmian (changes) oraz base_hash. Gdy którykolwiek wiersz jest błędny, ok ma wartość false, a config ma wartość null. Błędy: 400 invalid_base64, 404 unknown_catalog.

curl -X POST https://app.metronq.com/api/v1/integration/config/import/preview \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"catalog\": \"materials\", \"csv_base64\": \"$(base64 -w0 materials.csv)\"}"

POST /config/import/preview-json

Zakres: config:write. Podgląd importu całego dokumentu JSON. Parametry: config (dokument) i mode: merge (domyślnie) albo replace. Tryb decyduje o tym, co zostanie zapisane, a nie o tym, co wolno pominąć w żądaniu: w obu trybach dokument musi być kompletny, katalogi materiałów i maszyn są obowiązkowe, a każda pozycja musi mieć swoje pola wymagane. merge stosuje tylko wartości podane w dokumencie. replace stosuje dokument w całości, łącznie z usunięciem pozycji, których w nim nie ma.

curl -X POST https://app.metronq.com/api/v1/integration/config/import/preview-json \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "merge", "config": {"materials": [ ... ], "machines": [ ... ]}}'

POST /config/import

Zakres: config:write. Zapisuje dokument zwrócony przez podgląd. Parametry: config i base_hash otrzymany w podglądzie. Odpowiedź: zapisany dokument. Błąd: 409 config_changed, gdy cennik został zapisany po wykonaniu podglądu.

curl -X POST https://app.metronq.com/api/v1/integration/config/import \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @commit.json      # {"config": ..., "base_hash": "..."} from the preview

{
  "materials": [ { "key": "alu-6061", "price_per_kg": 32.0, "...": "..." } ],
  "machines": [ "..." ],
  "treatments": [ "..." ],
  "params": { "margin_pct": 30.0, "...": "..." },
  "gates": { "mode": "review_all", "...": "..." },
  "machine_selection": "cheapest",
  "stock_selection": "cheapest",
  "currency": "PLN"
}

GET /quotes

Zakres: quotes:read. Zwraca zapytania od najnowszych. Parametry: since= (zapytania utworzone w tej chwili lub później, ISO 8601), status=, external_ref=, limit (1-200, domyślnie 100) i offset. Bez zakresu customers:read pola kontaktowe mają wartość null.

curl "https://app.metronq.com/api/v1/integration/quotes?since=2026-09-16T00:00:00Z&status=priced&limit=50&offset=0" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}

Zakres: quotes:read. Zwraca jedno zapytanie z zapisanym rozbiciem kosztów (breakdown). GET /quotes, GET /quotes/{id}, GET /quotes/{id}/metrics i PATCH /quotes/{id} zwracają także wyceny, które zakład przeniósł w panelu do Kosza. Pozostałe wywołania dotyczące pojedynczej wyceny odpowiadają dla takiej wyceny 404.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}/metrics

Zakres: quotes:read. Zwraca wyniki analizy pliku. Dopóki analiza trwa: 409 not_analysed. Ten kod oznacza, że wynik jeszcze nie istnieje, a nie błędny identyfikator; zapytaj ponownie później.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/metrics \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /orders

Zakres: quotes:read. Zwraca zamówienia od najnowszych, z tymi samymi parametrami co GET /quotes. Zamówienia przeniesione przez zakład do Kosza nie są zwracane. Bez zakresu customers:read pola kontaktowe mają wartość null.

curl "https://app.metronq.com/api/v1/integration/orders?since=2026-09-16T00:00:00Z&external_ref=WO-2026-0912" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "items": [
    {
      "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
      "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
      "status": "confirmed",
      "payment_status": "unpaid",
      "created_at": "2026-09-16T09:12:40+00:00",
      "paid_at": null,
      "quantity": 25,
      "unit_price": 178.5,
      "total_price": 4462.5,
      "min_order_top_up": 0.0,
      "delivery_cost": 0.0,
      "currency": "PLN",
      "external_ref": "WO-2026-0912",
      "customer": {
        "name": "Anna Kowalska",
        "email": "zakupy@example.com",
        "company": "Kowalski sp. z o.o.",
        "phone": "+48 22 000 00 00",
        "address": "ul. Fabryczna 4",
        "postcode": "00-001",
        "city": "Warszawa"
      },
      "note": "",
      "customer_data_visible": true
    }
  ],
  "limit": 100,
  "offset": 0
}

GET /orders/{id}

Zakres: quotes:read. Zwraca jedno zamówienie z danymi klienta do faktury i wysyłki.

curl https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

PATCH /quotes/{id}

Zakres: quotes:write. Zapisuje external_ref na zapytaniu; pusty tekst usuwa numer. Wywołanie nie zmienia ceny, statusu ani zatwierdzenia, które należą do silnika i do technologa.

curl -X PATCH https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "RFQ-2026-0455"}'

PATCH /orders/{id}

Zakres: quotes:write. Zmienia external_ref, status (new, confirmed, in_production, shipped, cancelled) i payment_status (unpaid, paid) zamówienia. Zmieniane są tylko pola podane w treści żądania. Zmiana statusu na confirmed albo shipped wysyła e-mail do klienta zakładu, tak jak ta sama zmiana w panelu. Zmiana payment_status nie wysyła wiadomości.

curl -X PATCH https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "WO-2026-0912", "status": "in_production",
       "payment_status": "paid"}'

POST /quotes

Zakres: quotes:create. Tworzy wycenę dla pliku i zwraca adres, na który należy go wgrać. Odpowiedź: 201 z polami quote, release i upload. Błędy: 403 quoting_blocked:<reason>, 429 analysis_backlog, 422 dla nieznanego pola, typu pliku, materiału, wykończenia, terminu albo klasy.

curl -X POST https://app.metronq.com/api/v1/integration/quotes \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "bracket.step", "file_size_bytes": 482113, "quantity": 25,
       "material_key": "alu_6061", "tolerance_class": "f", "external_ref": "RFQ-2026-0455"}'

POST /quotes/{id}/confirm-upload

Zakres: quotes:create. Potwierdza wgranie pliku: analiza trafia do kolejki, a po niej silnik liczy cenę. Odpowiedź: 202. Działa tylko dla wyceny utworzonej przez API; dla innej wyceny: 409 not_an_api_quote. Limit planu i kolejka analiz są sprawdzane ponownie (403 quoting_blocked, 429 analysis_backlog). Gdy od utworzenia wyceny minęło ponad 45 minut: 409 upload_expired.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/confirm-upload \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

POST /quotes/{id}/reprice

Zakres: quotes:create. Zmienia parametry wyceny; silnik liczy cenę ponownie. Działa dla każdej wyceny zakładu, dopóki nie zostanie zatwierdzona, odrzucona albo zamówiona. Błędy: 409 analysis_pending (plik jest jeszcze analizowany), 409 drawing_needs_input (rysunek czeka na uzupełnienie), 409 quote_closed, 409 quote_in_review. W złożeniu klucz gwintu albo pasowania może wskazywać jedną część (1:M16, 2:80.0); klucze każdej części zwraca GET /quotes/{id}/parts.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/reprice \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 50, "confirmed_threads": ["M8"], "hole_fits": {"8.0": "H7"}}'

POST /quotes/{id}/drawing-inputs

Zakres: quotes:create. Uzupełnia materiał, skalę albo grubość dla rysunku wysłanego przez API, z którego silnik nie odtworzył modelu. Analiza rusza ponownie, a po niej silnik wycenia detal. Odpowiedź: 202. Wywołanie jest wliczane do limitu kolejki analiz tak jak nowy plik. Puste żądanie: 422 no_inputs_given.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/drawing-inputs \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scale_ratio": 2.0, "material_key": "steel_c45"}'

POST /quotes/{id}/submit-drawing

Zakres: quotes:create. Przekazuje taki rysunek (wysłany przez API) technologowi do wyceny ręcznej; release.state zmienia się na manual. Zakład dostaje powiadomienie tak jak przy rysunku przesłanym z widgetu. Parametry opcjonalne: quantity, material_key, customer_email.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/submit-drawing \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 10}'

GET /quotes/{id}/detail

Zakres: quotes:read. Zwraca dane ekranu wyceny; opis pól w sekcji Szczegóły wyceny.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/detail \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}/similar

Zakres: quotes:read. Zwraca trzy najbardziej podobne detale zakładu, już sprawdzone przez technologa. Przed analizą zwraca pustą listę.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/similar \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 1,
  "items": [
    {
      "id": "0d9e7c21-5b3a-4f10-8c6d-9a2e4b7f1c05",
      "number": 1017,
      "ref": "WID-1017",
      "original_filename": "bracket-rev-a.step",
      "approved_unit_price": 39.0,
      "quantity": 20,
      "currency": "EUR",
      "auto_error_pct": 4.1,
      "date": "2026-08-30T14:02:11+00:00"
    }
  ]
}

GET /quotes/{id}/machine-options

Zakres: quotes:read. Zwraca cenę detalu na każdej maszynie parku albo powody, dla których maszyna nie przyjmie detalu. auto oznacza maszynę wybieraną przez silnik, pinned - maszynę przypiętą przez technologa. Tylko odczyt. Przed analizą zwraca pustą listę.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/machine-options \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 2,
  "items": [
    { "key": "dmu50", "name": "DMU 50", "technology": "milling", "unit_price": 41.5,
      "feasible": true, "reasons": [], "pinned": false, "auto": true },
    { "key": "vf2", "name": "Haas VF-2", "technology": "milling", "unit_price": null,
      "feasible": false, "pinned": false, "auto": false,
      "reasons": [ { "raw": "part_exceeds_envelope:vf2:part_size_y:350:310", "code": "part_exceeds_envelope", "...": "..." } ] }
  ]
}

GET /quotes/{id}/parts

Zakres: quotes:read. Zwraca części złożenia, każdą z gwintami i otworami, które można dla niej potwierdzić, oraz z wyborami technologa dla tej części w panelu. Tylko odczyt. Dla pojedynczego detalu (jego opcje podaje blok choices w GET /quotes/{id}/detail) i przed analizą items jest pustą listą. 404 not_found dla nieznanej wyceny albo wyceny innego zakładu.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/parts \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 2,
  "items": [
    {
      "index": 1,
      "label": "housing",
      "count": 1,
      "gate_status": "instant",
      "gate_reasons": [],
      "unpriced_reason": null,
      "price_overrides": { "machine_key": "dmu50", "stock_selection": "standard_stock" },
      "choices": {
        "thread_candidates": [ { "designation": "M16", "count": 4, "total_depth_mm": 96.0, "hole_key": "14.0", "key": "1:M16", "item_index": 1 } ],
        "external_thread_candidates": [],
        "hole_fit_options": [ { "key": "1:80.0", "diameter": 80.0, "count": 1, "hole_key": "80.0", "item_index": 1 } ]
      }
    },
    {
      "index": 2,
      "label": null,
      "count": 4,
      "gate_status": "tbd",
      "gate_reasons": [ { "raw": "probable_norm_part", "code": "probable_norm_part", "...": "..." } ],
      "unpriced_reason": "norm_part",
      "price_overrides": {},
      "choices": { "thread_candidates": [], "external_thread_candidates": [], "hole_fit_options": [] }
    }
  ]
}

• index - numer części, ten sam co w items z GET /quotes/{id}/detail i w readout.parts. label ma wartość null, gdy plik nie nazywa części. count - ile razy część występuje w złożeniu.
• gate_status, gate_reasons - wynik bramek dla tej części; każdy powód jako surowy tekst i rozłożony na pola, jak w szczegółach wyceny.
• unpriced_reason - dlaczego silnik nie wycenił części: norm_part (prawdopodobnie część znormalizowana do kupienia), casting (prawdopodobnie odlew), implausible_time (obliczony czas obróbki jest niewiarygodny), no_machine (żadna maszyna parku nie przyjmie części; szczegóły w gate_reasons). null, gdy silnik wycenił część.
• price_overrides - wybory technologa dla tej części w panelu: machine_key, material_key i stock_selection (cheapest, cut_to_size albo standard_stock). Brak klucza oznacza, że część dziedziczy ustawienie wyceny; {} oznacza, że nic nie wybrano. Zmienić je można tylko w panelu.
• choices - opcje wyłącznie tej części: thread_candidates, external_thread_candidates i hole_fit_options. key to wartość, którą POST /quotes/{id}/reprice przyjmuje dla tej części: "<indeks>:<oznaczenie>" dla gwintu (1:M16) w confirmed_threads albo confirmed_external_threads, "<indeks>:<średnica>" dla pasowania (1:80.0) jako klucz w hole_fits. hole_key to średnica, pod którą otwór występuje w podglądzie 3D.

GET /quotes/{id}/pdf

Zakres: quotes:read. Zwraca dokument wyceny w formacie PDF. Parametr ?locale= wybiera jeden z języków oferowanych przez zakład; bez parametru dokument jest w języku zakładu. Inny język: 422 language_not_offered.

curl "https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/pdf?locale=en" \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o quote.pdf

GET /quotes/{id}/file

Zakres: quotes:read i files:read. Zwraca plik wgrany przez klienta pod oryginalną nazwą. Błędy: 409 file_not_uploaded (plik jeszcze nie dotarł), 404 files_deleted (plik usunięty po upływie okresu przechowywania).

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/file \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o bracket.step

GET /quotes/{id}/preview.glb i GET /quotes/{id}/items/{index}/preview.glb

Zakres: quotes:read i files:read. Zwraca podgląd 3D w formacie binarnego glTF (GLB): całego detalu albo jednej części złożenia ({index} z listy items). Węzły powierzchni face_<n> to klucze przyjmowane przez face_tolerances. Wycena bez podglądu: 404 no_preview.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/preview.glb \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o bracket.glb
curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/items/2/preview.glb \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o part-2.glb

Limity zapytań

Limity zapytań ustalamy indywidualnie z każdym zakładem, razem z dostępem do API; nie są publikowane w cenniku. Limity domyślne:

• 120 zapytań na minutę,
• 20 000 zapytań na dobę, liczonych od godziny 00:00 UTC.

Limity uzgodnione dla konkretnego konta mogą być inne. Synchronizacja katalogu co godzinę i odpytywanie o wyceny co minutę mieszczą się w limitach domyślnych z dużym zapasem. Limity obowiązujące Twój klucz podają nagłówki każdej odpowiedzi i GET /whoami, a panel pokazuje je w Ustawieniach, w zakładce Integracje. Przy tworzeniu klucza możesz ustawić dla niego niższy limit dzienny niż limit konta, w polu Limit dzienny dla tego klucza (opcjonalnie).

Przy dostępie testowym obowiązuje dodatkowo trzeci limit: łączna liczba zapytań na cały test, wspólna dla wszystkich kluczy konta. Ten limit się nie odnawia. Jego wysokość ustalamy indywidualnie z każdym zakładem; ma wystarczyć do zbudowania integracji, a do stałej pracy służy dostęp uzgodniony. Wartość limitu i liczbę zużytych zapytań pokazuje panel w Ustawieniach, w zakładce Integracje. GET /whoami zwraca je w polach requests_total, requests_total_used i requests_total_remaining, a nagłówki każdej odpowiedzi podają stan licznika. Liczby w przykładach na tej stronie są wyłącznie ilustracją. Po wyczerpaniu limitu serwer odpowiada 429 z kodem total_quota_exceeded, bez nagłówka Retry-After.

Każda odpowiedź zawiera nagłówki z limitami i liczbą pozostałych zapytań, więc klient może dostosować tempo, zanim osiągnie limit. X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset dotyczą minuty, X-RateLimit-Quota-* dotyczą doby; wartości *-Reset to liczba sekund do odnowienia. Dwa ostatnie nagłówki występują tylko przy limicie łącznym dostępu testowego:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 41
X-RateLimit-Quota: 20000
X-RateLimit-Quota-Remaining: 19863
X-RateLimit-Quota-Reset: 51240
X-RateLimit-Total: 1000
X-RateLimit-Total-Remaining: 947

Kody błędów

Odpowiedź z błędem zawiera kod w polu detail, np. {"detail": "missing_scope"}. Obsługę błędu opieraj na tym kodzie; sam status HTTP nie określa, co zrobić dalej. Wyjątek: treść żądania niezgodna ze schematem (wartość spoza zakresu, znak sterujący w nazwie pliku, nieznane pole w POST /quotes, POST /quotes/{id}/reprice, POST /quotes/{id}/drawing-inputs i POST /quotes/{id}/submit-drawing) zwraca 422 z listą FastAPI {"detail": [{"type", "loc", "msg"}]}, która wskazuje błędne pole. Pozostałe wywołania pomijają nieznane pola.

• 429 rate_limited - wyczerpany limit minutowy. To samo żądanie zadziała po czasie podanym w Retry-After (w sekundach).
• 429 daily_quota_exceeded - wyczerpany limit dobowy. Retry-After podaje liczbę sekund do godziny 00:00 UTC.
• 429 total_quota_exceeded - wyczerpany limit łączny dostępu testowego. Odpowiedź nie zawiera Retry-After, ponieważ limit się nie odnawia.
• 401 invalid_api_key - klucz nieznany, cofnięty albo wygasły albo konto, którego dostęp do API jest wyłączony lub którego okres próbny, plan albo licencja się zakończyły. Odpowiedź jest taka sama we wszystkich tych przypadkach, aby nie ujawniać, czy klucz istnieje.
• 403 missing_scope - klucz jest ważny, ale nie ma zakresu wymaganego przez endpoint. Ponowienie żądania nie pomoże; potrzebny jest klucz z odpowiednim zakresem.
• 404 not_found, unknown_catalog, unknown_machine, unknown_tool - na tym koncie nie ma takiej wyceny, zamówienia, katalogu, maszyny albo narzędzia.
• 404 file_not_found - pliku wyceny nie można odczytać z magazynu.
• 400 invalid_base64 - pole csv_base64 nie zawiera poprawnego base64.
• 409 config_changed - cennik został zapisany między podglądem a zatwierdzeniem, więc wysyłany dokument nie odpowiada już stanowi cennika. Odczytaj konfigurację ponownie, wykonaj podgląd i zatwierdź jeszcze raz.
• 409 not_analysed - wycena istnieje, ale nie ma jeszcze wyników analizy. Plik jest analizowany; zapytaj ponownie później.
• 403 quoting_blocked:<reason> - zakład nie może teraz tworzyć nowych wycen. Powody: trial_limit (wyczerpane wyceny okresu próbnego), plan_limit (wyczerpane wyceny miesiąca w planie), daily_limit (dzienny limit wycen zakładu). Powód po dwukropku odpowiada komunikatowi, który pokazałby panel.
• 429 analysis_backlog - w analizie jest już 5 plików zakładu wysłanych przez API (wyceny z widgetu i panelu nie są wliczane). Retry-After: 30 podaje, po ilu sekundach ponowić żądanie.
• 409 file_not_uploaded, quote_not_awaiting_upload - plik nie dotarł do magazynu albo wycena została już potwierdzona.
• 409 upload_expired - od utworzenia wyceny minęło ponad 45 minut, a plik nie dotarł. Utwórz nową wycenę.
• 409 not_a_drawing, quote_already_analyzed - drawing-inputs albo submit-drawing wywołane dla wyceny, która nie jest rysunkiem, albo dla rysunku, który został już odtworzony lub przekazany technologowi.
• 409 quote_in_review - technolog wpisał cenę dla tej wyceny albo dla jednej z jej części. Cenę tej wyceny zmienia się teraz w panelu.
• 409 analysis_pending - plik jest jeszcze analizowany.
• 409 drawing_needs_input - wycena jest rysunkiem, który czeka na uzupełnienie.
• 409 quote_closed - wycena została zatwierdzona albo odrzucona albo klient ją zamówił.
• 409 not_an_api_quote - confirm-upload, drawing-inputs albo submit-drawing wywołane dla wyceny, która nie została utworzona przez API.
• 404 files_deleted, no_preview - pliki zostały usunięte po upływie okresu przechowywania albo wycena nie ma podglądu 3D.
• 422 - żądanie zostało odrzucone i nic nie zostało zapisane. Kody: unknown_material, file_too_large, unsupported_file_type, unknown_treatment, unknown_lead_time, unknown_tolerance_class, unknown_geometric_class, unknown_surface_finish, unknown_thread, unknown_external_thread, unknown_hole, unknown_hole_fit, unknown_countersink_angle, unknown_region, no_inputs_given, implausible_scale, implausible_thickness, duplicate_tool_key, language_not_offered. Błędne wiersze importu cennika nie powodują 422: podgląd zwraca je w polu errors. Treść niezgodna ze schematem zwraca listę FastAPI opisaną wyżej.

Uprawnienia w panelu

Import i eksport w panelu są dostępne dla użytkowników z dostępem do zakładki Zasady wyceny: właściciela i pracowników, którym włączono tę zakładkę. Eksport w panelu to pobranie pliku w zalogowanej sesji. Poza panelem dane konta są dostępne wyłącznie przez klucz API z odpowiednim zakresem.

API nie obsługuje synchronizacji o stałej porze ani wysyłania wycen do systemu zakładu w chwili ich utworzenia. Jeśli potrzebujesz takiej funkcji, napisz na kontakt@metronq.pl i podaj nazwę systemu. Zgłoszenia są podstawą do ustalania kolejności prac.