Budowanie integracji API z agentem Cursora

Agent Cursora buduje produkcyjną integrację z zewnętrznym API, gdy pracuje na nieprzechodzących testach akceptacyjnych, aktualnej dokumentacji SDK i koncie testowym. Agent pisze wspólnego klienta (ponowienia, circuit breaker, klucze idempotencji), adaptery dostawców i podpisane handlery webhooków, a zamockowane testy i Stripe CLI dowodzą, że ścieżki awarii działają poprawnie.

Poprzedni programista zostawił niedokończoną integrację ze Stripe. Handler webhooków połyka błędy, wywołania SendGrid nie mają ponowień, a kod Twilio wywraca się przy pierwszym 429. Teraz płatność, e-mail z potwierdzeniem i SMS muszą działać jako jeden przepływ, a podwójne obciążenie karty albo zgubiony webhook to zgłoszenie od klienta, któremu zniknęły pieniądze.

Ta strona jest dla programistów, którzy z pomocą agenta Cursora podłączają zewnętrzne API do backendu w TypeScripcie. Przykłady korzystają z tras Next.js App Router oraz SDK dla Node: stripe (22.6.2), @sendgrid/mail (8.1.6), @sendgrid/eventwebhook (8.0.0) i twilio (6.1.2), sprawdzonych w npm 26 września 2026 roku. Funkcje Cursora wymienione na tej stronie (Plan Mode, Rules, MCP, pluginy, Bugbot) zweryfikowaliśmy w dokumentacji Cursora 28 sierpnia 2026 roku, na linii Cursor 3.x. Jeśli sama pętla pracy z czatem jest dla ciebie nowa, zacznij od strony praca z czatem agenta w Cursorze. Pracujesz z innym agentem? Zobacz integracje z zewnętrznymi API w Claude Code albo integracje w Codeksie.

Co daje ten sposób budowania integracji API

• Siedem kroków w ustalonej kolejności: od audytu do pull requesta z dowodami.
• Sześć promptów do skopiowania: audyt integracji, testy akceptacyjne, klient bazowy z adapterem Stripe, orkiestracja powiadomień, podpisane webhooki oraz raport z dowodami do pull requesta.
• Projektowy plik mcp.json, który daje agentowi aktualną dokumentację SDK (Context7) i konto Stripe w trybie testowym (Stripe MCP).
• Procedurę weryfikacji, która dowodzi działania ponowień, idempotencji i sprawdzania podpisów bez czytania każdej wygenerowanej linii.
• Sześć awarii produkcyjnych, każdą z krokiem naprawczym.

Jak agent Cursora buduje integrację, której możesz zaufać?

Kolejność znaczy więcej niż same prompty. Agent, który najpierw pisze klienta, a potem testy, tworzy testy opisujące to, co akurat zbudował. Agent, który pisze na podstawie nieaktualnej wiedzy z treningu, wywołuje wersje API i metody SDK, których już nie ma.

1. Zrób audyt tego, co istnieje. Zmapuj każdego dostawcę, każdy sekret i każdą ścieżkę awarii, zanim cokolwiek zmienisz.
2. Podłącz aktualną dokumentację i sandbox. Context7 dla dokumentacji SDK, Stripe MCP w trybie testowym dla danych testowych.
3. Napisz nieprzechodzące testy akceptacyjne. Jeden test na każde zachowanie z tabeli akceptacyjnej poniżej, każde wywołanie HTTP zamockowane.
4. Zbuduj klienta bazowego i jednego dostawcę. Najpierw Stripe, bo ma najostrzejsze reguły idempotencji i webhooków.
5. Dodaj pozostałych dostawców i orkiestrację. SendGrid i Twilio kopiują kształt adaptera Stripe.
6. Zabezpiecz webhooki. Weryfikacja podpisu na surowym body, okno ochrony przed powtórzeniem, deduplikacja po ID zdarzenia.
7. Uruchom bramki i zbierz dowody. Testy, sprawdzenie typów, linter, prawdziwy podpisany webhook ze Stripe CLI, a na końcu review.

Zrób audyt istniejących integracji, zanim cokolwiek zmienisz

Zacznij w Plan Mode, który tworzy plan przed napisaniem jakiegokolwiek kodu. Dzięki temu agent czyta i raportuje, zamiast „naprawiać” pierwszą rzecz, którą zobaczy. Dołącz katalogi z kodem integracji.

Prompt do skopiowania: audyt integracji

@src/integrations @src/services @src/app/api

Audit the third-party API integrations in this codebase. Do not edit any file.

For each provider (Stripe, SendGrid, Twilio, and any other you find), report:
1. Which operations are called, and from which files.
2. Where the API key comes from. Flag any key that is hard-coded or logged.
3. Retry behaviour: none, per-call, or shared. Which errors are retried?
4. Whether mutating calls send an idempotency key.
5. Whether each webhook route verifies the signature on the raw request body.
6. What happens when the call fails halfway through the payment -> email -> SMS flow.
7. Which of these paths have tests today.

End with a table: provider | status (production-ready / needs work / dangerous) | the one change that removes the biggest risk.

Zapisz tę tabelę w opisie pull requesta. To stan „przed” – pierwsza część twoich dowodów, a recenzent widzi z niej, które ryzyka ta zmiana ma usunąć.

Daj agentowi aktualną dokumentację SDK i sandbox

SDK płatności i komunikacji zmieniają nazwy metod, wersje API i helpery webhooków między wersjami głównymi. Dwa serwery MCP usuwają większość wynikającego z tego zgadywania:

• Context7 (@upstash/context7-mcp 4.1.1) na żądanie pobiera dokumentację dopasowaną do wersji biblioteki. Dopisz do promptu „use context7”, a agent sprawdzi SDK, zanim zacznie pisać wywołania.
• Stripe MCP (@stripe/mcp 0.3.3, zdalnie https://mcp.stripe.com z OAuth) pozwala agentowi tworzyć testowe produkty, ceny i klientów oraz przeglądać zdarzenia.

Stripe instaluj najpierw poleceniem /add-plugin stripe — to sposób instalacji w Cursorze, który podaje README Stripe. Alternatywnie dodaj zdalny serwer po adresie URL w projektowym pliku .cursor/mcp.json, obok Context7; Cursor poprosi o logowanie OAuth przy pierwszym użyciu (kształt wpisu według README Stripe, sprawdzone 2026-09-26). Żaden wpis nie zawiera poświadczeń, więc plik można bezpiecznie commitować: Context7 działa bez klucza (darmowy klucz podnosi limity), a serwer Stripe loguje cię przez OAuth.

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" },
    "stripe": { "url": "https://mcp.stripe.com" }
  }
}

Stripe MCP może przesuwać pieniądze

Podłączaj go wyłącznie do konta Stripe w trybie testowym. Jeśli uruchamiasz serwer lokalny, daj mu klucz z ograniczonymi uprawnieniami (restricted API key): to uprawnienia klucza decydują, które narzędzia serwer udostępnia. Nie łącz tego serwera w jednej sesji agenta z poświadczeniami produkcyjnymi. Szersze ryzyko prompt injection w serwerach z narzędziami opisuje strona bezpieczeństwo MCP.

Każdy podłączony serwer dokłada definicje swoich narzędzi do kontekstu agenta. Wyłącz te, których to zadanie nie potrzebuje; jak zmierzyć ten narzut, pokazuje strona ograniczanie kosztu tokenów MCP. Pełną konfigurację opisują strony konfiguracja MCP w Cursorze i przewodnik po Context7.

Napisz testy akceptacyjne, zanim powstanie klient

Tabela akceptacyjna to specyfikacja. Należy do ciebie, a agent zamienia każdy jej wiersz w test.

Zachowanie	Test, który to dowodzi
429 z Retry-After: 2 czeka co najmniej 2 sekundy, potem ponawia	Mock zwraca raz 429, potem 200; sztuczne timery sprawdzają opóźnienie
Ponowiona mutacja w Stripe używa tego samego klucza idempotencji	Mock zapisuje nagłówek Idempotency-Key przy obu próbach
Pięć nieudanych prób HTTP w ciągu 60 sekund (ponowienia się liczą) otwiera obwód; kolejne wywołania od razu kończą się błędem	Mock pięć razy zwraca 503; następne wywołanie nie wysyła żądania HTTP
Błąd e-maila lub SMS-a nigdy nie psuje checkoutu	Mock SendGrid zwraca 500; checkout kończy się sukcesem, a w bazie jest powiadomienie w kolejce
Webhook ze złym podpisem jest odrzucany	Zmienione body zwraca 400 i żaden handler się nie uruchamia
Zduplikowane doręczenie webhooka jest przetwarzane raz	To samo ID zdarzenia wysłane dwa razy; efekt uboczny występuje raz

Prompt do skopiowania: nieprzechodzące testy akceptacyjne

@src/integrations @src/services

Write failing tests for the integration layer we are about to build. Do not write any implementation.

Use vitest and msw (Mock Service Worker) to intercept every request to api.stripe.com, api.sendgrid.com and api.twilio.com. Fail the test run on any unhandled request, so no test can reach a real API.

Cover exactly these behaviours, one test each:
1. A 429 with Retry-After: 2 waits at least 2 seconds, then retries (use fake timers).
2. A retried Stripe mutation sends the same Idempotency-Key header on every attempt.
3. Five failed HTTP attempts within 60 seconds open the circuit (each retry counts as an attempt); the next call throws CircuitOpenError without an HTTP request.
4. Payment succeeds, SendGrid returns 500: checkout still resolves as paid, and a notification row with status "queued" exists.
5. A Stripe webhook with a tampered body returns 400 and no event handler runs. Build valid signatures with stripe.webhooks.generateTestHeaderString.
6. The same Stripe event ID posted twice triggers the side effect once.

Run the tests and show me the output. Every test must fail for the right reason (missing module or missing behaviour), not because of a syntax error.

Przeczytaj sześć testów, a nie cały diff. Zacommituj je osobno, żeby później móc udowodnić, że agent ich nie osłabił. Strategię mockowania opisuje szerzej strona wzorce testowania w Cursorze.

Zbuduj klienta bazowego i adapter Stripe

Gdy testy są już w repozytorium, poproś o wspólnego klienta i jednego dostawcę w tej samej turze. Klient bazowy zawiera ponowienia, circuit breaker i mapowanie błędów, więc każdy kolejny dostawca dziedziczy je automatycznie.

Prompt do skopiowania: klient bazowy i adapter Stripe

@src/integrations @src/integrations/__tests__

Make the committed tests pass. Do not modify any file under src/integrations/__tests__.

1. src/integrations/base-client.ts
   - Retries with exponential backoff and full jitter, max 4 attempts, only for network errors, 429 and 5xx.
   - Honour Retry-After when present.
   - Circuit breaker: open after 5 failures in 60 s, half-open after 30 s, allow a few probe requests, close only after 3 consecutive successes.
   - Per-provider timeout. Structured logs with API keys, card data and email bodies redacted.
2. src/integrations/errors.ts: IntegrationError (provider, code, retryable, cause) plus RateLimitError, AuthError, ValidationError, TimeoutError, CircuitOpenError.
3. src/integrations/stripe-client.ts
   - Uses the stripe npm package; read STRIPE_SECRET_KEY and the API version from environment variables.
   - createPaymentIntent, refundPayment, getPaymentStatus.
   - Every mutation passes an idempotencyKey derived from our order ID, and a retry reuses it.
   - Map Stripe errors (card declined, rate limit, connection error) to our error classes.
   use context7 to check the current stripe-node API before you write the calls.

After each file, run: npm test -- src/integrations && npx tsc --noEmit
Finish with the test output, the type-check output, and a list of any assumption you made.

Gdy Stripe przechodzi testy, powtórz prompt dla sendgrid-client.ts i twilio-client.ts z dopiskiem „follow the shape of @src/integrations/stripe-client.ts”. Żadne z tych SDK nie udostępnia opcji klucza idempotencji przy wysyłce (sprawdzone w @sendgrid/mail 8.1.6 i twilio 6.1.2), więc deduplikację e-maili i SMS-ów musi zapewnić twoja własna tabela powiadomień, którą tworzy następny krok.

Orkiestruj płatność, e-mail i SMS bez psucia checkoutu

Trudność nie leży w pojedynczym wywołaniu, tylko w decyzji, co oznacza częściowa awaria. Ten prompt koduje jedną zasadę: płatność jest źródłem prawdy, a powiadomienia wysyłamy w trybie best-effort, z ponowieniami.

Prompt do skopiowania: orkiestracja powiadomień

@src/integrations/stripe-client.ts @src/integrations/sendgrid-client.ts @src/integrations/twilio-client.ts @src/db/schema.ts

Create src/services/checkout-notifications.ts:

1. After a payment is confirmed, insert one notifications row per channel (payment_id, channel, status, attempt_count, last_error) with a UNIQUE constraint on (payment_id, channel). Write a migration for the table.
2. Send the receipt email, then the SMS. A failure marks the row "queued" with the error; it never throws to the checkout caller.
3. A retry worker picks up "queued" rows every 60 seconds with backoff, and moves a row to "dead" after 5 attempts.
4. Before sending, the worker re-reads the row and skips anything already "sent", so a crash between send and update cannot send twice from a normal retry.

Make test 4 in src/integrations/__tests__ pass and add tests for: the dead-letter transition, and two workers racing for the same row.
Run npm test and npx tsc --noEmit and show the output.

Projekt schematu bazy opisuje strona projektowanie bazy danych w Cursorze, a obsługę kolejki martwych wiadomości (dead letter) szerzej omawia przepis na wzorce odzyskiwania po awarii.

Zabezpiecz endpointy webhooków

Trasy webhooków to publiczne adresy URL. Każdy z trzech dostawców podpisuje żądania inaczej, a każdy helper potrzebuje surowego body: w trasie Next.js App Router oznacza to await request.text(), nigdy request.json(), bo ponownie zserializowany JSON nie pasuje już do podpisu.

Dostawca	Helper weryfikacji (sprawdzone 2026-09-26)	Nagłówek
Stripe	stripe.webhooks.constructEvent (Node) lub constructEventAsync (środowiska z Web Crypto); domyślna tolerancja 300 sekund	Stripe-Signature
SendGrid	new EventWebhook().verifySignature(ew.convertPublicKeyToECDSA(key), rawBody, signature, timestamp) z @sendgrid/eventwebhook; key to klucz weryfikacyjny z Mail Settings	X-Twilio-Email-Event-Webhook-Signature i -Timestamp
Twilio	twilio.validateRequest dla callbacków statusu	X-Twilio-Signature

Prompt do skopiowania: podpisane trasy webhooków

@src/integrations @src/app/api

Create src/app/api/webhooks/stripe/route.ts, src/app/api/webhooks/sendgrid/route.ts and src/app/api/webhooks/twilio/route.ts.

1. Read the body with await request.text() and verify it before parsing:
   Stripe with stripe.webhooks.constructEventAsync and STRIPE_WEBHOOK_SECRET;
   SendGrid with new EventWebhook().verifySignature from @sendgrid/eventwebhook, passing
   ew.convertPublicKeyToECDSA(SENDGRID_WEBHOOK_PUBLIC_KEY), never the raw key string;
   Twilio with twilio.validateRequest, TWILIO_AUTH_TOKEN, the full public callback URL
   (not the internal request URL) and the form-encoded params parsed from the body.
2. Reject a missing or invalid signature with 400 and log the reason without the body.
3. Reject SendGrid events whose timestamp header is older than 5 minutes.
4. In one database transaction, insert the event ID and the raw event (status "pending") into processed_webhook_events with a UNIQUE constraint on the event ID. A worker processes pending rows. On a duplicate, return 200 and do nothing else. Return 200 only after the transaction commits.
5. The payment_intent.succeeded handler looks up the order by metadata.order_id and calls checkout-notifications.
6. Handle events by type; for state changes, re-fetch the object from the API instead of trusting arrival order or payload snapshots.

Make tests 5 and 6 pass. Run npm test and npx tsc --noEmit and show the output.

Punkt 4 poprawia popularną instrukcję „zwróć 200 od razu, przetwarzaj asynchronicznie”. Jeśli proces padnie po wysłaniu 200, a przed zapisaniem zdarzenia, dostawca uznaje doręczenie za zakończone i zdarzenie przepada. Najpierw zapisz, potem potwierdź.

Wiersz deduplikacji i zapisane zdarzenie muszą trafić do bazy w tej samej transakcji (wzorzec transactional outbox). Gdyby były to dwa osobne zapisy, awaria między nimi zostawiłaby zapisane ID zdarzenia bez samego zdarzenia: ponowienie od dostawcy trafiłoby na ograniczenie UNIQUE, dostałoby 200, a zdarzenie przepadłoby bez śladu.

Jak zweryfikować integrację bez czytania każdej linii?

Sprawdzasz zachowanie i dowody, a nie wygenerowany kod. Dowód opiera się na czterech bramkach:

1. Zatwierdzone testy się nie zmieniły. Porównaj je z commitem, który je dodał, i wypisz pliki, których git jeszcze nie śledzi, na przykład nowy plik testów; jakikolwiek wynik którejkolwiek komendy oznacza, że agent zmienił specyfikację.

   git diff --stat TESTS_COMMIT -- src/integrations/__tests__/
   git status --porcelain src/integrations/__tests__/

   Zastąp TESTS_COMMIT hashem commita, który dodał testy akceptacyjne.

2. Testy, sprawdzenie typów i linter są zielone. Uruchom w terminalu te same komendy co CI, zamiast polegać na podsumowaniu agenta.

3. Prawdziwy podpisany webhook dociera do twojej trasy. Stripe CLI (npm install -g @stripe/cli lub brew install stripe) przekazuje zdarzenia z trybu testowego do serwera deweloperskiego i podpisuje je sekretem sesji, który wypisuje też stripe listen --print-secret. Wpisz ten sekret do STRIPE_WEBHOOK_SECRET w .env.local, a potem uruchom Stripe CLI w dwóch kolejnych terminalach. stripe listen działa na pierwszym planie, dopóki go nie zatrzymasz.

   Terminal 2:

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

   Terminal 3, z ID zamówienia, które dodałeś do testowej bazy danych:

   stripe trigger payment_intent.succeeded --add payment_intent:metadata.order_id=ORDER_ID

   Oczekuj 200 w wyjściu listen, jednego wiersza w processed_webhook_events i po jednym wierszu w notifications na kanał (e-mail, SMS). Nie traktuj drugiego stripe trigger jako testu duplikatu: każde uruchomienie tworzy nowy PaymentIntent z nowym ID zdarzenia, więc druga para powiadomień to poprawne zachowanie. Ponowne doręczenie zdarzenia o tym samym ID sprawdza test akceptacyjny 6.

4. Review ścieżek, które dotykają pieniędzy. Bugbot albo twój recenzent AI przegląda cały pull request; człowiek czyta tylko mutację płatności i trasę webhooka, bo tam błąd kosztuje pieniądze. Konfigurację opisuje strona Bugbot.

Poproś agenta o zebranie dowodów – wtedy recenzent nie musi robić tego sam.

Prompt do skopiowania: raport z dowodami do pull requesta

Prepare the pull request description for this integration work. Include:
1. The audit table from the start of this task, with a new column "after".
2. The output of npm test, npx tsc --noEmit and npm run lint, pasted verbatim.
3. The output of git diff --stat on src/integrations/__tests__ against the commit that added the tests, and of git status --porcelain on the same folder.
4. The list of files that move money or verify webhook signatures, so the human reviewer reads only those.
5. Every assumption you made about provider behaviour, with the doc you checked it against.
Do not summarise any command output. If a command fails, say so and stop.

Programista odpowiedzialny za integrację zatwierdza tabelę akceptacyjną; druga osoba zatwierdza pliki płatności i webhooków. Dodaj regułę projektu „never modify files under src/integrations/__tests__ unless asked”, żeby kolejne czaty przestrzegały kontraktu; jak to zrobić, pokazuje strona reguły projektu w Cursorze. Żeby wymusić tę zasadę, a nie tylko o nią prosić, hook Cursora może odrzucać edycje w tym folderze; bramka git diff opisana wyżej nadal to potwierdza.

Co psuje się, gdy integracje z zewnętrznymi API trafiają na produkcję?

Agent wywołuje metodę SDK, która już nie istnieje. Objaw: błędy typów przy wywołaniach stripe.* albo błędy w runtime po aktualizacji SDK. Naprawa: wróć do ostatniego zielonego commita, dopisz do promptu „use context7” i wersję SDK z package.json, po czym powtórz krok.

Ponowienia tworzą podwójne obciążenia. Żądanie przekracza limit czasu, choć Stripe już je przetworzył, a ponowienie obciąża kartę drugi raz. Naprawa: zwróć klientowi środki za zduplikowaną płatność w Stripe Dashboard, a potem upewnij się, że każda mutacja wyprowadza klucz idempotencji ze stabilnego identyfikatora biznesowego (ID zamówienia), nigdy z losowej wartości generowanej przy każdej próbie. Regresję wyłapie test 2.

Limity zapytań pojawiają się dopiero na produkcji. Zamockowane testy nigdy nie trafiają w prawdziwy limit. Naprawa: dodaj w kliencie bazowym token bucket per dostawca ustawiony na około 80% opublikowanego limitu, kolejkuj nadmiar i ustaw alert na częstość RateLimitError.

Zdarzenia webhooków przychodzą w złej kolejności albo dwa razy. Dostawcy nie gwarantują kolejności i ponawiają doręczenia, które uznali za nieudane. Naprawa: opieraj handlery na ID zdarzenia (już deduplikowanym przez trasy webhooków w kroku 6) i na bieżącym stanie obiektu pobranym z API, a nie na kolejności przyjścia zdarzeń.

Circuit breaker oscyluje. Przeciążony dostawca nie przechodzi jedynego żądania próbnego w stanie półotwartym, obwód znów się otwiera, a checkout działa w trybie awaryjnym przez kilka minut. Naprawa: w stanie półotwartym przepuszczaj niewielką część ruchu i zamykaj obwód dopiero po kilku kolejnych sukcesach; przejście przetestuj na sztucznych timerach.

Mocki rozjeżdżają się z prawdziwym API. Testy są zielone, a dostawca zmienił pole. Naprawa: uruchamiaj ten sam zestaw testów co noc na środowiskach testowych dostawców, poza bramką pull requesta, i głośno zgłaszaj każdą niezgodność struktury.

Kiedy serwer MCP powinien zastąpić kod integracji?

Serwery MCP to narzędzia dla agenta, a nie runtime twojej aplikacji. Używaj ich w trakcie budowania, a wszystko, co produkt robi w imieniu klienta, zostaw w kodzie.

Potrzeba	Użyj	Dlaczego
Tworzenie testowych produktów, klientów lub zdarzeń podczas pracy	Stripe MCP (tryb testowy)	Bez jednorazowych skryptów; agent przygotowuje dane testowe w tym samym czacie
Sprawdzenie aktualnej sygnatury SDK przed napisaniem wywołania	Context7	Dokumentacja dopasowana do wersji biblioteki
Zakładanie issues lub czytanie logów CI dotyczących integracji	Serwer GitHub MCP	Praca operacyjna, bez kodu produktu
Obciążenie klienta, wysłanie potwierdzenia, weryfikacja webhooka	Twój kod integracji	Potrzebujesz ponowień, idempotencji, logów i testów pod twoją kontrolą

Dokąd dalej z warstwą integracji

Wzorce testowania w Cursorze Strategia mockowania, dane testowe i pokrycie dla testów, które pilnują tej integracji.

Bezpieczeństwo w Cursorze Sprawdź integrację pod kątem wycieku kluczy, fałszowania webhooków i wstrzyknięć, zanim trafi na produkcję.

Wzorce tworzenia API Przepisy dla API, które obsługuje twoja integracja: walidacja, wersjonowanie i formaty błędów.

Mikroserwisy w Cursorze Przenieś worker powiadomień do osobnej usługi, gdy monolit stanie się za ciasny.