API pública

Documentació de l’API de ja.cat

Integra ja.cat amb les teves eines per crear, consultar i gestionar enllaços escurçats de manera programàtica. Totes les peticions s’adrecen a https://servei.ja.cat i requereixen una clau API activa.

URL base

https://servei.ja.cat

Format

JSON

Autenticació

X-API-Key

Autenticació

Per utilitzar l’API cal activar l’accés des del panell i enviar la clau API a cada petició mitjançant la capçalera X-API-Key. Les peticions amb request body JSON han d’incloure també la capçalera Content-Type: application/json.

X-API-Key: LA_TEVA_CLAU_API
Content-Type: application/json

Autenticació:

Cal incloure la capçalera X-API-Key en totes les peticions als endpoints documentats.

Límits d’ús

L’API aplica un límit global de peticions per segon a tots els endpoints, i un límit mensual addicional a la creació d’enllaços (POST /url).

Peticions per segon

Màxim de peticions per segon per clau API. S’aplica a tots els endpoints.

Creacions al mes

1.000

Màxim d’enllaços que pots crear amb `POST /url` durant un període de 30 dies.

Si superes algun d’aquests límits, l’API respon amb el codi 429 Too Many Requests.

Referència ràpida

Mètode	Ruta
GET	/urls
POST	/url
PUT	/url/{id}
DELETE	/url/{id}
PUT	/estat/{id}
GET	/disponibilitat/{path}

Endpoints

Tots els endpoints requereixen la capçalera X-API-Key i retornen respostes en JSON.

Enllaços

Crea i gestiona els enllaços escurçats del teu compte.

GET /urls

Llistar enllaços · Paginació opcional

Recupera els enllaços creats amb la teva clau API. Retorna un array d’objectes `UrlSummary`.

Query `skip`: offset de paginació (integer, per defecte 0)
Query `limit`: màxim per pàgina (integer, per defecte 30)
Query `search_query`: filtra per àlies o URL de destinació (string, opcional)
Camps de la resposta: `id`, `alias`, `created_at`, `url`, `enabled`

Request

Paginació: `?skip=0&limit=10`

curl -s -H "X-API-Key: LA_TEVA_CLAU_API" "https://servei.ja.cat/urls?skip=0&limit=10"

Response 200 OK

[
  {
    "id": 1,
    "alias": "article",
    "created_at": "2026-01-15T10:00:00.000000Z",
    "url": "https://exemple.cat/article",
    "enabled": true
  }
]

POST /url

Crear un enllaç

Genera un enllaç curt a partir d’una URL de destinació.

Body (`Url`): `url` (obligatori, URI, 1–2083 caràcters)
`path`: àlies personalitzat (string, opcional; pot ser `null`)

Request

curl -s -X POST "https://servei.ja.cat/url" \
  -H "X-API-Key: LA_TEVA_CLAU_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://exemple.cat/article",
    "path": "article"
  }'

Response 200 OK

PUT /url/{id}

Editar un enllaç

Actualitza les propietats d’un enllaç existent.

Path `id`: identificador de l’enllaç
Body (`EditUrl`): `url` (obligatori, URI, 1–2083 caràcters)
`enabled`: activa o desactiva l’enllaç (boolean, opcional)

Request

curl -s -X PUT "https://servei.ja.cat/url/1" \
  -H "X-API-Key: LA_TEVA_CLAU_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://exemple.cat/article-actualitzat",
    "enabled": true
  }'

Response 200 OK

DELETE /url/{id}

Eliminar un enllaç

Elimina un enllaç que ja no necessites mantenir actiu.

Path `id`: identificador de l’enllaç

Request

curl -s -X DELETE "https://servei.ja.cat/url/1" \
  -H "X-API-Key: LA_TEVA_CLAU_API"

Response 200 OK

PUT /estat/{id}

Alternar l’estat de l’enllaç

Canvia l’estat actiu o inactiu d’un enllaç existent. No requereix request body.

Path `id`: identificador de l’enllaç

Request

curl -s -X PUT "https://servei.ja.cat/estat/1" \
  -H "X-API-Key: LA_TEVA_CLAU_API"

Response 200 OK

Utilitats

Consulta informació auxiliar abans de crear o personalitzar un enllaç.

GET /disponibilitat/{path}

Comprovar disponibilitat

Valida si un àlies personalitzat està disponible per a un enllaç nou.

Path `path`: àlies a comprovar

Request

curl -s -H "X-API-Key: LA_TEVA_CLAU_API" "https://servei.ja.cat/disponibilitat/meu-alias"

Response 200 OK

Errors

L’API retorna codis HTTP estàndard i un response body en JSON amb el detall de l’error, quan n’hi ha.

422

Error de validació

Alguns camps tenen un valor no vàlid o no compleixen les regles del servei. El response body segueix l’esquema `HTTPValidationError`.

429

Límit d’ús superat

Has superat un límit d’ús (peticions per segon o creacions al mes). Espera abans de tornar a intentar-ho o revisa la secció «Límits d’ús».

Format d’error de validació (422)

Quan un camp no supera la validació, la resposta segueix l’esquema HTTPValidationError:

{
  "detail": [
    {
      "loc": ["body", "url"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Bones pràctiques

Desa la clau API en un gestor de secrets o en una variable d’entorn; mai la incloguis dins del codi client.
Regenera la clau des del panell si sospites que s’ha exposat o si ja no s’utilitza en una integració.
Valida les URL abans d’enviar-les i tracta els errors 422 per mostrar missatges clars a l’usuari.
Utilitza `skip` i `limit` per paginar el llistat d’enllaços, en lloc de demanar tota la llista d’una sola vegada.
Comprova la disponibilitat d’un àlies amb `/disponibilitat/{path}` abans de crear un enllaç amb un àlies personalitzat.
Respecta els límits d’ús (5 peticions per segon i 1.000 creacions al mes) i implementa reintents amb backoff quan rebis un error 429.