Courts API — List, Retrieve, and Create /api/canchas - PitchPro

The /api/canchas endpoints manage sports courts (canchas) — the bookable venues in PitchPro. All three routes are mounted behind the verifyToken middleware in main.ts, meaning every request must supply a valid JWT Bearer token in the Authorization header.

GET /api/canchas

Returns an ordered list of every court in the database (ORDER BY id ASC).

Authentication

All /api/canchas requests require Authorization: Bearer <accessToken>.

Example request

curl http://localhost:8000/api/canchas \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

Response — 200 OK

{
  "ok": true,
  "total": 2,
  "data": [
    {
      "id": 1,
      "nombre": "Sintética Central",
      "descripcion": "Cancha de fútbol 5 con iluminación",
      "precio_hora": "80000.00",
      "activa": true,
      "created_at": "2025-06-01T00:00:00.000Z"
    },
    {
      "id": 2,
      "nombre": "Cancha Rápida Norte",
      "descripcion": null,
      "precio_hora": "55000.00",
      "activa": true,
      "created_at": "2025-06-02T00:00:00.000Z"
    }
  ]
}

boolean

Always true on a successful response.

total

number

Count of courts returned in data. Equals data.length.

data

Cancha[]

Show Cancha object fields

number

Auto-incremented primary key of the court.

nombre

string

The court’s display name (up to 100 characters).

descripcion

string | null

Optional free-text description of the court. null if not provided.

precio_hora

string

Hourly rate as a decimal string (e.g. "80000.00"). PostgreSQL DECIMAL columns are serialised as strings by the pg driver.

activa

boolean

true if the court is currently available for booking.

created_at

string

ISO 8601 UTC timestamp of when the court was added to the database.

Error codes

Code	Meaning
`401`	Missing or invalid Bearer token
`500`	Internal server error

GET /api/canchas/:id

Fetches a single court by its integer primary key.

Authentication

Requires Authorization: Bearer <accessToken>.

Path parameters

integer

required

The numeric ID of the court. Must be a positive integer. Non-numeric or zero values return 400.

Example request

curl http://localhost:8000/api/canchas/1 \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

Response — 200 OK

{
  "ok": true,
  "data": {
    "id": 1,
    "nombre": "Sintética Central",
    "descripcion": "Cancha de fútbol 5 con iluminación",
    "precio_hora": "80000.00",
    "activa": true,
    "created_at": "2025-06-01T00:00:00.000Z"
  }
}

boolean

Always true on a successful response.

data

Cancha

Show Cancha object fields

number

The court’s primary key.

nombre

string

The court’s display name.

descripcion

string | null

Optional description. null if not set.

precio_hora

string

Hourly rate as a decimal string from PostgreSQL.

activa

boolean

Whether the court is currently active.

created_at

string

ISO 8601 UTC creation timestamp.

Error codes

Code	Meaning
`400`	`id` path segment is not a positive integer — `{ ok: false, mensaje: "El ID debe ser un número positivo" }`
`401`	Missing or invalid Bearer token
`404`	No court found with that ID — `{ ok: false, mensaje: "Cancha con ID <id> no encontrada" }` (thrown as `CanchaNoEncontradaError`)
`500`	Internal server error

POST /api/canchas

Creates a new court record. The request body is validated with the Zod schema CrearCanchaSchema defined in canchas.types.ts. Any Zod validation failure returns 422 with a structured error array.

Authentication

Requires Authorization: Bearer <accessToken>.

Request body

nombre

string

required

The court’s display name. Must be at least 1 character and no more than 100 characters.

descripcion

string

Optional free-text description (e.g. surface type, lighting, capacity). Omit or pass null to leave blank.

precio_hora

number

required

Hourly rental rate in the local currency. Must be a positive number greater than 0. Send as a JS number in the JSON body (e.g. 80000). The database stores it as DECIMAL and the API returns it as a string.

activa

boolean

Whether the court should be immediately available for booking. Defaults to true if omitted.

Example request

curl -X POST http://localhost:8000/api/canchas \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{"nombre": "Sintética Central", "descripcion": "Con iluminación", "precio_hora": 80000, "activa": true}'

Response — 201 Created

{
  "ok": true,
  "data": {
    "id": 3,
    "nombre": "Sintética Central",
    "descripcion": "Con iluminación",
    "precio_hora": "80000.00",
    "activa": true,
    "created_at": "2025-06-15T14:22:00.000Z"
  }
}

boolean

Always true on successful creation.

data

Cancha

The newly created court object returned from RETURNING *, including the auto-assigned id and created_at timestamp.

precio_hora is sent as a JS number in the request body (e.g. 80000) but is always returned as a string (e.g. "80000.00") in responses, because the PostgreSQL DECIMAL type is serialised as a string by the pg driver to preserve precision.

Response — 422 Unprocessable Entity

Returned when the body fails CrearCanchaSchema Zod parsing.

{
  "ok": false,
  "mensaje": "Datos de entrada inválidos",
  "errores": [
    { "campo": "nombre", "problema": "El nombre no puede estar vacío" },
    { "campo": "precio_hora", "problema": "El precio debe ser mayor a 0" }
  ]
}

boolean

Always false on a validation failure.

mensaje

string

Always "Datos de entrada inválidos" for Zod errors.

errores

array

Show Error item fields

campo

string

Dot-notation path of the invalid field (e.g. "nombre", "precio_hora").

problema

string

Human-readable description of the validation failure.

Error codes

Code	Meaning
`401`	Missing or invalid Bearer token
`422`	Request body failed Zod schema validation
`500`	Internal server error

Reservations API

Book a court for a specific date and time slot. Includes overlap conflict detection.

API Overview

All PitchPro endpoints at a glance with base URL, auth format, and error conventions.

Authentication Guide

Learn how to obtain and refresh Bearer tokens to authenticate all court requests.

Overview

Endpoints

Courts API — List, Retrieve, and Create /api/canchas

GET /api/canchas

Authentication

Example request

Response — 200 OK

Error codes

GET /api/canchas/:id

Authentication

Path parameters

Example request

Response — 200 OK

Error codes

POST /api/canchas

Authentication

Request body

Example request

Response — 201 Created

Response — 422 Unprocessable Entity

Error codes

Reservations API

API Overview

Authentication Guide

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/canchas

​Authentication

​Example request

​Response — 200 OK

​Error codes

​GET /api/canchas/:id

​Authentication

​Path parameters

​Example request

​Response — 200 OK

​Error codes

​POST /api/canchas

​Authentication

​Request body

​Example request

​Response — 201 Created

​Response — 422 Unprocessable Entity

​Error codes

Reservations API

API Overview

Authentication Guide

Build docs developers (and LLMs) love

GET /api/canchas

Authentication

Example request

Response — 200 OK

Error codes

GET /api/canchas/:id

Authentication

Path parameters

Example request

Response — 200 OK

Error codes

POST /api/canchas

Authentication

Request body

Example request

Response — 201 Created

Response — 422 Unprocessable Entity

Error codes