¿Qué es un SDK? SDK, biblioteca, framework y API

Un SDK (software development kit) empaqueta una capacidad junto con todo lo necesario para usarla: una o varias API, dependencias de ejecución, configuración y credenciales, documentación y ejemplos, y a veces una herramienta de línea de comandos. Lo que convierte un paquete en SDK no es la cantidad de código, sino si entrega también el trabajo alrededor: autenticación, errores y herramientas. La diferencia es concreta. Una biblioteca resuelve «estabas cansado de escribir esta lógica, usa la mía». Un SDK resuelve «necesitas integrar esta capacidad externa y he pensado todo, desde la autenticación hasta el manejo de fallos».

Distinguir los cuatro términos

Dimensión API Biblioteca Framework SDK
Quién llama a quién Tú envías peticiones Tú la llamas Él te llama Tú lo llamas, y trae herramientas
Forma Un contrato de interfaz (HTTP o firma de función) Código reutilizable Esqueleto, convenciones y ciclo de vida Paquete, documentación, configuración y ejemplos, quizá una CLI
Control Todo tuyo Todo tuyo El framework decide el flujo Tuyo: un SDK no se apodera de la estructura de la app
Ejemplo típico Endpoints REST, GraphQL Fechas, gráficos Framework front o back SDK de nube, de pagos, de feedback
Lo que aún haces tú Todo Ensamblar y llamar Rellenar lógica dentro de las convenciones Pedir credenciales, inicializar según la documentación
Regla mnemotécnica: una API es un contrato, una biblioteca es una pieza, un framework es un esqueleto y un SDK es la pieza más el manual más el esquema de conexión.

Qué suele haber dentro de un SDK

Componente Función Qué se rompe sin él
Envoltorio de la API Convierte detalles HTTP, reintentos y códigos de error en funciones Cada integrador lo reescribe, con comportamiento distinto
Runtime y dependencias Hace que funcione en el entorno objetivo (navegador, servidor Node) Conflictos de versión, tamaño de bundle descontrolado
Configuración y credenciales Claves, región, entorno, interruptores Secretos en duro, test y producción mezclados
Documentación y ejemplos Lleva a alguien a la primera llamada en diez minutos La integración depende de preguntar a una persona y el soporte recae en ti
Herramientas (opcional) CLI, panel de depuración, definiciones de tipos Diagnosticar se vuelve adivinar
La última fila suele tratarse como un extra. En realidad decide la reputación del SDK: los SDK con tipos completos y herramientas de depuración generan bastante menos retrabajo en los integradores.

Tres formas de distribuir, tres perfiles de coste

Forma Cómo se fija la versión Quién actualiza Coste principal
Gestor de paquetes (npm y similares) El lockfile fija una versión El integrador, a propósito Requiere pipeline de build; las versiones antiguas viven años
Etiqueta script (CDN) Determinada por la URL o la configuración El proveedor La CSP debe permitir el dominio; hay que diseñar la caché
Integrado en una plataforma Sigue la versión de la plataforma La plataforma No controlas casi nada el ritmo
La etiqueta script encaja en todo lo que «los visitantes también deben usar»: sin instalación, sin build, una línea y funciona. El precio es que la compatibilidad de versiones y la lista blanca de CSP son tuyas. Por eso muchos SDK de feedback y soporte eligen esta vía.

El coste oculto de un SDK propio

Empaquetar una función como SDK es fácil. Convivir con ella cinco años no:
  • Compatibilidad hacia atrás: nombres de funciones, parámetros y momentos de callback no cambian libremente tras publicarse. Un cambio y todos los integradores tienen que seguirlo.
  • Tamaño y rendimiento: el SDK corre en la página de otro. 100 KB extra pueden mover sus métricas de primer render.
  • Privacidad y cumplimiento: qué se recoge, cuánto se guarda y si se puede desactivar debe estar escrito y ser cierto — nuestros límites están en la política de privacidad.
  • Observabilidad: cuando el SDK falla, los integradores solo dicen «lo vuestro está roto». Necesitas tu propio reporte de errores y distribución de versiones.
  • Documentación y ejemplos: un SDK sin documentación no es un SDK; el coste vuelve como tickets de soporte.
  • De estos cinco, los tres primeros son los clásicos «invisibles antes del lanzamiento, inevitables después».

    Cómo es un SDK de feedback

    El SDK web de BugCapturer requiere dos pasos: crear un proyecto y definir una lista blanca de dominios en la consola, y luego poner el script en la página.
    html
    <script>window.BugCapturerConfig={key:"bcpk_xxxxxxxx",position:"bottom-right",requireContact:false}</script>
    <script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>
    
    La superficie de configuración es pequeña y cada opción tiene un límite claro:
    Opción Función Atención
    key Identificador del proyecto Público por diseño; el acceso lo limita la lista blanca de dominios
    position Posición del acceso flotante No tapar botones de pago o de soporte
    requireContact Si el visitante debe dejar contacto Desactivar en sitios públicos o baja la tasa de envío
    reporter Identidad de quien reporta, la pasa el sitio Nunca codificar una sola persona; rellenar desde la sesión
    La experiencia del visitante conviene contarla con precisión: quien tiene la extensión le delega la captura, sin ningún diálogo de permiso; quien no la tiene ve un permiso del navegador por informe y luego se toma la captura. Es el modelo de seguridad del navegador, no pereza — cualquier SDK web que prometa «capturas totalmente invisibles» merece una pregunta sobre cómo lo hace. La instalación completa está en el inicio rápido del SDK web; este artículo no la repite.

    Un SDK no es una extensión del navegador

    A ambos se les llama «formas de integrar», pero sus fronteras difieren:
    Dimensión SDK Extensión del navegador
    Quién lo instala El sitio, en el código Cada persona, individualmente
    A quién alcanza A todos los visitantes Solo a quien la instaló
    Origen del permiso Lista blanca de dominios más consentimiento por informe Permisos declarados por la extensión
    Encaja en Recoger feedback de clientes Pruebas y revisiones internas
    Límite principal Exige cambios de código en el sitio Los clientes no instalan una extensión por un sitio
    Así que «que los clientes puedan reportar» es, en esencia, un problema de SDK o de enlace compartido; la extensión es para uso interno. El equilibrio está en Extensión de Chrome vs herramientas de escritorio.

    Leer los números de versión

    El versionado importa más que en una biblioteca normal, porque quien actualiza no eres tú:
    • Mayor: cambios incompatibles; los integradores deben tocar código.
    • Menor: funciones nuevas, compatibles hacia atrás; normalmente seguro.
    • Parche: correcciones; riesgo más bajo.
    Con etiqueta script, la versión vive en la URL. Los proveedores deberían ofrecer dos modos: fijado (el integrador decide cuándo moverse) y automático (siempre la última). Fijado es estable; automático es cómodo, pero solo si confías en que una actualización no romperá la página de nadie — justo donde nacen muchos incidentes de SDK.

    Cinco preguntas antes de integrar un SDK

    Pregunta Por qué importa Cómo es una buena respuesta
    ¿Qué permisos pide? Scripts y extensiones pueden leer el contenido de la página Alcance mínimo, cada permiso explicado, se puede desactivar
    ¿Qué datos recoge? Cumplimiento y confianza del cliente Lista clara, campos sensibles enmascarados, plazo de conservación
    ¿Un fallo puede tumbar la página? Los errores de scripts de terceros se propagan Los timeouts no bloquean el flujo principal, errores aislados
    ¿Tamaño y momento de carga? Impacto directo en el primer render Carga asíncrona, inicio bajo demanda, tamaño publicado
    ¿Cómo salimos? El coste de migración se subestima Exportar datos, quitar en una línea, sin residuos
    Las preguntas dos y cinco son las que más se omiten, y las que se convierten en problema seis meses después.

    Construirlo o comprarlo

    Tu situación Recomendación
    La capacidad es tu negocio central (tú eres el servicio de pagos) Construirlo; el SDK es el producto
    Solo necesitas un punto de entrada y nadie para mantenerlo Comprar o adoptar, y dedicar el tiempo a negocio
    El cumplimiento exige que los datos no salgan de tu red Construir o autoalojar, tras calcular el mantenimiento
    Menos de cinco ingenieros y sin infraestructura front Empezar con etiqueta script; no construir tu propio empaquetado
    El único criterio que importa: ¿esta capacidad va a seguir comiéndose tu hoja de ruta? Si sí, constrúyelo. Si no, no asumas un pasivo a largo plazo por sentir control.

    Tres malentendidos frecuentes

    • Llamar SDK a una API: documentación de endpoints sin envoltorio, ejemplos ni configuración sigue siendo una API.
    • Tratar un SDK como framework: un SDK no debe apoderarse de la estructura de la app. Si impone tu árbol de carpetas, es un framework.
    • Cuanto más completo, mejor: un SDK que lo hace todo suele implicar bundle grande, permisos amplios y actualizaciones arriesgadas. Importa lo que necesitas.

    FAQ

    ¿Qué relación hay entre SDK y API? Un SDK normalmente contiene un envoltorio de una API. La API es el contrato; el SDK es su implementación con herramientas y documentación. ¿SDK versus biblioteca en una frase? Una biblioteca es código que llamas. Un SDK es todo lo necesario para integrar una capacidad: biblioteca, configuración, documentación y herramientas incluidas. ¿Una etiqueta script de front-end es un SDK? Sí. La distribución no decide si es un SDK; solo decide cómo se reparten versiones y responsabilidad de actualización. ¿Afecta el rendimiento de la página? Sí, según tamaño y momento de carga. Cargar en asíncrono e inicializar bajo demanda es lo habitual; el proveedor debería publicar el tamaño. ¿Hay que cambiar la configuración de build? Con etiqueta script, no — por eso encaja en sitios públicos. Con gestor de paquetes, sí, a cambio de fijar versión y disponer de tipos.