Vender desde tu plataforma

El recorrido completo para que tu web o tu app venda plazas del recinto: mirar qué hay libre, decir cuánto cuesta y cerrar la reserva.

El precio que te devolvemos es el precio

La cotización sale del mismo motor que el portal público y el mostrador. No es una estimación que luego se ajusta: incluye temporada, suplementos, tasa turística y cupón, y es exactamente lo que se cobrará. Si cambia algo entre que cotizas y reservas, la creación falla en vez de cobrar otra cosa.

1 · Mira si el recinto está abierto

Antes de enseñar un calendario, descarta los días cerrados. Cachéalo unos minutos, cambia poco:

curl https://pernocta.app/api/v1/closures \
  -H "Authorization: Bearer pna_live_TU_CLAVE"

Si bookingsClosed es true, el recinto no admite reservas ahora mismo y da igual la fecha que mires.

2 · Qué queda libre

curl "https://pernocta.app/api/v1/availability?from=2026-09-01&to=2026-09-04" \
  -H "Authorization: Bearer pna_live_TU_CLAVE"

Te devuelve las plazas libres con un precio «desde» y la estancia mínima del periodo (minStay y meetsMinStay). Ese «desde» sirve para pintar un listado, no para cobrar: para eso está el paso siguiente.

3 · El precio exacto

curl "https://pernocta.app/api/v1/quote?pitchId=UUID&from=2026-09-01&to=2026-09-04&persons=2&pets=1" \
  -H "Authorization: Bearer pna_live_TU_CLAVE"

Aquí entran los suplementos reales: personas de más, mascota, vehículo adicional, electricidad y la tasa turística, que va aparte porque no es tuya —la recauda el recinto para el ayuntamiento—.

La tasa turística no es ingreso

Viene en touristTaxCents, separada del resto. Si la sumas a tu comisión estarás cobrando sobre un dinero que no es del recinto ni tuyo.

Cupones

Pasa coupon=CODIGO y la cotización lo valida contra las reglas reales (vigencia, límite por cliente, primera reserva). Si no vale, te lo dice en vez de aplicarlo y fallar al reservar.

4 · Extras

curl https://pernocta.app/api/v1/services \
  -H "Authorization: Bearer pna_live_TU_CLAVE"

Ofrece solo los que traen bookableOnline: true: el resto son de mostrador y no deberían aparecer en una venta remota. Fíjate en unit para multiplicar bien —por noche, por estancia o por persona— y en mandatory, que se cobra sí o sí.

5 · Cierra la reserva

curl -X POST https://pernocta.app/api/v1/reservations \
  -H "Authorization: Bearer pna_live_TU_CLAVE" \
  -H "Idempotency-Key: venta-8f3a2b1c" \
  -H "Content-Type: application/json" \
  -d '{
    "pitchId": "UUID_DE_LA_PLAZA",
    "guestName": "Ana Pérez",
    "from": "2026-09-01",
    "to": "2026-09-04",
    "persons": 2,
    "email": "ana@example.com",
    "phone": "+34600111222",
    "plate": "1234ABC",
    "status": "confirmada"
  }'

«confirmada» solo se aplica si no queda nada por cobrar

Una reserva no se confirma con saldo pendiente: es la misma regla que impide confirmarla desde el panel sin registrar el cobro. Si pides confirmada y queda importe por cobrar, la reserva se crea igualmente pero en pendiente, y así te lo devuelve la respuesta — mira el status que recibes, no des por hecho el que mandaste. Cuando el cobro llega (por el enlace de pago, por la pasarela o en el mostrador), la reserva se confirma sola.

Manda siempre Idempotency-Key

Si tu petición se pierde por el camino y reintentas sin ella, creas dos reservas y le cobras dos veces al cliente. Con ella, el reintento recibe la primera respuesta.

Dos plataformas pueden pedir la misma plaza a la vez: el anti-overbooking es de base de datos, así que la segunda recibe un 409 limpio. Trátalo como «esa plaza acaba de irse», vuelve a consultar disponibilidad y ofrece otra.

6 · Después de vender

Recoge la matrícula aunque no sea obligatoria en tu formulario: es lo que abre la barrera sola cuando el cliente llega. Si la sabes después, actualízala con POST /reservations/{id}.
Suscríbete a reservation.cancelled: si el huésped cancela desde el recinto, enterarte por webhook evita que tu sistema siga contándola como viva.
El check-in de viajeros lo hace el huésped con el enlace que le manda el recinto. No tienes que replicarlo salvo que quieras, y entonces está POST /reservations/{id}/travelers.

Sobre el cobro

La reserva se crea con su importe, pero el cobro no pasa por esta API: o lo cobras tú en tu plataforma y liquidas con el recinto según lo que hayáis acordado, o se crea en estado pendiente y el recinto le manda su enlace de pago. Habladlo antes de montar nada: es una decisión comercial, no técnica.