sequenceDiagram
participant T as Tool
participant API as API del DMS
participant D as Sistema documental
T->>API: Request: buscar ACME / anexo seguridad
API->>D: Consulta interna
D-->>API: Resultados
API-->>T: Response: DOC-021 / firmado
APIs
Cómo se comunican los sistemas mediante interfaces definidas y qué significan request, response, parámetros, autenticación y permisos en una integración utilizada por una aplicación de IA.
En la página anterior llegamos a una escena concreta.
El modelo genera una solicitud estructurada:
buscar_documentos(
proveedor = "ACME",
tipo_documento = "anexo_seguridad"
)La aplicación decide ejecutar la tool.
Pero el contrato no está dentro del modelo.
Está en otro sistema.
¿Cómo consigue la tool pedirle algo a ese sistema?
Aquí aparece una abstracción fundamental del software moderno: la API.
Las APIs no fueron inventadas para los modelos de lenguaje. Existen desde mucho antes y permiten que aplicaciones diferentes se comuniquen mediante interfaces definidas.
Idea central
Una API —Application Programming Interface— es una interfaz mediante la cual un sistema permite que otro software solicite información u operaciones de una manera definida.
Para comprender su papel en este curso necesitamos seis ideas:
API → request → response → parámetros → autenticación → permisos.
Qué problema resuelve una API
Imaginemos un DMS.
Una persona puede abrir la aplicación, iniciar sesión, usar el buscador y descargar un archivo.
Pero nuestra tool no es una persona haciendo clic.
Es software.
Necesita una forma programática de pedir:
busca documentos del proveedor ACMEEl DMS puede exponer una interfaz para hacerlo.
Eso es precisamente una de las funciones de una API.
Una analogía: ventanilla y oficina interna
Podemos imaginar una organización con una gran oficina interna.
Los visitantes no entran libremente a todos los escritorios.
Existe una ventanilla donde se aceptan solicitudes definidas:
consultar expediente
solicitar copia
registrar solicitudLa analogía ayuda porque muestra que una API expone formas controladas de interacción sin revelar necesariamente cómo funciona internamente el sistema.
Pero deja de servir si imaginamos que la API comprende lenguaje natural como una persona en la ventanilla.
Las APIs suelen requerir estructuras, operaciones y formatos definidos.
La API no es el sistema completo
Un DMS puede ofrecer cientos de funcionalidades en su interfaz humana y sólo algunas mediante API.
También puede ocurrir lo contrario: la API puede exponer funciones que la interfaz no muestra directamente.
Por eso debemos distinguir:
SISTEMA
conjunto completo de capacidades
API
interfaz programática expuestaLa API es una puerta definida hacia parte del sistema.
Request: formular una petición
La interacción suele comenzar con una request.
Request significa simplemente:
solicitud.
Podemos representarla de manera conceptual:
OPERACIÓN
buscar documentos
PARÁMETROS
proveedor = ACME
tipo = anexo_seguridadEn una API web real podría verse como algo semejante a:
GET /documents?provider=ACME&type=security_scheduleNo necesitamos memorizar esta sintaxis.
Lo importante es leer su estructura:
GET
solicitud de obtener información
/documents
recurso u operación
provider=ACME
parámetro
type=security_schedule
otro parámetroResponse: recibir una respuesta
El sistema procesa la request y devuelve una response.
Podría ser:
{
"documents": [
{
"id": "DOC-021",
"name": "Anexo_Seguridad_ACME_2026.pdf",
"status": "signed"
}
]
}La response contiene información estructurada.
Aquí podemos interpretar:
id → identificador interno
name → nombre del documento
status → estadoLa tool puede transformar esta respuesta antes de entregarla al modelo.
El modelo no necesita conocer todos los detalles técnicos de la API.
Request y response forman un intercambio
Podemos representarlo así:
La API funciona como interfaz entre la tool y el sistema.
Parámetros: especificar qué queremos
Una misma operación puede producir resultados diferentes según los valores enviados.
Por ejemplo:
buscar_documentos(proveedor = "ACME")no es lo mismo que:
buscar_documentos(proveedor = "BETA")Ni:
tipo = "contrato"es lo mismo que:
tipo = "anexo_seguridad"Los parámetros permiten concretar la petición.
Y precisamente por eso constituyen una superficie de error.
Parámetros válidos y parámetros correctos
Supongamos que la API exige un campo de texto denominado provider.
Estas dos requests pueden ser técnicamente válidas:
provider = ACMEprovider = ACNELa API puede aceptar ambas.
Pero sólo una corresponde a nuestra tarea.
Volvemos a la distinción:
VALIDACIÓN TÉCNICA
¿cumple la forma esperada?
VALIDACIÓN SUSTANTIVA
¿es el valor correcto para esta tarea?No todo puede resolverse mediante el schema.
Métodos y operaciones
Las APIs web suelen distinguir tipos de operación.
No necesitamos estudiar HTTP en detalle, pero resulta útil reconocer una intuición muy básica.
Podemos tener operaciones orientadas a:
OBTENER
leer información
CREAR
generar un objeto nuevo
ACTUALIZAR
modificar uno existente
ELIMINAR
borrarLa nomenclatura técnica concreta puede variar según la API.
La enseñanza importante es que una misma interfaz puede exponer capacidades con efectos muy diferentes.
Esto conecta directamente con permisos.
Autenticación: ¿quién está llamando?
Hasta ahora hemos supuesto que cualquiera puede utilizar la API.
En sistemas reales eso sería normalmente inaceptable.
Antes de responder, el servicio necesita establecer quién realiza la solicitud.
A este problema lo llamamos autenticación.
Pregunta:
¿Quién eres?
La implementación puede utilizar claves, tokens, certificados u otros mecanismos.
No necesitamos aprenderlos ahora.
Lo importante es comprender el concepto.
Una aplicación puede realizar llamadas usando:
- la identidad del usuario;
- una cuenta de servicio;
- una credencial de la organización;
- otra identidad técnica.
Esa elección importa porque determina qué actor aparece frente al sistema externo.
Autenticación no es autorización
Supongamos que el sistema confirma:
Usuario: abogada AEso demuestra identidad.
Todavía no responde:
¿puede leer el matter X?
¿puede modificar el documento Y?
¿puede enviar mensajes?Esa segunda pregunta corresponde a autorización.
Podemos fijar la diferencia:
AUTENTICACIÓN
¿quién eres?
AUTORIZACIÓN
¿qué estás autorizado a hacer?Permisos: ¿qué operación y sobre qué recurso?
Una autorización bien diseñada no tiene por qué ser binaria.
No necesitamos elegir entre:
sin accesoy:
acceso totalPodemos delimitar:
leer contratos del matter ACMEsin permitir:
eliminar contratosO permitir:
crear borradoressin permitir:
aprobarlosLa API puede participar en la aplicación de estos permisos, pero la política puede involucrar también otras capas del sistema.
Scope: alcance de una credencial
Muchas integraciones utilizan la idea de scope o alcance.
Sin entrar en protocolos específicos, la intuición es:
una credencial puede estar autorizada para ciertas clases de acciones y no para otras.
Por ejemplo:
read:documentspodría permitir lectura.
write:documentspodría permitir escritura.
La sintaxis real varía.
Lo importante es que la autenticación puede combinarse con permisos limitados.
API ≠ Tool
Llegamos a una distinción central.
La API es una interfaz técnica de otro sistema.
La tool es una capacidad que decidimos exponer a nuestra aplicación basada en modelos.
Supongamos que la API del DMS permite:
buscar
crear
actualizar
eliminar
compartir
cambiar propietario
modificar permisosNo necesitamos exponer todo eso como una única tool.
Podemos construir:
buscar_contratos_autorizados(proveedor)La tool utiliza por debajo sólo una parte de la API.
flowchart LR
M[Modelo] --> T[Tool<br/>buscar_contratos]
T --> W[Wrapper / integración]
W --> A[API del DMS]
A --> D[DMS]
La capa intermedia puede:
- limitar operaciones;
- validar argumentos;
- aplicar permisos;
- transformar responses;
- registrar llamadas;
- ocultar complejidad innecesaria.
Una buena tool no necesita exponer toda la API
La API puede describir todo lo que un servicio permite hacer.
La tool debería exponer sólo la capacidad que el sistema necesita para su finalidad.
Menos superficie operacional suele facilitar control, evaluación y seguridad.
APIs y modelos como servicio
Las APIs también pueden utilizarse para acceder al propio modelo.
Huyen destaca que el modelo-as-a-service permite enviar una consulta mediante API y recibir una salida sin tener que desplegar toda la infraestructura del modelo.
Esto muestra que “API” no significa específicamente “tool”.
Puede existir:
API de modelo
API de DMS
API de correo
API de calendario
API financieraUna API es una forma general de interacción entre software.
Errores de API
Una request puede fallar por muchas razones.
Por ejemplo:
recurso inexistente
credencial vencida
permiso insuficiente
parámetro inválido
límite de uso excedido
servicio no disponibleLa tool debe decidir cómo traducir esos errores a información útil para la aplicación.
Un mensaje como:
403puede ser insuficiente para el modelo o el usuario.
Una traducción más informativa podría ser:
No tienes permiso para consultar este repositorio.
No intentes buscar el documento mediante otra identidad.
Solicita acceso al responsable del matter.Esto muestra que la integración no consiste sólo en “conectar la API”.
También requiere diseñar comportamiento ante fallos.
Un caso jurídico completo
Nuestra aplicación necesita recuperar el anexo de seguridad.
Tool
buscar_documentos(
proveedor = "ACME",
tipo = "anexo_seguridad"
)Request a la API
Conceptualmente:
buscar documentos
provider = ACME
type = security_scheduleAutenticación
La API recibe la solicitud con la identidad correspondiente.
Autorización
Comprueba si esa identidad puede leer el repositorio.
Response
DOC-021 | Anexo_Seguridad_ACME_2026.pdf | firmadoTool output
La tool transforma la response y devuelve al sistema sólo lo necesario.
Modelo
El modelo continúa:
Existe un anexo firmado de 2026. Debe recuperarse para completar el análisis.Ahora podemos ver con claridad que cada capa cumple una función distinta.
Por qué importa para abogados y procurement
Si un proveedor afirma:
“Nuestra aplicación se integra por API con sus sistemas”
la frase todavía deja muchas preguntas abiertas.
Necesitamos saber:
¿con qué sistemas?
¿qué operaciones?
¿qué datos?
¿con qué identidad?
¿qué scopes o permisos?
¿puede escribir?
¿puede eliminar?
¿qué ocurre si la API cambia?
¿cómo se registran llamadas?Comprender la arquitectura permite formular requisitos contractuales mucho más precisos.
Endpoint: una dirección funcional dentro de la API
Sin entrar en ingeniería web avanzada, conviene reconocer una palabra que aparece con frecuencia en documentación técnica: endpoint.
Podemos entenderlo como un punto concreto de la API donde se solicita una determinada operación o recurso.
Por ejemplo:
/documentspodría ser un endpoint relacionado con documentos.
Y:
/providersotro relacionado con proveedores.
No necesitamos asumir que todas las APIs utilizan exactamente esta estructura. La utilidad del concepto es poder leer documentación y distinguir:
API
interfaz completa
ENDPOINT
punto concreto dentro de esa interfazLa request puede contener más que parámetros visibles
Una solicitud real puede incluir también información técnica que el usuario no escribe manualmente.
Por ejemplo:
credencial de autenticación
identificador de la aplicación
tipo de contenido
información de sesiónEsto importa porque parte del flujo de datos puede permanecer invisible en la interfaz humana.
Cuando evaluamos una integración, la pregunta no debería limitarse a “¿qué escribió el usuario?”. También puede ser relevante saber qué datos técnicos acompañan cada llamada.
La response puede contener más información de la necesaria
Del mismo modo, una API puede devolver campos que la aplicación no necesita.
Supongamos una response con:
nombre
correo
id interno
departamento
historial completo
permisos
metadata técnicasi la tool sólo necesita:
estado del proveedorUna integración bien diseñada puede filtrar el resto.
Esto aplica una forma de minimización arquitectónica: no transportar ni exponer datos simplemente porque la API puede devolverlos.
Los códigos de error no son el error mismo
Las APIs suelen comunicar estados técnicos mediante códigos o estructuras.
Un 401, 403 o 404 puede ser significativo para un desarrollador, pero un usuario jurídico necesita comprender su efecto funcional.
Por ejemplo:
401
→ identidad no autenticada o credencial inválida
403
→ identidad reconocida pero operación no autorizada
404
→ recurso no encontradoLa interpretación exacta depende de la API, pero la distinción ayuda a diagnosticar.
No es lo mismo:
el documento no existeque:
el usuario no puede verloConfundir ambos podría llevar al modelo a una conclusión incorrecta sobre el expediente.
API estable no significa comportamiento estable del sistema
También conviene recordar una observación de Huyen: una API puede mantenerse formalmente igual mientras cambia el servicio que existe detrás.
Por ejemplo, un proveedor de modelos puede conservar la misma interfaz y actualizar el modelo subyacente.
En otros sistemas puede cambiar:
lógica interna
datos
versiones
límitessin que la request principal parezca diferente.
Por eso al contratar una API no basta con documentar la sintaxis. También importa qué prestación se promete detrás de esa interfaz y cómo se gestionan cambios.
Qué debes recordar
Una API es una interfaz programática entre sistemas.
La interacción básica puede pensarse como:
REQUEST
solicitud
↓
API
↓
RESPONSE
resultadoLos parámetros especifican qué pedimos.
La autenticación responde quién realiza la solicitud.
La autorización determina qué puede hacer esa identidad.
Y una tool puede utilizar una API sin ser idéntica a ella.
El problema que todavía queda abierto
Las APIs nos permiten construir integraciones, pero hacerlo desde cero puede exigir bastante trabajo técnico.
Para cada sistema hay que conocer operaciones, autenticación, errores, formatos y mantenimiento.
Muchas veces esa integración ya viene preparada.
El siguiente nodo introduce precisamente esa capa: los connectors, es decir, integraciones construidas para conectar aplicaciones, repositorios, DMS, correo, calendario y otros sistemas con mayor facilidad.