API weryfikacji kontrahentów i przewoźników
Sprawdzaj firmy prosto z TMS, CRM albo systemu księgowego: jedno zapytanie z numerem NIP lub VAT UE zwraca wynik z ponad 70 rejestrów i baz z 19 krajów — status firmy, VAT, długi, upadłości, licencję przewoźnika i sankcje. Każda sprawdzona firma trafia też na Twoją listę kontrahentów w panelu, z pełnym raportem, osobami kontaktowymi i polisą OCP.
Jak zacząć
- Wykup plan weryfikacji (Start, Biznes albo Firma) w panelu narzędzi. API nie działa w planie Demo.
- W panelu otwórz Ustawienia konta → Zespół i API i kliknij „Wygeneruj token”. Token pokazujemy tylko raz — zapisz go w konfiguracji swojego systemu.
- Wyślij pierwsze zapytanie (przykład niżej). Wynik zobaczysz też w panelu, na liście kontrahentów.
Autoryzacja i limity
Każde zapytanie wymaga nagłówka Authorization: Bearer wk_…. Tokeny generuje i unieważnia właściciel konta. Zapytania wysyłaj z serwera — nie umieszczaj tokenu w kodzie strony ani aplikacji mobilnej.
- Każde sprawdzenie firmy zużywa jedno sprawdzenie z miesięcznego limitu planu.
- Ponowne sprawdzenie tej samej firmy w ciągu 24 godzin nie zużywa limitu.
- Odczyt listy, raportu i wykorzystania planu jest bez limitu planu.
- Najwyżej 60 zapytań na minutę na token.
Sprawdzenie firmy
POST https://spedytor.org/api/v1/verify/companies — sprawdza firmę w rejestrach, zapisuje ją na liście i zwraca wynik z pełnym raportem. Trwa zwykle kilkanaście sekund — ustaw limit czasu zapytania na co najmniej 60 sekund.
| Pole | Opis |
|---|---|
| taxId (wymagane) | NIP albo numer VAT UE z prefiksem kraju, np. 5260250995, SK2022942746, CZ24705128. |
| country | Kod kraju (PL, CZ, …), gdy taxId podajesz bez prefiksu. |
| carrier | true dla przewoźnika — raport dodaje licencję i uprawnienia przewoźnika. Domyślnie false. |
| website | Adres strony firmy, gdy rejestr go nie podaje — sprawdzimy domenę. |
curl -X POST https://spedytor.org/api/v1/verify/companies \
-H "Authorization: Bearer wk_TWÓJ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"taxId": "6621004747", "carrier": true}'Odpowiedź (skrócona)
{
"company": {
"id": "fadee522-5380-4462-82c9-342b600fbe04",
"name": "Regesta S.A.",
"country": "PL",
"taxId": "6621004747",
"type": "carrier",
"result": {
"level": "ok",
"label": "Brak sygnałów ostrzegawczych",
"summary": "…"
},
"problems": [],
"contacts": 0,
"ocp": null,
"decision": { "value": "none", "reason": null, "by": null, "at": null },
"monitoring": false,
"checkedAt": "2026-11-17T12:52:42.972Z",
"reportUrl": "https://spedytor.org/narzedzia/panel?zakladka=weryfikacja&firma=fadee522-…",
"report": { "signals": [ … ], "company": { … }, "companyDetails": { … } }
},
"usage": {
"plan": "Biznes",
"periodEnd": "2026-12-17T10:17:16.146Z",
"checksUsed": 38,
"checksLimit": 200,
"extraChecks": 0
}
}Lista firm
GET https://spedytor.org/api/v1/verify/companies — wszystkie firmy z listy konta (bez pełnych raportów). Parametr ?taxId= zawęża wynik do jednej firmy — przydatne, żeby sprawdzić, czy kontrahent był już weryfikowany i jaką ma decyzję.
curl "https://spedytor.org/api/v1/verify/companies?taxId=PL6621004747" \
-H "Authorization: Bearer wk_TWÓJ_TOKEN"Raport firmy
GET https://spedytor.org/api/v1/verify/companies/{id} — ostatni wynik i pełny raport firmy z listy, bez ponownego sprawdzania rejestrów.
curl https://spedytor.org/api/v1/verify/companies/fadee522-5380-4462-82c9-342b600fbe04 \
-H "Authorization: Bearer wk_TWÓJ_TOKEN"Wykorzystanie planu
GET https://spedytor.org/api/v1/verify/usage — plan, koniec opłaconego okresu, zużyte sprawdzenia w tym miesiącu, limit i sprawdzenia z dokupionych pakietów.
Pola odpowiedzi
| result.level | ok — brak sygnałów ostrzegawczych; warn — sprawdź przed zleceniem; danger — wysokie ryzyko; unknown — za mało danych. |
| problems | Ostrzeżenia (warn) i poważne sygnały (danger): tytuł, szczegóły i źródło danych. |
| type | carrier albo counterparty. |
| decision.value | Decyzja o współpracy z panelu: none, approved, hold, blocked. |
| contacts | Liczba osób kontaktowych dodanych w panelu. |
| ocp | Ubezpieczyciel i data ważności wgranej polisy OCP (przewoźnicy). |
| reportUrl | Link do raportu w panelu — dla użytkowników Twojego systemu. |
| report | Pełny raport: wszystkie sprawdzenia (signals), dane firmy, finanse, zarząd. |
Przykład problemu
"problems": [
{
"id": "sk-tax-debt",
"level": "warn",
"group": "firma",
"title": "Firma o tej nazwie jest na liście dłużników podatkowych (SK): 30 733,39 €",
"detail": "Adres z listy: 05911 Hozelec. …",
"source": "Zoznam daňových dlžníkov (Finančná správa SR)"
}
]Błędy
Błąd ma postać {"error": {"code": "…", "message": "…"}}.
| 400 invalid_request | Brak albo zły numer taxId. |
| 401 unauthorized | Brak tokenu, token nieznany albo unieważniony. |
| 402 plan_required | Plan konta wygasł albo to plan Demo. |
| 402 limit_reached | Wykorzystany limit sprawdzeń w tym miesiącu — dokup pakiet albo zmień plan. |
| 404 company_not_found | Rejestry nie znają firmy o tym numerze. |
| 429 rate_limited | Więcej niż 60 zapytań na minutę. |
Masz pytania o integrację?
Napisz na biuro@spedytor.org — pomożemy podłączyć API do Twojego TMS albo CRM.