Un'API REST che copre tutto quello che fa la dashboard

Due ambiti di chiave, perché ci sono due tipi di chiamante

Una chiave di area di lavoro agisce dentro una sola area di lavoro: link, analytics, domini a essa disponibili e il proprio consumo. Una chiave partner agisce su tutta l'attività: i clienti e i loro abbonamenti, i piani che vendi, tutti i domini, i pagamenti con il dettaglio delle commissioni, i payout e una panoramica aggregata delle analytics. I due prefissi sono visibilmente diversi, così una chiave incollata nel servizio sbagliato fallisce subito invece di fare qualcosa di sorprendente.

Le chiavi si creano nella dashboard, si mostrano una volta sola e si memorizzano solo come hash. Ogni chiave porta il proprio elenco di ambiti, così a un'integrazione che deve solo leggere le analytics si può dare una chiave che non può creare né cancellare nulla. Alle chiavi si può dare una data di scadenza e si possono revocare all'istante, e viene mostrata l'ultima volta in cui ciascuna è stata usata: è così che trovi l'integrazione che nessuno ricorda di aver configurato.

• ✓POST /links, GET /links, GET /links/{id}, PATCH /links/{id}, DELETE /links/{id}
• ✓POST /links/bulk — fino a cento link per chiamata
• ✓GET /links/{id}/qr — PNG o SVG, con un preset e una dimensione
• ✓GET /analytics/summary, /timeseries, /breakdown, /links/top, /export.csv
• ✓GET e POST /domains — collega un dominio e leggi i record DNS che gli servono
• ✓GET /workspace — limiti del piano e consumo corrente
• ✓GET /partner/clients, /partner/plans, /partner/payments, /partner/payouts

Prevedibile nei modi che contano alle tre di notte

Ogni errore ha la stessa forma — un codice, un messaggio leggibile e un URL di documentazione — così una libreria client può ramificare sul codice e una persona può leggere il messaggio. Gli elenchi sono paginati con cursori invece che con numeri di pagina, il che mantiene stabili i risultati mentre sotto di te vengono creati nuovi link.

I limiti di frequenza sono per impostazione predefinita seicento richieste al minuto su una chiave di area di lavoro e il doppio su una chiave partner, con il limite, il residuo e l'orario di reset restituiti come header su ogni risposta. Superarli restituisce 429 con un header Retry-After invece di una connessione azzerata, così i client ben educati arretrano correttamente. Le esportazioni di analytics sono in streaming, quindi centomila righe non richiedono di tenere un report in memoria da nessuna delle due parti.

Webhook per gli eventi che altrimenti dovresti interrogare

Registra un endpoint e ricevi creazione, aggiornamento e cancellazione dei link; gli eventi del ciclo di vita del dominio via via che un hostname passa da in attesa di SSL ad attivo o in stato di errore; e, sulle chiavi partner, gli eventi di abbonamento e pagamento dei clienti. Interrogare un endpoint di stato del dominio una volta al minuto è esattamente il tipo di codice che nessuno dovrebbe scrivere.

Ogni consegna porta un header di firma HMAC-SHA256 con marca temporale, così il tuo ricevitore può verificare che il payload venga da noi e non sia una ripetizione. Le consegne fallite vengono ritentate cinque volte con intervalli crescenti — un minuto, cinque, trenta, due ore, dodici — dopo di che l'endpoint viene marcato come guasto e parte un'email. Dalla dashboard si può inviare un evento di prova, così l'integrazione è verificabile prima che qualcosa di reale dipenda da essa.

Documentazione generata dal codice che gira

La specifica OpenAPI è costruita dagli stessi schemi con cui l'API valida le richieste, il che significa che non può divergere dall'implementazione come succede a un reference scritto a mano. È pubblicata come file che puoi dare in pasto a un generatore di client e resa come documentazione di riferimento navigabile su questo sito, accanto alle guide scritte a mano su avvio rapido, paginazione, errori, webhook e limiti di frequenza.

La versione uno è congelata. Possono essere aggiunti nuovi campi, il comportamento esistente non cambierà, e tutto ciò che romperebbe un chiamante aspetta una versione due a un percorso diverso. Se stai scegliendo un accorciatore su cui costruire, e non solo da usare, quella promessa vale più di qualsiasi singolo endpoint.

Codice che parla da sé

curl -X POST https://api.linkprofit.com/v1/links \
  -H 'Authorization: Bearer lp_live_XXXXXXXX' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/spring-collection",
    "domain_id": "dom_8kq2vn41",
    "slug": "spring",
    "title": "Spring collection",
    "utm": {
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "spring-2026"
    }
  }'

const response = await fetch("https://api.linkprofit.com/v1/links", {
  method: "POST",
  headers: {
    Authorization: "Bearer lp_live_XXXXXXXX",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/spring-collection",
    domain_id: "dom_8kq2vn41",
    slug: "spring",
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(error.code + ": " + error.message);
}

const link = await response.json();
console.log(link, response.headers.get("X-RateLimit-Remaining"));

import requests

response = requests.post(
    "https://api.linkprofit.com/v1/links",
    headers={"Authorization": "Bearer lp_live_XXXXXXXX"},
    json={
        "url": "https://example.com/spring-collection",
        "domain_id": "dom_8kq2vn41",
        "slug": "spring",
    },
    timeout=10,
)

if response.status_code == 429:
    raise SystemExit("rate limited, retry after " + response.headers["Retry-After"])

response.raise_for_status()
print(response.json())