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ąć

  1. Wykup plan weryfikacji (Start, Biznes albo Firma) w panelu narzędzi. API nie działa w planie Demo.
  2. W panelu otwórz Ustawienia konta → Zespół i API i kliknij „Wygeneruj token”. Token pokazujemy tylko raz — zapisz go w konfiguracji swojego systemu.
  3. 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.

PoleOpis
taxId (wymagane)NIP albo numer VAT UE z prefiksem kraju, np. 5260250995, SK2022942746, CZ24705128.
countryKod kraju (PL, CZ, …), gdy taxId podajesz bez prefiksu.
carriertrue dla przewoźnika — raport dodaje licencję i uprawnienia przewoźnika. Domyślnie false.
websiteAdres 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.levelok — brak sygnałów ostrzegawczych; warn — sprawdź przed zleceniem; danger — wysokie ryzyko; unknown — za mało danych.
problemsOstrzeżenia (warn) i poważne sygnały (danger): tytuł, szczegóły i źródło danych.
typecarrier albo counterparty.
decision.valueDecyzja o współpracy z panelu: none, approved, hold, blocked.
contactsLiczba osób kontaktowych dodanych w panelu.
ocpUbezpieczyciel i data ważności wgranej polisy OCP (przewoźnicy).
reportUrlLink do raportu w panelu — dla użytkowników Twojego systemu.
reportPeł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_requestBrak albo zły numer taxId.
401 unauthorizedBrak tokenu, token nieznany albo unieważniony.
402 plan_requiredPlan konta wygasł albo to plan Demo.
402 limit_reachedWykorzystany limit sprawdzeń w tym miesiącu — dokup pakiet albo zmień plan.
404 company_not_foundRejestry nie znają firmy o tym numerze.
429 rate_limitedWię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.