Reservation Lifecycle and Workflow in Despacho Backend

A reservation in Despacho Backend is an appointment request submitted by a prospective client who needs legal services. The system is built around a clear two-actor model: a client submits a reservation form without needing any account or login, and a lawyer (authenticated via JWT) reviews, accepts, schedules, and optionally removes those reservations through a set of protected API endpoints. Every reservation begins life as unaccepted and only transitions to confirmed once a lawyer explicitly approves it.

Reservation lifecycle

Client submits a reservation

The client sends a POST request to /api/form/reserve/create with their personal details and the legal service they require. No authentication is needed — this endpoint is fully public so that any prospective client can reach it without creating an account.

curl -X POST https://api.despacho.example.com/api/form/reserve/create \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "María García López",
    "email": "maria@example.com",
    "phone": 5551234567,
    "required_service": "Derecho familiar",
    "preferred_date": "2024-03-15",
    "preferred_hour": "10:00",
    "additional_message": "Necesito orientación sobre custodia de menores."
  }'

Required fields: full_name, email, phone, required_service, preferred_date, preferred_hour. The additional_message field is optional.

Reservation stored as pending

The FormReserve document is saved to MongoDB with reservation_accepted set to false. The server responds with a confirmation message and the full saved document.

{
  "msj": "Reserva creada correctamente. Cuando tu reserva sea confirmada te notificaremos",
  "status": true,
  "data_response": {
    "_id": "64b2f3a1e5c0d6g7a8b9e0f1",
    "full_name": "María García López",
    "email": "maria@example.com",
    "phone": 5551234567,
    "required_service": "Derecho familiar",
    "preferred_date": "2024-03-15",
    "preferred_hour": "10:00",
    "additional_message": "Necesito orientación sobre custodia de menores.",
    "reservation_accepted": false,
    "createdAt": "2024-02-20T14:30:00.000Z",
    "updatedAt": "2024-02-20T14:30:00.000Z"
  }
}

Lawyer views pending reservations

After logging in and obtaining a JWT, the lawyer calls POST /api/form/reserve/list/reservation-false to retrieve all reservations where reservation_accepted is false. Results are paginated and sorted newest-first (sort({ _id: -1 })).

curl -X POST https://api.despacho.example.com/api/form/reserve/list/reservation-false \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

The response includes a pagination object alongside the data array (see Pagination below).

Lawyer accepts and schedules the reservation

The lawyer sends POST /api/form/reserve/accept/:reserveId/reserve with the confirmed preferred_date and preferred_hour in the request body. The controller sets reservation_accepted: true and updates the date and time fields in a single $set operation.

curl -X POST https://api.despacho.example.com/api/form/reserve/accept/64b2f3a1e5c0d6g7a8b9e0f1/reserve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "preferred_date": "2024-03-15",
    "preferred_hour": "11:00"
  }'

{
  "msj": "Reserva aceptada/modificada correctamente",
  "status": true,
  "update_reserve": {
    "_id": "64b2f3a1e5c0d6g7a8b9e0f1",
    "reservation_accepted": true,
    "preferred_date": "2024-03-15",
    "preferred_hour": "11:00"
  }
}

Lawyer deletes a reservation (optional)

If a reservation needs to be removed — whether cancelled by the client or resolved — the lawyer calls POST /api/form/reserve/remove/reservation/:reservationId. The controller verifies the document exists before performing a hard delete with FormReserve.deleteOne().

curl -X POST https://api.despacho.example.com/api/form/reserve/remove/reservation/64b2f3a1e5c0d6g7a8b9e0f1 \
  -H "Authorization: Bearer <token>"

{
  "msj": "Reserva eliminada exitosamente.",
  "status": true
}

Public vs protected endpoints

The reservation creation endpoint (POST /api/form/reserve/create) requires no authentication. This is intentional — clients should be able to submit appointment requests without needing to register an account. All management operations (listing, accepting, deleting) are restricted to authenticated lawyers.

Endpoint	Method	Auth required
`/api/form/reserve/create`	`POST`	Public — no token needed
`/api/form/reserve/accept/:reserveId/reserve`	`POST`	Protected — `Token`
`/api/form/reserve/list/reservation-true`	`POST`	Protected — `Token` + `Paginate`
`/api/form/reserve/list/reservation-false`	`POST`	Protected — `Token` + `Paginate`
`/api/form/reserve/list/reservation-all`	`POST`	Protected — `Token` + `Paginate`
`/api/form/reserve/remove/reservation/:reservationId`	`POST`	Protected — `Token`

Pagination

The three listing endpoints (reservation-true, reservation-false, reservation-all) use the Paginate middleware before the route handler. It reads pagination parameters from the URL path params and injects computed values into req.body for the controller to use.

// src/middleware/lib/Paginate.js
export const Paginate = (req, res, next) => {
  let perpage = req.params.perpage ? req.params.perpage : 10;
  let pag = req.params.pag > 1 ? req.params.pag - 1 : 0;

  req.body.skippag = pag * perpage;
  req.body.limit = perpage;
  next();
};

Parameter	Source	Default	Description
`perpage`	`req.params.perpage`	`10`	Number of records to return per page
`pag`	`req.params.pag`	`0`	Current page number (1-indexed in the URL; converted to 0-indexed offset internally)
`skippag`	Computed → `req.body.skippag`	—	Number of documents to skip: `(pag - 1) * perpage`
`limit`	Computed → `req.body.limit`	—	Passed directly to Mongoose’s `.limit()`

Every listing response includes a pagination object:

{
  "msj": "Cargando reservas no aceptadas",
  "status": true,
  "data": [...],
  "pagination": {
    "pag": "1",
    "perpage": 10,
    "pags": 4
  }
}

Field	Description
`pag`	The current page number from the request params
`perpage`	The number of results per page (from `req.body.limit`)
`pags`	Total number of pages: `Math.ceil(totalCount / perpage)`

Legal service categories

The required_service field on a reservation is an enum — the submitted value must exactly match one of the following six strings defined in FormReserveSchema:

Derecho civil

Civil law — contracts, property, personal injury, and general civil disputes.

Derecho familiar

Family law — divorce, child custody, adoption, and domestic matters.

Derecho mercantil

Commercial law — business formation, contracts, and trade regulations.

Derecho penal

Criminal law — defense and representation in criminal proceedings.

Derecho laboral

Labor law — employment contracts, wrongful termination, and workplace rights.

Derecho inmobiliario

Real estate law — property transactions, leases, and land disputes.

Submitting any value outside this list will cause Mongoose validation to fail and the reservation will not be saved.

Get Started

Core Concepts

Reservation Lifecycle and Workflow in Despacho Backend