API integracje z partnerami – jak ograniczyć błędy danych i ręczną obsługę

Błędy danych w integracjach z partnerami ogranicza się czterema elementami: pisemnym kontraktem danych uzgodnionym z każdym partnerem, walidacją każdego komunikatu przed zapisem, uporządkowanym onboardingiem nowego partnera na środowisku testowym oraz osobną ścieżką dla odrzuconych rekordów, w której wiadomo, kto poprawia błąd i jak dane wracają do obiegu. Integracja rzadko zawodzi dlatego, że serwer nie umie wysłać żądania HTTP. Zawodzi, gdy dystrybutor inaczej nazywa pola, marketplace zmienia format bez uprzedzenia, a przewoźnik zwraca status, którego nikt nie przewidział.

Czym integracja z partnerem różni się od wewnętrznej

Przy integracji własnego ERP z własnym portalem obie strony kontrolujesz sam. Z partnerem zewnętrznym jest inaczej:

• nie masz wpływu na jego system, wersje i terminy zmian,
• partner ma własne słowniki: kody produktów, statusy, jednostki,
• jakość danych zależy od jego procesów, nie od Twojego kodu,
• błąd po jego stronie wpływa na Twoich klientów – opóźnione zamówienie, zły stan, brak śledzenia przesyłki.

Dlatego dobra integracja API i automatyzacja z partnerami obejmuje nie tylko kod, ale też ustalenia organizacyjne. Techniczną stronę – kolejki, ponowienia, idempotencję i monitoring w Laravel – opisujemy osobno we wpisie Integracje API Laravel z ERP i B2B.

Typowe grupy partnerów i ich pułapki

Dystrybutorzy i dealerzy – wysyłają zamówienia, pobierają cenniki i stany. Pułapki: własne kody produktów zamiast Twoich, zamówienia w jednostkach opakowań zamiast sztuk, ceny liczone według starego cennika.

Marketplace'y – przyjmują oferty, stany i ceny, oddają zamówienia i zwroty. Pułapki: wymagane atrybuty zależne od kategorii, limity zapytań, zmiany wymagań po stronie platformy, różne statusy dla tego samego etapu.

Przewoźnicy – przyjmują zlecenia nadania, zwracają etykiety i statusy przesyłek. Pułapki: walidacja adresów i kodów pocztowych, limity wymiarów i wagi, statusy pośrednie, które klient odbiera jako problem.

Dostawcy – przysyłają katalogi, cenniki zakupowe, potwierdzenia zamówień. Pułapki: pliki w zmiennym układzie kolumn, brak identyfikatorów, zmiana ceny bez daty obowiązywania.

Kontrakt danych – co musi zawierać

Kontrakt to dokument uzgodniony z partnerem, a nie tylko specyfikacja endpointu. Powinien określać:

• zakres – jakie komunikaty wymieniacie i w którą stronę,
• identyfikatory – czyje kody są kluczem i gdzie przechowywana jest mapa,
• pola wymagane i opcjonalne, typy, formaty dat, waluty i jednostki,
• słowniki – dozwolone statusy, kody krajów, jednostki miary,
• zachowanie przy błędzie – co odsyłamy, w jakim formacie, w jakim czasie,
• częstotliwość i limity – jak często partner może wysyłać dane,
• wersjonowanie – jak ogłaszane są zmiany i jak długo działa poprzednia wersja,
• osoby kontaktowe po obu stronach – techniczna i biznesowa.

Przykładowy wpis w kontrakcie dla zamówienia od dystrybutora: „Pozycja zamówienia zawiera nasz indeks produktu lub kod partnera z tabeli mapowań; ilość w jednostce sprzedaży z karty produktu; zamówienie bez identyfikatora odbiorcy jest odrzucane z kodem MISSING_BUYER”.

Walidacja przed zapisem, nie po reklamacji

Każdy komunikat od partnera przechodzi walidację zanim zmieni stan zamówienia, produktu czy dokumentu. Warto ją podzielić na poziomy:

1. Format – poprawny JSON lub XML, zgodność ze schematem, kodowanie znaków.
2. Słowniki – czy status, jednostka i waluta są na liście dozwolonych.
3. Referencje – czy produkt, klient i adres dostawy istnieją w systemie lub w tabeli mapowań.
4. Reguły biznesowe – czy ilość mieści się w rozsądnym zakresie, czy cena zgadza się z cennikiem partnera, czy termin nie jest w przeszłości.

Walidacja rozróżnia błąd techniczny od biznesowego. Niedostępny serwer obsługuje się ponowieniem, ale zamówienia z nieznanym kodem produktu nie wolno przyjąć automatycznie ani „poprawić” zgadywaniem.

Onboarding nowego partnera

Każdy kolejny partner to powtórka tych samych kroków, więc warto zrobić z nich procedurę:

1. Przekazanie kontraktu i dokumentacji, najlepiej z przykładowymi komunikatami.
2. Dostęp do środowiska testowego z osobnymi danymi dostępowymi.
3. Uzgodnienie mapowań – kody produktów, statusy, adresy dostaw.
4. Testy scenariuszy: poprawne zamówienie, duplikat, brakujące pole, nieznany produkt, anulowanie.
5. Okres równoległy – dane płyną automatycznie, ale zespół porównuje je z dotychczasowym kanałem, np. mailem.
6. Przełączenie na produkcję i wyłączenie starego kanału.
7. Przegląd po kilku tygodniach: które błędy się powtarzały i co poprawić w kontrakcie.

Warto też ustalić, kto po stronie partnera może zgłaszać problemy i jaką drogą – osobny adres lub formularz dla spraw integracyjnych zamiast korespondencji z handlowcem. Dzięki temu zgłoszenia nie giną w skrzynkach osób, które nie mają wpływu na integrację.

Dobrze przygotowany onboarding skraca kolejne wdrożenia, bo partner dostaje gotowy zestaw testów zamiast serii maili z pytaniami.

Obsługa odrzuconych rekordów

Odrzucony komunikat nie może zniknąć w logu. Potrzebna jest osobna kolejka odrzuceń widoczna dla operatora, w której każdy rekord ma:

• partnera, typ komunikatu i identyfikator biznesowy,
• czas otrzymania i kod błędu z czytelnym opisem,
• właściciela poprawki – partner lub zespół wewnętrzny,
• bezpieczny podgląd danych, bez haseł, tokenów i nadmiarowych danych osobowych,
• akcje: ponów po poprawie mapowania, oznacz jako rozwiązane, odeślij do partnera.

Przykład: dystrybutor wysyła zamówienie z nowym kodem produktu. System odrzuca pozycję z kodem UNKNOWN_PRODUCT. Operator dodaje mapowanie kodu w panelu i jednym kliknięciem ponawia przetworzenie. Jeśli kod jest błędny po stronie partnera, rekord wraca do niego z opisem, a zamówienie czeka w statusie „wstrzymane”.

Warto też raportować odrzucenia per partner. Rosnąca liczba błędów jednego typu zwykle oznacza zmianę po stronie partnera, o której nikt nie poinformował.

Zmiany po stronie partnera

Nawet najlepszy kontrakt nie zatrzyma zmian w systemach partnerów. Marketplace dodaje wymagany atrybut, przewoźnik wprowadza nowy status, dystrybutor wymienia oprogramowanie magazynowe. Żeby takie zmiany nie wychodziły na jaw dopiero w reklamacjach klientów:

• zapisuj się na komunikaty techniczne partnerów i przypisz osobę, która je czyta,
• nieznane wartości słownikowe traktuj jako błąd do przeglądu, a nie ignoruj ich po cichu,
• monitoruj brak komunikatów – cisza od partnera, który zwykle wysyła dane codziennie, jest sygnałem problemu,
• raz w roku przejrzyj kontrakt z każdym partnerem i usuń z niego to, co przestało obowiązywać.

Lista kontrolna przed uruchomieniem

1. Czy kontrakt jest podpisany przez obie strony technicznie i biznesowo?
2. Czy każde pole ma format, słownik i źródło prawdy?
3. Czy tabela mapowań kodów jest kompletna i ma właściciela?
4. Czy partner przeszedł scenariusze testowe, w tym błędne?
5. Czy operator widzi kolejkę odrzuceń i może zareagować bez dostępu do serwera?
6. Czy istnieje procedura wyłączenia integracji i powrotu do poprzedniego kanału?

Następny krok

Wybierz jednego partnera, z którym dziś najwięcej danych przepisujecie ręcznie, i zbierz kilkanaście prawdziwych komunikatów lub plików – także tych, które sprawiały kłopoty. To wystarczy, żeby spisać pierwszy kontrakt i oszacować zakres. Jeśli integracja dotyczy większego systemu, warto zacząć od audytu systemu B2B. Możesz też od razu skontaktować się z nami.