Empezar

Introducción

Qué hace la API, lo común a todas sus operaciones y los primeros pasos.

Con el estándar de Qbox, un software de gestión de trasteros publica los centros de sus clientes en quetrastero.com, con sus tamaños, sus precios, sus trasteros libres al momento y su plano, y recibe sus solicitudes. Es el mismo para todos los softwares, y es gratis.

Tu software llama a nuestra API y nos manda cada cambio al momento: no preguntamos cada pocos minutos.
Lo comprobamos todo al entrar. Lo que no pasa no se publica, y la respuesta dice qué campo falla y por qué.
Te mandamos avisos firmados: las solicitudes, lo que decide la revisión y lo que le falta a una ficha.
Cada gestora da permiso a su software desde Qbox (OAuth 2.0). Tu software solo ve lo de las gestoras que se lo han dado.

Lo común

Qué	Cómo
Dirección	`https://api.findqbox.com/connect/v1`, la misma en pruebas y en producción: lo decide cada credencial
Credenciales	Las de tu software, en su área: `client_id` y `client_secret`, de pruebas (`qt_test_…`) y, al certificarte, de producción (`qt_live_…`)
Tokens	`Authorization: Bearer <token>`. Cada token es de una gestora que dio permiso; caduca a la hora y se renueva con su `refresh_token`
Formato	JSON en UTF-8, con los nombres en camelCase. Lo que no conozcas de una respuesta, ignóralo
Fechas	`AAAA-MM-DD`; un mes, `AAAA-MM`; los momentos, en ISO 8601 y UTC: `2026-10-26T08:15:00Z`
Importes	Con hasta dos decimales, en euros, tal cual los tenga el centro: con el IVA o sin él (`pricesIncludeVat`). El portal enseña siempre el precio final
Identificadores	Los de tu software, opacos y estables (un GUID vale): de 1 a 64 letras, cifras, `.`, `_` o `-`
Mensajes	En español o en inglés, con `Accept-Language: es` o `en`. Por defecto, en inglés. Los `code` no cambian nunca
Repetir sin duplicar	`Idempotency-Key` (un UUID) en todo lo que cambia algo. Lo explica Errores y límites

Empieza en tres pasos

1. Pide tus credenciales

Pide acceso desde la página de Desarrolladores. Cuando lo aceptamos, creas en tu área las credenciales de pruebas y das permiso a tu «Gestora de pruebas», como lo hará una gestora de verdad: lo explica El permiso de la gestora.

2. Manda un centro

Con el token de la gestora, el centro entero, con su dirección, su punto y su horario:

curl -X PUT https://api.findqbox.com/connect/v1/facilities/madrid-01 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @centro.json

Después, sus tamaños, sus trasteros y su plano: Publica tus centros.

3. Recibe los avisos

Pon en tu área la dirección de tus avisos y comprueba la firma de cada uno antes de usarlo: Los avisos.

Las operaciones

Permiso	Operación	Para qué
`facilities.write`	`PUT /facilities/{facilityId}`	Da de alta un centro o lo pone al día, entero
`facilities.write`	`GET /facilities/{facilityId}`	Cómo está en el portal y lo que le falta
`facilities.write`	`DELETE /facilities/{facilityId}`	Lo quita del portal
`facilities.write`	`PUT /facilities/{facilityId}/unit-types`	Sus tamaños
`facilities.write`	`PUT /facilities/{facilityId}/units`	Todos sus trasteros
`facilities.write`	`PUT /facilities/{facilityId}/units/{unitId}`	Un trastero que cambia, al momento
`facilities.write`	`PUT /facilities/{facilityId}/floor-plan`	Su plano: el SVG de cada planta
`facilities.write`	`PUT /facilities/{facilityId}/photos/{photoId}`	Sube una foto
`facilities.write`	`PUT /facilities/{facilityId}/photos`	El orden de las fotos y sus pies
`facilities.write`	`PUT /facilities`	La lista de cada día
`leads.read`	`GET /leads`	Las solicitudes de los últimos 30 días
`leads.read`	`PUT /leads/{leadId}/status`	Marca una solicitud como atendida
Tu software	`GET /connections`	Las gestoras que te han dado permiso
Tu software	`POST /webhooks/test`	Te manda un aviso `test.ping`