API REST v1

Documentació de l'API

REST API + webhooks. Tot el que necessites per connectar els teus sistemes a MiEspacio en un dia.

Primers passos

URL base

Totes les sol·licituds d'API es fan a la següent URL base:

/api//v1

Els endpoints públics es poden accedir sense autenticació. Els endpoints autenticats requereixen un token Bearer obtingut a través de l'endpoint de login.

Endpoints

Endpoints públics

Aquests endpoints estan disponibles sense autenticació.

Mètode	URL	Descripció	Auth
GET	`/companies`	Llistar empreses	No
GET	`/companies/{slug}`	Detalls d'empresa	No
GET	`/companies/{slug}/services`	Serveis d'empresa	No
GET	`/companies/{slug}/reviews`	Ressenyes d'empresa	No
GET	`/companies/{uuid}/booking/availability`	Disponibilitat de reserves	No
POST	`/companies/{uuid}/bookings`	Crear reserva	No
GET	`/restaurants`	Llistar restaurants	No
GET	`/events`	Llistar esdeveniments	No
GET	`/vacancies`	Llistar ofertes de treball	No
GET	`/blog/posts`	Publicacions del blog	No
GET	`/business-types`	Tipus de negoci	No
GET	`/platform-stats`	Estadístiques de la plataforma	No

Endpoints d'autenticació

Usats per obtenir i gestionar tokens d'accés.

Mètode	URL	Descripció	Auth
POST	`/auth/login`	Iniciar sessió	No
POST	`/auth/register`	Registrar-se	No
POST	`/auth/refresh`	Refrescar token	Sí
GET	`/auth/me`	Usuari actual	Sí

Autenticació

MiEspacio usa autenticació Bearer token amb Laravel Sanctum. Per accedir als endpoints autenticats:

Envia una sol·licitud POST a /auth/login amb les teves credencials.
Inclou el token retornat a la capçalera Authorization de les sol·licituds posteriors.
Refresca el token abans que expiri usant l'endpoint de refresc.

Exemple de capçalera:

Authorization: Bearer your-token-here

Límits de velocitat

Les sol·licituds d'API estan limitades per IP per garantir un ús just.

Àmbit	Límit
Endpoints públics	`2.000 sol/min`
Endpoints de reserves	`300 sol/min`
Endpoints d'autenticació	`25 sol/min`

Quan se supera el límit, rebràs una resposta 429 Too Many Requests. La capçalera Retry-After indica quants segons esperar.

Format de resposta

Totes les respostes es retornen en format JSON. Les respostes exitoses solen seguir aquesta estructura:

{
  "data": [
    {
      "id": 1,
      "name": "La Maison Barcelona",
      "slug": "la-maison-barcelona"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 20,
    "total": 78
  }
}

Les respostes paginades inclouen metadades de paginació estàndard de Laravel (current_page, last_page, per_page, total).

Codis d'error

L'API usa codis d'estat HTTP estàndard per indicar el resultat d'una sol·licitud.

Codi	Significat
`200`	OK — Sol·licitud exitosa
`201`	Created — Recurs creat exitosament
`400`	Bad Request — Paràmetres de sol·licitud invàlids
`401`	Unauthorized — Autenticació faltant o invàlida
`403`	Forbidden — Permisos insuficients
`404`	Not Found — El recurs no existeix
`422`	Unprocessable Entity — Errors de validació
`429`	Too Many Requests — Límit de velocitat excedit
`500`	Internal Server Error — Alguna cosa ha anat malament al nostre servidor

Les respostes d'error inclouen un missatge i, quan aplica, un codi d'error estructurat:

{
  "message": "The selected time slot is no longer available.",
  "errors": {
    "slot": [
      "Please choose another available time."
    ]
  }
}

Necessites una clau d'API?

Contacta amb el nostre equip per sol·licitar accés a l'API per a la teva aplicació.

Contactar