AIO APEX
Claude Sonnet 4.6 or GPT-5A backend developer is wiring up a new payment provider integration before a Monday demo. She has the API docs open but needs to make sure she is not missing the error handling edge cases or webhook verification details that will cause production incidents later.Developer Tools

مشخصات یکپارچه‌سازی API: هر API شخص ثالث را به یک طرح پیاده‌سازی آماده برای تولید تبدیل کنید

اشتراک‌گذاری:
مشخصات یکپارچه‌سازی API: هر API شخص ثالث را به یک طرح پیاده‌سازی آماده برای تولید تبدیل کنید

Why this prompt matters

Most API integration failures are not caused by calling the wrong endpoint — they happen because of unhandled error codes, missing retry logic, incorrect webhook signature verification, or silent rate-limit failures discovered only in production. A post-incident analysis of these bugs costs 10-50x more than preventing them. This prompt surfaces the integration gotchas upfront — the knowledge that normally requires either a painful incident or a colleague who has already burned their hand on this specific API.

What we use it for

A backend developer is wiring up a new payment provider integration before a Monday demo. She has the API docs open but needs to make sure she is not missing the error handling edge cases or webhook verification details that will cause production incidents later.

Prompt

Act as a senior software engineer with extensive experience integrating third-party APIs into production systems. You specialize in identifying edge cases, failure modes, and the "gotchas" that developers only discover after a painful production incident.

API to integrate: [API NAME, e.g., Stripe Payments, Twilio SMS, Salesforce, SendGrid]
My application: [DESCRIBE YOUR APP IN 1-2 SENTENCES]
What I need to do: [DESCRIBE THE SPECIFIC FUNCTIONALITY, e.g., "Process one-time payments and store customer payment methods for recurring billing"]
Tech stack: [LANGUAGE/FRAMEWORK, e.g., Node.js + Express, Python + Django, Go + Gin]
Known constraints: [ANY KNOWN LIMITS, e.g., "We are on the free tier", "Must be GDPR compliant", or "none"]

Generate a complete API integration spec with the following sections:

1. AUTHENTICATION SETUP
   - How authentication works for this API (API keys, OAuth 2.0, JWT, mTLS, etc.)
   - Where and how to store credentials securely in [TECH STACK]
   - Token refresh logic if required, including expiry handling

2. CORE IMPLEMENTATION PLAN
   - The exact sequence of API calls needed to fulfill [WHAT I NEED TO DO]
   - Required vs. optional parameters for each call
   - The shape of the request payload and what a successful response looks like
   - Any stateful dependencies between calls (e.g., must create customer before charging)

3. ERROR HANDLING MAP
   - The most common error codes this API returns and their root causes
   - Which errors are safe to retry vs. which are fatal and require user action
   - Recommended retry strategy: backoff timing, max attempts, jitter
   - How to surface errors to the user vs. handle silently

4. RATE LIMITS & QUOTAS
   - Request limits per second, minute, and day
   - How to detect when you are approaching limits (headers, error codes)
   - Recommended approach for high-volume usage (queuing, batching, caching)

5. WEBHOOKS & ASYNC EVENTS (if applicable)
   - What events this API delivers via webhook and their payload structure
   - How to verify webhook signatures to prevent spoofing
   - Idempotency: how to handle duplicate webhook deliveries safely

6. PRE-LAUNCH TESTING CHECKLIST
   - How to test this integration in sandbox or test mode without real data
   - The 5 most critical edge cases to validate before going to production
   - What metrics to monitor after launch (latency p95, error rate, success rate)

Constraints:
- Be specific to [API NAME]. Use real endpoint names, real error codes, and real response field names where known.
- Explicitly flag anything that commonly trips up developers integrating this API for the first time.
- If there are known quirks, undocumented behaviors, or common pitfalls with this API, mention them explicitly.

Result

API Integration Spec: Stripe Payments API
Application: SaaS subscription platform (Node.js + Express)
Goal: Process one-time payments and store payment methods for monthly recurring billing

1. Authentication Setup

  • Stripe uses separate secret and publishable API keys. Secret key (sk_live_...) stays server-side only — never exposed to the browser. Publishable key (pk_live_...) is safe for the frontend.
  • Store STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in environment variables, never in source code. In Node.js: process.env.STRIPE_SECRET_KEY.
  • No token refresh needed — Stripe API keys do not expire. Rotate them via the Stripe Dashboard if compromised.

2. Core Implementation Plan

  • Step 1 — Create a Customer: POST /v1/customers with email and metadata. Store the returned customer.id in your database. This must happen before charging.
  • Step 2 — Collect payment method securely: Use Stripe.js on the frontend to tokenize card details. Your server never sees raw card numbers. The frontend returns a paymentMethod.id.
  • Step 3 — Create a PaymentIntent: POST /v1/payment_intents with amount (in cents), currency, customer, and payment_method. Set confirm: true to charge immediately.
  • Step 4 — Attach payment method for recurring billing: After first successful payment, call POST /v1/payment_methods/:id/attach with customer ID. Set as default: POST /v1/customers/:id with invoice_settings.default_payment_method.

3. Error Handling Map

  • card_declined — Card issuer rejected. Fatal; show user a human-readable message. Do NOT retry.
  • insufficient_funds — Fatal for this attempt. Prompt user to use a different card.
  • rate_limit (HTTP 429) — Safe to retry with exponential backoff: 1s, 2s, 4s, max 3 attempts.
  • idempotency_key_in_use — You sent the same idempotency key for a different request body. Use a new UUID.
  • Network timeout — Always use idempotency keys on POST requests so retries are safe. Check PaymentIntent status before retrying to avoid double charges.

4. Rate Limits

  • Default: 100 read requests/second, 100 write requests/second per account.
  • Approaching limits: Stripe returns X-RateLimit-Remaining and X-RateLimit-Reset headers. Watch for HTTP 429.
  • For high volume: use idempotency keys and consider Stripe's batch API for bulk operations.

5. Webhooks

  • Critical events to handle: payment_intent.succeeded, payment_intent.payment_failed, invoice.payment_failed (for subscriptions), customer.subscription.deleted.
  • Always verify the webhook signature: stripe.webhooks.constructEvent(payload, sig, process.env.STRIPE_WEBHOOK_SECRET). Reject any webhook that fails verification — forged webhooks are a real attack vector.
  • Make all webhook handlers idempotent. Stripe may deliver the same event twice. Use the event id to deduplicate.

6. Pre-Launch Testing Checklist

  • Use test card 4242 4242 4242 4242 for successful charges; 4000 0000 0000 9995 to simulate insufficient funds.
  • Test cases: successful charge → subscription creation → card decline → webhook delivery → duplicate webhook (send same event twice via Stripe Dashboard).
  • Monitor in production: payment success rate (alert if drops below 95%), PaymentIntent creation latency p95, webhook processing latency, and payment_intent.payment_failed rate by failure reason.

First-time Stripe gotcha: If you confirm a PaymentIntent server-side and the charge requires 3D Secure authentication, you will get a requires_action status instead of succeeded. Your frontend must handle this with stripe.handleNextAction(). Most developers hit this only when testing with European test cards.

یکپارچه‌سازی یک API شخص ثالث به‌ندرت از همان ابتدا دردسرساز می‌شود. مشکل اصلی آن چیزی است که بعدتر گریبانتان را می‌گیرد: پاسخ rate limit‌ای که فراموش کرده‌اید مدیریتش کنید، تأیید امضای webhook که از آن چشم‌پوشی کرده‌اید، یا حالت مرزی‌ای که یک تایم‌اوت شبکه شما را در بلاتکلیفی رها می‌کند که آیا پرداخت نهایی شده یا نه. باگ‌هایی که به حوادث پروداکشن ختم می‌شوند تقریباً هرگز از جنس «اندپوینت اشتباهی را صدا زدم» نیستند — بلکه «از وجود این کد خطای خاص بی‌خبر بودم» یا «فرض کردم webhook دقیقاً یک‌بار تحویل داده می‌شود».

این پرامپت پیش از نوشتن حتی یک خط کد، یک مشخصات کامل یکپارچه‌سازی برایتان می‌سازد. کدهای خطا، منطق retry، و نکات پنهان webhook را روشن می‌کند — چیزهایی که معمولاً فقط از دل تجربه تلخ یا جلسات پست‌مورتم یاد می‌گیرید.

خروجی این پرامپت چیست

خروجی یک مشخصات یکپارچه‌سازی ساختاریافته در شش بخش است: تنظیمات احراز هویت، ترتیب دقیق فراخوانی‌های API برای use case شما، نقشه مدیریت خطا به تفکیک کد خطا، جزئیات rate limit، تأیید امضای webhook، و یک چک‌لیست پیش از راه‌اندازی شامل پنج حالت مرزی که بیشترین احتمال ایجاد حوادث پروداکشن را دارند.

محدودیت کلیدی تعبیه‌شده در پرامپت، جزئی‌نگری است: این پرامپت صریحاً به نام اندپوینت‌های واقعی، کدهای خطای واقعی، و نام فیلدهای واقعی پاسخ نیاز دارد — نه توصیه‌های کلی یکپارچه‌سازی API. برای API‌های پرکاربردی مثل Stripe، Twilio، Salesforce، SendGrid، Slack، و GitHub، مدل‌های فعلی داده‌های آموزشی کافی برای تولید خروجی واقعاً مفید و API-specific دارند. برای API‌های کمتر رایج، توضیح مکانیزم احراز هویت و چند اندپوینت کلیدی را paste کنید تا مدل بقیه را از روی context کامل کند.

چه زمانی از آن استفاده کنیم

این پرامپت را پیش از شروع هر یکپارچه‌سازی API جدیدی اجرا کنید — نه وقتی که happy path را از قبل نوشته‌اید. هدف این است که الزامات مدیریت خطا را پیش از آن‌که به جلسات دیباگ بی‌پایان تبدیل شوند، بشناسید. این پرامپت به‌ویژه برای API‌هایی با جریان‌های احراز هویت پیچیده (OAuth 2.0 با refresh token، mTLS)، API‌هایی که نتایج ناهمزمان را از طریق webhook تحویل می‌دهند، و API‌هایی با الزامات غیرشهودی idempotency ارزشمند است.

چگونه آن را سفارشی کنیم

پنج فیلد براکت‌دار بالای پرامپت همه چیز را هدایت می‌کنند. هرچه فیلد «آنچه باید انجام دهم» دقیق‌تر باشد، ترتیب فراخوانی‌ها هدفمندتر خواهد بود. اگر با یک API کمتر رایج کار می‌کنید، در بخش «محدودیت‌های شناخته‌شده» نام اندپوینت‌ها یا جزئیات احراز هویتی که از قبل می‌دانید را اضافه کنید — این کار دقت خروجی را به‌طور قابل‌توجهی بالا می‌برد.

برای تیم‌هایی که به‌طور منظم کار یکپارچه‌سازی انجام می‌دهند، خروجی را به‌عنوان یک فایل مشخصات Markdown در کنار کد یکپارچه‌سازی ذخیره کنید. این فایل هم به مستندات زنده تبدیل می‌شود، هم به یک چک‌لیست عملی برای code review.

developer toolsai-promptscodingbackendapi-integration
اشتراک‌گذاری: