PetCareers Python SDK

Typed synchronous and asynchronous clients for the PetCareers Partner API. Requires Python 3.11+. Distributed under MIT; see the included LICENSE.

Install

python -m pip install petcareers-sdk

The package name is petcareers-sdk; the import name is petcareers.

Synchronous client

import os
from petcareers import PetCareers, PetCareersError

with PetCareers(
    api_key=os.environ["PARTNER_API_KEY"],
    environment="sandbox",
    locale="en",
) as client:
    identity = client.get_identity("clinics:read")
    clinics = client.list_clinics(limit=10)
    for clinic in client.iterate_clinics(limit=100):
        profile = client.get_clinic(clinic["connectionId"])
        # Process the authorized clinic without logging personal data.

Asynchronous client

import asyncio
import os
from petcareers import AsyncPetCareers


async def main():
    async with AsyncPetCareers(api_key=os.environ["PARTNER_API_KEY"]) as client:
        offers = await client.list_offers(limit=10)
        async for offer in client.iterate_offers(limit=100):
            pass  # Process each offer.


asyncio.run(main())

Responses preserve the wire envelope: response["data"] and response["requestId"]. List data contains items and nextCursor. Keep API keys server-side. Your key needs the scopes and clinic connections required by each operation. Use a separate production application/key with environment="production" when ready.

Both clients expose get_clinic, get_offer, get_logo, mutation operations and webhook management. verify_webhook verifies signed raw webhook bytes; your receiver must persist event IDs for deduplication. Catch PetCareersError and inspect sanitized code, status, request_id, retry_after and current_version rather than logging raw payloads. Reads have bounded retries; eligible idempotent writes require explicit retry opt-in. Always close clients using context managers or close() / aclose(). The SDK sends no telemetry.

Polski

SDK wymaga Python 3.11+. Instalacja: python -m pip install petcareers-sdk; import: from petcareers import PetCareers. Licencja MIT obejmuje SDK, a dostęp do API wymaga osobnej autoryzacji.

PetCareers działa synchronicznie, a AsyncPetCareers obsługuje asyncio. Używaj with lub async with, aby zamknąć połączenia. Domyślne środowisko to sandbox; ustaw locale="pl" dla języka polskiego. Klucz przechowuj wyłącznie na serwerze i nadaj mu wymagane zakresy dostępu.

Odpowiedzi zawierają data i requestId; listy mają data.items i data.nextCursor. Iteratory automatycznie obsługują strony. Błędy mają typ PetCareersError i oczyszczone pola diagnostyczne. Nie loguj danych osobowych ani kluczy. Zapis wymaga osobnego klucza idempotencji i jawnego włączenia ponowień dla obsługiwanych operacji. verify_webhook weryfikuje podpis oryginalnych bajtów; odbiorca musi zapisywać identyfikatory zdarzeń, aby zapobiegać duplikatom. SDK nie wysyła telemetrii.

English guide · Polski poradnik

Repository guides require access while the GitHub repository is private.

Prepared 0.2.0 / Przygotowana wersja 0.2.0

0.1.0 is already published on npm and PyPI. 0.2.0 is prepared locally and is NOT published; install its local tarball/wheel to use the APIs below. Build with npm run build and npm pack --workspace @petcareers/sdk --pack-destination dist. Ordinary identity calls remain read-only.

0.1.0 jest już opublikowana w npm i PyPI. 0.2.0 jest przygotowana lokalnie i NIE jest opublikowana; nowe API wymagają instalacji lokalnego tgz/wheel. Budowanie: npm run build i npm pack --workspace @petcareers/sdk --pack-destination dist. Zwykłe wywołanie identity wykonuje wyłącznie odczyt.

The SDK automatically sends X-PetCareers-SDK: typescript/0.2.0 or python/0.2.0 from package metadata. Optional sandboxRunId / sandbox_run_id must be a UUID and is rejected in production; X-PetCareers-Test-Run is correlation metadata and grants no authority. Custom fetch/HTTPX transports, credentials, retries and idempotency behavior are preserved.

SDK automatycznie wysyła wersję z metadanych pakietu. Opcjonalne sandboxRunId / sandbox_run_id musi być UUID i jest odrzucane w produkcji; nagłówek przebiegu służy tylko korelacji i nie nadaje uprawnień. Własne transporty fetch/HTTPX, klucze, ponowienia i idempotencja zachowują dotychczasowe działanie.

const client = new PetCareers({ apiKey, sandboxRunId: runId });
await client.acknowledgeConsentCallback({ receipt });

with PetCareers(api_key=api_key, sandbox_run_id=run_id) as client:
    client.acknowledge_consent_callback(receipt=receipt)
# AsyncPetCareers exposes the same keyword method, awaited.

Acknowledgement sends strict {receipt} to POST /api/partner/v1/{environment}/consents/acknowledge with clinics:write. Read the 64 lowercase hex token from your own registered callback's receipt query parameter, validate your initiating consent state, and acknowledge within 10 minutes. Never log the token, callback URL or state. A valid replay is 200; invalid/expired/stale/wrong-scope receipts are409 after authentication; malformed input is400. SDK validation rejects malformed receipt input locally. This POST does not automatically retry; a caller may explicitly repeat the same receipt after a lost response. Success retains {data:{acknowledged:true},requestId}. Denied consent is not successful activation.

Potwierdzenie wysyła ścisłe {receipt} do tego endpointu z clinics:write. Odczytaj token64 małych znaków hex z parametru receipt własnego zarejestrowanego callback, sprawdź stan rozpoczętej zgody i potwierdź w ciągu10 minut. Nie loguj tokenu, adresu callback ani stanu. Poprawne powtórzenie zwraca200; błędny/wygasły/nieaktualny token lub zakres zwraca409 po uwierzytelnieniu; błędny format400. SDK odrzuca błędny format lokalnie. POST nie ponawia automatycznie; po utracie odpowiedzi można jawnie powtórzyć ten sam token. Odmowa zgody nie oznacza aktywacji.