Bibliotecas de cliente

La API REST es HTTP y JSON a secas, y una llamada con fetch es una forma perfectamente válida de usarla. Las bibliotecas de cliente existen para las partes que a nadie le apetece escribir dos veces: reintentar bien una solicitud que ha topado con el límite, hacer que una creación reintentada sea segura y recorrer un cursor hasta el final de una lista.

Tres bibliotecas, un mismo contrato:

| Lenguaje | Paquete | Código fuente | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

Instalación

Los paquetes todavía no están en npm, PyPI ni Packagist. La publicación depende de las cuentas en los registros; el código está terminado y hoy se instala desde una copia local del repositorio, y los comandos de abajo se convertirán en un solo npm install @linkprofit/sdk (y sus equivalentes) en cuanto existan esas cuentas.

Node, desde una copia local:

npm install /path/to/linkprofit/packages/sdk-node

Python, desde una copia local:

pip install /path/to/linkprofit/sdk/python

PHP, mediante un repositorio de tipo path de Composer en tu composer.json:

{
  "repositories": [
    { "type": "path", "path": "/path/to/linkprofit/sdk/php" }
  ],
  "require": {
    "linkprofit/linkprofit-php": "*"
  }
}

Lo que las tres hacen igual

Las bibliotecas son deliberadamente aburridas y deliberadamente parecidas. Aprende el comportamiento una vez y te vale en cualquier lenguaje.

Autenticación. Le pasas una clave de espacio de trabajo (lp_live_…) y el cliente pone la cabecera Authorization en cada solicitud. La URL base es una opción, así que el mismo código puede ejecutarse contra una instancia local en las pruebas. Consulta Autenticación para los alcances y la rotación.

Reintentos que respetan al servidor. Un 429 o un 5xx pasajero se reintenta con espera creciente, y Retry-After se respeta en lugar de adivinarse: el servidor ya sabe cuándo se libera la ventana. El número de intentos está topado, y una solicitud que falla por sus propios motivos (validation_failed, conflict, not_found) no se reintenta nunca: repetir una solicitud incorrecta solo gasta presupuesto del límite de solicitudes.

Mutaciones idempotentes. Toda llamada que modifica algo lleva una Idempotency-Key, así que un reintento tras un tiempo de espera agotado en la red devuelve la respuesta guardada en lugar de crear un segundo enlace. Puedes aportar tu propia clave —el id de un pedido, el id de una tarea— cuando el reintento pueda venir de otro proceso o de una ejecución posterior. Las claves viven 24 horas; la misma clave con un cuerpo distinto responde 409.

Paginación por cursor como iterador. Los endpoints de listado se paginan por cursor, y los clientes los exponen como iteradores: tú recorres los enlaces, el cliente pide la página siguiente cuando se agota la actual y se detiene cuando el cursor vale null. Sin aritmética de páginas y sin el riesgo de ese desfase de uno que se come una fila en silencio.

Errores como excepciones. Los fallos lanzan el tipo de error natural de cada lenguaje, con el code de la API, el mensaje para personas y, en los fallos de validación, los details por campo. Ramifica según el código y no según el texto del mensaje: los códigos son el contrato documentado.

Los tipos de solicitud y respuesta del cliente de Node se generan a partir del mismo documento OpenAPI que renderiza la referencia —publicado en /openapi.json—, así que los tipos no pueden desviarse de la API en funcionamiento. Los clientes de Python y PHP siguen ese mismo documento a mano, con los modismos de su lenguaje.

Inicio rápido

Cada paquete incluye un README con toda su superficie; los fragmentos de abajo muestran la forma que comparten los tres: construyes un cliente con una clave, llamas al grupo de recursos y recibes de vuelta un objeto tipado.

Node

import { LinkProfit } from "@linkprofit/sdk";

const client = new LinkProfit({ apiKey: process.env.LINKPROFIT_API_KEY });

const created = await client.createLink({
  url: "https://example.com/summer-sale",
  title: "Summer sale",
});

console.log(created.data.short_url);

Python

import os

from linkprofit import LinkProfit

client = LinkProfit(os.environ["LINKPROFIT_API_KEY"])

created = client.create_link(
    {"url": "https://example.com/summer-sale", "title": "Summer sale"}
)

print(created["data"]["short_url"])

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LinkProfit\LinkProfit;

$client = new LinkProfit(getenv('LINKPROFIT_API_KEY'));

$created = $client->createLink([
    'url' => 'https://example.com/summer-sale',
    'title' => 'Summer sale',
]);

echo $created['data']['short_url'];

Cuál conviene usar

• Node / TypeScript — la superficie más completa, porque sus tipos salen directamente del documento OpenAPI. La opción natural para un backend en JavaScript, una función serverless o un script de compilación.
• Python — para informes y trabajo con datos: llevar las analíticas a un cuaderno, a una tarea programada o a la alimentación de un panel.
• PHP — para el mundo de los CMS. Un plugin de WordPress o un servicio en Laravel que acorta enlaces a medida que se publica el contenido.
• Ninguna de ellas — si tu lenguaje es otro, la API es HTTP corriente. El inicio rápido empieza por curl, y todo lo que hacen los clientes (reintentos, idempotencia, cursores) es comportamiento documentado que puedes implementar en cincuenta líneas.

Elijas lo que elijas, la referencia de la API es la lista completa de endpoints, campos y códigos de error: las bibliotecas son una comodidad por encima de ella, nunca una API distinta.

También merece la pena leer

• Límites de solicitudes — el presupuesto dentro del cual trabaja la lógica de reintentos.
• Webhooks — recibe los eventos empujados en lugar de sondearlos.
• Servidor MCP — las mismas operaciones desde un asistente de IA.