Search by

speedfin / speedfin-wrapper

speedfin

Speedfin 2.0 API wrapper for Finance Admin (clients, documents, etc.)

Package info

bitbucket.org/speedfin/speedfin-wrapper

pkg:composer/speedfin/speedfin-wrapper

Statistics

Installs: 246

Dependents: 0

Suggesters: 0

1.0.13 2026-11-19 09:03 UTC

This package is auto-updated.

Last update: 2026-11-19 09:06:28 UTC


README

Klient PHP do API Speedfin Backend. Pakiet udostępnia moduły AdviserProfile, Calendar, Notification, Client, ProductPrint, ProductSimulation i SchedulePrint.

Wymagania

  • PHP 8.2 lub nowszy.
  • Symfony ^6.4 || ^7.4 || ^8.0. Symfony 8 wymaga PHP 8.4 lub nowszego.

Przekazywanie tokenu

AdviserProfile i Notification pobierają token z providera. Pozostałe moduły przyjmują token doradcy w każdym wywołaniu. Podaj samą wartość tokenu, bez prefiksu Bearer. Pusty token lub token zawierający spacje, znaki sterujące albo znaki spoza ASCII powoduje InvalidArgumentException przed wysłaniem żądania.

Obsługa klientów w Symfony

Dodaj pakiet speedfin/speedfin-wrapper do zależności aplikacji. Zarejestruj bundle w config/bundles.php.

SpeedfinWrapper\SpeedfinWrapperBundle::class => ['all' => true],

W config/packages/speedfin_wrapper.yaml skonfiguruj adres bazowy Backendu. W apps/ai można użyć zmiennej SPEEDFIN_BASE_URL.

speedfin_wrapper:
    api_domain: '%env(resolve:SPEEDFIN_BASE_URL)%'

Wstrzyknij ClientServiceInterface do serwisu aplikacji. W metodzie obsługującej zalogowanego doradcę przekaż jego aktualny token dostępu w postaci samego JWT, bez prefiksu Bearer.

use SpeedfinWrapper\Client\Dto\ClientCreateDto;
use SpeedfinWrapper\Client\Service\ClientServiceInterface;

final readonly class CreateAdviserClient
{
    public function __construct(private ClientServiceInterface $clients)
    {
    }

    public function create(string $adviserToken): int
    {
        return $this->clients->create(
            new ClientCreateDto(name: 'Jan', surname: 'Kowalski', email: 'jan@example.com'),
            $adviserToken,
        )->id;
    }
}

create() wysyła POST /api/clients jako application/ld+json. name i surname są wymagane. cellPhone, email i comment są opcjonalne. Backend przypisuje klienta do doradcy z tokenu. Wrapper zwraca ClientCreatedDto po odpowiedzi 201 Created z id w postaci dodatniej liczby całkowitej.

Ten sam serwis udostępnia listę, szczegóły i częściową edycję danych klienta. Każde wywołanie przyjmuje aktualny token doradcy.

use SpeedfinWrapper\Client\Dto\ClientUpdateDto;

$list = $clients->getAll($adviserToken);
$filtered = $clients->getAll($adviserToken, page: 1, limit: 20, search: 'Jan Kowalski');
$client = $clients->getById($clientId, $adviserToken);
$updated = $clients->update($clientId, new ClientUpdateDto(email: 'nowy@example.com'), $adviserToken);

getAll() zwraca tablicę ClientItemDto, a getById() i update() zwracają jeden ClientItemDto. DTO zawiera id, name, surname, cellPhone, email i comment. update() wysyła PATCH w formacie application/merge-patch+json. Pola pominięte w ClientUpdateDto zachowują dotychczasowe wartości. Aby wyczyścić cellPhone, email lub comment, przekaż pusty ciąg. Odpowiedź 404 przy odczycie lub edycji jest dostępna jako ClientExceptionInterface.

Opcjonalne page, limit i search są przekazywane jako parametry query do GET /api/clients. Wartości null są pomijane. search przyjmuje jeden tekst o długości do 255 znaków. Backend wyszukuje fragment imienia, nazwiska, e-maila lub pełnego imienia i nazwiska w obu kolejnościach. Normalizuje białe znaki i ignoruje wielkość liter. Pusty tekst lub same białe znaki oznaczają zwykłe listowanie. Przekaż tekst wprost, a Symfony HttpClient zakoduje znaki specjalne i Unicode. Backend traktuje % i _ dosłownie i zwraca błędy walidacji API przy niepoprawnych parametrach.

Błędy walidacji i autoryzacji są dostępne jako ClientExceptionInterface z Symfony HttpClient. Kod HTTP można odczytać przez $exception->getResponse()->getStatusCode(), a treść JSON przez $exception->getResponse()->toArray(false). Po błędzie transportu wywołujący decyduje o ponowieniu zapisu, ponieważ Backend mógł już utworzyć klienta.

Profil klienta do badania hipotecznej zdolności kredytowej

ClientServiceInterface udostępnia odczyt profilu:

public function getAbilityProfile(
    int $clientId,
    string $accessToken,
    ?int $interviewId = null,
): ClientAbilityProfileDto;

Metoda wysyła GET /api/clients/{clientId}/ability-profile z Accept: application/json i Authorization: Bearer <accessToken>. Wymaga dodatnich identyfikatorów i aktualnego tokenu doradcy bez prefiksu Bearer. Argumenty są sprawdzane przed HTTP. Przy interviewId = null parametr query jest całkowicie pomijany; jawny wybór dodaje wyłącznie ?interviewId=.... Token dotyczy jednego wywołania. Backend ustala doradcę, firmę i dostępność klienta na podstawie uwierzytelnienia.

Odczyt, jawny wybór źródła i braki

use SpeedfinWrapper\Client\Enum\AbilityProfileStatus;
use SpeedfinWrapper\Client\Service\ClientServiceInterface;

/** @var ClientServiceInterface $clients */
$profile = $clients->getAbilityProfile($clientId, $accessToken);

if ($profile->status === AbilityProfileStatus::SelectionRequired) {
    // Przekaż sourceCandidates do interfejsu wyboru; nie wybieraj pierwszego ani najnowszego.
    // Po jawnym wyborze przez użytkownika wykonaj osobne wywołanie:
    $profile = $clients->getAbilityProfile(
        clientId: $clientId,
        accessToken: $accessToken,
        interviewId: $selectedInterviewId,
    );
}

foreach ($profile->missingFields as $missing) {
    $path = $missing->path;
    $scope = $missing->scope->value; // profile albo scenario
    $code = $missing->code->value;
    $label = $missing->label;
    $sourcePaths = $missing->sourcePaths;
    // Zbierz wyjaśnienie lub uzupełnienie tego braku od użytkownika.
}

selection_required jest poprawną odpowiedzią HTTP 200: source i abilityInput mają wartość null, kandydaci są w sourceCandidates, a missingFields i fieldSources są pustymi listami. Wrapper zwraca kandydatów w otrzymanej kolejności, bez automatycznego wyboru, ponawiania żądania ani łączenia źródeł. W przykładzie $selectedInterviewId pochodzi z osobnej decyzji użytkownika.

incomplete również jest poprawną odpowiedzią HTTP 200. Zwraca częściowe abilityInput i braki, także przy source = null. Ukończony wywiad i jego completedAt nie dowodzą gotowości. Wrapper przyjmuje też ready, przewidziane w kontrakcie. Obecne mapowanie Backendu 1 produkuje wyłącznie incomplete lub selection_required.

Typy odpowiedzi

Wszystkie DTO są lokalne, typowane i niemutowalne (final readonly) w SpeedfinWrapper\Client\Dto.

DTOPola
ClientAbilityProfileDtoschemaVersion, clientId, status: AbilityProfileStatus, asOf, source, sourceCandidates, abilityInput, missingFields, fieldSources
ProfileSourceDtotype, id, revision, schemaVersion, updatedAt, completedAt, mappingVersion
SourceCandidateDtoid, completedAt, revision
MissingFieldDtopath, scope: MissingFieldScope, code: MissingFieldCode, label, sourcePaths
FieldSourceDtopath, sourcePaths
AbilityInputDtohouseholds, creditClientAge, creditValue, secureValue, creditPeriod
HouseholdDtopeople, cars, area, status, region, applicants
ApplicantDtoincomes, outcomes
IncomeDtoid, value, periodFrom, periodForward
OutcomeDtoid, value, limit, currency, period

asOf pozostaje dokładnym tekstem YYYY-MM-DD. Daty ISO 8601 źródła i kandydatów są mapowane na DateTimeImmutable z zachowaniem offsetu, precyzji do mikrosekund i null. Wiek i dzień odniesienia nie są przeliczane. Wspierana wersja koperty to string "1"; wersje schematu źródła i mapowania są osobnymi, niezależnymi ciągami, zachowywanymi bez interpretacji.

Pola częściowego wejścia mogą zawierać null. Nieznana lista pozostaje null; [] oznacza potwierdzony brak pozycji. Kwoty zachowują typ int|float|null, w tym zera i grosze. Wrapper nie uzupełnia wartości domyślnych. Ścieżki są zwykłym tekstem, także households[0].applicants[].incomes[0].id. missingFields pozostaje listą: kilka braków może dotyczyć tej samej ścieżki. fieldSources zachowuje otrzymane ścieżki pochodzenia.

Konsument zbiera brakujące dane i potwierdzenia, uzupełnia lub jawnie zmienia scenariusz oraz ustala bankIds. Następnie waliduje kompletne wejście, słowniki i wymagania warunkowe przed utworzeniem AbilityCalculationFilterDto i wywołaniem Calculators. Wrapper nie tworzy tego filtra, nie mapuje słowników ani nie wykonuje obliczeń. Również przyszłe ready nie zastępuje walidacji końcowego scenariusza i wyboru banków. GET nie zapisuje uzupełnień.

Błędy profilu

Dla tej metody ClientAbilityProfileException zawiera statusCode: ?int, providerCode: ?string i transportFailure: bool. Odczyt wykorzystuje istniejący adapter i dedykowany HttpClient modułu Client, bez automatycznych ponowień i przekierowań. Błędy HTTP i transportu są przekładane na bezpieczny wyjątek zgodnie z konwencją dedykowanych wyjątków pozostałych modułów. Dotychczasowe metody klientów nadal propagują wyjątki Symfony opisane wyżej.

HTTP / zdarzenieZnaczenie
400Niepoprawne parametry lub identyfikatory
401Brak albo niepoprawne uwierzytelnienie; odpowiedź JWT może mieć inny format
403Brak uprawnienia doradcy
404Niedostępny klient lub wywiad
422Własny draft albo nieobsługiwany schemat źródła
5xxAwaria usługi
Błąd transportutransportFailure = true; statusCode = null, jeśli nie odebrano jeszcze HTTP, w przeciwnym razie zachowuje odebrany status

providerCode zachowuje rozpoznane detail: ability_invalid_parameters, ability_invalid_identifier, ability_adviser_required, ability_client_not_found, ability_source_not_found, ability_source_not_completed, ability_unsupported_source_schema. Dla innych treści, w tym odpowiedzi JWT, ma wartość null. Wrapper nie interpretuje opisów błędów, type ani title. Błąd nigdy nie staje się zastępczym incomplete.

use SpeedfinWrapper\Client\Exception\ClientAbilityProfileException;

try {
    $profile = $clients->getAbilityProfile($clientId, $accessToken, $selectedInterviewId);
} catch (ClientAbilityProfileException $exception) {
    $httpStatus = $exception->statusCode;
    $safeCode = $exception->providerCode;
    $transportFailed = $exception->transportFailure;
    // Obsłuż dostęp, wybór źródła lub awarię; nie wybieraj automatycznie innego wywiadu.
}

Niepoprawne argumenty powodują InvalidArgumentException. Niepoprawny JSON, typy, nieznany status, nieobsługiwana wersja koperty, brak pól lub odpowiedź dotycząca innego klienta powodują UnexpectedValueException, bez zwracania pustego profilu. Komunikaty nowych błędów nie zawierają tokenu ani treści odpowiedzi i nie zachowują niesanitowanych wyjątków transportu jako previous.

Backend deklaruje Cache-Control: private, no-store. Wrapper nie zapisuje profilu we współdzielonym cache ani go nie loguje. Konsument również powinien respektować prywatność profilu i nie logować pełnych danych finansowych ani tokenu.

Zapisane symulacje klienta

W apps/ai wstrzyknij ProductSimulationServiceInterface do serwisu aplikacji. Bundle korzysta z istniejącego speedfin_wrapper.api_domain. Przekaż ID aktualnie wybranego klienta i aktualny token doradcy w postaci samego JWT.

use SpeedfinWrapper\ProductSimulation\Dto\ProductSimulationPageDto;
use SpeedfinWrapper\ProductSimulation\Service\ProductSimulationServiceInterface;

final readonly class ListClientSimulations
{
    public function __construct(private ProductSimulationServiceInterface $simulations)
    {
    }

    public function list(int $clientId, string $adviserToken, int $page = 1): ProductSimulationPageDto
    {
        return $this->simulations->listForClient($clientId, $adviserToken, $page);
    }
}

listForClient(int $clientId, string $adviserToken, int $page = 1): ProductSimulationPageDto przyjmuje dodatnie clientId i page. Wysyła GET /api/products/simulations?clientId=42&removed=0&page=1 z Accept: application/ld+json i bearerem doradcy. Backend ustala widoczność symulacji i zwraca je od najnowszych.

ProductSimulationPageDto udostępnia items (list<ProductSimulationItemDto>), totalItems (int) i hasNext (bool). Każdy element zawiera slug i type jako string oraz created jako DateTimeImmutable. Dla pustej kolekcji items jest pustą tablicą. Jeśli hasNext jest prawdziwe, wywołaj listForClient() ponownie z page zwiększonym o 1. hasNext wynika z linku next w metadanych view Backendu.

Przy listowaniu odpowiedzi 401 i 403 są dostępne jako ClientExceptionInterface. Timeout i inne awarie transportu zgłasza Symfony przez TransportExceptionInterface. Niepoprawna kolekcja, w tym wpis z niezgodnym clientId, powoduje UnexpectedValueException.

Pobranie zapisanego PDF

Po wybraniu pozycji z listy przekaż jej slug do downloadPdf() wraz z aktualnym tokenem doradcy. Przykład używa pierwszej pozycji z listy.

$page = $simulations->listForClient($clientId, $adviserToken);
$selected = $page->items[0] ?? null;

if ($selected !== null) {
    $pdf = $simulations->downloadPdf($selected->slug, $adviserToken);
    // $pdf->filename zawiera nazwę do pobrania, a $pdf->content bajty PDF.
}

downloadPdf(string $slug, string $adviserToken, int $maxBytes = 20_000_000): ProductSimulationPdfDto pobiera istniejący plik przez GET /api/products/simulations/{slug} z Accept: application/pdf. DTO zawiera slug, filename i binarne content. Przy brakującej lub niebezpiecznej nazwie w Content-Disposition wrapper używa symulacja.pdf. Limit bajtów jest sprawdzany podczas odczytu strumienia także przy braku Content-Length.

ProductSimulationDownloadException udostępnia reason i statusCode. Authorization oznacza 401 lub 403, NotFound oznacza 404, a Rejected oznacza pozostałe odrzucenia HTTP 4xx z wyjątkiem 408. Unavailable obejmuje awarię transportu oraz HTTP 408 i 5xx. InvalidResponse oznacza przekierowanie, nieoczekiwany status lub niepoprawny PDF. TooLarge oznacza przekroczony limit bajtów.

Wydruki hipoteczne i trwałe PDF

ProductPrintServiceInterface korzysta z tego samego api_domain i rejestracji bundle co moduł Client. W Symfony 8 wstrzyknij interfejs do serwisu aplikacji. Przekaż aktualny token doradcy i referencje snapshotów z istniejących wyników kalkulatora.

use SpeedfinWrapper\ProductPrint\Dto\ProductPrintCreateDto;
use SpeedfinWrapper\ProductPrint\Dto\ProductPrintFilterDto;
use SpeedfinWrapper\ProductPrint\Dto\ProductPrintItemDto;
use SpeedfinWrapper\ProductPrint\Dto\ProductPrintPdfDto;
use SpeedfinWrapper\ProductPrint\Dto\ScenarioContextDto;
use SpeedfinWrapper\ProductPrint\Service\ProductPrintServiceInterface;

final readonly class DownloadMortgageOffers
{
    public function __construct(private ProductPrintServiceInterface $prints)
    {
    }

    public function download(
        #[\SensitiveParameter] string $adviserToken,
        string $sessionId,
        int $offerId,
        string $snapshotRequestId,
    ): ProductPrintPdfDto {
        $scenario = new ScenarioContextDto($sessionId);
        $definition = $this->prints->createPrint(
            new ProductPrintCreateDto(
                filter: new ProductPrintFilterDto(creditValue: 400000, secureValue: 600000, creditPeriod: 300),
                items: [new ProductPrintItemDto(id: $offerId, requestId: $snapshotRequestId, sort: 0, print: [])],
                print: [],
            ),
            $adviserToken,
            $scenario,
        );
        $artifact = $this->prints->createArtifact($definition, $adviserToken);
        $receipt = $this->prints->getArtifactReceipt($artifact->id, $adviserToken, $artifact->scenario);

        return $this->prints->downloadArtifact($receipt, $adviserToken);
    }
}

createPrint() wysyła POST /api/products/prints z Accept i Content-Type równymi application/ld+json. Odpowiedź 201 jest mapowana na ProductPrintCreatedDto z slug, status i kontekstem scenariusza. createArtifact() przyjmuje ten wynik, dzięki czemu używa kontekstu z utworzenia definicji. Wysyła POST /api/products/prints/{slug}/artifacts z Accept: application/json i zwraca ProductPrintArtifactReceiptDto z id, filename i scenario po odpowiedzi 201.

getArtifactReceipt() wykonuje GET /api/products/print-artifacts/{id}/receipt z Accept: application/json. Weryfikuje odpowiedź 200, format UUID v4, bezpieczną nazwę pliku PDF oraz zgodność ID z żądaniem. downloadArtifact() przyjmuje potwierdzenie i wykonuje GET /api/products/print-artifacts/{id} z Accept: application/pdf. Zwraca ProductPrintPdfDto z id, filename i zawartością content przechowywaną w pamięci. Sprawdza typ odpowiedzi i sygnaturę %PDF-. Domyślny limit to 20_000_000 bajtów, a trzeci argument maxBytes pozwala ustawić własny limit. Limit jest sprawdzany podczas odczytu strumienia.

Ścieżka trwałych artefaktów jest przeznaczona dla hipotek. ProductPrintCreateDto wysyła type: mortgage. Filtr obsługuje investmentValue, creditValue, secureValue, incomeValue, creditPeriod, creditClientAge, ability, bankNameVisible i currencyIndex. ability przyjmuje tablicę zgodną z kontraktem Backendu, z gospodarstwami i wnioskodawcami. Kolejność pozycji, ich sort, istniejące requestId oraz tablice opcji print są przekazywane do Backendu w podanej postaci.

Opcjonalny ScenarioContextDto tworzy nagłówek X-Speedfin-Scenario-Context z schema: 1 i UUID sesji. Każda operacja przyjmuje jawny token doradcy. Transport bundle używa osobnego NativeHttpClient, wyłącza przekierowania i wykonuje pojedyncze żądanie dla każdej operacji.

Wyjątki dziedziczą po ProductPrintException. Udostępniają operation, statusCode i isWriteResultUncertain().

  • ProductPrintRejectedException oznacza jawne odrzucenie HTTP 4xx, w tym 406 przy negocjacji formatu definicji.
  • ProductPrintUnconfirmedException oznacza błąd transportu lub niepotwierdzony wynik, w tym HTTP 408 i 5xx.
  • ProductPrintInvalidResponseException oznacza błędny JSON, niepoprawne pola odpowiedzi, niepoprawny PDF lub przekroczenie limitu rozmiaru.

Po błędzie operacji zapisu sprawdź isWriteResultUncertain() przed decyzją o ponowieniu. Wartość true oznacza, że zapis mógł już nastąpić, również gdy odpowiedź 201 miała niepoprawną treść. Etap odczytasz z operation->value, a kod HTTP z statusCode. Przy błędach argumentów przed wysłaniem żądania zgłaszany jest InvalidArgumentException.

Harmonogram spłaty kredytu hipotecznego

Wstrzyknij SchedulePrintServiceInterface. Serwis korzysta z speedfin_wrapper.api_domain i w każdej operacji przyjmuje aktualny token doradcy w postaci samego JWT. Opcjonalny ScenarioContextDto z utworzenia definicji jest przekazywany automatycznie przy pobraniu.

use SpeedfinWrapper\ProductPrint\Dto\ScenarioContextDto;
use SpeedfinWrapper\SchedulePrint\Dto\SchedulePrintCreateDto;
use SpeedfinWrapper\SchedulePrint\Dto\SchedulePrintInterestPeriodDto;
use SpeedfinWrapper\SchedulePrint\Dto\SchedulePrintPdfDto;
use SpeedfinWrapper\SchedulePrint\Enum\SchedulePrintType;
use SpeedfinWrapper\SchedulePrint\Service\SchedulePrintServiceInterface;

final readonly class DownloadMortgageSchedule
{
    public function __construct(private SchedulePrintServiceInterface $prints)
    {
    }

    public function download(
        #[\SensitiveParameter] string $adviserToken,
        ?ScenarioContextDto $scenario = null,
    ): SchedulePrintPdfDto {
        $definition = $this->prints->createPrint(
            new SchedulePrintCreateDto(
                creditValue: 200_000,
                creditPeriod: 180,
                margins: [new SchedulePrintInterestPeriodDto(periodFrom: 1, periodTo: 180, interestRate: 5)],
                type: SchedulePrintType::EqualInstallmentFull,
            ),
            $adviserToken,
            $scenario,
        );

        return $this->prints->downloadPdf($definition, $adviserToken);
    }
}

Przykład generuje pełny harmonogram rat równych dla 200 000 PLN na 180 miesięcy przy nominalnym oprocentowaniu 5% rocznie przez cały okres. EqualInstallmentFull określa rodzaj rat i odpowiada FIXED_INSTALLMENT_FULL = 1 w Backendzie. interestRate w margins[] jest roczną stopą procentową, a periodFrom i periodTo oznaczają miesiące włącznie. Okresy muszą kolejno pokrywać cały czas spłaty. Backend oblicza harmonogram i renderuje PDF. DTO żądania obejmuje kwotę, czas spłaty, okresy oprocentowania i wariant wydruku. Konfiguracja transz pozostaje poza tym zakresem.

createPrint() wysyła POST /api/scheduler/prints jako application/ld+json. Po 201 Created zwraca SchedulePrintCreatedDto z slug, status równym CREATED i kontekstem. downloadPdf() wykonuje GET /api/scheduler/prints/{slug}. Backend renderuje PDF przy każdym takim żądaniu. SchedulePrintPdfDto zawiera filename i bajty content. Aplikacja może zachować te bajty we własnej pamięci trwałej i użyć ich ponownie, np. do kilku wysyłek z tym samym załącznikiem.

Zasób GET w Backendzie deklaruje obecnie application/vnd.openxmlformats jako jedyny typ negocjacji dla formatu pdf, a udane pobranie zwraca Content-Type: application/pdf. Wrapper wysyła Accept: application/pdf, application/vnd.openxmlformats;q=0.9, żeby obsłużyć obecną deklarację oraz jej korektę. Po stronie Backendu należy zarejestrować application/pdf w formats['pdf'] operacji GET. Można tymczasowo zachować dotychczasowy typ jako alias dla starszych klientów.

Wrapper weryfikuje MIME, nazwę pliku z Content-Disposition i sygnaturę %PDF-. Limit 20 MB (20_000_000 bajtów) jest sprawdzany podczas odczytu. Transport wyłącza przekierowania i automatyczne ponawianie zapisu. Wyjątki SchedulePrintRejectedException, SchedulePrintUnconfirmedException i SchedulePrintInvalidResponseException dziedziczą po SchedulePrintException i udostępniają operation, statusCode oraz isWriteResultUncertain(). statusCode jest null, jeśli kod HTTP nie był dostępny. Niepewny wynik zapisu oznacza, że Backend mógł już zapisać definicję.

Trwały artefakt harmonogramu

Obecny slug identyfikuje definicję harmonogramu. Backend potrzebuje osobnego kontraktu, żeby apps/ai mogło później pobierać ten sam PDF bez renderowania i bez przechowywania bajtów po swojej stronie. Proponowane operacje odpowiadają strukturze API ProductPrint.

Proponowana operacja BackenduOdpowiedź i działanie
POST /api/scheduler/prints/{slug}/artifactsRenderuje i zapisuje bajty, a po zapisie zwraca 201 z potwierdzeniem JSON zawierającym odrębne id (UUID), filename i contentType.
GET /api/scheduler/print-artifacts/{id}/receiptZwraca 200 z tym samym potwierdzeniem JSON.
GET /api/scheduler/print-artifacts/{id}Zwraca 200, Content-Type: application/pdf, Content-Disposition i zapisane bajty, bez ponownego renderowania.

Każda z proponowanych operacji powinna sprawdzać tożsamość doradcy i zgodność kontekstu scenariusza. Wrapper udostępnia dziś createPrint() i downloadPdf().

Kalendarium CRM

Wstrzyknij CalendarServiceInterface. Serwis korzysta z speedfin_wrapper.api_domain. Każde wywołanie przyjmuje aktualny JWT doradcy jako $adviserToken. Wrapper przesyła daty z offsetem i dokładnością do sekund oraz identyfikator strefy IANA. Backend sprawdza uprawnienia, interpretuje czas lokalny i oblicza wystąpienia oraz terminy przypomnień.

MetodaOperacja względem /api/crm/calendarWynik
createEvent()POST /events201, CalendarEventDto
getEvent()GET /events/{id}200, CalendarEventDto
updateEvent()PATCH /events/{id}200, CalendarEventDto
cancelEvent()POST /events/{id}/cancel200, CalendarEventDto ze stanem canceled
listOccurrences()GET /occurrences200, CalendarOccurrencePageDto
moveOccurrence()PATCH /events/{id}/occurrences/{occurrenceKey}200, definicja serii z nową wersją
cancelOccurrence()POST /events/{id}/occurrences/{occurrenceKey}/cancel200, definicja serii z nową wersją
getOccurrenceReminders()GET /events/{id}/occurrences/{occurrenceKey}/reminders200, CalendarOccurrenceRemindersDto

Spotkanie z klientem i przypomnieniem

Przykład zakłada istniejącego klienta doradcy i cotygodniowe spotkanie w czwartki. Dwie reguły przekazują przypomnienie doradcy w aplikacji oraz klientowi przez e-mail.

use SpeedfinWrapper\Calendar\Dto\CalendarEventCreateDto;
use SpeedfinWrapper\Calendar\Dto\CalendarRecurrenceDto;
use SpeedfinWrapper\Calendar\Dto\CalendarReminderRuleDto;
use SpeedfinWrapper\Calendar\Enum\CalendarFrequency;
use SpeedfinWrapper\Calendar\Enum\CalendarReminderChannel;
use SpeedfinWrapper\Calendar\Enum\CalendarReminderMode;
use SpeedfinWrapper\Calendar\Enum\CalendarReminderRecipient;
use SpeedfinWrapper\Calendar\Service\CalendarServiceInterface;

/** @var CalendarServiceInterface $calendar */
$series = $calendar->createEvent(
    new CalendarEventCreateDto(
        type: 'MEETING',
        title: 'Omówienie dokumentów',
        startsAt: new \DateTimeImmutable('2026-11-19T15:00:00+01:00'),
        endsAt: new \DateTimeImmutable('2026-11-19T16:00:00+01:00'),
        timezone: 'Europe/Warsaw',
        clientId: $clientId,
        recurrence: new CalendarRecurrenceDto(CalendarFrequency::Weekly, interval: 1, weekdays: [4], count: 4),
        reminders: [
            new CalendarReminderRuleDto(
                CalendarReminderMode::AtLocalTime,
                CalendarReminderRecipient::Adviser,
                CalendarReminderChannel::InApp,
                localTime: '10:00',
                dayOffset: 0,
            ),
            new CalendarReminderRuleDto(
                CalendarReminderMode::BeforeStart,
                CalendarReminderRecipient::Client,
                CalendarReminderChannel::Email,
                minutesBefore: 60,
            ),
        ],
    ),
    $adviserToken,
    idempotencyKey: $creationKey,
);

Przy tworzeniu przekaż klucz przypisany do operacji użytkownika. Backend dopuszcza jego pominięcie. Powtórzenie tego samego żądania z tym samym kluczem zwraca aktualną reprezentację wydarzenia. Zmiana danych przy użyciu tego samego klucza daje konflikt. Pola opcjonalne o wartości null w DTO tworzenia są pomijane.

Listowanie, przesunięcie terminu i odwołanie serii

use SpeedfinWrapper\Calendar\Dto\CalendarOccurrenceMoveDto;
use SpeedfinWrapper\Calendar\Dto\CalendarOccurrenceQueryDto;

$page = $calendar->listOccurrences(
    new CalendarOccurrenceQueryDto(
        from: new \DateTimeImmutable('2026-11-26T00:00:00+01:00'),
        to: new \DateTimeImmutable('2026-11-27T00:00:00+01:00'),
        clientId: $clientId,
        page: 1,
        itemsPerPage: 25,
    ),
    $adviserToken,
);

// $occurrence to element $page->items wybrany przez doradcę.
$moved = $calendar->moveOccurrence(
    $occurrence->eventId,
    $occurrence->occurrenceKey,
    new CalendarOccurrenceMoveDto(
        expectedVersion: $occurrence->version,
        startsAt: new \DateTimeImmutable('2026-11-26T16:00:00+01:00'),
        endsAt: new \DateTimeImmutable('2026-11-26T17:00:00+01:00'),
    ),
    $adviserToken,
);

$canceled = $calendar->cancelEvent($moved->id, $moved->version, $adviserToken);

Wynik listowania zawiera items, totalItems, odnośniki stronicowania w view i pozostałe metadane JSON-LD w metadata. Do kolejnego zapytania przekaż zakres i numer strony. Po przesunięciu używaj oryginalnego occurrenceKey. Każda edycja i każde odwołanie wymagają wersji z ostatniego potwierdzonego odczytu lub zapisu.

W CalendarEventUpdateDto pomiń clientId, description lub recurrence, aby zachować dotychczasową wartość. Podaj jawne null, aby ją wyczyścić. reminders: [] usuwa wszystkie reguły. Aktualizacja istniejącej reguły wymaga przekazania jej id i pełnej definicji.

Odczyt dostaw zachowuje status i reason Backendu. blocked oznacza blokadę dostawy. accepted oznacza przyjęcie przez kanał. isOutcomeUnknown() rozpoznaje zarówno zwracane przez Backend uncertain, jak i outcome_unknown. Oba stany wymagają uzgodnienia wyniku z dostawcą przed ponowieniem dostawy.

Wrapper negocjuje JSON-LD, wysyła POST jako JSON i PATCH jako JSON Merge Patch. Wyłącza przekierowania i automatyczne ponawianie. CalendarException udostępnia operation, reason i statusCode. reason rozróżnia walidację, autoryzację, brak zasobu, konflikt idempotencji, konflikt wersji lub stanu wydarzenia, pozostałe odrzucenia, uszkodzoną odpowiedź, niedostępny odczyt i niepotwierdzony zapis. Jeśli isWriteResultUncertain() zwraca true, Backend mógł zapisać zmianę. Przed kolejną edycją odczytaj bieżącą wersję. Przy ponowieniu utworzenia użyj tego samego klucza i tych samych danych.

Kolejne wydanie

Moduł Calendar jest przewidziany w wydaniu 1.0.10. Historia zmian znajduje się w CHANGELOG.md.