Respuesta breve
Una API es un conjunto de reglas que permite a un programa pedir datos o una acción a otro sin que una persona pase por las pantallas. La petición va a una dirección con una clave y la respuesta vuelve con un código de estado. El servicio dueño de la API fija los límites, el precio y las versiones, así que una integración necesita un responsable de las claves, un registro de errores y alguien que siga los cambios.
Una API es una ventanilla para programas, no para personas
El proveedor dice que la web y el CRM se conectarán por la API, y el dueño asiente sin una imagen en la cabeza. Entonces, ¿qué es una API, dicho sin un programador de por medio? MDN Web Docs la define como un conjunto de funciones y reglas dentro de un programa que permiten interactuar con él mediante software, y no mediante una interfaz pensada para personas. MDN añade que puede verse como un contrato sencillo entre la aplicación y el software que la utiliza.
Wikipedia lo cuenta desde el otro lado: una interfaz de usuario conecta una máquina con una persona, una API conecta programas entre sí. Piensa en un banco: tú ves pantallas y botones en su aplicación, mientras tu programa de contabilidad ve una ventanilla con una lista fija de formularios. Entrega un formulario acordado, recibe una respuesta acordada y nunca pasa a la trastienda. Wikipedia señala ahí uno de los propósitos principales de una API: ocultar los detalles internos de cómo funciona un sistema.
De qué se componen una petición y una respuesta, sin código
Las API que encuentra una empresa pequeña son casi siempre API web; Telegram, por ejemplo, describe su Bot API como una interfaz basada en HTTP. El resumen de HTTP de MDN habla de un intercambio de mensajes: el cliente envía peticiones y el servidor devuelve respuestas. Una petición tiene un método, un verbo como GET o POST, la ruta del recurso, cabeceras opcionales y a veces un cuerpo. En términos de tienda son la acción, la dirección de la ventanilla, una nota sobre quién pregunta y el formulario en sí.
La respuesta trae un código de estado que, según MDN, indica si la petición tuvo éxito y, si no, por qué. MDN agrupa los códigos en cinco clases: de 200 a 299 significan éxito, de 400 a 499 un error del cliente y de 500 a 599 un error del servidor. Lo útil para un dueño es que cada intercambio deja rastro. La queja de que la integración no funciona se convierte en una pregunta precisa: qué se envió y qué código volvió.
Qué conecta de verdad una pyme mediante las API
Las conexiones típicas son pocas. Un formulario de la web pasa el contacto nuevo al CRM y nadie lo copia de un correo. La web pide a un servicio de pagos que cree un cobro y más tarde se entera de que se pagó. Una tienda pregunta al transportista el coste del envío y el número de seguimiento. Los pedidos entran en el programa de contabilidad y un bot de mensajería avisa al vendedor cuando llega uno.
No todos los programas tienen ventanilla, y no todas están abiertas para ti. Wikipedia distingue tres políticas de publicación: una API privada es solo para uso interno de la empresa, una de socios es para socios comerciales concretos y una pública está disponible para cualquiera. Por eso, averigua primero si el servicio que ya pagas tiene API y si tu plan la incluye. Además, una API ofrece solo lo que su dueño decidió exponer: si una acción no figura en la documentación, ningún proveedor podrá invocarla.
Una clave de API es una contraseña, y una clave filtrada, una puerta abierta
La ventanilla tiene que saber quién pregunta, y para eso sirve la clave. YooKassa, un servicio de pagos ruso, toma el identificador de la tienda como nombre de usuario y una clave secreta como contraseña. La guía de Stripe sobre claves lo dice sin rodeos: las claves secretas son credenciales de la cuenta, como un usuario y una contraseña. Quien consiga una, dice la guía, puede hacer cargos no autorizados, acceder a datos de clientes o alterar la integración. Stripe añade que hay actores maliciosos rastreando sin pausa los repositorios públicos de código en busca de claves, y pide no compartirlas por correo ni por chat.
El API Security Top 10 de OWASP coloca la autenticación rota en el segundo puesto de su lista de 2023 y cuenta el envío de tokens y contraseñas en la URL entre las señales de una API vulnerable. La respuesta de Stripe es la clave restringida, con solo los permisos de una tarea; su ejemplo es un tercero que vigila las disputas y recibe acceso de solo lectura a esos datos. Una clave expuesta, dice la guía, debe rotarse de inmediato. Para un dueño son tres hábitos: las claves se crean en tu propia cuenta, cada proveedor recibe la más estrecha y tú sabes cómo revocarla.
Límites de peticiones, planes de pago y versiones: los fija la otra parte
Una API es maquinaria ajena, y su dueño la protege. Stripe dice que limita la frecuencia de peticiones para maximizar la estabilidad y evitar abusos; su documentación da hoy un límite global de 100 peticiones por segundo en modo real, y el programa que lo supera recibe el estado 429 Too Many Requests. Los límites marcan también dónde acaba lo gratuito y empieza lo de pago. Las preguntas frecuentes de Telegram para bots limitan hoy el envío masivo a unos 30 mensajes por segundo y describen difusiones de pago que suben el techo a 1000 con un cargo en Telegram Stars.
Las versiones son la tercera regla. Wikipedia recuerda que los cambios en una API pueden romper la compatibilidad con los clientes que dependen de ella, y que una API pública puede declarar obsoletas algunas de sus partes. Stripe describe su propio ritmo: publica versiones nuevas cada mes sin cambios incompatibles y, dos veces al año, una versión mayor que sí los contiene, de modo que actualizar puede exigir cambios en una integración existente. Así que alguien tiene que leer los avisos de cambios del servicio, y el mantenimiento entra en el plan desde el primer día.
Webhooks: cuando el otro sistema llama primero a tu dirección
En el esquema normal tu programa pregunta y el servicio responde. Pero algunas cosas ocurren más tarde y sin ti: un banco confirma un pago minutos después de que el cliente haya cerrado la página. Preguntar cada minuto si ya está pagado malgasta peticiones, así que los servicios ofrecen el canal inverso, el webhook. Le das al servicio una dirección y él envía allí un mensaje cuando sucede algo. La documentación de Stripe dice que envía datos en tiempo real al punto registrado cuando, por ejemplo, el banco de un cliente confirma un pago.
Un webhook también tiene sus normas. Stripe exige una dirección HTTPS accesible públicamente, y la entrega no dura para siempre: Stripe reintenta hasta tres días en modo real y YooKassa sigue entregando una notificación durante 24 horas desde el evento. Stripe avisa además de que el mismo evento puede llegar más de una vez y de que, sin verificación, un atacante podría enviar eventos falsos para provocar acciones como despachar pedidos. Si una web pasa caída un fin de semana largo, algunos pedidos pagados pueden seguir como impagados hasta que alguien los concilie.
Qué preguntar a un proveedor antes de empezar la integración
Empieza por las claves. Pregunta quién las crea y en qué cuenta, porque la cuenta debe ser tuya y no del proveedor. Pregunta dónde se guardarán: la guía de Stripe dice que nunca se pongan claves secretas en el código fuente. Pregunta qué puede hacer cada clave y cómo se sustituirá cuando termine el trabajo. Pregunta también por un entorno de pruebas: Stripe, por ejemplo, tiene uno aislado, con sus propias claves, donde las redes de tarjetas no procesan pagos.
Después pregunta qué pasa cuando algo falla. La documentación de YooKassa ofrece un buen ejemplo: si no puede dar una respuesta precisa en 30 segundos devuelve HTTP 500, y ese código no dice si la operación salió bien, así que primero hay que comprobar el resultado. También describe una clave de idempotencia, que hace que una petición repetida cuente como la original y ayuda a evitar transacciones repetidas. Pregunta si el cliente está protegido de un doble cobro, dónde está el registro y a quién se avisa de un error.
Conector listo, herramienta sin código o desarrollo a medida, y qué preparar
Hay tres caminos, y el correcto es el más barato de los que encajan. Primero revisa los ajustes de los servicios que ya usas, porque muchos CRM, creadores de sitios y servicios de pago ya traen conectores entre sí. Si no los hay, los servicios de automatización sin código enlazan dos API con una cadena visual: un contacto nuevo, una ficha en el CRM, un mensaje al vendedor. El desarrollo a medida se justifica cuando no existe conector, cuando la lógica es propia, cuando los volúmenes se acercan a los límites o cuando hay dinero de por medio y los fallos deben tratarse con precisión.
Elijas el camino que elijas, prepara antes una hoja. Describe cada enlace en una frase: cuando aquí pasa esto, allí debe aparecer aquello. Apunta tus sistemas y planes, los campos de datos que viajan, el número aproximado de eventos al día y el titular de cada cuenta. Con esa hoja, un estudio como VITON13 Studio o tu propio desarrollador puede decir qué camino encaja y presupuestarlo con exactitud. Y la duda de qué es una API deja paso a otra más útil: qué dos sistemas de tu negocio deberían hablarse primero.
Lista práctica
- Anota los servicios que ya pagas y comprueba en los ajustes de cada uno si tu plan incluye la API.
- Escribe cada enlace en una frase: cuando en el sistema A pasa esto, en el sistema B debe aparecer aquello.
- Crea las claves de API en tus propias cuentas y da al proveedor la de permisos más estrechos para la tarea.
- Acuerda dónde se registran los errores, a quién se avisa de un fallo y quién relee los avisos de cambios del servicio.
- Prueba la integración en el entorno de pruebas del servicio con claves de prueba antes del primer pago real.
Preguntas frecuentes
¿Necesita una pyme un programador para usar una API?
No siempre. Muchos servicios traen conectores listos que se activan en los ajustes, y los servicios de automatización sin código enlazan dos sistemas con una cadena visual. Hace falta un desarrollador cuando no existe conector, cuando la lógica es particular de tu negocio o cuando hay pagos y los errores y duplicados no pueden dejarse al azar.
¿Una clave de API equivale a la contraseña de mi cuenta?
En la práctica, sí. La guía de Stripe llama a las claves secretas credenciales de la cuenta, como un usuario y una contraseña: el programa que presenta la clave actúa en tu cuenta dentro de los permisos que tenga. Las diferencias juegan a tu favor, porque una clave puede limitarse a unas pocas operaciones y revocarse sin cambiar tu acceso personal.
¿Qué hago si una clave de API acaba en un chat o en un correo?
Darla por expuesta y sustituirla. Stripe indica rotar de inmediato una clave expuesta aunque no conste que alguien la viera: se emite una nueva, la antigua deja de funcionar y la integración pasa a la nueva. Después revisa el registro de peticiones por si hay llamadas que no hiciste, y deja de enviar claves por mensajería.
¿En qué se diferencia un webhook de una petición normal a una API?
En el sentido. En una petición normal tu programa pregunta al servicio y espera la contestación. Con un webhook registras una dirección una sola vez y el servicio envía allí un mensaje cuando ocurre algo, por ejemplo un pago confirmado. Ahorra consultas constantes, pero tu dirección tiene que estar disponible y hay que verificar quién envía.
¿Puede una integración por API dejar de funcionar sola tras el lanzamiento?
Sí, y casi siempre por una de tres razones: el servicio publicó una versión con cambios incompatibles, una clave caducó o fue revocada, o el volumen de peticiones tocó un límite. Nada de eso se ve en la web hasta que los pedidos dejan de llegar al CRM. Por eso una integración necesita un registro, una alerta y un responsable de leer los avisos del servicio.