La API, per automatitzar el teu compte

Què hi guanyes: llegir i canviar coses del teu compte des dels teus propis programes: baixar-te les factures a la teva comptabilitat, obrir tiquets des del teu sistema d’incidències, consultar l’estat dels teus serveis.

Dues maneres d’entrar, i no serveixen per al mateix

Amb què	Per a quina part	Quant dura
Clau d’API	Els teus llocs: webs, dominis, DNS, correu, bases de dades, FTP i certificats.	No caduca fins que tu la revoques.
Usuari i contrasenya (token JWT)	Factures, tiquets, avisos i el teu perfil.	60 minuts, i cal renovar-lo.

Si el que vols és automatitzar els teus llocs —una còpia de seguretat nocturna, un pas del teu pipeline, un script que crea el lloc de cada client nou— el que necessites és la clau d’API. És el que comença aquí sota.

Important

Per a la part de llocs, el token JWT no funciona. No és que estigui desaconsellat: retorna un error de permisos. Fes servir la clau.

Crear la teva clau

Al tauler, a Compte ‣ Claus per a IA. La clau es mostra una sola vegada: copia-la en aquell moment i desa-la on desis les teves contrasenyes. Si la perds, no es recupera — es revoca i se’n crea una altra.

nxp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Què pot fer la teva clau

Una clau acabada de crear només llegeix. Els permisos van per separat perquè els riscos són diferents:

Permís	Què obre	Com s’aconsegueix
`sitios:leer`	Consultar (`GET`)	En crear la clau
`sitios:escribir`	Crear i canviar (`POST`, `PUT`, `PATCH`)	Demana’l en un tiquet
`sitios:borrar`	Esborrar (`DELETE`)	Demana’l en un tiquet

Esborrar no va dins d’escriure expressament: crear un lloc de més s’arregla esborrant-lo; esborrar el que no tocava, no.

Si a la teva clau li falta el permís, la resposta et diu quin falta. No ho has d’endevinar provant.

Fer-la servir

Una capçalera, a cada petició:

Authorization: Bearer nxp_tu_clave

O X-API-Key: nxp_tu_clave si la teva eina no et deixa tocar Authorization.

Un exemple sencer, llistar els teus llocs:

curl -H "Authorization: Bearer $HOSTBRID_TOKEN" \
     https://my.hostbrid.com/api/sites/v1/sites/

I crear-ne un:

curl -X POST \
     -H "Authorization: Bearer $HOSTBRID_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"domain": "ejemplo.com", "php_version": "8.3"}' \
     https://my.hostbrid.com/api/sites/v1/sites/

Tip

Si prefereixes no escriure curl, hi ha una eina de línia d’ordres que fa el mateix en una línia.

La llista completa d’operacions

És a https://my.hostbrid.com/api/docs/, i es llegeix sense compte. Cada operació diu el permís que necessita.

Només veus el que és teu

Tot va acotat al teu compte. Demanar per identificador alguna cosa d’un altre client retorna 404, no 403: un 403 confirmaria que aquest identificador existeix.

Límits

Cada clau té el seu propi límit de peticions per minut. Quan te’n passes, la resposta és un 429: espera i torna-ho a provar. El comptador de l’API va a part del de la botiga, així que automatitzar còpies de seguretat no et deixa sense cercador de dominis al web.

Si creus que la clau s’ha filtrat

Revoca-la al tauler, a la mateixa pantalla on la vas crear. Deixa de valer a l’instant. Després crea’n una altra: no hi ha manera de «canviar-li la contrasenya» a una clau, i és expressament.

Factures, tiquets i perfil: això continua amb usuari i contrasenya

Aquesta part encara no accepta la clau. Es demana un token:

POST /api/v1/auth/token/

{ "username": "tu-usuario", "password": "tu-contraseña" }

i respon access (60 minuts, el que es fa servir a cada petició) i refresh (7 dies, el que serveix per demanar-ne un altre, a /api/v1/auth/token/refresh/).

Si tens la verificació en dos passos activada, cal enviar a més el codi de sis dígits al camp otp, i només en demanar el token, no a cada petició.

Important

El token de renovació canvia cada vegada que el fas servir: la resposta en porta un de nou i l’anterior deixa de valer. Desa sempre l’últim.

Per això aquesta part no serveix per a processos desatesos: renovar necessita la teva contrasenya, i amb verificació en dos passos, un codi que un programa no pot teclejar. Estem treballant perquè la clau valgui també aquí. Si és el que necessites, digues-nos-ho en un tiquet: serveix per prioritzar-ho.

Què hi ha a la part d’usuari i contrasenya

Filtrat al teu compte, com tot: només veus el que és teu.

Per a què	On
Resum del teu compte — comptadors de tots els mòduls alhora	`GET /api/v1/dashboard/stats/`
Factures — llistar-les i llegir-les, amb número, base, impostos, total i línies de detall	`GET /billing/api/invoices/`
Subscripcions — quins plans tens i fins quan	`GET /billing/api/subscriptions/`
Pagaments — l’històric	`GET /billing/api/payments/`
Dades de facturació — les teves dades fiscals	`/billing/api/profiles/`
Consum — els registres d’ús que es facturen	`GET /billing/api/usage/`
Tiquets — obrir-los, llegir-los i respondre	`/tickets/api/tickets/`
Avisos — les notificacions del tauler	`/notifications/api/v1/notifications/`
Les teves claus SSH	`/accounts/api/ssh-keys/`
El teu perfil	`/accounts/api/`

Les factures són de només lectura expressament: les emet el sistema, i una factura emesa no s’esborra ni s’inventa des de fora.

Exemple amb el token: baixar-se les factures

En tres passos:

1. POST /api/v1/auth/token/
   { "username": "…", "password": "…" }
   → guarda "access" y "refresh"

2. GET /billing/api/invoices/
   Authorization: Bearer <access>
   → la primera página de facturas

3. GET /billing/api/invoices/?page=2
   Authorization: Bearer <access>
   → las siguientes

Les llistes vénen paginades de 20 en 20. La resposta porta l’enllaç a la pàgina següent; segueix aquest enllaç fins que no n’hi hagi més.

El que pots fer depèn del teu rol

Dins d’una organització hi ha tres rols, i l’API els respecta igual que el tauler:

Administrador i membre — poden llegir i canviar.
Només lectura — poden llegir, i qualsevol intent de crear o esborrar respon que no tens permisos suficients.

Si una petició d’escriptura et retorna un error de permisos i creus que no hauria de ser així, mira primer quin rol tens a l’organització.

El que encara no està llest

Què	Estat
La clau per a factures, tiquets i perfil	Avui la clau només obre la part de llocs. L’altra continua amb usuari i contrasenya. En curs.
Desplegament des de git (Projects) i el seu CLI	En desenvolupament. L’eina de línia d’ordres que ja existeix (La terminal: hostbrid) és per al hosting, no per a això.
Avisos automàtics cap als teus sistemes (webhooks)	No disponibles per a clients encara.

Problemes freqüents

Amb la clau, tot em respon que no estic autenticat: Comprova que la capçalera diu Bearer, un espai, i la clau sencera començant per nxp_. Si continua, mira al tauler que no l’hagis revocada.
Amb la clau, els llocs em donen error de permisos i la resta també: Estàs fent servir la clau contra factures o tiquets: allà encara no val. Aquesta part va amb usuari i contrasenya.
Amb el token, tot em respon que no estic autenticat: Gairebé sempre és que han passat els 60 minuts. Renova el token. I si l’estàs fent servir contra /api/sites/v1/, allà no funciona: fes servir la clau.
El refresc em diu que el token no val: Estàs reutilitzant-ne un de ja gastat. Cada renovació en retorna un de nou: desa sempre l’últim. Si l’has perdut, torna a demanar la parella amb usuari i contrasenya.
Demano el token i me’l rebutja encara que la contrasenya és bona: Tens la verificació en dos passos activada i falta el camp otp.
Em respon que no tinc permisos: O el teu rol és de només lectura, o estàs demanant alguna cosa d’una altra organització.

Si et falta alguna cosa, digues-ho

Aquesta part està creixent. Si necessites una dada o una operació que no és a la taula, obre’ns un tiquet explicant què vols automatitzar. És la millor manera que aparegui aquí.