Cómo configurar una API en n8n paso a paso

El nodo HTTP Request de n8n puede devolver datos en pocos minutos. El trabajo profesional empieza justo después: tratar credenciales, paginación, límites, errores, datos incompletos, duplicados y operaciones que no deben repetirse.

Esta guía está pensada para empresas que quieren conectar n8n con APIs reales: Holded, WhatsApp Business, Stripe, Shopify, Google, Meta, CRMs, ERPs, reservas, facturación, formularios, hojas de cálculo y sistemas internos. Si necesitas la parte de infraestructura, empieza antes por instalar n8n con Docker. Si ya tienes n8n operativo, esta página es el mapa para conectar una API sin convertir la automatización en una ruleta.

Respuesta rápida

Para configurar una API en n8n escribe primero el contrato: endpoint, método, autenticación, entrada, respuesta, límites, paginación, efectos e idempotencia. Prueba una llamada mínima fuera de n8n, crea una credencial segura, configura HTTP Request, valida la respuesta, trata errores y solo después conecta la llamada al resto del workflow.

No trates un 200 OK como éxito de negocio. Muchas APIs devuelven un código técnicamente correcto con errores funcionales dentro del JSON. La automatización tiene que comprobar el campo que confirma el resultado, no solo el estado HTTP.

Paso 1: entiende que acción quieres automatizar

Antes de abrir n8n, escribe una frase concreta:

• "Crear un contacto en Holded cuando entra un lead cualificado".
• "Enviar un mensaje de WhatsApp cuando se aprueba un presupuesto".
• "Consultar pedidos de Shopify cada hora y guardarlos en una hoja".
• "Crear una tarea en el CRM si un formulario llega con urgencia alta".
• "Generar una factura cuando un pago de Stripe se marca como completado".

Si no puedes escribir la acción en una frase, todavía no tienes un workflow; tienes una intuición. n8n no arregla procesos confusos. Los acelera, para bien o para mal.

Paso 2: localiza la documentación oficial

Trabaja siempre desde documentación oficial o desde un contrato privado del proveedor. Un tutorial de terceros puede ayudar a entender el patrón, pero no garantiza endpoints vigentes, permisos reales ni límites actuales.

Fuentes útiles:

• n8n HTTP Request node: nodo base para conectar APIs.
• n8n credentials: almacenamiento de credenciales y autenticación.
• n8n error handling: workflows de error, retry y manejo de fallos.
• OAuth 2.0 RFC 6749: base del flujo OAuth2 cuando el proveedor lo exige.

Guarda el enlace oficial junto al workflow. Cuando algo falle dentro de seis meses, no querrás buscar en capturas antiguas.

Paso 3: escribe el contrato de la API

Una API no se conecta "a ojo". Se documenta así:

Este contrato puede vivir en Notion, Google Docs, un Markdown interno o la descripción del workflow. Lo importante es que exista.

Paso 4: prueba fuera de n8n

Antes de culpar a n8n, comprueba que la API responde con una herramienta externa: consola oficial, curl, Bruno, Postman o Insomnia.

Ejemplo anónimo:

curl --request GET \
  --url "https://api.example.com/v1/customers?limit=10" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json"

Guarda tres respuestas:

• una correcta;
• una sin permisos;
• una con datos inválidos.

Esto acelera muchísimo el diagnóstico. Si el proveedor cambia una respuesta, verás enseguida que se ha roto.

Paso 5: crea la credencial sin filtrar secretos

La clave no debe aparecer en:

• Code node;
• URL;
• body;
• notas del workflow;
• nombre del workflow;
• capturas compartidas;
• JSON exportado;
• histórico de ejecuciones innecesario.

Usa la credencial nativa del proveedor si existe. Si no existe, usa una credencial genérica compatible: Header Auth, Basic Auth, OAuth2, Bearer Token o custom auth según el caso. Para OAuth2, comprueba redirect URL, scopes, expiración del token y refresh token.

En entornos serios, separa credenciales de pruebas y producción. No pruebes con permisos de administrador si luego el workflow vivirá con permisos limitados.

Paso 6: configura HTTP Request con una llamada mínima

Empieza por la llamada más pequeña posible. No metas diez parámetros en el primer intento.

Comprueba:

• método correcto;
• URL sin espacios;
• headers necesarios;
• query params;
• body con el tipo correcto;
• respuesta JSON parseada;
• status code;
• campos obligatorios;
• zona horaria;
• identificador estable.

Si el proveedor devuelve arrays muy grandes, limita la primera llamada a 10 o 20 resultados. Tu primer objetivo no es traerlo todo; es confirmar el contrato.

Paso 7: valida la respuesta

El error típico es conectar el HTTP Request directamente al siguiente nodo y asumir que siempre vendrá lo esperado. Antes de continuar, añade un IF, Switch o Code node defensivo.

Valida:

• existe el campo esperado;
• el array no está vacío si debe traer datos;
• el estado funcional es correcto;
• el ID externo existe;
• no hay duplicados evidentes;
• los importes tienen formato numérico;
• las fechas están en la zona horaria correcta;
• los emails y teléfonos tienen forma válida.

Esto evita que una respuesta incompleta cree facturas mal, mensajes raros o leads duplicados.

Paso 8: página sin saltar ni repetir

La paginación suele ser el punto donde una automatización amateur se rompe. Hay varios modelos:

Define siempre:

1. condición de continuidad;
2. límite máximo de páginas;
3. pausa entre llamadas si hay rate limit;
4. deduplicación por ID;
5. registro del último cursor o fecha procesada;
6. alerta si se supera el volumen normal.

Un bucle sin límite puede bloquear la API, disparar costes o dejar el workflow ejecutando durante horas.

Paso 9: trata rate limits

Muchas APIs limitan llamadas por minuto o por día. Busca cabeceras como Retry-After, X-RateLimit-Remaining o similares. Si existen, úsalas. Si no existen, aplica una pausa razonable y evita ráfagas.

No hagas esto:

• consultar toda la base cada minuto;
• repetir un POST fallido sin mirar el error;
• lanzar cien llamadas paralelas contra una API pequeña;
• ignorar 429 Too Many Requests.

Una automatización sostenible consulta solo lo necesario y recuerda lo ya procesado.

Paso 10: errores y reintentos

Los reintentos son útiles para timeouts, errores 5xx o rate limits temporales. Son peligrosos para escrituras no idempotentes.

Asigna un workflow de error que avise con contexto reducido: nombre del workflow, nodo, ID de ejecución, error resumido y responsable. No envíes payloads completos a Telegram, Slack o email si contienen datos personales.

Paso 11: idempotencia, la diferencia entre demo y producción

Idempotencia significa que repetir una operación no crea un desastre. Ejemplos:

• Si vuelves a crear el mismo contacto, no debe duplicarse.
• Si repites una factura por timeout, no debe emitirse dos veces.
• Si reenvías un WhatsApp, no debe parecer spam.
• Si sincronizas pedidos, no debes importar el mismo pedido cada hora.

Formas de conseguirlo:

• usar external_id cuando la API lo permite;
• buscar antes de crear;
• guardar IDs procesados;
• crear claves compuestas, por ejemplo origen + id_externo;
• usar una tabla de control;
• separar "preparar" y "confirmar".

En facturación, pagos y mensajes a clientes, la idempotencia no es opcional.

Paso 12: ejemplo práctico con Holded

Un caso realista: entra un formulario de contacto, el equipo marca el lead como cualificado y n8n crea el contacto en Holded.

Estructura:

1. Webhook o formulario.
2. Normalización de nombre, email, teléfono y empresa.
3. Validación de email y teléfono.
4. Búsqueda de contacto existente en Holded por email o CIF.
5. Si existe, actualizar nota.
6. Si no existe, crear contacto.
7. Guardar ID de Holded en la ficha interna.
8. Avisar al equipo comercial.

El paso clave no es "crear contacto". Es "buscar antes de crear". Sin eso, en tres meses tendrás el ERP lleno de duplicados.

Si esta parte te interesa, también tenemos una guía específica para automatizar facturas con Holded y n8n.

Paso 13: ejemplo práctico con WhatsApp

WhatsApp es potente, pero hay que usarlo con cuidado. Una automatización básica puede:

• avisar al equipo cuando entra un lead urgente;
• enviar confirmación al cliente si ha aceptado comunicación;
• mandar un enlace de presupuesto;
• recordar una cita;
• solicitar información pendiente.

Nunca conviene automatizar respuestas agresivas sin consentimiento, contexto ni límite. Lo importante es que el cliente sienta rapidez, no una máquina pesada.

Lee después automatizar respuestas de WhatsApp en empresa para ver flujos más concretos.

Paso 14: ejemplo práctico con Shopify o WooCommerce

Para ecommerce, n8n puede consultar pedidos, clientes, devoluciones, stock o eventos de pago. La arquitectura sería:

1. Webhook de pedido creado.
2. Validación de pago.
3. Normalización de datos.
4. Alta o actualización de cliente.
5. Creación de factura o documento.
6. Aviso logístico.
7. Registro de estado.
8. Alerta si hay datos incompletos.

El error común es hacer polling continuo cuando el sistema puede enviar webhooks. Usa webhook si el proveedor lo permite, polling solo cuando no haya alternativa.

Paso 15: seguridad de datos personales

Una API suele mover datos sensibles: emails, teléfonos, direcciones, facturas, citas, pagos o historiales. Aplica mínimo:

• permisos mínimos;
• retención consciente de ejecuciones;
• no guardar payloads completos si no hace falta;
• no enviar datos sensibles a canales inseguros;
• separar pruebas de producción;
• registrar quién tiene acceso a credenciales;
• rotar credenciales cuando una persona deja el proyecto.

Si el workflow pasa a producción, revisa también n8n en producción: seguridad, errores y escalado.

Paso 16: plantilla de decisión

Antes de activar, responde:

Si falta una respuesta, el workflow aún está verde.

Checklist final

• Contrato de API documentado.
• Documentación oficial guardada.
• Credencial fuera de nodos.
• Entorno de prueba separado.
• HTTP Request probado con llamada mínima.
• Validación de campos obligatorios.
• Paginación limitada.
• Rate limit tratado.
• Errores clasificados.
• Escrituras idempotentes.
• Workflow de error asignado.
• Retención de ejecuciones definida.
• Responsable de negocio y técnico.
• Prueba real antes de activar.

Casos de uso que una pyme entiende rápido

Una API en n8n no es un capricho técnico. Es la forma de que sistemas que ya usa la empresa se hablen sin que una persona copie datos a mano. Estos son ejemplos que vemos una y otra vez.

Lead que entra por la web y llega al CRM

La web recibe un formulario. n8n valida nombre, teléfono, email, servicio y ciudad. Después consulta el CRM para ver si el contacto ya existe. Si existe, añade una nota. Si no existe, crea contacto y oportunidad. Luego avisa al comercial responsable.

El detalle importante es que el workflow no debe crear un contacto nuevo cada vez que la misma persona pide información. La API debe buscar primero por email, teléfono o identificador externo. Esta pequeña decisión evita meses de CRM sucio.

Presupuesto que se convierte en factura

Un equipo comercial marca un presupuesto como aceptado. n8n consulta los datos, valida que hay cliente, CIF si aplica, conceptos, impuestos y total. Después crea la factura en el ERP y guarda el ID de factura en la ficha interna.

Aquí no se puede improvisar. Antes de emitir, el workflow debe validar importes, moneda, impuestos y duplicados. Una factura duplicada no es un fallo visual; es un problema administrativo.

WhatsApp después de una acción concreta

Una API puede enviar un mensaje cuando un pedido cambia de estado, cuando falta documentación o cuando un cliente pide soporte. Pero debe respetar consentimiento, plantillas permitidas y frecuencia. n8n no debe convertirse en una máquina de molestar.

La buena automatización parece atención rápida. La mala parece spam.

Publicación y aprobación de contenido

Para redes sociales, n8n puede mover ideas desde una hoja o base de datos, generar borradores, avisar para revisión, preparar recursos y registrar la fecha de publicación. Si se conecta con APIs de plataformas, conviene mantener una revisión humana en contenido sensible.

Este tipo de flujo encaja con empresas que quieren publicar más sin perder control de marca. Si el proceso comercial depende de redes, revisa también automatizar publicaciones en redes sociales.

Cómo documentar la integración

Una integración que no está documentada acaba siendo una caja negra. La ficha mínima debería incluir:

• nombre del workflow;
• objetivo de negocio;
• sistemas conectados;
• credenciales usadas;
• endpoints principales;
• campos obligatorios;
• ejemplos de payload;
• errores esperados;
• responsable;
• fecha de última prueba;
• enlace a documentación oficial;
• cómo pausar;
• cómo reactivar;
• qué no debe tocarse.

No hace falta escribir un manual de cincuenta páginas. Hace falta que, si el workflow falla un viernes por la tarde, alguien pueda entender qué hace y dónde mirar.

Cómo medir si la API merece la pena

Mide antes y después:

La automatización no se justifica solo por ahorrar tiempo. También por responder antes, reducir errores, mejorar la experiencia del cliente y tener datos más limpios.

Antes de pedir presupuesto a una agencia

Prepara esta información:

• qué sistema inicia el proceso;
• qué sistema debe recibir datos;
• ejemplo real de entrada;
• ejemplo real de salida;
• volumen mensual;
• errores actuales;
• sistemas con API;
• permisos disponibles;
• si hay datos personales;
• si debe haber revisión humana;
• qué resultado esperas.

Con eso se puede saber si encaja en un flujo básico o si hace falta arquitectura. Sin eso, cualquier proveedor serio tendrá que empezar descubriendo el proceso.

Matriz por tipo de API

No todas las APIs se tratan igual. Una API de lectura para traer informes tiene poco riesgo. Una API de escritura que emite facturas, cobra pagos o envía mensajes a clientes exige controles mucho más estrictos.

Esta matriz ayuda a decidir cuánta seguridad necesita cada flujo. No tiene sentido pedir aprobación humana para guardar una métrica agregada, pero sí para emitir una factura o borrar un dato.

Ejemplo de payload normalizado

Antes de enviar datos a una API externa, normaliza una estructura interna. Así puedes cambiar de proveedor sin reescribir todo el workflow.

{
  "source": "formulario-web",
  "externalId": "lead-2026-0001",
  "contact": {
    "name": "Cliente ejemplo",
    "email": "cliente@example.com",
    "phone": "+34600000000"
  },
  "context": {
    "service": "automatizacion",
    "city": "Madrid",
    "priority": "media"
  },
  "tracking": {
    "utmSource": "google",
    "utmCampaign": "seo-madrid"
  }
}

El nodo siguiente transforma ese payload al formato exacto de Holded, HubSpot, Google Sheets o la API que toque. Esta capa intermedia evita que todo el workflow dependa de un proveedor.

Lo que debe quedar en una prueba aceptada

Una prueba de API no está aceptada hasta tener evidencia:

• captura o log sin secretos de una ejecución correcta;
• ID externo creado o actualizado;
• ejemplo de error controlado;
• confirmación de que no duplica;
• tiempo de ejecución normal;
• responsable que valida el resultado;
• nota de cómo pausar el flujo.

Cuando un cliente pregunta "¿qué pasa si falla?", la respuesta no puede ser "esperemos que no falle". Tiene que haber un procedimiento.

Escenarios reales de fallo

La API responde, pero con datos nuevos

Un proveedor puede añadir campos, cambiar nombres o devolver null donde antes venía texto. Si el workflow espera siempre una estructura exacta, puede romperse. Por eso conviene validar campos obligatorios y usar transformaciones defensivas. No todo cambio requiere parar, pero sí requiere que el workflow no explote.

La API tarda demasiado

Un timeout no siempre significa que la acción no ocurrió. Puede que el proveedor haya creado el recurso y n8n no recibiera respuesta a tiempo. En escrituras, no repitas sin comprobar. Primero consulta si el recurso existe. Después decide si crear, actualizar o avisar.

La API cambia permisos

OAuth2, scopes y permisos pueden cambiar cuando el proveedor actualiza su plataforma o cuando un administrador modifica la app. Un workflow que funcionaba ayer puede devolver 403 hoy. El aviso debe explicar que es un problema de permisos, no un error genérico.

El dato de entrada viene mal

La API no tiene la culpa si la web envía un teléfono sin prefijo, un email mal escrito o una ciudad vacía. Normaliza antes de llamar. Cuanto más cerca del inicio controles los datos, menos errores caros tendrás al final.

Plantilla de resumen para el cliente

Cuando entregues una integración, deja algo así:

Este resumen hace que la automatización sea entendible para negocio, no solo para quien la construyó.

Glosario rápido

Endpoint: URL concreta de la API que consulta o ejecuta una acción.

Header: cabecera de la petición. Suele llevar autenticación, tipo de contenido o datos de control.

Query param: parámetro que viaja en la URL, por ejemplo ?limit=10.

Body: contenido de la petición, normalmente JSON cuando se crea o actualiza algo.

Token: clave temporal o permanente que autoriza la llamada.

Scope: permiso concreto concedido a una credencial OAuth2.

Rate limit: límite de llamadas permitido por el proveedor.

Paginación: forma de recorrer muchos resultados sin pedir todo de golpe.

Idempotencia: control para que repetir una operación no cree duplicados ni efectos no deseados.

Webhook: URL que recibe eventos de otro sistema y despierta un workflow.

CTA

Una API bien conectada no se nota porque haga ruido. Se nota porque el equipo deja de copiar datos, el cliente recibe respuesta antes y los errores aparecen antes de causar problemas.

Si tienes una API que quieres conectar con tu web, CRM, ERP, WhatsApp, Shopify, WooCommerce o Holded, podemos revisar el proceso y decirte si encaja en un flujo básico o si necesita una arquitectura más seria. Mira el servicio de automatizaciones n8n para empresas o cuéntanos el caso desde contacto.