Qué es una API y para qué sirve

Un contrato entre programas

Una API (interfaz de programación de aplicaciones) es el conjunto de reglas con las que un programa permite que otro le pida cosas. Define qué se puede pedir, cómo se formula la petición, qué se recibe de vuelta y qué pasa cuando algo sale mal. Es un contrato: si cumples tu parte, el otro lado responde de forma predecible.

La palabra clave es predecible. Una integración no es un cable entre dos sistemas; es un acuerdo sobre qué significa cada mensaje. Cuando el acuerdo está bien definido y documentado, dos equipos que nunca se han hablado pueden conectar sus sistemas. Cuando no lo está, la integración depende de adivinar.

Casi todas las APIs con las que vas a cruzarte en tu operación (facturación electrónica, pasarelas de pago, mensajería, tus propias plataformas) hablan sobre HTTP, el mismo protocolo del navegador. Así que vale la pena entender sus piezas.

HTTP, recursos y métodos

HTTP es el protocolo que define cómo un cliente le envía una petición a un servidor y cómo el servidor responde. Su versión vigente está descrita en la RFC 9110 de la IETF. Sobre HTTP, una API expone recursos: cosas con nombre y dirección, como una novedad de minuta, un turno o una sede. Cada recurso tiene una URL.

Sobre cada recurso se aplican métodos, que son los verbos del contrato. Los cinco que vas a ver siempre:

• GET: leer. Pide el recurso sin cambiarlo. Se puede repetir sin efectos secundarios.
• POST: crear. Envía datos para que el servidor cree algo nuevo.
• PUT: reemplazar. Sustituye el recurso completo por la versión que envías.
• PATCH: modificar. Cambia solo los campos que envías y deja el resto igual.
• DELETE: eliminar. Borra o desactiva el recurso.

Que los métodos tengan un significado fijo es lo que permite que alguien lea la documentación y sepa qué esperar. Un POST que borra datos rompe el contrato, aunque técnicamente funcione.

Códigos de estado y JSON

Cada respuesta HTTP trae un código de tres cifras que resume qué pasó. La primera cifra dice la familia: 2xx es éxito, 4xx es error del cliente (pediste mal, no tienes permiso, no existe) y 5xx es error del servidor. Los que más vas a ver: 200 (listo), 201 (creado), 400 (petición inválida), 401 (sin autenticar), 403 (sin permiso), 404 (no existe), 429 (demasiadas peticiones) y 500 (falló el servidor).

Cuando la respuesta es un error, conviene que el cuerpo explique por qué en un formato estándar. La RFC 9457 define uno, llamado Problem Details, que muchas APIs adoptan para que los errores sean legibles tanto por programas como por personas.

Los datos van y vienen casi siempre en JSON, un formato de texto con llaves, comillas y dos puntos que cualquier lenguaje sabe leer y que está definido en la RFC 8259. Un ejemplo mínimo, como el que usaría una app de vigilancia para registrar una novedad en la minuta de una sede:

POST /v1/sedes/centro-norte/novedades HTTP/1.1
Host: api.ejemplo.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "tipo": "ingreso_visitante",
  "descripcion": "Visitante autorizado por la unidad 402",
  "ocurrida_en": "2026-08-19T14:32:00-05:00",
  "foto_id": "f_8a21"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/sedes/centro-norte/novedades/nv_7f3c

{
  "id": "nv_7f3c",
  "tipo": "ingreso_visitante",
  "registrada_por": "usr_19",
  "registrada_en": "2026-08-19T14:32:07-05:00",
  "estado": "abierta"
}

Fíjate en tres cosas. El cliente envía lo que sabe. El servidor responde 201 con un identificador y una hora de registro que puso él mismo, no el celular. Y la cabecera Location dice dónde vive el recurso nuevo. Eso es el contrato funcionando.

Autenticación, versionado y límites de uso

Nadie debería poder crear novedades en tu sede sin identificarse. La forma habitual es un token: una cadena secreta que el servidor emite y que el cliente envía en cada petición, como en el ejemplo. El token identifica quién pide y qué permisos tiene, y se puede revocar sin cambiar contraseñas. Los tokens son secretos: no van en la URL, no se comparten por chat y se rotan periódicamente.

El versionado es la promesa de que el contrato no cambiará debajo de tus pies. El v1 en la URL del ejemplo dice qué versión del contrato estás usando. Cuando el proveedor necesita cambiar algo incompatible, publica v2 y deja v1 funcionando durante un tiempo anunciado. Sin versionado, cada mejora del proveedor puede romper tu integración sin aviso.

Los límites de uso definen cuántas peticiones puedes hacer por minuto o por día. Cuando los superas, recibes un 429. No es un castigo: es la forma en que el servidor protege a todos sus clientes. Tu integración debe saber esperar y reintentar.

Webhooks: cuando el servidor es el que avisa

Todo lo anterior es el cliente preguntando. Pero a veces quieres que el servidor te avise cuando pasa algo: se pagó una factura, se disparó una alerta, se cerró una ronda. Para eso existen los webhooks: le das al proveedor una URL tuya y él le envía un POST cada vez que ocurre el evento.

Es eficiente, porque evita preguntar cada minuto, pero exige dos cosas de tu lado: que tu URL esté disponible y que verifiques que el aviso viene de quien dice venir, normalmente con una firma en la cabecera.

Documentación que se puede ejecutar

Un contrato que solo vive en la cabeza del desarrollador no es un contrato. El estándar para documentar APIs HTTP es la OpenAPI Specification: un archivo que describe cada recurso, método, parámetro, respuesta y error. Con ese archivo se generan documentación navegable, clientes en varios lenguajes y pruebas automáticas.

Cuando un proveedor te entrega su archivo OpenAPI, sabes exactamente qué puedes pedir. Cuando no lo tiene, la integración empieza con una investigación, y las investigaciones no tienen presupuesto cerrado.

Qué preguntar antes de contratar una integración

• ¿Los dos sistemas tienen API documentada? Si uno no la tiene, la integración va a depender de trucos frágiles como leer pantallas o archivos exportados.
• ¿Cómo se autentica y quién administra los tokens? Deben ser tuyos, no del contratista.
• ¿Qué pasa si uno de los sistemas está caído? Debe haber reintentos y una cola, no datos perdidos.
• ¿Cómo sabré que funciona? Pide monitoreo y alertas, no solo la entrega.
• ¿Qué versión de la API se usa y cuándo deja de tener soporte?
• ¿Dónde quedan el código y la documentación? Deben quedar contigo, con acceso propio.

Qué puedes hacer esta semana

1. Haz una lista de los sistemas que usa tu operación y marca cuáles tienen API documentada. Búscalo en su sitio como API, desarrolladores o integraciones.
2. Identifica el dato que hoy alguien copia a mano de un sistema a otro. Ese es el candidato natural a primera integración.
3. Pídele a cada proveedor su documentación OpenAPI o equivalente y guárdala en un lugar que el equipo pueda consultar.
4. Con esa información en mano, pide una cotización que responda las preguntas de arriba, no solo un precio.