Una API define cómo un programa puede pedir información o solicitar una acción a otro componente. En un negocio, puede servir para que la tienda consulte existencias o para registrar un pago sin volver a capturarlo a mano.
La sigla significa interfaz de programación de aplicaciones. Existen API de distintos tipos; aquí nos concentramos en las que permiten conectar sistemas a través de la web. La definición no implica que cualquier dato de una aplicación esté disponible. Definición de API en MDN.
Un pedido que pasa de la tienda al sistema de trabajo
Ejemplo hipotético: una empresa recibe un pedido en su tienda y alguien vuelve a escribir productos y cantidades en el sistema que utiliza el almacén. Una integración podría transmitir esos datos y registrar la respuesta, siempre que ambos sistemas permitan las operaciones necesarias.
Antes de programarlo hay preguntas del negocio: ¿quién manda sobre el inventario?, ¿qué ocurre si un producto tiene nombres diferentes?, ¿cuándo se considera aceptado el pedido? La API ofrece las operaciones; el proyecto debe establecer las reglas que conectan el trabajo de ambos lados.
Consultar y recibir un aviso son cosas distintas
Una aplicación puede consultar otra para obtener un dato. También puede recibir una notificación cuando ocurre algo; este mecanismo suele llamarse webhook. Por ejemplo, Stripe documenta avisos sobre pagos y otros eventos para que una aplicación reaccione sin depender de que una persona revise el panel. Documentación de webhooks de Stripe.
En esa misma documentación, Stripe advierte que pueden recibirse eventos duplicados y que su entrega no garantiza el orden. Por eso una integración de pagos debe identificar lo que ya procesó y verificar el estado pertinente. Recibir dos avisos no debería convertirse en dos registros de la misma operación.
Este ejemplo corresponde a Stripe. Los mecanismos, permisos y comportamiento deben verificarse en la documentación del proveedor que realmente utilizará el proyecto.
| Forma | Ejemplo en el pedido | Qué debe quedar definido |
|---|---|---|
| Consulta a la API | La integración pregunta por el estado del pedido. | Cuándo consulta, qué permisos tiene y qué hace si no obtiene respuesta. |
| Aviso por webhook | El sistema avisa que ocurrió un cambio. | Cómo se verifica el aviso, cómo se evitan duplicados y cuándo consultar el estado actualizado. |
Un aviso repetido no debería crear otro pedido
En nuestro ejemplo hipotético, el pedido tiene la referencia P-1002. La integración registra esa referencia y el resultado del envío. Si pierde la respuesta del almacén, no puede concluir automáticamente que el registro falló: necesita comprobar qué ocurrió antes de repetir una operación que podría crear otro pedido.
- Pedido recibido: valida los productos y cantidades necesarios.
- Envío al almacén: conserva la referencia y la respuesta que permita relacionar ambos sistemas.
- Respuesta incierta o aviso repetido: consulta o reconoce la operación existente según las capacidades del proveedor; no crea otra a ciegas.
- Error que requiere revisión: deja el caso pendiente con una causa y una persona responsable, sin marcarlo como terminado.
Diseñar un reintento para que no repita su efecto se conoce como idempotencia. No basta con guardar un número en una tabla: el mecanismo debe impedir duplicados también si llegan dos solicitudes al mismo tiempo. La referencia y el proceso anteriores son una propuesta conceptual, no un contrato que cualquier API ofrezca. La especificación HTTP explica por qué los reintentos dependen de la idempotencia de la operación.
Por qué “tener API” no termina la evaluación
Para decidir si la conexión sirve, pide comprobar tres cuestiones con una operación concreta:
- La información disponible
- ¿La API permite consultar o cambiar exactamente el dato necesario? Ver una pantalla del sistema no demuestra que exista una operación equivalente.
- Las reglas del negocio
- ¿Qué sistema conserva el dato principal y cómo se resuelven diferencias? Un código de producto distinto puede requerir una equivalencia explícita.
- El trabajo cuando algo falla
- ¿Dónde se registra el error, quién lo revisa y cómo se completa la operación pendiente sin duplicarla?
También conviene revisar las condiciones de acceso y mantenimiento de la API elegida. Un presupuesto de integración necesita contemplar su funcionamiento después del arranque, no sólo una demostración donde el envío salió bien.
Antes de aceptar la entrega, prueba un pedido válido, un producto desconocido, una respuesta tardía y un aviso repetido. Define qué debe ver el equipo en cada caso. La guía sobre cómo comprobar una integración entre sistemas desarrolla esta revisión.
Cuándo vale la pena investigarlo
Busca una tarea repetida y describe cuánto trabajo implica. Si el mismo dato se copia entre sistemas con frecuencia, o los errores de captura producen correcciones constantes, tienes un proceso que vale la pena evaluar. Si casi no ocurre o requiere una decisión humana diferente cada vez, el beneficio de automatizarlo necesita una revisión más cuidadosa.
Para comenzar basta con describir qué dispara la tarea, qué dato debe llegar a dónde y qué tendría que pasar después. Un ejemplo sin información sensible suele explicar mejor la necesidad que una lista de tecnologías.
¿Estás capturando lo mismo en dos sistemas?
Cuéntanos cuáles son y qué información necesitas trasladar. Podemos conversar sobre una integración y qué convendría comprobar primero.
Conocer automatización e integraciones