Claude Code + apiCEP: validación SPEI en cualquier stack

Claude Code es la CLI de Anthropic que convierte instrucciones en lenguaje natural en código funcional directamente en tu terminal. Puede leer tu proyecto, escribir archivos, ejecutar comandos y construir features completas de forma autónoma.

Si estás usando Claude Code para construir una aplicación que recibe pagos por transferencia bancaria en México, agregar validación de comprobantes SPEI con apiCEP es una tarea que Claude Code puede implementar por ti en minutos — con el prompt correcto y el contexto adecuado.

Antes de empezar: qué necesitas

Claude Code instalado y configurado en tu terminal (npm install -g @anthropic-ai/claude-code) [web:191]
Tu API key de apiCEP — créala gratis, incluye 50 validaciones sin costo
Tu proyecto existente (Node.js, Python, Next.js, FastAPI, cualquier stack)
Un archivo .env donde guardar el API key de forma segura

Paso 1 — Documenta apiCEP en tu CLAUDE.md

El archivo CLAUDE.md es donde le explicas a Claude Code cómo funciona tu proyecto y qué herramientas tiene disponibles. [web:197][web:198] Agregar la especificación de apiCEP aquí hace que Claude Code entienda la API sin que tengas que explicarla cada vez.

Agrega esta sección a tu CLAUDE.md:

## Integración de pagos: apiCEP

Para validar comprobantes de transferencia SPEI en este proyecto usamos apiCEP.

**Endpoint:** POST https://api.apicep.cloud/validate-transfer
**Autenticación:** Bearer token via variable de entorno APICEP_API_KEY

**Request body:**
{
  \"imageUrl\": \"URL pública HTTPS del comprobante (JPEG o PNG)\",
  \"beneficiary\": {
    \"clabe\": \"CLABE de 18 dígitos de la cuenta receptora\",
    \"bank\": \"Nombre del banco receptor (ej: BBVA MEXICO)\",
    \"name\": \"Nombre del beneficiario (opcional)\"
  }
}

**Campos clave de la respuesta:**
- status: \"valid\" | \"invalid\" | \"pending\" | \"error\"
- confidence: score del OCR (0.0 a 1.0)
- validation.banxicoConfirmed: true si Banxico confirmó la transferencia
- extracted.amount: monto leído del comprobante
- downloads.cepXml, downloads.cepPdf: CEP oficial (expira en 15 días)

**Regla importante:** HTTP 200 no significa pago válido. Siempre verificar `status` y `validation.banxicoConfirmed`.

**Documentación completa:** https://www.apicep.cloud/documentacion

Paso 2 — Dale el contexto con el prompt inicial

Con el CLAUDE.md actualizado, abre Claude Code en tu proyecto y dale el contexto:

Lee el CLAUDE.md, entiende la integración de apiCEP y revisa la estructura actual del proyecto. Luego dime si ya hay alguna función de validación de pagos o si necesito crearla desde cero.

Claude Code leerá tu codebase y te dará un diagnóstico antes de escribir cualquier línea.

Paso 3 — Pídele que implemente la integración

Una vez que Claude Code conoce tu proyecto, dale la instrucción de implementación:

Para Node.js / TypeScript:

Crea una función validateSpeiPayment(imageUrl, beneficiaryClabe, beneficiaryBank) que:
1. Lea el APICEP_API_KEY del .env
2. Haga un POST a https://api.apicep.cloud/validate-transfer con imageUrl y el objeto beneficiary
3. Retorne un objeto con isValid (true si status es \"valid\" y banxicoConfirmed es true), amount extraído, y las URLs del CEP
4. Maneje errores de red y casos donde status sea \"error\" o \"pending\"
Agrega los tipos TypeScript correspondientes y un test básico.

Para Python / FastAPI:

Crea un endpoint POST /validate-payment que reciba imageUrl y clabe como body, llame a apiCEP usando el APICEP_API_KEY del .env, y retorne si el pago es válido junto con el monto y los links del CEP oficial. Maneja los casos de status \"invalid\", \"pending\" y \"error\" con respuestas HTTP apropiadas.

Para Next.js (API Route):

Crea una API Route en /api/validate-payment que reciba imageUrl y clabe por POST, llame a apiCEP desde el servidor usando APICEP_API_KEY del .env (nunca expongas el key en el frontend), y retorne el resultado de validación al cliente.

Claude Code escribirá el código, lo colocará en los archivos correctos de tu proyecto y verificará que compile. [web:205]

Ejemplo del código que Claude Code generará

Para Node.js, la implementación se verá así:

// lib/validateSpei.ts
interface SpeiValidationResult {
  isValid: boolean;
  amount: number | null;
  senderName: string | null;
  banxicoConfirmed: boolean;
  cepPdf: string | null;
  cepXml: string | null;
  rawStatus: string;
}

export async function validateSpeiPayment(
  imageUrl: string,
  clabe: string,
  bank: string,
  name?: string
): Promise<SpeiValidationResult> {
  const response = await fetch(\"https://api.apicep.cloud/validate-transfer\", {
    method: \"POST\",
    headers: {
      \"Authorization\": `Bearer ${process.env.APICEP_API_KEY}`,
      \"Content-Type\": \"application/json\",
    },
    body: JSON.stringify({
      imageUrl,
      beneficiary: { clabe, bank, name },
    }),
  });

  const data = await response.json();

  return {
    isValid: data.status === \"valid\" && data.validation?.banxicoConfirmed === true,
    amount: data.extracted?.amount ?? null,
    senderName: data.extracted?.senderName ?? null,
    banxicoConfirmed: data.validation?.banxicoConfirmed ?? false,
    cepPdf: data.downloads?.cepPdf ?? null,
    cepXml: data.downloads?.cepXml ?? null,
    rawStatus: data.status,
  };
}

Paso 4 — Pídele que agregue el manejo de casos especiales

Con el código base listo, afina el comportamiento con prompts adicionales:

Modifica validateSpeiPayment para que:
- Si el confidence del OCR es menor a 0.7, retorne un aviso de baja calidad de imagen en lugar de rechazar automáticamente
- Si status es \"pending\", reintente la validación después de 15 segundos (máximo 2 reintentos)
- Guarde cada resultado de validación en la tabla \"payment_validations\" de la base de datos con validationId, status, amount y timestamp

Claude Code implementará estos casos sin que tengas que escribir ninguna línea de código. [web:196][web:200]

Paso 5 — Guarda el API key de forma segura

Dile a Claude Code que valide el manejo de secrets:

Revisa todo el código relacionado con apiCEP y asegúrate de que APICEP_API_KEY solo se lea desde variables de entorno, nunca esté hardcodeado en el código ni aparezca en logs. Agrega APICEP_API_KEY al .env.example con un valor placeholder.

Claude Code auditará el código y corregirá cualquier exposición accidental del key. [web:197]

Casos de uso que puedes describir con lenguaje natural

Una vez que Claude Code conoce apiCEP desde tu CLAUDE.md, puedes pedirle features más complejas directamente:

"Cuando el usuario suba un comprobante en el formulario de pago, valídalo con apiCEP y si es válido actualiza el estado del pedido a 'pagado' y envía un correo de confirmación"
"Crea un endpoint webhook que reciba la URL del comprobante, lo valide con apiCEP y registre el resultado en logs para auditoría"
"Agrega un panel de administración donde se puedan ver todos los comprobantes validados, su status y el link al CEP oficial de cada uno"

Claude Code construirá cada feature completa, incluyendo la llamada a apiCEP, el manejo de errores y la actualización de la base de datos. [web:205]

Tips para mejores resultados con Claude Code + apiCEP

Usa Plan Mode (/plan) antes de implementaciones grandes — Claude Code te mostrará qué archivos va a modificar antes de hacer cualquier cambio. [web:196]
Incluye el link a la documentación en el CLAUDE.md — con https://www.apicep.cloud/documentacion disponible, Claude Code puede leerla directamente si necesita consultar un campo específico.
Pídele tests desde el inicio — Claude Code puede generar mocks de las respuestas de apiCEP para que tus tests no dependan de llamadas reales a la API en CI/CD.
Especifica el stack en cada prompt — "usando Express y Prisma" o "en FastAPI con SQLAlchemy" ayuda a Claude Code a generar código idiomático para tu proyecto.

Documentación completa de apiCEP

Todos los campos, los 82 bancos soportados, los códigos de error y los ejemplos de request/response están en apicep.cloud/documentacion. Puedes pasarle ese link directamente a Claude Code y él leerá la documentación por ti.

Planes sin contratos

| Plan | Precio | Validaciones | Vigencia |
|---|---|---|---|
| Bienvenida | Gratis | 50 | 30 días |
| Básico | $100 MXN | 200 | 30 días |
| Premium | $200 MXN | 800 | 30 días |
| Business | $400 MXN | 1,600 | 30 días |

Crea tu cuenta gratuita en apicep.cloud, copia tu API key al .env de tu proyecto y dale el primer prompt a Claude Code.