API importu i eksportu danych — Bizami

Dokumentacja opisuje mechanizmy wymiany danych między systemem a zewnętrznymi klientami (systemami ERP): import danych do systemu oraz eksport danych z systemu.

:::info Zakres Ten dział dokumentacji obejmuje import danych (POST /api/push) oraz eksport danych — na przykładzie eksportu symulacji do systemu ERP. :::

Uwierzytelnianie

Wymaganie	Wartość
Middleware	auth:sanctum, token_ip
Metoda autoryzacji	Token Bearer (Laravel Sanctum)
Nagłówek	Authorization: Bearer {token}
Ograniczenie IP	Żądanie musi pochodzić z adresu IP przypisanego do tokenu (middleware token_ip)

Tokeny dostępowe są zarządzane w panelu administracyjnym systemu (sekcja API Tokens).

Format żądania i odpowiedzi

• Format treści: application/json
• Metoda: POST
• Każde żądanie może zawierać jeden lub więcej typów importu jednocześnie — jako klucze najwyższego poziomu obiektu JSON.
• Odpowiedź zawiera, dla każdego wysłanego typu, tablicę wyników przetwarzania poszczególnych rekordów.

Wspólny format wyniku rekordu

Każdy przetworzony rekord (niezależnie od typu importu) zwraca w odpowiedzi obiekt:

Pole	Typ	Opis
PK	string/number	Identyfikator rekordu przekazany przez klienta w żądaniu — zwracany bez zmian, służy do powiązania wyniku z wysłanym rekordem
SendStatus	"Y" | "N"	Czy rekord został zaimportowany poprawnie
SendMessage	string	Treść błędu — obecna tylko gdy SendStatus = "N"

Błąd nieprawidłowego JSON

Jeśli treść żądania nie jest poprawnym JSON-em, odpowiedź to:

{
  "error": {
    "code": 4,
    "message": "not Valid JSON"
  }
}

Obsługiwane typy importu

Klucz JSON	Opis
products	Kartoteka produktów
documents	Dokumenty sprzedażowe
stock	Stany magazynowe (ilości)
statuses	Status/norma dostępności produktu na magazynie
MaterialGroup	Słownik grup towarowych
Producer	Słownik producentów
Supplier	Słownik dostawców
warehouses	Kartoteka magazynów

Eksport danych

Strona	Opis
Eksport symulacji	Eksport danych symulacji do zewnętrznego systemu ERP

Przykład żądania z wieloma typami naraz

curl -X POST https://{host}/api/push \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouses": [ ... ],
    "products": [ ... ],
    "stock": [ ... ]
  }'

Uwagi ogólne

• Wartości liczbowe dziesiętne mogą być przesyłane z przecinkiem (,) jako separatorem — są automatycznie normalizowane do float.
• Import każdego rekordu jest niezależny — błąd jednego rekordu (SendStatus: "N") nie przerywa przetwarzania pozostałych.
• Każde żądanie jest logowane w kanale logów api (treść żądania i odpowiedzi).