Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-situacao-integracao-api-terceiros

tpl-situacao-integracao-api-terceiros

Verified

Template do pack (situacao/09-integracao-api-terceiros.md). Orienta o agente em tarefas situacionais como debug, seguranca e refactor alinhado a esse contexto.

SITUATION: Third-Party API Integration

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: situacao/09-integracao-api-terceiros.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

CONTEXT

Use this configuration when integrating external APIs — payment gateways (Stripe, PagSeguro), communication services (SendGrid, Twilio), OAuth providers, data providers, or any external system you consume but don't control. External APIs have versioned contracts, rate limits, downtime, and breaking changes. This configuration prevents those realities from cascading into your application.

OBJECTIVES

  • Integrate external APIs through a proper abstraction layer
  • Handle every failure mode gracefully (rate limits, downtime, timeouts, 4xx/5xx)
  • Make the integration testable without calling the real API
  • Monitor for deprecation warnings and version changes
  • Ensure webhook security when receiving events from third parties

APPROACH RULES

  1. Anti-Corruption Layer (ACL) is mandatory. Never call a third-party SDK or HTTP client directly from business logic. Wrap it in an adapter class that speaks your domain language. Example: StripeClient.createCustomer() wraps Stripe's SDK — your OrderService never imports Stripe directly.

  2. Map external errors to internal errors. Stripe throws StripeCardDeclinedError. Your code throws PaymentDeclinedError. Internal code should never catch external SDK error classes.

  3. Every external call needs a timeout. Network calls without timeouts hang forever. Default timeout: 5-10 seconds. Adjust per endpoint characteristics.

  4. Idempotency keys for all mutating calls. Any POST that creates or modifies a resource must include an idempotency key. This prevents duplicate charges/orders if requests are retried.

  5. Retry with exponential backoff for transient failures. Retry on 429 (rate limit) and 5xx errors. Do not retry on 4xx (client errors — they will keep failing). Cap at 3 retries with exponential backoff + jitter.

  6. Never store raw API responses. Map them to your domain types immediately. If the third-party changes a field name, you update one place (the adapter).

  7. Webhook security is non-negotiable. Verify webhook signatures. Reject requests without a valid signature. Replay attack prevention: check event timestamp is within 5 minutes.

ROUTING TABLE

If you encounterThen
HTTP 429 Too Many RequestsImplement exponential backoff with jitter. Respect Retry-After header if present. Log throttling occurrences.
HTTP 503 / connection timeoutRetry up to 3 times. If still failing, throw ExternalServiceUnavailableError and activate fallback.
HTTP 401 UnauthorizedDo NOT retry. Token is invalid or expired. Handle token refresh flow or surface auth config error.
HTTP 400 Bad RequestDo NOT retry. A mapping/validation error on your side. Log the request body for debugging.
Webhook receivedVerify signature FIRST before any processing. Respond HTTP 200 immediately, process async.
API deprecation warning in response headersCreate a ticket immediately. Never ignore Deprecation or Sunset headers.
No OpenAPI spec availableWrite types manually from API docs. Add a note to re-check when the API version changes.
API requires OAuth flowImplement token refresh automatically. Never require user to re-auth due to expired token.
Need to test integrationUse the sandbox/test environment during development. Use recorded fixtures (VCR/nock) for unit tests.
Third party data doesn't match your schemaApply data normalization in the adapter. Never let invalid external data reach your database.

Adapter Pattern Template

// External dependency isolated here only
import Stripe from 'stripe'

// Your domain types — no Stripe types leak out
export interface CreatePaymentResult {
  paymentId: string
  status: 'succeeded' | 'requires_action' | 'failed'
  errorCode?: string
}

export class PaymentGateway {
  private stripe: Stripe

  constructor(apiKey: string) {
    this.stripe = new Stripe(apiKey, { apiVersion: '2024-06-20' })
  }

  async createPayment(
    amountCents: number,
    currency: string,
    customerId: string,
    idempotencyKey: string
  ): Promise<CreatePaymentResult> {
    try {
      const intent = await this.stripe.paymentIntents.create(
        { amount: amountCents, currency, customer: customerId },
        { idempotencyKey }
      )
      return { paymentId: intent.id, status: 'succeeded' }
    } catch (err) {
      if (err instanceof Stripe.errors.StripeCardError) {
        return { paymentId: '', status: 'failed', errorCode: err.code }
      }
      throw new ExternalServiceError('PaymentGateway', err)
    }
  }
}

Webhook Security Template

// Stripe webhook signature verification
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature']
  
  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET)
  } catch (err) {
    return res.status(400).send(`Webhook signature verification failed: ${err.message}`)
  }
  
  // Respond immediately, process asynchronously
  res.status(200).json({ received: true })
  
  // Process in background
  processWebhookEvent(event).catch(logger.error)
})

DO NOT

  • DO NOT import third-party SDK classes directly in business logic or controllers
  • DO NOT store raw third-party API responses in the database — map to your schema
  • DO NOT log full request/response bodies that may contain PAN, CVV, or auth tokens
  • DO NOT process a webhook before verifying its signature
  • DO NOT make synchronous HTTP calls in request handlers — always async/await
  • DO NOT ignore the Deprecation and Sunset headers in API responses
  • DO NOT hardcode API endpoints (they change) — use SDK or configurable base URL
  • DO NOT catch all errors and swallow them — map to domain errors and let them propagate

OUTPUT FORMAT

For each third-party integration, produce:

Integration Spec Document:

## Integration: [Service Name]

### SDK/Method
- SDK: stripe-node v14
- API Version: 2024-06-20 (pinned)
- Authentication: Secret key (env: STRIPE_SECRET_KEY)

### Adapter Class
- Location: src/infrastructure/payment/StripeGateway.ts
- Interface: src/domain/PaymentGateway.ts (interface definition)

### Operations Implemented
| Operation | Method | Idempotent? | Retry? |
|-----------|--------|-------------|--------|
| Create payment | POST /payment_intents | Yes (idempotency key) | No (card errors) |
| Refund | POST /refunds | Yes | Yes (network errors) |

### Error Mapping
| Stripe Error | Internal Error |
|-------------|----------------|
| StripeCardError | PaymentDeclinedError |
| StripeConnectionError | ExternalServiceUnavailableError |

### Testing Strategy
- Unit tests: mock PaymentGateway interface
- Integration tests: Stripe test mode with test cards
- Webhook tests: Stripe CLI `stripe trigger` command

QUALITY GATES

  • Zero direct third-party SDK imports outside the adapter layer
  • All external calls have explicit timeouts configured
  • All mutating external calls have idempotency keys
  • Error mapping table documented (external error → internal error)
  • Webhook signature verification implemented and tested
  • Retry logic implemented with exponential backoff for transient errors
  • Integration tests use sandbox/test environment (never production for tests)
  • Deprecation/Sunset header monitoring in place (log warning)
  • No secrets hardcoded — loaded from environment variables
  • Adapter has 100% unit test coverage with mocked HTTP layer
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall