Alquiler online

Con el nivel 2, los clientes alquilan en la ficha del centro y entran el mismo día. El portal lleva el recorrido y pregunta en vivo a tu software; el cliente solo sale del portal para pagar, en la página de pago del banco de la gestora, la de siempre (con Redsys, su TPV por redirección), y vuelve.

Tu software decide y cobra: el precio y lo que se paga hoy, guardar el trastero mientras se paga, el contrato, el pedido firmado con la clave de la gestora, el aviso del banco y la referencia de la tarjeta para las mensualidades, y el PIN y el QR. Qbox nunca ve una tarjeta ni una clave de la pasarela, y no toca el dinero: va directo a la cuenta de la gestora.

El recorrido

Tu dirección para el alquiler

Ponla en tu área, en «Alquiler online»: por ejemplo, https://api.tu-software.example/qbox/v1. Las llamadas le añaden /rentals y lo demás. Cada una:

• va firmada como los avisos: Qbox-Signature, con el secreto de tus avisos (el cuerpo, vacío en GET y DELETE);
• dice si es de pruebas o de producción, con Qbox-Mode: test o live;
• lleva Idempotency-Key en POST, PUT y DELETE: con la misma clave, la misma respuesta, sin hacerlo dos veces;
• espera tu respuesta 8 segundos como mucho: hay un cliente esperando;
• y entiende tus errores como los nuestros: {"error": {"code": "…", "message": "…"}}, con su código HTTP.

Lo que se paga hoy

POST /rentals trae {id, connectionId, facilityId, unitId, startDate, locale}. Guarda el id: es el nuestro, el de PUT /connect/v1/rentals/{rentalId}. Comprueba que el trastero sigue libre, guárdalo y responde con el alquiler. Si ya no está libre, 409 unit_not_available.

Lo que se paga hoy lo calculas tú; el portal lo enseña línea a línea, sin calcular nada. Casi todas las gestoras cobran hoy los días que quedan del mes y la fianza entera, y después cada día 1:

{
  "id": "rnt_8f2c41",
  "status": "held",
  "heldUntil": "2026-10-26T17:42:00Z",
  "firstPayment": {
    "lines": [
      { "kind": "rent", "from": "2026-10-26", "to": "2026-10-31", "amount": 8.71 },
      { "kind": "deposit", "amount": 45 }
    ],
    "total": 53.71
  },
  "monthlyPrice": 45,
  "nextPayments": { "amount": 45, "dayOfMonth": 1, "from": "2026-11-01" },
  "minimumStayMonths": 0,
  "noticeDays": 15
}

El contrato

GET /rentals/{id}/contract responde {version, title, text}: el texto entero, en español, con sus condiciones generales dentro, con los datos del alquiler y sin número ni fecha, que se ponen al pagar. Al aceptarlo, POST /rentals/{id}/acceptance te manda la prueba: la huella del texto que leyó (textSha256), la versión, la hora, el correo, la IP, el navegador y si un particular pidió entrar antes de que acaben sus 14 días para desistir (earlyStart). Si el contrato ha cambiado, 409 contract_changed.

El pago

POST /rentals/{id}/payment trae {returnUrls: {ok, ko}}, las páginas del portal a las que vuelve el cliente. Prepara el pedido con la clave de la gestora, pon ok y ko como sus vueltas (con Redsys, URLOK y URLKO; acepta solo las que empiezan por https://www.quetrastero.com/) y responde adónde llevarlo:

{
  "redirect": {
    "method": "POST",
    "url": "https://pasarela.banco-de-la-gestora.example/pago",
    "fields": {
      "Ds_SignatureVersion": "HMAC_SHA256_V1",
      "Ds_MerchantParameters": "eyJEU19NRVJDSEFOVF9BTU9VTlQi…",
      "Ds_Signature": "Kz3rQ1v8…"
    }
  },
  "heldUntil": "2026-10-26T18:04:00Z"
}

El pago lo da por hecho el aviso de tu pasarela a tu servidor, nunca la vuelta del navegador.

Con ese aviso conviertes el alquiler en un contrato, guardas la referencia de la tarjeta para las mensualidades y nos lo dices, con el token de la gestora del centro (en pruebas, el de tu «Gestora de pruebas»):

curl -X PUT https://api.findqbox.com/connect/v1/rentals/$RENTAL_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid", "contractNumber": "TS-2026-0418"}'

También payment_failed (el trastero sigue guardado y se puede volver a intentar), expired, cancelled y refunded: si el pago llega cuando el trastero ya no era de ese alquiler, devuélvelo y dínoslo. Si no nos dices nada, el portal te lo pregunta con GET /rentals/{id} al volver el cliente y cada pocos minutos.

Cómo se entra

Ya pagado, GET /rentals/{id}/access responde {pin, qr, app, instructions}, cada uno opcional; si aún no está, 409 access_not_ready. El portal lo enseña en «¡Ya es tuyo!» y no lo guarda. GET /rentals/{id}/signed-contract da el contrato firmado, en PDF, que también le llega al cliente por correo.

Lo que activa el alquiler online de un centro

1. Tu software, con el nivel 2 certificado.
2. El centro, con onlineRental: true en PUT /facilities/{id}: cobra online con tu software.
3. La gestora lo activa en Qbox, en «Conecta tu software», centro a centro.

Además, el centro tiene que estar publicado y tener trasteros libres con precio. Entonces su ficha pasa a «Alquila y entra hoy».

Las pruebas y la certificación

En tu área, «Alquiler online», empieza alquileres de prueba en los centros de tu «Gestora de pruebas»: el portal te lleva por todo el recorrido hasta la pasarela de pruebas de tu software (en tu ordenador, también con http://localhost). Paga con sus tarjetas de prueba: no se cobra nada. Las seis pruebas pasan solas:

• lo que se paga hoy, y el trastero guardado;
• un pago que sale bien, con tu PUT;
• uno que no sale: payment_failed;
• uno que llega tarde y se devuelve: refunded;
• dejarlo: DELETE /rentals/{id};
• cómo se entra, después de un pago.

«Las llamadas en vivo» enseña cada llamada del portal a tu software y cada PUT tuyo, con su resultado y su tiempo. Con todas pasadas y el nivel 1 certificado, pides la revisión. Cada llamada y sus campos están en la referencia de la API, en sus webhooks.

Los errores de tu software