contrato-api

/dc:contrato-api

Objetivo

Diseñar contratos de API completos (REST o GraphQL), definir webhooks, planificar manejo de errores y reintentos para asegurar la resiliencia de integraciones con plataformas externas.

Uso

/dc:contrato-api <descripción de la integración>
/dc:contrato-api --tipo rest "Integración con Stripe para pagos"
/dc:contrato-api --tipo graphql "API de catálogo de productos"
/dc:contrato-api --tipo webhook "Recibir eventos de Shopify"

Diferencia con /dc:planificar-tecnico

Aspecto	planificar-tecnico	contrato-api
Alcance	Blueprint completo de una feature	Solo el contrato de API/integración
Profundidad	Contrato básico (request/response)	Contrato completo (errores, reintentos, webhooks, idempotencia)
Cuándo	Después de spec	Cuando la integración es el foco principal

Output para API REST

## Contrato API: Integración de Pagos con Stripe

### Endpoints

#### POST /api/v1/pagos
**Propósito:** Crear un cobro
**Auth:** Bearer token (JWT)
**Rate limit:** 100 req/min por usuario
**Idempotencia:** Sí (header `Idempotency-Key`)

**Request:**
```json
{
  "monto": 5000,          // centavos, min: 100, max: 99999900
  "moneda": "USD",        // ISO 4217
  "cliente_id": "uuid",
  "metodo_pago_id": "pm_xxx",
  "descripcion": "Pedido #1234",
  "metadata": {}          // opcional, max 50 keys
}

Responses:

Status	Significado	Body
201	Cobro creado	{ id, status, monto, stripe_id, created_at }
400	Datos inválidos	{ error, field, message }
402	Pago rechazado	{ error, decline_code, message }
409	Idempotency conflict	{ error, original_id }
429	Rate limit	{ error, retry_after }
500	Error interno	{ error, request_id }

Headers de respuesta:

X-Request-Id: uuid          // Para soporte/debugging
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1616544000

Webhooks (recibir desde Stripe)

POST /api/v1/webhooks/stripe

Verificación: HMAC-SHA256 con Stripe-Signature header Tolerancia de timestamp: 300 segundos (5 min) Respuesta esperada: 200 OK (body vacío) en < 5s

Eventos soportados:

Evento	Acción	Idempotente
payment_intent.succeeded	Marcar pedido como pagado	Sí
payment_intent.payment_failed	Notificar al usuario	Sí
charge.refunded	Procesar reembolso	Sí
charge.dispute.created	Alertar al equipo	Sí

Procesamiento:

1. Verificar firma HMAC
2. Parsear evento
3. Verificar idempotencia (event.id en tabla processed_events)
4. Responder 200 INMEDIATAMENTE
5. Procesar en cola async (no bloquear respuesta)
6. Registrar en audit log

Manejo de Errores

Errores del cliente (4xx):

{
  "error": {
    "tipo": "validation_error",
    "mensaje": "El monto debe ser mayor a $1.00",
    "campo": "monto",
    "codigo": "MONTO_INVALIDO"
  }
}

Errores del servidor (5xx):

{
  "error": {
    "tipo": "internal_error",
    "mensaje": "Error procesando el pago",
    "request_id": "req_abc123"
  }
}

Códigos de error consistentes:

Código	Significado	HTTP
MONTO_INVALIDO	Monto fuera de rango	400
MONEDA_NO_SOPORTADA	Moneda no en whitelist	400
PAGO_RECHAZADO	Tarjeta rechazada	402
DUPLICADO	Idempotency conflict	409
RATE_LIMIT	Demasiadas requests	429
STRIPE_ERROR	Error de comunicación con Stripe	502

Política de Reintentos

Estrategia: Exponential backoff con jitter