Integracje z API Zewnętrznymi przez CLI

Musisz zintegrować Stripe do płatności do czwartku. Dokumentacja jest obszerna, ale rozległa — webhooks, klucze idempotentności, sesje checkout, portal klienta, rozliczenia subskrypcji, proration, obliczanie podatków. Kopiujesz przykład quickstart, uruchamiasz podstawowe obciążenie i spędzasz kolejne dwa dni obsługując przypadki brzegowe: nieudane webhooks, zduplikowane zdarzenia, wygasłe sesje, niezgodności walut. Każdy dostawca płatności, usługa email i dostawca OAuth ma tę samą historię: happy path zajmuje godzinę, gotowa produkcyjnie integracja zajmuje tydzień.

Co Wyniesiesz z Tej Lekcji

Przepływ pracy Claude Code do generowania integracji API gotowych do produkcji wraz z obsługą błędów, logiką retry i weryfikacją webhooków
Prompty copy-paste dla Stripe, Resend/SendGrid, OAuth 2.0 i przetwarzania webhooków, które produkują kod gotowy do wdrożenia, nie tylko demo
Strategię serwerów MCP, która daje Claude Code bezpośredni dostęp do dokumentacji zewnętrznych API podczas generowania

Budowanie Kompletnej Integracji Płatności

Różnica między integracją demo a produkcyjną to obsługa błędów, idempotentność i niezawodność webhooków. Claude Code generuje wszystkie trzy, gdy opiszesz pełne wymagania.

Prompt copy-paste — integracja Stripe z webhookami:

Zbuduj kompletną integrację płatności Stripe dla naszego Express API. Uwzględnij: 1) endpoint sesji checkout, który tworzy sesję Stripe Checkout z pozycjami z naszego koszyka, obsługuje zarówno rozliczenia jednorazowe jak i subskrypcyjne, oraz zawiera metadane z naszym wewnętrznym ID zamówienia, 2) handler webhooków pod /api/webhooks/stripe, który weryfikuje sygnaturę używając STRIPE_WEBHOOK_SECRET, obsługuje zdarzenia checkout.session.completed, invoice.payment_failed i customer.subscription.deleted, przechowuje tabelę webhook_events dla idempotentności (pomija zdarzenia już przetworzone), 3) obsługę błędów, która rozróżnia błędy API Stripe, błędy sieciowe i nasze własne błędy aplikacji, 4) mechanizm retry dla nieudanego przetwarzania webhooków. Użyj naszego istniejącego połączenia z bazą danych i umieść logikę Stripe w pliku services/stripe.ts.

Claude Code generuje dobrze zorganizowaną integrację, ponieważ prompt określa dokładne zdarzenia, strategię idempotentności i kategorie błędów. Bez tych szczegółów otrzymasz implementację tylko happy-path.

Po wygenerowaniu zweryfikuj obsługę webhooków lokalnie:

# Zainstaluj Stripe CLI do lokalnego testowania webhooków
stripe listen --forward-to http://localhost:3000/api/webhooks/stripe

# W innym terminalu wyzwól testowe zdarzenie
stripe trigger checkout.session.completed

Następnie poproś Claude Code o obsługę przypadków brzegowych:

Endpoint webhooków działa dla udanych płatności. Teraz obsłuż te przypadki brzegowe: 1) zduplikowana dostawa webhooka (Stripe wysyła to samo zdarzenie dwa razy), 2) webhook przybywa przed zakończeniem przekierowania sesji checkout (race condition), 3) płatność subskrypcji klienta nie powiedzie się i musimy wysłać email z przypomnieniem przez Resend, 4) zwrot jest wydawany i musimy zaktualizować status naszego zamówienia.

Integracja Usługi Email

Integracje email wyglądają prosto, dopóki nie obsłużysz szablonów, załączników, obsługi odrzuceń i limitów częstotliwości.

Prompt copy-paste — transakcyjna usługa email:

Stwórz moduł usługi email (services/email.ts) używając Resend jako dostawcy. Uwzględnij: 1) typowaną funkcję sendEmail, która przyjmuje to, subject, nazwę szablonu i zmienne szablonu, 2) szablony email przechowywane jako komponenty React Email w katalogu emails/ dla: welcome, password-reset, order-confirmation i payment-failed, 3) rate limiting (maks. 10 emaili na sekundę, aby zmieścić się w limitach Resend), 4) mechanizm kolejki, który ponawia nieudane wysyłki do 3 razy z exponential backoff, 5) tryb deweloperski, który loguje emaile do konsoli zamiast wysyłać. RESEND_API_KEY pochodzi ze zmiennej środowiskowej.

Rate limiting i logika retry to elementy odróżniające integrację produkcyjną od przykładu z tutoriala. Claude Code generuje oba, ponieważ prompt wyraźnie o nie prosi.

Integracja OAuth 2.0

OAuth to protokół, który każdy implementuje nieco inaczej. Claude Code obsługuje niuanse każdego dostawcy.

Zaimplementuj logowanie OAuth 2.0 z Google i GitHub dla naszej aplikacji Express. Dla każdego dostawcy: 1) stwórz URL autoryzacji z prawidłowymi scope (email i profile dla Google, user:email dla GitHub), 2) obsłuż route callback, który wymienia kod na tokeny, 3) pobierz profil użytkownika i email, 4) stwórz lub połącz konto użytkownika w naszej bazie danych (dopasuj po email), 5) wydaj nasz własny token sesji JWT, 6) obsłuż przypadek, gdy użytkownik odmówi dostępu, 7) obsłuż przypadek, gdy email użytkownika już istnieje z innym dostawcą auth. Przechowuj client IDs i sekrety w zmiennych środowiskowych. Obsługuj zarówno przepływ przekierowania webowego, jak i przepływ mobilny, który zwraca token we fragmencie URL.

Architektura Przetwarzania Webhooków

W miarę integrowania większej liczby usług, obsługa webhooków staje się systemem samym w sobie. Claude Code może wygenerować solidną architekturę przetwarzania webhooków.

Prompt copy-paste — system przetwarzania webhooków:

Stwórz generyczny system przetwarzania webhooków, który obsługuje webhooks ze Stripe, GitHub i naszego dostawcy płatności. Uwzględnij: 1) router, który wysyła do właściwego handlera na podstawie źródła webhooka (identyfikowanego przez ścieżkę URL lub nagłówek), 2) weryfikację sygnatury dla każdego dostawcy (Stripe używa nagłówka stripe-signature, GitHub używa x-hub-signature-256), 3) magazyn zdarzeń (tabela webhook_events), który zapisuje każdy przychodzący webhook z timestampem, źródłem, typem zdarzenia, payloadem i statusem przetwarzania, 4) idempotentne przetwarzanie (sprawdź ID zdarzenia przed obsługą), 5) dead letter queue dla zdarzeń, które nie powiodły się po 3 próbach, 6) endpoint administracyjny, który wyświetla ostatnie zdarzenia webhooków z ich statusem do debugowania.

Ten system rośnie wraz z tobą. Gdy dodajesz nową integrację, po prostu dodajesz nowy handler i weryfikator sygnatury do istniejącego frameworku.

Używanie Serwerów MCP dla Kontekstu API

Serwery MCP (Model Context Protocol) mogą dać Claude Code bezpośredni dostęp do dokumentacji zewnętrznych API, czyniąc integracje bardziej dokładnymi.

# Dodaj oficjalny serwer MCP Stripe
claude mcp add stripe -- npx -y @stripe/mcp

# Teraz Claude Code może odwoływać się do aktualnej dokumentacji API Stripe podczas generowania kodu

Z skonfigurowanym MCP twoje prompty mogą być mniej szczegółowe, ponieważ Claude Code może wyszukać prawidłowe ścieżki endpointów, nazwy parametrów i formaty odpowiedzi:

Używając dokumentacji API Stripe, stwórz endpoint, który pozwala klientom zaktualizować plan ich subskrypcji. Obsłuż proration automatycznie i wyślij email z potwierdzeniem z nową kwotą rozliczenia.

Generowanie Wrapperów Klienta API

Zamiast używać zewnętrznych SDK (które dodają rozmiar bundla i coupling wersji), Claude Code może wygenerować typowane klienty API.

Wygeneruj typowanego klienta HTTP dla SendGrid v3 API. Obejmij te endpointy: wyślij email, stwórz listę kontaktów, dodaj kontakty do listy, pobierz statystyki email. Użyj fetch (bez zewnętrznej biblioteki HTTP). Uwzględnij typy TypeScript dla wszystkich ciał request/response na podstawie ich dokumentacji API. Dodaj logowanie request/response na poziomie debug oraz obsługę błędów, która rzuca typowane błędy z kodem i wiadomością błędu SendGrid.

To daje ci cienkiego, typowanego klienta, którym masz pełną kontrolę — brak aktualizacji SDK do zarządzania, brak rozdęcia bundla i łatwość debugowania, ponieważ wywołania HTTP są widoczne.

Kiedy To Się Psuje

Weryfikacja sygnatury webhooka zawodzi w produkcji, ale działa lokalnie. Najczęstszą przyczyną jest load balancer lub reverse proxy, który modyfikuje ciało żądania, zanim twój handler je zobaczy. Weryfikacja sygnatury Stripe wymaga surowego ciała, nie sparsowanego ciała JSON. Zapytaj Claude Code: “Zaktualizuj endpoint webhooka, aby używał surowego ciała żądania do weryfikacji sygnatury. Nasza aplikacja Express używa express.json(), który parsuje ciało przed uruchomieniem naszego handlera.”

Callback OAuth zwraca 500 po udanej autoryzacji. Zwykle brakujący handler błędów w kroku wymiany tokena. Przekaż błąd do Claude Code: “Callback OAuth Google rzuca ten błąd po autoryzacji użytkownika. Kod autoryzacji jest prawidłowy, ale wymiana tokena nie powiedzie się. Zdebuguj problem.”

Zdarzenia webhooków przybywają w niewłaściwej kolejności. Stripe może wysłać invoice.payment_succeeded przed checkout.session.completed. Twoje handlery muszą być niezależne od kolejności. Zapytaj Claude Code: “Zrefaktoruj nasze handlery webhooków, aby były idempotentne i niezależne od kolejności. Każdy handler powinien sprawdzić aktualny stan zasobu i przetwarzać zdarzenie tylko wtedy, gdy przejście stanu jest prawidłowe.”

Limit częstotliwości API jest osiągany podczas operacji wsadowej. Podczas importowania 10 000 kontaktów do SendGrid nie możesz wysłać 10 000 żądań jednocześnie. Claude Code generuje klientów z ograniczeniem częstotliwości, ale zweryfikuj: “Dodaj limiter współbieżności do naszego klienta SendGrid, który wysyła maksymalnie 5 żądań na sekundę i kolejkuje resztę.”

Co Dalej

Audyt Bezpieczeństwa Zweryfikuj, że twoje integracje obsługują sekrety bezpiecznie i walidują wszystkie przychodzące dane

Automatyzacja Zadań Automatyzuj wielousługowe przepływy pracy, takie jak pipeline przetwarzania zamówień

Monitoring i Obserwowalność Monitoruj swoje integracje z zewnętrznymi usługami pod kątem awarii i opóźnień