API VAT UE do Twojego systemu fakturowania i ERP

Po co łączyć sprawdzenie numeru z systemem fakturowania

Ręczne sprawdzenie działa, dopóki faktur jest kilka w tygodniu. Przy setkach dokumentów miesięcznie ktoś w końcu pominie numer, wpisze go z literówką albo sprawdzi go dzień po wysyłce. Integracja przenosi sprawdzenie w miejsce, w którym i tak powstaje faktura. System pyta o status numeru, zanim dokument zostanie zatwierdzony, zapisuje wynik przy fakturze i blokuje stawkę 0% albo adnotację odwrotne obciążenie, gdy numer jest nieważny.

Druga korzyść to porządek w danych kontrahentów. Nowy odbiorca dodany w ERP może od razu trafić do monitoringu, a zmiany statusu wracają do systemu i oznaczają kartotekę. Dział IT nie musi budować własnej obsługi rejestrów 27 krajów i Irlandii Północnej, ich przerw w działaniu ani formatów numerów.

Klucz API i uwierzytelnienie

Klucz tworzysz w panelu, w zakładce /panel/api. Widzisz go tylko raz, w chwili utworzenia, więc od razu zapisz go w menedżerze sekretów albo w zmiennej środowiskowej aplikacji. My przechowujemy wyłącznie skrót klucza, dlatego zgubionego klucza nie da się odczytać, a jedynie unieważnić i utworzyć nowy.

Klucz przesyłasz w nagłówku X-Api-Klucz każdego zapytania. Nigdy w adresie. Zapytanie z kluczem w parametrze adresu odrzucamy z kodem 400, bo adresy zostają w logach serwerów pośrednich, w historii przeglądarki i w narzędziach analitycznych. Klucz należy do zespołu, a nie do jednej osoby, więc odejście pracownika nie przerywa integracji. Przydział zapytań wynika z planu właściciela zespołu.

Sprawdzenie numeru jednym zapytaniem

Sprawdzenie numeru to zapytanie GET z dwuliterowym kodem kraju i numerem bez prefiksu. Przykład dla numeru niemieckiego, w którym klucz zastępujesz własnym:

curl -H "X-Api-Klucz: TWOJ_KLUCZ" https://biznesmeni.eu/api/v1/sprawdz/DE/123456789

Odpowiedź ma postać JSON. Przykładowa odpowiedź dla ważnego numeru z kraju, który nie udostępnia nazwy ani adresu, wygląda tak:

{
  "kraj": "DE",
  "numer": "123456789",
  "numer_pelny": "DE123456789",
  "status": "wazny",
  "nazwa": null,
  "adres": null,
  "numer_konsultacji": "WAPIAAAAZ1x2y3z4",
  "sprawdzono": "2026-10-17T09:41:22+02:00",
  "id": 18452,
  "potwierdzenie_pdf": "https://biznesmeni.eu/potwierdzenie/18452"
}

Pole status przyjmuje jedną z wartości wazny, niewazny, kraj_niedostepny albo zly_format. Pola nazwa i adres mają wartość null, gdy rejestr kraju ich nie podaje, co jest normalne między innymi przy numerach niemieckich. Numer konsultacji pojawia się, gdy w ustawieniach konta podasz numer VAT UE swojej firmy jako wnioskodawcy. Czas sprawdzenia podajemy w formacie ISO 8601 ze strefą czasową.

Monitoring kontrahentów z poziomu API

Lista monitoringu, którą widzisz w panelu, jest dostępna także przez API. Numery z listy sprawdzamy każdej nocy, a o zmianie statusu wysyłamy mail, tak samo jak przy liście prowadzonej ręcznie.

• POST /api/v1/monitoring dodaje kontrahenta. W treści zapytania przesyłasz pola kraj, numer i opcjonalnie etykieta, na przykład identyfikator kontrahenta z ERP. Nowy wpis wraca z kodem 201, a numer, który już jest na liście, z kodem 409 i danymi istniejącego wpisu.
• GET /api/v1/monitoring zwraca listę kontrahentów zespołu z ostatnim statusem i czasem ostatniego sprawdzenia, po 200 wierszy na stronę. Kolejne strony pobierasz parametrem strona.
• DELETE /api/v1/monitoring/{id} usuwa kontrahenta z listy. Usunięcie nie zwalnia miejsca w limicie monitoringu do końca okresu rozliczeniowego.
• GET /api/v1/zmiany z parametrem od w formacie ISO 8601 zwraca zmiany statusu wykryte od wskazanej chwili, z wartością poprzednią i nową. To wygodny sposób, żeby raz dziennie oznaczyć w ERP kontrahentów, których numer przestał być ważny.

Przykład dodania kontrahenta z etykietą:

curl -X POST -H "X-Api-Klucz: TWOJ_KLUCZ" -H "Content-Type: application/json" \
  -d '{"kraj": "CZ", "numer": "12345678", "etykieta": "K-00417"}' \
  https://biznesmeni.eu/api/v1/monitoring

Kody odpowiedzi i obsługa błędów

Błędy zwracamy jako JSON z polem blad i opisem po polsku. Integracja powinna rozróżniać przynajmniej poniższe przypadki.

Kod 200 ze statusem kraj_niedostepny zasługuje na osobną uwagę. Rejestry poszczególnych państw mają przerwy techniczne i okresy przeciążenia. W takiej sytuacji nie zgadujemy wyniku i nie podajemy statusu z pamięci, tylko mówimy wprost, że rejestr nie odpowiedział. Integracja powinna ponowić zapytanie po kilkunastu minutach, a fakturę z odwrotnym obciążeniem albo stawką 0% zatwierdzić dopiero po rozstrzygnięciu.

Limity zapytań w planach

Każde przyjęte zapytanie zużywa jedno miejsce z przydziału w okresie rozliczeniowym, a przydział odnawia się z nowym okresem. Nagłówki X-Limit-Okres i X-Limit-Zostalo pozwalają śledzić zużycie bez zaglądania do panelu.

• Start, bez dostępu przez API.
• Eksport, 5 000 zapytań miesięcznie, 499 zł netto albo 249 zł netto miesięcznie przy płatności rocznej.
• Biuro, 30 000 zapytań miesięcznie, 999 zł albo 499 zł netto.
• Instytucja, 200 000 zapytań miesięcznie oraz dziennik dostępu zespołu, w którym widać tworzenie i unieważnianie kluczy, 1 990 zł albo 995 zł netto.

Do cen doliczamy 23% VAT. Pełne porównanie planów jest w cenniku.

Dobre praktyki integracji

• Cache po swojej stronie. Jeden kontrahent na kilku fakturach tego samego dnia nie wymaga kilku zapytań. Zapisz wynik z datą i używaj go do końca dnia, a stałych odbiorców przenieś do monitoringu, który sprawdzamy co noc bez zużywania przydziału API.
• Ponowienia tylko tam, gdzie mają sens. Ponawiaj przy statusie kraj_niedostepny i przy błędach sieci, z rosnącym odstępem. Nie ponawiaj przy 401, 403 i 422, bo wynik się nie zmieni.
• Numer konsultacji przy fakturze. Zapisz w dokumencie albo w jego metadanych numer konsultacji, czas sprawdzenia i identyfikator potwierdzenia. Przy kontroli wskażesz dowód z dnia transakcji w kilka sekund.
• Osobny klucz dla każdego systemu. Program fakturujący, sklep i hurtownia danych dostają własne klucze, więc wyciek jednego nie zatrzymuje pozostałych.
• Walidacja formatu przed wysyłką. Usuń spacje i kropki, sprawdź dwuliterowy kod kraju. Pamiętaj, że Grecja ma prefiks EL, a Irlandia Północna przy towarach XI.

Jeśli dopiero porządkujesz zasady sprawdzania numerów w firmie, zacznij od strony, na której wyjaśniamy, czego wymaga ustawa przy tym, czym jest weryfikacja VAT UE. Biura, które obsługują wielu klientów, znajdą opis teczek na stronie weryfikacja kontrahentów dla biura rachunkowego, a mechanikę nocnego sprawdzania listy opisujemy przy temacie, jakim jest stała weryfikacja kontrahenta. Pojedynczy numer sprawdzisz bez klucza na stronie głównej, gdzie robisz każde sprawdzenie VAT unijnego.