eDofinansowania API dla partnerów

Klucze, limity, nagłówki

Każde żądanie poza GET /v1/health wymaga klucza. Klucz podajesz w nagłówku Authorization ze schematem Bearer albo, jeśli tak wygodniej Twojej bibliotece, w nagłówku X-API-Key. Obie drogi są równoważne i prowadzą do tego samego sprawdzenia.

curl 'https://edofinansowania.pl/api/v1/health' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ'

# to samo, jeśli Twoja biblioteka woli własny nagłówek
curl 'https://edofinansowania.pl/api/v1/health' \
  -H 'X-API-Key: sk_live_TWOJ_KLUCZ'

Budowa klucza

Klucz to prefiks, 43 znaki losowe i 8 znaków sumy kontrolnej. Suma kontrolna jest liczona z części losowej, więc klucz z literówką albo obcięty przy kopiowaniu odpada, zanim dotkniemy bazy. Praktyczny wniosek: jeśli dostajesz problem-invalid-key natychmiast, to prawie zawsze wina kopiowania, a nie uprawnień.

sk_live_9f3Kq2mVXbT8sLpR7dWnA4uZcE1yH6jG0oB5tNfQiMx1a2b3c4d
└──┬───┘└────────────────────┬────────────────────┘└──┬───┘
prefiks         43 znaki losowe (base64url)    suma kontrolna

Klucz sekretny kontra publikowalny

Blokada domeny przy kluczu publikowalnym jest zabezpieczeniem przed nadużyciem, nie zabezpieczeniem kryptograficznym. Prawdomówny nagłówek Origin wysyła tylko przeglądarka, a narzędzie wiersza poleceń może go podrobić. Dlatego klucz publikowalny nie dostaje niczego, czego nie można pokazać publicznie.

Zakresy

Konto partnera ma włączone zakresy, a każda trasa należy do jednego z nich. Trasa spoza Twoich zakresów odpowiada problem-endpoint-not-enabled i jest to ustawienie po naszej stronie, nie przełącznik w panelu.

Limity

Obowiązują dwa liczniki naraz: na minutę i na miesiąc. Domyślnie 60 żądań na minutę dla klucza sekretnego, 30 dla publikowalnego i 50 000 miesięcznie na całe konto, ale wartości ustalamy per partner, więc wiążące jest to, co przychodzi w nagłówkach. Okno minutowe jest stałe, nie przesuwne: zaczyna się o pełnej sekundzie zerowej każdej minuty.

• Odpowiedź 304 zużywa limit. Licznik rusza na bramce, zanim ustalimy, czy cokolwiek się zmieniło. Warunkowe żądanie oszczędza transfer, nie pulę.
• Żądanie odrzucone z powodu limitu minutowego nie zjada puli miesięcznej. Ponowienie po Retry-After nic nie kosztuje poza czasem.
• GET /v1/health nie zużywa niczego, bo kończy się przed licznikiem. Możesz go odpytywać z monitoringu tak często, jak chcesz.
• Odpowiedzi 4xx i 5xx z uwierzytelnionej ścieżki liczą się normalnie. Pętla ponawiająca błędne żądanie wyczerpie pulę tak samo jak pętla poprawna.

Nagłówki odpowiedzi

Jedna rzecz, której nie widać po samych nazwach: nagłówki limitów pojawiają się dopiero wtedy, gdy wiadomo, czyj jest klucz. Odpowiedź 401 i trzy z czterech odmian 403 zapadają wcześniej i nie niosą żadnego licznika. Nie buduj więc sterowania ponawianiem na założeniu, że X-RateLimit-Remaining jest zawsze obecny.

Przy kluczu publikowalnym przeglądarka pokaże te nagłówki tylko dlatego, że wymieniamy je w Access-Control-Expose-Headers. Bez tego widget nie miałby jak się wycofać przed wyczerpaniem limitu.

Kwalifikowalność

Dopasowanie dotacji do klienta opiera się na trzech kryteriach: gdzie klient prowadzi działalność, jak duża jest firma i co chce zainstalować. Te same trzy kryteria działają w katalogu jako filtry zapytania i w POST /v1/eligibility/check jako profil firmy. Rozdział poniżej opisuje dokładnie, jakie wartości są dopuszczalne i jak liczymy trafienie, żeby nie trzeba było tego odtwarzać z zachowania.

Dopuszczalne wartości

Porównanie jest dokładne co do znaku. Nie normalizujemy niczego celowo: wartość spoza słownika kończy się odpowiedzią 400 z listą allowed, a nie pustym wynikiem, bo puste wyniki są znacznie trudniejsze do wykrycia w cudzym systemie.

Województwa jako kody ISO 3166-2:PL. Wartość NATIONWIDE nie jest kodem podziału terytorialnego: tak oznaczamy dotacje obejmujące cały kraj i pasują one do klienta z dowolnego miejsca.

• PL-DS
• PL-KP
• PL-LU
• PL-LB
• PL-LD
• PL-MA
• PL-MZ
• PL-OP
• PL-PK
• PL-PD
• PL-PM
• PL-SL
• PL-SK
• PL-WN
• PL-WP
• PL-ZP
• NATIONWIDE

Wielkość firmy.

• micro
• small
• medium
• large
• small_mid_cap
• mid_cap

Rodzaje instalacji. Do API wysyłasz kod z lewej kolumny, użytkownikowi pokazujesz etykietę z prawej. Oba pola zwraca też GET /v1/meta/vocabularies, więc nie trzeba ich przepisywać do siebie.

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "Unknown voivodeship: PL-XX",
  "instance": "/v1/grants",
  "allowed": ["PL-DS", "PL-KP", "PL-MZ", "NATIONWIDE"]
}

Reguła dopasowania

Dotacja trafia do wyniku, gdy spełnia wszystkie poniższe warunki naraz. Kolejność nie ma znaczenia, ale warto przeczytać je jako całość, bo dwa pierwsze punkty odpowiadają za większość pytań w rodzaju "dlaczego nie widzę dotacji, którą widziałem wczoraj".

• Jest opublikowana. Rekord wycofany z katalogu znika z wyników natychmiast, również wtedy, gdy jego nabór nadal trwa.
• Termin naboru nie minął. Porównujemy z dzisiejszą datą, więc dotacja z terminem dzisiejszym jeszcze się liczy, a jutro zniknie. Szczegóły takiej dotacji nadal odpowiadają 200 pod GET /v1/grants/{id}, z polem isOpen: false.
• Województwo pasuje, gdy dotacja wymienia dokładnie ten kod albo gdy jest oznaczona jako NATIONWIDE.
• Wielkość firmy pasuje, gdy dotacja wymienia dokładnie tę wartość. Nie ma tu odpowiednika jokera ogólnopolskiego.
• Rodzaje instalacji łączą się alternatywą: wystarczy, że dotacja obsługuje jeden z podanych. Kryterium ma sens sprzedażowy, bo klient pytający o fotowoltaikę i magazyn energii chce zobaczyć również program finansujący samą fotowoltaikę.
• Kryterium pominięte nie zawęża niczego. Pusty profil zwraca cały otwarty katalog.

Dlaczego dotacja pasuje

POST /v1/eligibility/check dokłada do każdej dotacji obiekt matchedOn, żeby handlowiec widział powód, a nie samą listę. Trzy stany są tu istotne i nie należy ich mylić.

{
  "profile": {
    "voivodeship": "PL-MZ",
    "companySize": "small",
    "installationTypes": ["pv", "heat_pump"]
  },
  "total": 2,
  "data": [
    {
      "grantCode": "EDF-0004",
      "title": "Kredyt ekologiczny",
      "eligibleLocations": ["NATIONWIDE"],
      "eligibleInstallations": ["pv", "heat_pump", "energy_storage"],
      "eligibleCompanySizes": ["micro", "small", "medium"],
      "matchedOn": {
        "voivodeship": { "matched": true, "via": "nationwide", "value": "NATIONWIDE" },
        "companySize": { "matched": true, "value": "small" },
        "installationTypes": { "matched": true, "values": ["pv", "heat_pump"] }
      }
    }
  ]
}

"matchedOn": {
  "voivodeship": { "matched": true, "via": "exact", "value": "PL-SL" },
  "companySize": { "matched": null, "reason": "not_filtered" },
  "installationTypes": { "matched": null, "reason": "not_filtered" }
}

Ten endpoint nie stronicuje i zwraca najwyżej 200 dotacji, a pole total liczy to, co faktycznie przyszło. Przy bardzo szerokim profilu, na przykład samym województwie, warto dołożyć rodzaj instalacji, zamiast zakładać, że widzisz komplet.

Pełne sprawdzenie: silnik pytań

Dopasowanie po profilu odpowiada na pytanie "co w ogóle wchodzi w grę". Właściwą kwalifikowalność sprawdza POST /v1/eligibility/run, który prowadzi przez pytania konkretnego programu. Uruchamiaj go tylko dla dotacji z hasEligibilityEngine: true, bo pozostałe nie mają skonfigurowanego silnika.

• Endpoint jest bezstanowy. Za każdym razem wysyłasz komplet zebranych dotąd odpowiedzi, a my odtwarzamy przejście od pytania startowego. Nie ma identyfikatora sesji do przechowywania.
• Odpowiedź ma jeden z dwóch kształtów, rozróżnianych polem status: incomplete z polem nextQuestion albo complete z polem verdict.
• Pole path to pytania faktycznie odwiedzone, w kolejności. Nadaje się do zapisania w historii klienta jako ślad, na jakiej podstawie zapadł werdykt.
• progress.totalQuestions jest górnym ograniczeniem, nie liczbą dokładną. Graf pytań się rozgałęzia, więc konkretna ścieżka bywa krótsza. Pasek postępu zbudowany na tej liczbie nie dojdzie do końca i lepiej pokazać sam licznik odpowiedzi.
• Odsyłaj identyfikator wybranej opcji z nextQuestion.options, nie jej tekst. Tekst jest etykietą i może zostać przeredagowany; identyfikator jest tym, po czym silnik wybiera gałąź.

Cztery rzeczy mogą pójść nie tak i każda ma własny wpis w katalogu błędów: odpowiedź na pytanie, którego silnik nie zna, odpowiedź spoza dozwolonych opcji, odpowiedzi nieukładające się w jedną ścieżkę oraz wada w samym grafie pytań. Pierwsze trzy to 422 i wynikają z żądania, czwarta to 500 i wynika z naszych danych.

Scenariusze integracji

1. Katalog u siebie i jego odświeżanie

Zacznij od jednego pełnego przejścia po katalogu. Bierz największą dozwoloną stronę, bo limit liczy żądania, a nie rekordy, więc 200 na stronę kosztuje cztery razy mniej niż 50.

curl 'https://edofinansowania.pl/api/v1/grants?limit=200' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ'

{
  "data": [ /* 200 dotacji */ ],
  "pagination": {
    "limit": 200,
    "hasMore": true,
    "nextCursor": "eyJkIjoiMjAyNi0wOS0zMCIsImkiOiI3YzQuLi4ifQ"
  }
}

Dopóki hasMore jest prawdą, powtarzaj z cursor równym nextCursor z poprzedniej odpowiedzi. Przepisuj tę wartość w całości. Kursor jest nieprzezroczysty celowo: pod spodem siedzi pozycja w sortowaniu po terminie naboru, a opakowanie go pozwala nam zmienić sortowanie bez psucia gotowych integracji.

curl 'https://edofinansowania.pl/api/v1/grants?limit=200&cursor=eyJkIjoiMjAyNi0wOS0zMCIsImkiOiI3YzQuLi4ifQ' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ'

Od tego momentu nie powtarzaj pełnego przejścia. Raz dziennie wystarczy jedno wywołanie GET /v1/grants/changes ze znacznikiem z poprzedniego razu.

curl 'https://edofinansowania.pl/api/v1/grants/changes?since=2026-07-30T09:00:00.000Z' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ'

{
  "since": "2026-07-30T09:00:00.000Z",
  "syncedAt": "2026-07-31T09:00:04.812Z",
  "upserted": [
    { "id": "7c4...", "grantCode": "EDF-0012", "title": "...", "applicationDeadline": "2026-11-30" }
  ],
  "removed": [
    { "id": "1b9...", "grantCode": "EDF-0031", "reason": "expired", "removedAt": "2026-07-31T00:00:00.000Z" }
  ],
  "truncated": false
}

• Zapisz syncedAt i odeślij je jako since następnym razem. Nie używaj do tego własnego zegara. System spieszący się o kilka minut na stałe pomijałby okno zmian, i to bez żadnego objawu, bo odpowiedzi wyglądałyby poprawnie.
• Lista upserted to rekordy do wstawienia albo zaktualizowania. Klucz to id, a nie grantCode.
• Lista removed mówi, co wypadło z katalogu, a pole reason, co z tym zrobić. expired to zakończony nabór, warto zachować rekord w historii klienta. unpublished i deleted to rekordy do usunięcia. Pokrywa się to z zachowaniem GET /v1/grants/{id}: dotacja wygasła nadal odpowiada 200, pozostałe dwie 404.
• Endpoint nie stronicuje i nie obsługuje ETag, bo syncedAt zmienia się przy każdym wywołaniu. Lista upserted jest ucinana na 200 pozycjach, a flaga truncated dotyczy wyłącznie listy removed. Po dłuższej przerwie w synchronizacji odpytaj katalog w całości zamiast pytać o zmiany.

2. Odświeżanie warunkowe

Jeśli odpytujesz katalog z konkretnym filtrem częściej niż raz dziennie, na przykład żeby odświeżyć widok w CRM, użyj ETag. Przy braku zmian odpowiedź to 304 bez treści.

# pierwsze pobranie: zapisz ETag z odpowiedzi
curl -i 'https://edofinansowania.pl/api/v1/grants?voivodeship=PL-MZ' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ'
# ETag: W/"3f9a1c08b2d4e6f7a8b9c0d1e2f3a4b5"

# kolejne: odeślij go i licz się z odpowiedzią 304 bez treści
curl -i 'https://edofinansowania.pl/api/v1/grants?voivodeship=PL-MZ' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ' \
  -H 'X-If-None-Match: W/"3f9a1c08b2d4e6f7a8b9c0d1e2f3a4b5"'

• Przez adres edofinansowania.pl/api użyj nagłówka X-If-None-Match. Warstwa proxy nie przekazuje standardowego If-None-Match do serwera, więc żądanie z samym nagłówkiem standardowym zawsze dostanie pełną odpowiedź. Sprawdzone na produkcji, nie wywnioskowane z dokumentacji proxy.
• 304 oszczędza transfer, nie limit. Licznik minutowy rusza na bramce, zanim zajrzymy do bazy.
• ETag jest liczony z całej odpowiedzi razem ze stroną wyników, więc zmiana parametrów zapytania to inny ETag. Trzymaj go obok filtra, którego dotyczy.

3. Prowadzenie sprawdzenia kwalifikowalności

Pętlę prowadzi Twój system. Zaczynasz od samego grantId z pustą mapą odpowiedzi.

curl -X POST 'https://edofinansowania.pl/api/v1/eligibility/run' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ' \
  -H 'Content-Type: application/json' \
  -d '{"grantId":"EDF-0004","answers":{}}'

{
  "status": "incomplete",
  "engine": { "id": "eng_kredyt_eko", "version": "3" },
  "nextQuestion": {
    "id": "q1",
    "text": "Czy firma prowadzi działalność dłużej niż 12 miesięcy?",
    "type": "yes-no",
    "options": [{ "id": "yes", "label": "Tak" }, { "id": "no", "label": "Nie" }],
    "description": null,
    "helpText": "Liczy się data rozpoczęcia działalności z CEIDG lub KRS."
  },
  "progress": { "answered": 0, "totalQuestions": 6 },
  "path": []
}

Zadajesz pytanie użytkownikowi, dokładasz do mapy id wybranej opcji, nie jej tekst, i wołasz ponownie z kompletem. Nie wysyłasz samej ostatniej odpowiedzi, bo endpoint nie pamięta poprzednich.

curl -X POST 'https://edofinansowania.pl/api/v1/eligibility/run' \
  -H 'Authorization: Bearer sk_live_TWOJ_KLUCZ' \
  -H 'Content-Type: application/json' \
  -d '{"grantId":"EDF-0004","answers":{"q1":"yes"}}'

Powtarzasz, dopóki status to incomplete. Werdykt przychodzi w tej samej strukturze, tylko z innym kształtem.

{
  "status": "complete",
  "engine": { "id": "eng_kredyt_eko", "version": "3" },
  "verdict": "not_eligible",
  "message": "Program nie obejmuje firm bez historii kredytowej.",
  "failedCondition": "Brak zdolności kredytowej potwierdzonej przez bank",
  "progress": { "answered": 3, "totalQuestions": 6 },
  "path": ["q1", "q2", "q4"]
}

• Przy cofnięciu użytkownika usuń z mapy wszystkie odpowiedzi po zmienianym pytaniu. Zostawione odpowiedzi z porzuconej gałęzi dają 422 z listą unreachable.
• Zapisz engine.version razem z werdyktem. Jeśli zmieni się w trakcie rozmowy, zebrane odpowiedzi mogą przestać układać się w ścieżkę i rozmowę trzeba zacząć od nowa. Zapisana wersja tłumaczy też później, dlaczego ten sam klient dostał inny wynik.
• failedCondition nadaje się do pokazania handlowcowi, bo mówi, który warunek przesądził. message jest pisane pod klienta końcowego.

Katalog błędów

Błędy przychodzą jako application/problem+json w formacie RFC 9457. Rozpoznawaj je po polu type, nie po treści title: adres w type jest identyfikatorem i się nie zmienia, a tytuł jest zdaniem dla człowieka i może zostać przeredagowany.

Poza polami type, title, status, detail i instance dokument bywa uzupełniony o pola dodatkowe, wymienione przy odpowiednich wpisach. Zgodnie z RFC leżą one na najwyższym poziomie, a nie w zagnieżdżonym obiekcie.

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-missing-key",
  "title": "Missing API key",
  "status": 401,
  "detail": "Send the key in an Authorization: Bearer <key> or X-API-Key header.",
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-invalid-key",
  "title": "Invalid API key",
  "status": 401,
  "detail": "The key has an invalid format or checksum.",
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-key-revoked",
  "title": "API key revoked",
  "status": 401,
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-key-expired",
  "title": "API key expired",
  "status": 401,
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-origin-not-allowed",
  "title": "Origin not allowed for this key",
  "status": 403,
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-partner-suspended",
  "title": "Partner access suspended",
  "status": 403,
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-subscription-lapsed",
  "title": "Subscription lapsed",
  "status": 403,
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-endpoint-not-enabled",
  "title": "Endpoint not enabled for your account",
  "status": 403,
  "instance": "/v1/eligibility/run"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-rate-limit-exceeded",
  "title": "Per-minute rate limit exceeded",
  "status": 429,
  "instance": "/v1/grants",
  "retryAfter": 17
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-quota-exceeded",
  "title": "Monthly quota exhausted",
  "status": 429,
  "instance": "/v1/grants",
  "retryAfter": 216000
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No published grant with the identifier EDF-9999.",
  "instance": "/v1/grants/EDF-9999"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "Unknown voivodeship: PL-XX",
  "instance": "/v1/grants",
  "allowed": [
    "PL-DS",
    "PL-KP",
    "PL-MZ",
    "NATIONWIDE"
  ]
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-invalid-cursor",
  "title": "Invalid cursor",
  "status": 400,
  "detail": "A cursor comes from the nextCursor field of a previous response and must not be constructed by hand.",
  "instance": "/v1/grants"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-unknown-question",
  "title": "Unknown question in the answers",
  "status": 422,
  "detail": "The engine does not know these questions: q9.",
  "instance": "/v1/eligibility/run",
  "unknownQuestions": [
    "q9"
  ],
  "questionIds": [
    "q1",
    "q2",
    "q3"
  ]
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-invalid-answer",
  "title": "Invalid answer",
  "status": 422,
  "detail": "The answer to question q2 is not one of its options.",
  "instance": "/v1/eligibility/run",
  "questionId": "q2",
  "options": [
    {
      "id": "yes",
      "label": "Tak"
    },
    {
      "id": "no",
      "label": "Nie"
    }
  ]
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-contradictory-answers",
  "title": "The answers do not form a single path",
  "status": 422,
  "detail": "The answers given belong to questions this path does not reach.",
  "instance": "/v1/eligibility/run",
  "unreachable": [
    "q5"
  ],
  "path": [
    "q1",
    "q2"
  ]
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-no-engine-for-grant",
  "title": "No eligibility engine for this grant",
  "status": 404,
  "detail": "Grant EDF-0004 has no active question engine.",
  "instance": "/v1/eligibility/run"
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-engine-misconfigured",
  "title": "The eligibility engine is inconsistent",
  "status": 500,
  "detail": "Stopped at question q3 (no-next-question).",
  "instance": "/v1/eligibility/run",
  "cause": "no-next-question",
  "path": [
    "q1",
    "q2",
    "q3"
  ]
}

{
  "type": "https://edofinansowania.pl/dokumentacja-api#problem-internal",
  "title": "Server error",
  "status": 500,
  "instance": "/v1/grants"
}