Integracje z zewnętrznymi API w Claude Code

Claude Code buduje produkcyjne integracje z usługami zewnętrznymi (płatności Stripe, e-maile transakcyjne, logowanie OAuth 2.0 i przychodzące webhooki), gdy prompt z góry nazywa zdarzenia, klucz idempotentności i kategorie błędów. Wtyczki dostawców lub serwery MCP dostarczają aktualną dokumentację API, a odtwarzane zdarzenia testowe, testy podpisów i testy podwójnego doręczenia dowodzą poprawności bez czytania kodu linijka po linijce.

Subskrypcje Stripe mają działać w czwartek. Płatność z quickstartu działa po godzinie, a potem przychodzą zduplikowane webhooki, zdarzenia docierające przed przekierowaniem, proxy psujące weryfikację podpisu i e-mail windykacyjny, którego nikt nie napisał. Ta strona jest dla programistów, którzy podłączają zewnętrzne usługi do aplikacji w Claude Code, oraz dla tech leadów, którzy chcą, żeby każda integracja przechodziła te same kontrole, zanim trafi na main.

Sprawdzone z Claude Code 2.1.283

Polecenia sprawdzono 2026-09-26 z zainstalowanym claude --help (v2.1.283, kanał latest), @stripe/mcp 0.3.3, @upstash/context7-mcp 4.1.1 i SDK stripe dla Node 22.6.2. Poleceń Stripe CLI (stripe listen, stripe trigger) nie uruchamiano w tym środowisku.

Co zyskasz, budując integracje w Claude Code

• Konfigurację, która daje Claude Code aktualną dokumentację dostawcy: przez oficjalne wtyczki Stripe i Resend albo przez Context7 dla każdej innej biblioteki.
• Macierz zdarzeń: jednostronicowy kontrakt, który człowiek przegląda zamiast kodu handlerów.
• Pięć promptów do skopiowania: macierz zdarzeń, wycinek Stripe pisany od testów, e-maile transakcyjne, logowanie OAuth 2.0 z PKCE i wspólna skrzynka webhooków.
• Zestaw weryfikacji (podpisane fikstury, powtórki podwójnych i nieuporządkowanych doręczeń, Stripe CLI i hook Stop), który dowodzi działania integracji bez czytania każdej linii.
• Awarie, które docierają na produkcję, każdą ze sposobem naprawy.

Jak dać Claude Code aktualną dokumentację dostawcy?

API płatności i poczty zmieniają się szybciej niż dane treningowe dowolnego modelu. Agent piszący pod zeszłoroczne API produkuje kod, który się kompiluje, a potem wywraca się w czasie działania. Zanim wyślesz pierwszy prompt, podłącz do sesji żywe źródło. Trzy drogi, od najbardziej do najmniej szczegółowej:

Droga	Co dodaje	Instalacja (terminal)	Kiedy jej użyć
Wtyczka Stripe	Skille Stripe (stripe-best-practices, upgrade-stripe i inne) oraz jego serwer MCP, aktualizowane automatycznie	claude plugin install stripe@claude-plugins-official	Wszystko, co dotyka Stripe
Wtyczka Resend	Skille Resend (resend, react-email, email-best-practices i inne) oraz hostowany serwer MCP Resend (OAuth)	claude plugin marketplace add resend/resend-skills, potem claude plugin install resend@resend-skills	E-maile transakcyjne przez Resend
Context7 MCP	Dokumentacja konkretnych wersji większości publicznych bibliotek	claude mcp add --transport http context7 https://mcp.context7.com/mcp	Każdy dostawca bez własnej wtyczki (klucz API jest opcjonalny i podnosi limity)

Polecenia instalacji pochodzą z repozytoriów dostawców: stripe/ai, resend/resend-skills i upstash/context7. Zakresy i położenie .mcp.json opisuje konfiguracja MCP w Claude Code. Narzędzia i użycie Context7 znajdziesz na stronie Context7. Proces opisany na tej stronie działa bez zmian z innymi agentami, różni się tylko instalacja. W Codeksie wtyczkę Stripe instalujesz poleceniem codex plugin add stripe@openai-curated (zobacz konfigurację MCP w Codeksie), a użytkownicy Cursora zaczynają od konfiguracji MCP w Cursorze.

Jeśli zespół woli lokalny serwer MCP Stripe w .mcp.json zapisanym w repozytorium, odwołaj się do klucza zamiast go wklejać. Serwer czyta STRIPE_SECRET_KEY ze swojego środowiska, a Claude Code rozwija ${VAR} przy starcie:

claude mcp add stripe --scope project \
  -e 'STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}' \
  -- npx -y @stripe/mcp@0.3.3

Serwer MCP Stripe może przesuwać pieniądze

Lokalny serwer udostępnia te narzędzia, na które pozwala klucz. Wyeksportuj ograniczony klucz trybu testowego (rk_test_…) z uprawnieniami potrzebnymi tylko do zadania. Nigdy nie dawaj sesji agenta produkcyjnego klucza tajnego: zmyślony zwrot czy zmiana ceny staje się wtedy prawdziwa.

Który model? Zostań przy domyślnym modelu Claude Code, czyli Claude Opus 5.5 na kanale latest, który działa z wysiłkiem medium. Zanim zmienisz model, podnieś wysiłek poleceniem /effort high. Kanał stable 26 września 2026 r. miał jeszcze starsze ustawienia domyślne, więc jeśli korzystasz z kanału stable (cask Homebrew claude-code, npm stable albo autoUpdatesChannel: "stable"), sprawdź model poleceniem /model. Claude Fable 5.1 (/model fable) wybieraj świadomie, tylko do długiego przepisywania wielu integracji, którego według twoich własnych prób Opus 5.5 nie kończy. Ceny i ustawienia domyślne dla planów są w zestawieniu modeli.

Napisz macierz zdarzeń przed pierwszym handlerem

Większość błędów integracji to błędy stanu, a nie HTTP: zdarzenie przetworzone dwa razy, zdarzenie, które przychodzi przed wierszem, który ma zaktualizować, ponowienie wysyłające drugi e-mail. Lekarstwem jest kontrakt, który wymienia każde przychodzące zdarzenie, jego klucz idempotentności, dozwolone przejście stanu i skutki uboczne. Człowiek przegląda tę tabelę, a nie 800 linii, które ją implementują.

docs/integrations/stripe.md

| Event                          | Idempotency key | Allowed transition          | Side effects                  | Retry on failure? |
|--------------------------------|-----------------|-----------------------------|-------------------------------|-------------------|
| checkout.session.completed     | event.id        | order pending -> paid       | grant entitlement, receipt    | yes (5xx, network)|
| invoice.payment_failed         | event.id (email: invoice.id) | subscription active -> past_due | dunning email (once per invoice) | yes |
| customer.subscription.deleted  | event.id        | any -> cancelled            | revoke entitlement            | yes               |
| charge.refunded                | event.id        | paid -> refunded            | revoke entitlement, notify    | yes               |
| anything else                  | —               | none                        | log and return 200            | no                |

Dodaj dwie linie do CLAUDE.md, żeby każda sesja trzymała się kontraktu: „Integration contracts live in docs/integrations/. Change the table first, in its own commit, and never add a handler for an event that is not in it.” Zobacz, jak Claude Code wczytuje pliki pamięci.

Zbuduj integrację płatności Stripe krok po kroku

1. Przygotuj macierz zdarzeń w trybie planowania.

   Uruchom claude --permission-mode plan albo wpisz /plan w działającej sesji. Claude Code czyta kod i proponuje zmiany, ale niczego nie edytuje.

   Prompt do skopiowania: szkic kontraktu integracji

   Read CLAUDE.md, src/routes/, src/db/schema.ts and package.json. We are adding
   Stripe Checkout for one-time and subscription purchases. Use the Stripe
   plugin's skills for current API guidance, not your memory.
   
   Produce docs/integrations/stripe.md containing:
   1. The event matrix: every Stripe event we must handle, its idempotency key,
      the allowed state transition on our orders/subscriptions tables, its side
      effects, and whether a failure is retried.
   2. The Stripe API version to pin and the SDK version in package.json.
   3. The environment variables needed, with no values.
   4. Open questions you had to guess at.
   Do not write handler code.

   Przejrzyj tabelę, odpowiedz na otwarte pytania i zatwierdź ją w osobnym commicie.

2. Zaimplementuj jeden wycinek, zaczynając od testów.

   Wyjdź z trybu planowania klawiszami Shift+Tab. Testy podpisują zdarzenia helperem samego Stripe, więc dowodzą obsługi podpisu, zamiast ją zamockować.

   Prompt do skopiowania: Stripe Checkout i webhooki, najpierw testy

   Implement docs/integrations/stripe.md for our Express + TypeScript API.
   
   1. First write tests in tests/integrations/stripe.test.ts using Vitest and
      supertest. Build signed payloads with
      stripe.webhooks.generateTestHeaderString against a test secret. Cover:
      valid signature -> 200; missing or tampered signature -> 400 with no DB
      write; the same event delivered twice -> exactly one side effect;
      invoice.payment_failed before checkout.session.completed -> no crash and
      a correct final state; an unknown event type -> 200 and a log line;
      a handler that throws -> 500 so Stripe retries.
      Run them and show me they fail.
   2. Then implement: POST /api/checkout creating a Checkout Session with our
      internal orderId in metadata; POST /api/webhooks/stripe mounted with
      express.raw({ type: 'application/json' }) BEFORE express.json();
      a webhook_events table (event_id primary key, type, status, received_at)
      that makes processing idempotent; Stripe logic in src/services/stripe.ts.
   3. Classify errors as Stripe API errors, network errors, or our own errors;
      only the first two are retried.
   4. Run the tests until they pass. Do not edit a test to make it pass.
      Finish with the changed files and the test output.

3. Odtwórz prawdziwe zdarzenia na działającej aplikacji.

   Testy jednostkowe dowodzą logiki, Stripe CLI dowodzi połączeń. W jednym terminalu:

   stripe listen --forward-to http://localhost:3000/api/webhooks/stripe

   stripe listen wypisuje przy starcie sekret podpisywania webhooków (whsec_…). Wpisz go do lokalnego .env jako STRIPE_WEBHOOK_SECRET, zrestartuj aplikację, a potem w drugim terminalu:

   stripe trigger checkout.session.completed
   stripe trigger invoice.payment_failed

   Każde wywołanie powinno pojawić się w wyjściu stripe listen ze statusem 200 i dokładnie raz w tabeli webhook_events.

4. Domknij przypadki brzegowe, które wymienia macierz.

   The happy path passes. Now handle: 1) the webhook arrives before the
   Checkout redirect returns, so the order row may still be pending;
   2) a failed subscription payment sends a dunning email through our
   email service at most once per invoice; 3) a refund updates the order
   and revokes the entitlement. Add a failing test for each case first.

Dodaj e-maile transakcyjne przez Resend

E-mail wygląda banalnie, dopóki ponowienie nie wyśle dwóch linków do resetu hasła albo pętla odbić nie spowoduje dławienia twojej domeny. Poproś wprost o zachowanie w razie błędów i trzymaj pocztę z developmentu z dala od prawdziwych skrzynek.

Prompt do skopiowania: usługa e-maili transakcyjnych

Create src/services/email.ts using the resend SDK. Use the Resend plugin's
skills for the current API. Include:
1. A typed sendEmail({ to, template, data, idempotencyKey }) function.
2. React Email templates in emails/ for welcome, password-reset,
   order-confirmation and payment-failed.
3. A send queue that retries 429 and 5xx responses up to 3 times with
   exponential backoff and jitter, and never retries 4xx validation errors.
4. An idempotency key per business event (for example "dunning:<invoiceId>")
   so a retried webhook never sends the same email twice.
5. A development mode that writes rendered HTML to .tmp/emails/ instead of
   sending when NODE_ENV is not production.
RESEND_API_KEY comes from the environment. Write the tests first: a 429 is
retried, a 422 is not, and the same idempotency key sends once.

Nie wpisuj z pamięci limitu żądań na sekundę. Odczytaj aktualny limit swojego konta w panelu Resend i zapisz go w docs/integrations/resend.md, żeby agent korzystał z udokumentowanej liczby.

Dodaj logowanie OAuth 2.0 przez Google i GitHub

Błędy w OAuth to błędy bezpieczeństwa, więc prompt nazywa zabezpieczenia, a nie tylko przepływ. Liczą się dwie rzeczy: weryfikuj state przy każdym callbacku i używaj przepływu authorization code z PKCE dla klientów mobilnych i SPA. Nigdy nie zwracaj tokenów we fragmencie URL: to stary przepływ implicit, przed którym przestrzega OAuth 2.0 Security Best Current Practice (RFC 9700).

Prompt do skopiowania: logowanie OAuth 2.0 z PKCE

Add Google and GitHub login to our Express app. If package.json already has
an auth library, use it; otherwise implement the flows directly.
For each provider:
1. Authorization URL with minimal scopes (openid email profile for Google,
   read:user user:email for GitHub), a random state bound to the session,
   and PKCE (S256).
2. A callback that rejects a missing or mismatched state with 400, exchanges
   the code, and fetches the verified primary email (GitHub may hide it on
   /user; use /user/emails).
3. Create or link the account by verified email. If the email already exists
   under another provider, do not auto-link: ask the user to sign in with the
   original provider first.
4. Handle access_denied and token-exchange failures with a redirect to
   /login?error=<code>, never a 500.
5. Issue our own session cookie (HttpOnly, Secure, SameSite=Lax).
Client IDs and secrets come from environment variables. Write tests for:
bad state, denied consent, unverified email, and the existing-email case.

Kieruj webhooki wszystkich dostawców do jednej skrzynki

Gdy odbierasz webhooki od trzech dostawców, daj im jeden potok: weryfikacja, zapis, deduplikacja, przetwarzanie, kolejka martwych komunikatów (dead-letter queue, DLQ). Nowa integracja dodaje wtedy weryfikator i handler, a nie nowy zestaw sposobów na awarię.

Prompt do skopiowania: wspólna skrzynka webhooków

Refactor our webhook handling into src/webhooks/:
1. One route per provider (/api/webhooks/stripe, /api/webhooks/github),
   each mounted with a raw-body parser.
2. A verifier per provider: Stripe via the SDK's constructEvent and the
   Stripe-Signature header; GitHub via HMAC-SHA256 of the raw body against
   X-Hub-Signature-256 with a constant-time comparison.
3. An inbox table (provider, event_id, type, payload, status, attempts,
   last_error, received_at) with a unique (provider, event_id) constraint.
4. Respond 2xx as soon as the event is stored; process it asynchronously.
5. After 3 failed attempts, mark it dead_lettered and log provider, event_id
   and last_error.
6. A read-only admin endpoint listing the last 100 events and their status.
Keep every existing test green and add one duplicate-delivery test per provider.

Kierunek odwrotny, czyli wysyłanie podpisanych webhooków do własnych klientów, opisuje strona budowanie API REST i GraphQL w Claude Code.

SDK dostawcy czy klient wygenerowany przez Claude Code?

Sytuacja	Wybierz	Dlaczego
Dostawca utrzymuje oficjalne SDK (Stripe, Resend)	SDK	Ma weryfikację podpisów, ponowienia i przypinanie wersji API, które wygenerowany klient musiałby wymyślać od nowa
Brak oficjalnego SDK dla twojego języka lub runtime’u albo SDK nie działa na twoim runtime brzegowym	Wygenerowany typowany klient na fetch	Małe, widoczne wywołania HTTP; poproś o typowane błędy niosące kod błędu dostawcy
Wołasz dwa lub trzy endpointy dużego API	Wygenerowany klient tylko dla tych endpointów	Unikasz ciężkiej zależności dla wąskiego zastosowania
Weryfikacja wrażliwa na bezpieczeństwo (podpisy webhooków, walidacja JWT)	Nigdy ręcznie pisana, jeśli SDK lub sprawdzona biblioteka to oferuje	Porównanie w stałym czasie i tolerancję przesunięcia zegara łatwo zepsuć w subtelny sposób

Jak udowodnić, że integracja działa, bez czytania każdej linii?

Przeglądaj macierz zdarzeń i testy, a kod niech sprawdzają bramki. Integracja gotowa do merge’a przechodzi wszystkie poniższe:

1. Podpisane testy na fiksturach dla każdego wiersza macierzy: poprawny, brakujący i zmieniony podpis; podwójne doręczenie; doręczenie w złej kolejności; handler rzucający wyjątek zwraca 5xx. Testy podpisują payloady helperem dostawcy, więc zamockowany weryfikator je oblewa.
2. Odtworzenie na żywo poleceniem stripe trigger dla każdego obsługiwanego zdarzenia, sprawdzone w wyjściu stripe listen i w tabeli skrzynki.
3. Hook Stop, który uruchamia zestaw testów integracji i nie pozwala sesji zakończyć się na czerwono (konfiguracja jest pod listą).
4. /code-review i /security-review w sesji, zanim otworzysz pull request. Oba są wbudowane w Claude Code: pierwsze przegląda diff pod kątem poprawności, drugie robi przegląd tych samych zmian pod kątem bezpieczeństwa.
5. Sygnały z produkcji: każde przetworzone zdarzenie loguje dostawcę, ID zdarzenia i wynik, a alert odpala się, gdy liczba zdarzeń w kolejce DLQ jest większa od zera. Zobacz monitoring z Claude Code.

Hook Stop zamienia zdanie „integracja działa” w twierdzenie poparte przebiegiem testów. Zapisz skrypt, nadaj mu prawo wykonania (chmod +x) i zarejestruj go w .claude/settings.json:

#!/usr/bin/env bash
# .claude/hooks/integration-tests.sh (Stop)
set -uo pipefail
input=$(cat)
if out=$(npm test --silent -- tests/integrations </dev/null 2>&1); then exit 0; fi
if [[ $(jq -r '.stop_hook_active' <<<"$input") == "true" ]]; then
  jq -nc '{systemMessage: "Integration tests still fail after one retry. Stopping for a human."}'
  exit 0
fi
jq -nc --arg r "Integration tests fail. Fix them before you finish. Last 40 lines:
$(tail -n 40 <<<"$out")" '{decision: "block", reason: $r}'

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/integration-tests.sh", "args": [], "timeout": 300 }] }
    ]
  }
}

Hook blokuje pierwsze zakończenie przy czerwonych testach, a jeśli ponowna próba też się nie uda, oddaje sprawę tobie. Kody wyjścia, flagę stop_hook_active i wersję pomijającą czyste drzewo robocze opisuje strona hooki Claude Code. Dlaczego bramki testowe zastępują czytanie kodu linijka po linijce, wyjaśnia strona dowody zamiast czytania kodu.

Kto zatwierdza: programista odpowiada za testy i odtworzenie zdarzeń, tech lead zatwierdza macierz zdarzeń i alert kolejki DLQ. Człowiek czyta linijka po linijce tylko weryfikację podpisów i wszystko, co przesuwa pieniądze.

Prompt do skopiowania: audyt testów integracji

Act as a reviewer for our Stripe integration. Compare docs/integrations/stripe.md
with tests/integrations/. For every row of the event matrix, list which test
proves the idempotency key, the allowed transition, the side effects and the
retry behaviour. For each row or column with no test, write the missing test,
run it, and report whether it passes. Then temporarily make the signature
verifier always return true, run the suite, confirm at least one test fails,
and restore the verifier. Do not change application code otherwise.

Kiedy integracje z zewnętrznymi usługami się psują

Weryfikacja podpisu przechodzi lokalnie, a na produkcji zawodzi. Parser ciała żądania albo proxy zmienił surowe bajty, zanim zobaczył je weryfikator. Naprawa: „Mount the webhook route with express.raw before express.json, and add a test that sends a pretty-printed copy of a signed payload and expects 400.” Potem sprawdź, czy load balancer nie przepisuje ciał żądań.

Agent napisał kod pod nieaktualne API. Nazwy parametrów lub kształt zdarzeń nie zgadzają się z tym, co wysyła dostawca. Naprawa: zainstaluj wtyczkę dostawcy lub Context7, przypnij wersję API w docs/integrations/ i poproś: „Compare src/services/stripe.ts with the current Stripe API version using the plugin’s skills and list every call that changed.” Aktualizacje wersji obsługuje skill upgrade-stripe.

Testy przechodzą, bo weryfikację zamockowano. Wygenerowany test podmienia constructEvent tak, że zwraca payload, więc zestaw jest zielony dla każdego podpisu. Naprawa: uruchom powyższy prompt audytowy; wyłapuje to krok „weryfikator zawsze zwraca true”.

Zdarzenia przychodzą w złej kolejności. invoice.payment_failed dociera przed checkout.session.completed. Naprawa: „Make every handler check the current state and apply only the transitions the event matrix allows; add a test per out-of-order pair.”

Jeden webhook dał dwa e-maile albo dwa nadania uprawnień. Idempotentność oparto na czymś innym niż ID zdarzenia albo skutek uboczny wykonał się, zanim zapis do skrzynki został zatwierdzony. Naprawa: „Write the inbox row and the side effect in one transaction, or make the side effect idempotent with its own key; add a duplicate-delivery test that fails today.”

Zadanie wsadowe trafia w limit żądań dostawcy. Naprawa: „Add a concurrency limiter to the client using the rate documented in docs/integrations/, retry 429 with backoff that honours Retry-After, and add a test with a mocked 429.”

Agent użył produkcyjnego klucza przez MCP. Naprawa: natychmiast unieważnij klucz w panelu dostawcy, przejrzyj dziennik zdarzeń dostawcy pod kątem wykonanych akcji i przełącz sesję na ograniczony klucz trybu testowego. Zobacz bezpieczeństwo MCP.

Dokąd dalej z integracjami

Wymaganie wstępne: konfiguracja MCP w Claude Code. Następny krok: testowanie z Claude Code przenosi podejście z podpisanymi fiksturami na resztę zestawu testów.

Bezpieczeństwo MCP Ogranicz klucze i narzędzia, zanim serwer MCP zacznie działać na żywym koncie

Budowanie API REST i GraphQL API projektowane od kontraktu, w tym podpisane webhooki wysyłane do innych

Hooki Claude Code Hook Stop, który pilnuje, żeby zestaw testów integracji był zielony

Audyt bezpieczeństwa Sprawdź obsługę sekretów i walidację danych we wszystkich integracjach