Skip to main content

API Reference

Wszystkie routery są montowane przez app.api.api_router z prefiksem z env (API_PREFIX, domyślnie /api). Swagger UI dostępne pod /api/docs, a ReDoc pod /api/redoc.

Health​

  • Endpoint: GET /api/health
  • Auth: brak
  • Opis: prosty heartbeat. Używany przez load balancery i wakelock dla health checków.
  • Przykład odpowiedzi:
{
  "status": "ok",
  "app": "VendorHubBackend",
  "environment": "local"
}

Katalogi (catalog)​

Każde zapytanie zwraca CatalogListResponse:

{
  "list": [
    {
      "id": 1,
      "name": "Cloud Services",
      "description": "Dostawcy chmury",
      "icon": null,
      "image": null
    }
  ]
}
  • GET /api/v1/catalog/products
  • GET /api/v1/catalog/sectors
  • GET /api/v1/catalog/categories
  • GET /api/v1/catalog/competences
  • GET /api/v1/catalog/certificates

Każdy endpoint sortuje wyniki po name i nie wymaga uwierzytelnienia. Lista służy do budowania filtrów i formularzy dla aplikacji klienckich.

Vendor​

Wyszukiwanie (wyszczególnione filtrowanie)​

  • Endpoint: POST /api/v1/vendors/search
  • Body: VendorListRequest
    • pageNumber / pageCount – paginacja.
    • filter – Wein filtrowy: name, vatId, shortDescription, filterCategoryIds itd.
    • sort – mapa {"name": "ASC"}.
    • fullTextSearch – baza podkreśleń.

Przykład żądania:

{
  "pageNumber": 1,
  "pageCount": 25,
  "filter": {
    "name": "Logis",
    "shortDescription": "platforma"
  },
  "filterCategoryIds": [3, 5],
  "filterProductIds": [7],
  "sort": { "officialName": "DESC" }
}

Przykład odpowiedzi: VendorListResponse

{
  "vendorListRows": [
    {
      "id": 49,
      "name": "VendorLogic Services",
      "vatIdPrefix": "PL",
      "vatId": "1234567890",
      "subscriptionType": 1,
      "categories": [],
      "products": [],
      "sectors": [],
      "shortDescription": null,
      "description": null
    }
  ],
  "totalCount": 1
}

Szczegóły vendora​

  • GET /api/v1/vendors/by-vat/{vat_prefix}/{vat_id} – pobiera vendor według kompletnego numeru VAT (wspiera prefix dla krajów).
  • GET /api/v1/vendors/{vendor_id} – pobiera vendor po wewnętrznym ID.
  • Oba zwracają VendorDetailResponse: oprócz pól VendorBase (np. name, vatId, shortDescription) dołączone są relacje (categories, products, sectors, certificates, competences) oraz surowe profile ESG/monitoringu.

JSON Patch – aktualizacja opisów​

  • Endpoint: PATCH /api/v1/vendors/{vendor_id}
  • Body: lista RFC 6902 operacji. Obsługiwane ścieżki: /short_description, /description, /official_name.
  • Content-Type: application/json-patch+json

Przykład:

[
  { "op": "replace", "path": "/short_description", "value": "Nowy opis" },
  { "op": "replace", "path": "/official_name", "value": "VendorLogic Polska" }
]

Po udanej operacji endpoint zwraca zaktualizowany VendorDetailResponse.

Relacje (produkty, sektory, kategorie, kompetencje, certyfikaty)​

  • Dodawanie: POST /api/v1/vendors/{vendor_id}/{relation}

    • {relation} ∈ products, sectors, categories, competences, certificates.
    • Body: {"productId": 5} lub odpowiednio sectorId, categoryId, competenceId, certificateId.
    • Zwraca {"id": <relation_id>} (identyfikator nowego rekordu).

  • Usuwanie: DELETE /api/v1/vendors/{vendor_id}/{relation}/{relation_id}

    • Usuwa rekord relacji, zwraca {"id": <relation_id>}.
    • Relacja jest weryfikowana względem vendor_id (status 404 jeśli nie pasuje).

Lista nazw​

  • GET /api/v1/vendors/names – VendorNameListResponse z podstawowymi identyfikatorami, wykorzystywane przez dropdowny.

Tenant​

  • GET /api/v1/vendors/{vendor_id}/access – zwraca VendorAccessResponse(hasAccess: true). W przyszłości walidacja faktycznego dostępu.
  • GET /api/v1/users/vendors – demo: zwraca listę VendorUserResponse z tenantId, vendorId, vendorName. Przygotowane do zastąpienia rzeczywistym powiązaniem JWT → vendor.

ESG​

  • GET /api/v1/vendors/esg – lista VendorEsg z tabeli vendor_esg.
  • GET /api/v1/vendors/{vendor_id}/esg – szczegóły ESG dla vendora (status 404 jeśli brak).
  • GET /api/v1/vendors/by-vat/{vat_id}/modules/{module_lookup} – dodatkowe dane VendorAdditionalData, tzn. rozbudowane moduły dla lookup (np. financial). module_lookup traktowane case-insensitive.

Kwestionariusze (questionnaires)​

Wszystkie endpointy wymagają nagłówka Authorization: Bearer <token>. Token dekodowany jest przy użyciu app.core.security – wymagane sub, user_id, uid lub nameidentifier.

Lista zestawów​

  • GET /api/v1/questionnaires – zwraca QuestionSetListResponse.
    • Łączy UserVendor + QuestionSetEntity + QuestionSet.
    • W odpowiedzi pojawiają się totalQuestions, answeredQuestions, status, vendorName.

Szczegóły zestawu​

  • GET /api/v1/questionnaires/{vendor_question_set_id} – QuestionSetDetailResponse.
    • Zwraca pytania, zakładki (TabResponse), odpowiedzi (AnswerResponse), parametry (QuestionnaireParamResponse).
    • W sekcji answer pojawiają się value, comment, questionnaireParam.

Tworzenie odpowiedzi​

  • POST /api/v1/questionnaires/answers
    • Body: AnswerBatchRequest (lista questionAnswers z vendorQuestionSetId, questionnaireId, value, questionnaireParamId, comment).
    • Po stworzeniu odpowiedzi zwraca {"message":"Answers created successfully","count":N}.

Aktualizacja odpowiedzi​

  • PATCH /api/v1/questionnaires/answers
    • Body: JSON Patch, dopuszczalne ścieżki /answers/{answerId}/{value|comment|questionnaireParamId}.
    • Mechanizm waliduje uprawnienia użytkownika do vendora (przez UserVendor).
    • Przykład:
[
  { "op": "replace", "path": "/answers/42/value", "value": "1234.56" },
  { "op": "replace", "path": "/answers/42/comment", "value": "Niepotwierdzone dane" }
]

Po poprawnej walidacji i patchu endpoint zwraca {"message":"Answers updated successfully","count":N}.

Struktury danych i modele​

  • app.schemas.catalog.CatalogItem – id, name, description, icon, image, createdAt, updatedAt.
  • app.schemas.vendor.VendorRow/VendorDetailResponse – zawierają relacje products, categories, certificates, competences, sectors.
  • app.schemas.questionnaire – QuestionSetDetailResponse, AnswerResponse itd. Są zgodne z aliasami camelCase dla aplikacji klienckich.

Dokumentacja kodu źródłowego (FastAPI/OpenAPI) jest zawsze dostępna przy uruchomionym serwerze pod /api/openapi.json.

Nagłówki i błędy​

  • Authorization: Bearer <token> – wymagany dla kwestionariuszy.

  • Content-Type: application/json, /json-patch+json – w zależności od endpointu (PATCH vendor, odpowiedzi).

  • X-Request-ID – może być przekazywany przez klienta aplikacji; logowany w uvicorn (proszę dodać middleware, jeśli potrzebny).

  • Błędy:

    • 400 – nieprawidłowe dane lub brak dostępu (np. brak powiązanego vendora).
    • 401 – brak lub nieprawidłowy JWT przy kwestionariuszach.
    • 404 – vendor/relacja/kwestionariusz nie znaleziony.
    • 422 – JSON Patch waliduje dostępne ścieżki; zapytanie w złym formacie.
    • 500 – nieoczekiwany wyjątek (sprawdź logi, odśwież wnioski).

Każdy endpoint korzysta z modeli Pydantic (opis w app/schemas) i jest udokumentowany na OpenAPI. Możesz użyć curl lub httpie, np.:

http POST http://localhost:8000/api/v1/vendors/search pageNumber=1 pageCount=10 filter:='{"name":"Demo"}'