API e integraciones

Tiempo: unos 30 min de lectura + 25 min de práctica

Lo esencial

Una API es el idioma con el que los programas hablan entre sí. Imagina que cada servicio (Stripe, Gmail, WhatsApp, un CRM) es un país con su propio idioma. La API es, al mismo tiempo, el intérprete y el protocolo diplomático. Claude Code conoce ese idioma y habla con cualquier servicio en tu nombre.

Conceptos clave

API (Application Programming Interface, interfaz de programación de aplicaciones): una forma estandarizada de que los programas se comuniquen
REST API: el tipo más común. Una URL + un método de solicitud + datos en JSON
Claude Code crea herramientas que hacen llamadas a APIs
Integraciones = flujos de trabajo (workflows) + herramientas para servicios externos

Teoría

Qué es una API, sin tecnicismos

Cuando abres WhatsApp y ves mensajes nuevos, la app le pide los mensajes a los servidores del servicio a través de una API: "dame los mensajes del usuario X". El servidor responde con una lista de mensajes. Eso es una API en acción.

La analogía del mesero: tú estás sentado a la mesa (tu app), el mesero (la API) lleva tus pedidos a la cocina (el servidor) y te trae la comida (los datos). Tú no entras a la cocina; no necesitas saber cómo funciona por dentro.

Por qué te importa: la mayoría de las herramientas que un negocio quiere automatizar tienen API. Stripe recibe pagos a través de una API. SendGrid envía correos a través de una API. Notion guarda tareas y se consulta por API. Si un servicio tiene API, Claude Code puede trabajar con él.

REST API: cómo se arma una solicitud

🎨 Imagínalo así: una REST API es como un formulario de trámite estándar. La estructura es la misma en todos lados: a quién va dirigido, qué pides, tus datos, tu firma. No importa el banco o la oficina de gobierno: el formulario es igual. Aprendes a llenar uno y sabes llenarlos todos.

La mayoría de las APIs modernas son REST API. Una solicitud tiene:

1. URL (la dirección)

Escribe esto en el chat

https://api.stripe.com/v1/customers

Es la dirección del recurso. Como la dirección de una casa: sabes a dónde dirigirte.

2. Método de solicitud

GET: obtener datos ("dame la lista de clientes")
POST: crear algo nuevo ("crea un cliente nuevo")
PUT / PATCH: actualizar algo que ya existe ("cambia el email del cliente")
DELETE: borrar ("borra al cliente")

3. Datos en formato JSON

json

{
  "email": "[email protected]",
  "name": "Alejandro Rojas",
  "plan": "premium"
}

JSON es texto entre llaves. Legible y estructurado. Como un formulario ya llenado.

4. Encabezados (headers) Los metadatos de la solicitud: quién eres, qué formato esperas, tu token de autorización.

Claves de API: cómo funciona la autorización

🎨 Imagínalo así: una clave de API es el gafete para entrar a la fábrica. Sin él, el guardia no te deja pasar. Con el gafete de otra persona, entras como si fueras ese empleado y puedes hacer desastres a su nombre. Por eso nadie deja su gafete en la caseta de entrada.

La mayoría de las APIs piden un "gafete": la clave de API. Es una cadena larga de caracteres que te identifica como usuario autorizado.

Ejemplo: una clave de Stripe se ve como sk_live_AbCdEfGh1234... (una cadena larga de caracteres).

Regla de importancia crítica: las claves de API son como contraseñas. Nunca, bajo ninguna circunstancia, las pegues directamente en el código. Si una clave termina en GitHub, alguien con malas intenciones puede cobrar desde tu cuenta de Stripe o mandar spam desde tu SendGrid.

La forma correcta de guardarlas:

Código

# Archivo .env (local)
STRIPE_SECRET_KEY=sk_live_AbCdEfGh1234...
SENDGRID_API_KEY=SG.xyz...
TELEGRAM_BOT_TOKEN=1234567890:AbCdEf...

El archivo .env se agrega a .gitignore (no entra al repositorio). En el código se usa process.env.STRIPE_SECRET_KEY: una referencia a la variable, no la clave misma.

Claude Code suele seguir esta regla y no pega claves en el código, pero antes de cada commit revisa de todos modos los cambios y confirma que no haya claves en ellos.

Probar una API

Antes de meter una API en un flujo de trabajo, compruebas que funciona. Eso se llama "solicitud de prueba".

Con curl (en la terminal):

bash

curl -X GET "https://api.stripe.com/v1/customers?limit=3" \
  -H "Authorization: Bearer sk_test_..."

Con Postman / Insomnia: herramientas gráficas donde mandas solicitudes desde una interfaz, sin línea de comandos.

Con Claude Code: solo dices "envía una solicitud de prueba a la API de Stripe y muéstrame qué devuelve", y el agente escribe y ejecuta la solicitud.

Manejo de errores: la realidad de las integraciones

🎨 Imagínalo así: los códigos de respuesta de una API son como un semáforo. 200: verde, avanza. 401: rojo, no traes gafete. 429: amarillo, frena, vas demasiado rápido. 500: un choque en el cruce; no es tu culpa, espera.

Las APIs no siempre responden con éxito. Códigos de respuesta:

Código	Significado	Qué hacer
200	Éxito	Todo bien, procesa los datos
201	Creado	El recurso se creó correctamente
400	Solicitud incorrecta	Revisa el formato de los datos
401	No autorizado	Revisa la clave de API
403	Prohibido	No tienes permiso para esta operación
404	No encontrado	URL o ID incorrectos
429	Demasiadas solicitudes	Límite de velocidad (rate limit), espera
500	Error del servidor	El problema está del lado del servicio

Rate limiting es un límite a la cantidad de solicitudes. Cada servicio tiene el suyo, y en Stripe, por ejemplo, el límite del modo de pruebas (sandbox) es más bajo que el del modo real; las cifras cambian, así que revisa las vigentes en la documentación del servicio. Si te pasas, recibes un 429. Tu flujo de trabajo debe tomarlo en cuenta: o bajar el ritmo, o repetir la solicitud después de una pausa (cada vez más larga).

El agente conoce las formas típicas de manejar los rate limits y agrega ese manejo, pero los límites concretos compáralos con la documentación del servicio.

Integraciones reales: ejemplos

Stripe (pagos)

Qué puede hacer: recibir pagos con tarjeta, crear suscripciones, administrar clientes, enviar facturas (invoices), hacer reembolsos.

Escenario: el flujo de trabajo le manda automáticamente una factura al cliente cuando el proyecto se termina: el agente crea la factura en Stripe por API y envía el enlace de pago.

python

# El agente escribe este código por ti
import stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

invoice = stripe.Invoice.create(
    customer="cus_abc123",
    auto_advance=True,
)

Modo de prueba: Stripe da claves de prueba (sk_test_...) y un entorno de pruebas (sandbox): puedes probar pagos con tarjetas de prueba sin dinero real.

Twilio (SMS y llamadas)

Qué puede hacer: enviar SMS, hacer llamadas, WhatsApp Business API, verificación por número de teléfono.

Escenario: el flujo de trabajo vigila las solicitudes nuevas. Cuando llega una de un cliente VIP (monto > $10,000), el agente le manda un SMS al celular del responsable.

python

from twilio.rest import Client
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

message = client.messages.create(
    body="Nueva solicitud VIP: $15,000, contáctalo hoy",
    from_="+1415xxxxxxx",
    to="+52155xxxxxxx"
)

SendGrid (email)

Qué puede hacer: enviar correos transaccionales (confirmaciones, avisos), campañas de marketing, plantillas de correo, estadísticas de apertura.

Escenario: después de pagar, el cliente recibe automáticamente un correo con las instrucciones para entrar al curso: el agente lo envía por la API de SendGrid.

El patrón de integración: flujo de trabajo + herramientas

🎨 Imagínalo así: un flujo de trabajo con herramientas es como un centro de mando. El comandante (el flujo de trabajo) da órdenes: "contacta al proveedor", "manda la factura", "avisa al almacén". Cada especialista (herramienta) conoce su tarea y su contraparte. El comandante no llama él mismo: delega.

En la arquitectura WAT (Workflow + Agent + Tools: flujo de trabajo + agente + herramientas), las integraciones con APIs viven en las herramientas:

yaml

# workflows/invoice-on-completion.yaml
name: auto-invoice
description: Crea y envía una factura cuando el proyecto se marca como terminado
steps:
  - action: get_project_details
  - action: create_stripe_invoice    # API de Stripe
  - action: send_notification_email  # API de SendGrid
  - action: send_sms_to_manager      # API de Twilio
  - action: update_crm_status        # API del CRM

Cada action es una llamada a una herramienta distinta. La herramienta sabe cómo dirigirse a su API.

Cómo te ayuda Claude Code con las APIs

🎨 Imagínalo así: Claude Code con APIs es como un intérprete diplomático. Tú dices "quiero cerrar un acuerdo de suministro". El intérprete conoce el idioma del país, el protocolo y la manera correcta de dirigirse. Las negociaciones van en el idioma correcto y tú recibes el resultado en el tuyo.

Buscar documentación: "encuentra cómo crear un pago con la API de Stripe para una compra única sin guardar la tarjeta"; el agente encuentra el endpoint correcto en la documentación.

Escribir código: el agente escribe una función-herramienta para una llamada concreta a la API, con manejo de errores y uso correcto de las variables de entorno.

Depurar: si la API devuelve un error, el agente lee la respuesta, entiende la causa y lo corrige.

Actualizar: si la API cambió (versión nueva), el agente encuentra qué cambió y actualiza el código.

Práctica

Tarea: crea un endpoint de API y pruébalo

Pídele a Claude Code: "Crea un endpoint de API sencillo en Express.js que reciba una solicitud POST con los campos name y email, valide que no estén vacíos y devuelva un JSON confirmando que los datos llegaron"
El agente creará el archivo server.js. Ejecútalo: node server.js
Pruébalo con curl (el agente te ayuda con el comando):

bash

curl -X POST http://localhost:3000/subscribe \
  -H "Content-Type: application/json" \
  -d '{"name": "Alejandro", "email": "[email protected]"}'

Prueba mandar una solicitud sin email y observa cómo se maneja el error
Extra: pídele al agente que agregue una integración con un servicio real, por ejemplo "cuando llegue un email, agrégalo a la lista de Mailchimp por API" (necesitas una clave de API de Mailchimp)

Herramientas y recursos

Postman: cliente gráfico para probar APIs, gratis
Insomnia (insomnia.rest): alternativa a Postman, más ligera
OpenAPI Specification: el estándar para describir REST APIs (Swagger). Si un servicio ofrece su especificación OpenAPI, Claude Code puede leerla y generar código automáticamente
Stripe Dashboard: administración de pagos, claves de prueba
SendGrid (sendgrid.com): tiene periodo de prueba gratis; condiciones y precios en su sitio
Twilio: número de prueba gratis al registrarte
httpbin.org: API de prueba para experimentar (te devuelve lo que le mandaste)
JSONPlaceholder (jsonplaceholder.typicode.com): REST API falsa para practicar

Las condiciones de los planes gratis cambian; precios y versiones vigentes: Lo vigente.

Ideas clave

Una API no es difícil, es un estándar. Cuando entiendes que una solicitud = URL + método + datos, entiendes la base de cualquier API.

Las claves van en .env, nunca en el código. No es una recomendación, es una regla sin excepciones. Una sola clave filtrada puede costar miles de dólares.

Claude Code te lleva de "la persona que no sabe programar" a "la persona que puede integrar cualquier servicio". Eso cambia de raíz el valor que puedes ofrecer a tus clientes.

Lecciones relacionadas

→ MCP: amplía lo que puede hacer Claude Code: MCP es una capa encima de las APIs; en lugar de escribir las llamadas a mano, un servidor MCP lo hace por ti
→ MCP Builder: cómo crear tu propio conector MCP para cualquier API

Siguiente lección

→ MCP: amplía lo que puede hacer Claude Code: cómo conectar herramientas externas