Zakresy API

Dla: Programista

Przykłady na tej stronie używają adresu . Zmień adres

Zakres to uprawnienie integracji do jednej domeny Prynt, w trybie odczytu albo zapisu. O zakresy wnioskuje administrator drukarni, a zatwierdza je Prynt. Klucz API widzi operacje i pola swoich zakresów oraz operacje o samym kluczu, które nie wymagają zakresu: wszystko inne nie istnieje w jego schemacie.

Jak działają zakresy

Operacja w referencji API podaje jedenwymagany zakres. Bez niego API odpowiada błędem FORBIDDEN z sub-kodemAPI_SCOPE_MISSING, a nazwę brakującego zakresu podaje params.scope. Wyjątkiem są operacje o samym kluczu (currentApiKey): nie wymagają zakresu, więc wywoła je każdy ważny klucz.
Zakres zapisu nie otwiera zapytań: listy i odczyt rekordów daje zakres odczytu. Mutacja odpowiada zmienionym rekordem, więc integracja z samym zakresem zapisu widzi to, co zapisuje — także każdy rekord, którego identyfikator zna (zmiana bez żadnego pola niczego nie zapisuje, ale zwraca rekord). Nadawaj zakres zapisu tylko systemom, którym ufasz w tym samym stopniu. Jeśli integracja ma tworzyć zamówienia, a potem je wyszukiwać albo synchronizować, potrzebujeorders:write i orders:read.
Zakres zapisu otwiera mutacje swojej domeny. Co dokładnie może zapisać integracja, podają operacje tego zakresu w referencji.
Pole z innej domeny wymaga też jej zakresu, np. klient zamówienia (Order.client) — clients:read. W referencji takie pola mają dopisek z nazwą zakresu.
Stan produkcji zamówienia — Operation.productionStatus, zadania operacji i podsumowania production zamówienia, produktu i elementu — to pola zamówienia widoczne z orders:read razem z production:read. Sam production:read daje listę zadań produkcyjnych ze statusem, czasami, maszyną i terminem (to termin zamówienia z chwili utworzenia zadania); to, co wskazuje zamówienie — nazwę zadania (z numerem zamówienia i opisem operacji), operację zadania i filtr orderId — dopiero z orders:read. Ani zadania, ani stan produkcji nie zdradzają, kto z pracowników drukarni pracował nad zamówieniem ani ile czasu mu to zajęło.
Słowniki (reference:read) czytaj w całości, z wycofanymi pozycjami: includeInactive: true przy referenceData, vatRates i currencies, a machines bez filtra isActive. Starsze zamówienia wskazują pozycje, których drukarnia już nie oferuje, a domyślnie te listy podają tylko bieżące.
Proś tylko o zakresy, których integracja naprawdę potrzebuje. Prynt może zatwierdzić węższy zakres niż we wniosku, a kolejny zakres dodasz później wnioskiem o rozszerzenie.

Lista zakresów

Zamówienia

Zakres	Co obejmuje
`orders:read` OdczytDane osobowe	Zamówienia — odczyt Zamówienia z produktami, elementami i operacjami, statusy, kontakty zamówienia, dostawy, płatności i koszty dodatkowe.
`orders:write` ZapisDane osobowe	Zamówienia — zapis Tworzenie i zmiana zamówień, produktów, statusów, kontaktów zamówienia, dostaw, płatności i kosztów dodatkowych, z odczytem zmienianego zamówienia. Także zmiana pojedynczych operacji technologii: maszyna, ilość, czas i cena (maszyny nie zmieni, dopóki hala ma zadanie tej operacji), a przeniesiona operacja schodzi z przypiętych w kolejce starej maszyny.

Klienci

Zakres	Co obejmuje
`clients:read` OdczytDane osobowe	Klienci — odczyt Klienci z kontaktami, adresami, notatkami i tagami.
`clients:write` ZapisDane osobowe	Klienci — zapis Dodawanie i zmiana klientów, kontaktów, adresów, notatek i tagów.

Magazyn

Zakres	Co obejmuje
`warehouse:read` OdczytDane osobowe	Magazyn — odczyt Papiery, farby, folie, wykrojniki i matryce, stany i ruchy magazynowe, dostawcy z osobami kontaktowymi (imię i nazwisko, e-mail, telefon), zamówienia zakupu i inwentaryzacje.
`warehouse:write` ZapisDane osobowe	Magazyn — zapis Przyjęcia i wydania papieru, farb i folii, dostawcy z osobami kontaktowymi oraz zamówienia zakupu z przyjęciem dostaw.

Produkcja

Zakres	Co obejmuje
`production:read` Odczyt	Produkcja — odczyt Zadania produkcyjne operacji zamówień (status, czasy, maszyna) oraz stan i postęp produkcji operacji, elementów, produktów i zamówień — bez danych pracowników. To, co wskazuje zamówienie (nazwa zadania z numerem zamówienia, operacja zadania, stan produkcji przy zamówieniu), wymaga też zakresu zamówień.

Faktury

Zakres	Co obejmuje
`invoices:read` OdczytDane osobowe	Faktury — odczyt Faktury sprzedaży produktów i faktury zakupu od dostawców: numery, daty, typy, waluty i stawki VAT. Kwoty z zakresem cen i kosztów, dokumenty (PDF) z zakresem plików.

Pliki

Zakres	Co obejmuje
`files:read` Odczyt	Pliki — odczyt Pobieranie plików zamówień i produktów, które integracja widzi dzięki zakresowi zamówień, oraz dokumentów faktur (PDF) — z zakresem faktur. Dokument faktury zawiera dane nabywcy.
`files:write` Zapis	Pliki — zapis Wgrywanie plików do zamówień i produktów, które integracja widzi dzięki zakresowi zamówień.

Słowniki

Zakres	Co obejmuje
`reference:read` Odczyt	Słowniki — odczyt Maszyny, stawki VAT, waluty, podmioty rozliczeniowe drukarni (przy jednoosobowej działalności z danymi właściciela) oraz słowniki kategorii produktów, typów elementów, typów operacji, uszlachetnień i profili kolorystycznych.

Ceny i koszty

Zakres	Co obejmuje
`prices:read` Odczyt	Ceny i koszty Dodatek do pozostałych zakresów: bez niego odczyt cen i kosztów oraz filtry po nich są niedostępne. Ceny podawane przy zapisie należą do zakresu zapisu.

Ceny i koszty

prices:read jest dodatkiem do pozostałych zakresów. Bez niego pola cen i kosztów w odpowiedziach, a także filtry i sortowania po nich, nie istnieją w schemacie Twojego klucza. Zapytanie o takie pole kończy się błędem API_SCOPE_MISSING z params.scope równym prices:read i współrzędną pola w params.coordinate. W referencji takie pola mają dopisek Wymaga zakresu prices:read. Ceny, które integracja podaje przy zapisie (np. cenę produktu w nowym zamówieniu), należą do zakresu zapisu: zapis niczego nie ujawnia.

Dotyczy to także faktur: invoices:read daje numery, daty, typy, waluty i stawki VAT faktur, a ich kwoty i kursy walut — jak każda cena — dopiero razem z prices:read. Integracja księgowa potrzebuje więc obu zakresów, a dokumentu faktury (PDF) — także files:read.

Dane osobowe

Zakresy oznaczone jako Dane osobowe dają dostęp do danych osób: osób kontaktowych, odbiorców, klientów indywidualnych. Wniosek o taki zakres wymaga od drukarni akceptacji zasad powierzenia przetwarzania danych osobowych, a integracja musi je chronić tak samo jak Prynt.

invoices:read jest oznaczony jako zakres z danymi osobowymi, bo faktura sprzedaży należy do zamówienia konkretnego nabywcy, często osoby prywatnej: z files:read integracja pobiera jej dokument z imieniem, nazwiskiem i adresem nabywcy, a z orders:read — zamówienie, które go wskazuje.

Podmiot rozliczeniowy drukarni (billingEntities) bywa jednoosobową działalnością: wtedy jego nazwa zawiera imię i nazwisko właściciela, a adres bywa adresem domowym. To dane samej drukarni, więc reference:read nie wymaga zasad powierzenia, ale integracja chroni je tak samo jak dane osobowe.

Zakresy klientów obejmują osoby kontaktowe, adresy i notatki CRM zespołu drukarni (bez prywatnych notatek pracowników i bez ich nazwisk: autora API podaje tylko przy notatce integracji); treść notatek może zawierać dane osobowe. Integracja synchronizująca klientów, np. z CRM, przetwarza dane każdego klienta drukarni, więc przechowuje je tylko dla celu integracji i usuwa, gdy drukarnia przestaje ich potrzebować — także osobę kontaktową, adres albo notatkę, które zniknęły z klienta w Prynt (usunięte, a notatka także oznaczona przez autora jako prywatna).