Integracja narzędziowni z ERP w Studio TCS.net opiera się na jednej generycznej usłudze API: system zewnętrzny wysyła żądanie POST w formacie JSON z kluczem API, wskazuje identyfikator predefiniowanego zapytania i przekazuje dane, a odpowiedź wraca jako JSON. Standardowo przygotowana jest metoda kosztów wydań (dokumenty RW i LK według MPK, pracownika lub pozycji). Wymiana zleceń produkcyjnych z ERP nie jest funkcją standardową i wymaga rozszerzenia projektowego.
Poniżej jest opis mechanizmu, tego, co dostajesz dziś, oraz modelu rozszerzenia dla zleceń produkcyjnych. Zakres, konta i klucze ustala się w analizie przedwdrożeniowej. Metodę kosztów opisuje strona o API kosztów wydań, a przykłady zapytań pokazuje zakładka Integracja w kokpicie narzędziowni.
Jak działa API narzędziowni
| Element | W Studio TCS.net | Uwagi |
|---|---|---|
| Adres i metoda | Usługa Execute pod adresem ApiService.asmx, żądanie POST, treść w formacie JSON | Jedno wejście dla wszystkich metod |
| Uwierzytelnienie | Klucz API w nagłówku X-API-KEY, przypisany do dedykowanego konta integracyjnego | Bez tokenów sesyjnych: klucz trzyma się poza kodem i przesyła po HTTPS |
| Treść żądania | Pole actionUid wskazuje zapytanie, pole actionData niesie dane wejściowe jako obiekt JSON | Dane trafiają do zapytania jako parametr JSON |
| Odpowiedź | Wynik zapytania w formacie JSON: obiekt, tablica albo pusta tablica | Kształt odpowiedzi definiuje zapytanie |
| Kody statusu | 200 powodzenie, 400 błędne dane lub nieznany actionUid, 401 błąd klucza, 500 błąd wykonania | Szczegóły wyniku w treści odpowiedzi |
| Zakres danych | Ograniczony do oddziału konta integracyjnego | Dane innych oddziałów nie są widoczne |
Wymagania techniczne: baza danych w wersji obsługującej JSON (SQL Server 2016 lub nowszy) oraz skonfigurowane konto integracyjne. Konto API wymaga specjalnej konfiguracji po stronie administratora wdrożenia.
Co jest dostępne standardowo: koszty wydań
- Dane. Koszty wydań z dokumentów RW (rozchód) i LK (likwidacja), z wartością liczoną jako ilość razy cena ewidencyjna z kartoteki.
- Grupowanie. Według miejsca powstawania kosztów, pracownika albo pozycji. Zmiana grupowania nie wymaga zmiany integracji.
- Zakres. Daty początkowa i końcowa oraz opcjonalnie filtr MPK i pracownika. Dane ograniczone do oddziału konta integracyjnego.
- Granica. Metoda zwraca zestawienie wydań, a księgowanie kosztów zostaje po stronie ERP. Obejmuje dokumenty RW i LK, a nie NP ani US.
Rozliczanie kosztów według MPK w programie opisuje artykuł o rozliczaniu kosztów narzędzi według MPK.
Przykład wywołania
Poniżej jest przykład struktury żądania. Wartości są poglądowe, a identyfikator zapytania i pola danych zależą od wdrożonej metody.
POST /ApiService.asmx/Execute
Host: [adres instancji]
X-API-KEY: [klucz konta integracyjnego]
Content-Type: application/json
{
"actionUid": "[identyfikator zapytania]",
"actionData": {
"dateFrom": "2026-10-01",
"dateTo": "2026-10-31",
"groupBy": "mpk"
}
}Zlecenia produkcyjne z ERP: model rozszerzenia projektowego
Program nie ma słownika zleceń produkcyjnych ani pola zlecenia na dokumencie wydania NW. Jeżeli zakład chce wydawać narzędzia na zlecenia z ERP, taką wymianę buduje się w projekcie na tym samym mechanizmie API.
- Wczytywanie zleceń. Zapytanie przyjmuje w danych wejściowych kod zlecenia, nazwę, indeks wyrobu, gniazdo robocze lub maszynę, planowane daty i status. Działa jak zapis typu upsert: nowe zlecenie dodaje, istniejące aktualizuje, więc ponowne wysłanie tych samych danych nie tworzy dubli.
- Cykl życia. Zlecenie ze statusem aktywnym trafia na listę podpowiedzi przy wydaniu. Po zamknięciu w ERP system wysyła aktualizację ze statusem zamkniętym, a zlecenie znika z listy bieżących wydań, żeby nie pobierać narzędzi na rozliczoną partię. Historia dokumentów powiązanych z kodem zostaje.
- Pole zlecenia na dokumencie. Formularz wydania NW wymaga rozszerzenia o pole wyboru zlecenia z listy aktywnych, dostępne także w aplikacji mobilnej, jeśli zakład tego potrzebuje.
- Raport kosztów w układzie zlecenia. Koszty wydań i zużycia przypisane do zlecenia, w tym zwrotne przekazanie do ERP, wymagają dodatkowych zapytań i raportów.
Do czasu wdrożenia takiego rozszerzenia numer zlecenia można wpisywać jako odnośnik w numerze dokumentu wewnętrznego, co opisuje artykuł o kittingu narzędzi pod zlecenie produkcyjne. Przykład ładunku dla zlecenia (poglądowy):
"actionData": {
"kod": "ZL-2026-11-0482",
"nazwa": "Obróbka korpusu pompy P-102",
"indeksWyrobu": "WYR-POM-102",
"gniazdoRobocze": "CNC-04",
"dataPlanStart": "2026-11-04T06:00:00",
"dataPlanStop": "2026-11-06T22:00:00",
"status": "AKTYWNE"
}Bezpieczeństwo integracji
- Dedykowane konto. Osobne konto integracyjne na system, z ograniczonym zakresem i rozpoznawalną nazwą w dzienniku.
- Klucz poza kodem. Klucz API trzyma się w sejfie sekretów integratora, a nie w repozytorium kodu, i wymienia po zmianie osób albo podejrzeniu wycieku.
- Tylko HTTPS. Wywołania wyłącznie szyfrowanym połączeniem.
- Zakres oddziału. Konto widzi dane swojego oddziału, więc zlecenia i koszty różnych lokalizacji nie mieszają się.
- Idempotencja zapisu. Metody zapisujące powinny przyjmować ponowne wysłanie tego samego rekordu bez dubli, bo integrator ponawia nieudane wywołania.
Czego standardowo nie ma
- Osobnych adresów dla poszczególnych zasobów w stylu
/api/slowniki/...i kodów 201 oraz 409. Jest jedno wejście Execute z kodami 200, 400, 401 i 500. - Uwierzytelnienia tokenem Bearer. Stosuje się klucz API w nagłówku.
- Słownika zleceń produkcyjnych, pola zlecenia na dokumencie NW i raportu kosztów w układzie zlecenia.
- Gotowych konektorów do konkretnych systemów ERP.
- Zwrotnego przekazywania kosztów z dokumentów NP i US: metoda kosztów obejmuje RW i LK.
Co dalej
Zasady pracy z kompletami i rozliczanie zużycia opisuje artykuł o kittingu narzędzi, a wskaźniki z zakładką Integracja - artykuł o kokpicie narzędziowni. Architekturę bazy opisuje strona o bazie danych SQL Server. Całość obszaru opisuje strona o systemie dla narzędziowni.