Maintenance API — Schedules, Checklists, and Approvals

The Maintenance API manages the monthly preventive maintenance cycle for water dispenser fleets. Each month a batch of MaintenanceSchedule records is generated — one per active dispenser — and technicians then visit, complete a structured checklist, and obtain a digital signature from the customer representative. The resulting MaintenanceApproval carries a SHA-512 + AES-256-GCM cryptographic signature that can be independently verified without authentication.

GET /api/maintenance

Returns all maintenance schedules matching the supplied filters, ordered by scheduledMonth (descending) then dispenserId (ascending). Each schedule includes the linked dispenser and its checklist. Required permission: maintenance:read

Query parameters

month

string

Filter by scheduled month in YYYY-MM format (e.g. 2024-06).

plantId

string

Filter by the plant ID of the dispenser’s current location.

status

MaintenanceStatus

Filter by schedule status. Accepted values: PENDING, COMPLETED, OVERDUE, EXPIRED, SIGNED.

Response fields

(root)

MaintenanceSchedule[]

Array of schedule objects. Each object contains:

string

Schedule ID (CUID).

dispenserId

string

Associated dispenser ID.

scheduledMonth

string

Month in YYYY-MM format.

status

MaintenanceStatus

Current schedule status.

dispenser

object

Nested dispenser with id, marca, modelo, and its location (including plant.nombre).

checklist

MaintenanceChecklist | null

Linked checklist if completed; null if the visit has not occurred yet.

approvalId

string | null

ID of the linked MaintenanceApproval if signed.

createdAt

string

ISO 8601 creation timestamp.

Example

curl -X GET "https://your-domain.com/api/maintenance?month=2024-06&status=PENDING" \
  -H "Cookie: sb-access-token=<token>"

[
  {
    "id": "maint-sched-001",
    "dispenserId": "DISP-042",
    "scheduledMonth": "2024-06",
    "status": "PENDING",
    "approvalId": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "dispenser": {
      "id": "DISP-042",
      "marca": "Acuaservice",
      "modelo": "Pro 600",
      "location": {
        "nombre": "Comedor",
        "plant": { "nombre": "Planta Norte" }
      }
    },
    "checklist": null
  }
]

Error cases

Status	Description
`401`	Missing or invalid authentication session.
`403`	Caller lacks `maintenance:read`.

POST /api/maintenance/generate

Generates PENDING maintenance schedules for a given month. The endpoint iterates over all active dispensers with status IN_SERVICE, BACKUP, UNDER_REPAIR, or IN_TECHNICAL_SERVICE, and creates one schedule per dispenser that does not already have one for the requested month. Existing schedules are silently skipped. Required permission: maintenance:write

Request body

month

string

required

Target month in YYYY-MM format (e.g. "2024-07"). Must match the pattern exactly — any other format returns 400.

Response fields

success

boolean

true when the operation completed without error.

message

string

Human-readable summary of results.

created

number

Number of new schedule records created.

skipped

number

Number of dispensers that already had a schedule for the month and were therefore skipped.

Example

curl -X POST "https://your-domain.com/api/maintenance/generate" \
  -H "Cookie: sb-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{ "month": "2024-07" }'

{
  "success": true,
  "message": "Mantenimiento generado: 38 creados, 2 ya existían.",
  "created": 38,
  "skipped": 2
}

Error cases

Status	Description
`400`	`month` is missing or does not match `YYYY-MM`.
`401`	Missing or invalid authentication session.
`403`	Caller lacks `maintenance:write`.

POST /api/maintenance/{id}/checklist

Submits a maintenance checklist for a schedule and transitions it to COMPLETED. The operation is fully transactional: consumables/spare parts consumed during the visit are deducted from plant inventory in the same atomic unit.

This endpoint can only be called once per schedule. A 400 error is returned if a checklist already exists for the schedule.

Required permission: maintenance:write

Request body

condicionGeneral

ConditionRating

required

Overall equipment condition. Accepted values: GOOD, FAIR, POOR, CRITICAL.

fallas

string[]

List of detected failures or malfunctions. Stored as a JSON array.

problemasEstructurales

string[]

List of structural or physical problems observed. Stored as a JSON array.

observaciones

string

Free-text observations and technician notes.

consumablesUsed

array

Consumables and spare parts installed during the visit. Stock is deducted from the dispenser’s plant inventory.

Show consumablesUsed entry

materialCode

string

required

Catalog material code. Must exist in MaterialCatalog.

nombre

string

required

Display name for the item.

cantidad

number

required

Quantity consumed (must be > 0).

type

string

"SERIALIZED" or "BULK". Serialized items require an id field pointing to the specific Consumable record.

string

Internal Consumable.id — required when type is "SERIALIZED".

Response fields

success

boolean

true when checklist and schedule were updated successfully.

checklist

MaintenanceChecklist

The newly created checklist record.

Show checklist fields

string

Checklist ID (CUID).

scheduleId

string

Parent schedule ID.

condicionGeneral

ConditionRating

General condition rating submitted.

fallas

string[]

Failure list.

problemasEstructurales

string[]

Structural issues list.

observaciones

string | null

Free-text observations.

completedById

string

ID of the user who completed the checklist.

completedAt

string

ISO 8601 completion timestamp.

schedule

MaintenanceSchedule

The updated schedule with status: "COMPLETED".

Example

curl -X POST "https://your-domain.com/api/maintenance/maint-sched-001/checklist" \
  -H "Cookie: sb-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "condicionGeneral": "GOOD",
    "fallas": [],
    "problemasEstructurales": [],
    "observaciones": "Filtros reemplazados. Equipo operativo.",
    "consumablesUsed": [
      {
        "materialCode": "FILT-001",
        "nombre": "Filtro de carbón activado",
        "cantidad": 1,
        "type": "BULK"
      }
    ]
  }'

{
  "success": true,
  "checklist": {
    "id": "clxchecklist001",
    "scheduleId": "maint-sched-001",
    "condicionGeneral": "GOOD",
    "fallas": [],
    "problemasEstructurales": [],
    "observaciones": "Filtros reemplazados. Equipo operativo.",
    "completedById": "user-tech-007",
    "completedAt": "2024-06-15T10:00:00.000Z"
  },
  "schedule": {
    "id": "maint-sched-001",
    "dispenserId": "DISP-042",
    "scheduledMonth": "2024-06",
    "status": "COMPLETED"
  }
}

If the plant has insufficient stock for any listed consumable, the entire transaction is rolled back. No checklist is created, the schedule status remains PENDING, and no stock is modified. The response body will contain a descriptive error string.

Error cases

Status	Description
`400`	`condicionGeneral` is missing, or the checklist was already submitted for this schedule, or insufficient stock for a listed consumable.
`401`	Missing or invalid authentication session.
`403`	Caller lacks `maintenance:write`.
`404`	Schedule not found.

POST /api/maintenance/{id}/complete

An alternative completion endpoint that creates both the checklist and marks the schedule COMPLETED in one step. Unlike the dedicated /checklist endpoint, this variant also accepts fotosUrls for photo evidence and is intended for mobile flows where photos are uploaded as part of completion. Required permission: maintenance:write

Request body

condicionGeneral

ConditionRating

required

Overall equipment condition. Accepted values: GOOD, FAIR, POOR, CRITICAL.

fallas

string[]

List of detected failures.

problemasEstructurales

string[]

List of structural problems.

observaciones

string

Free-text observations.

fotosUrls

string[]

Array of photo URLs or base64-encoded image strings captured during the visit.

Response fields

string

Schedule ID.

status

string

Always COMPLETED on success.

dispenserId

string

The associated dispenser ID.

scheduledMonth

string

Month in YYYY-MM format.

Example

curl -X POST "https://your-domain.com/api/maintenance/maint-sched-002/complete" \
  -H "Cookie: sb-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "condicionGeneral": "FAIR",
    "fallas": ["Dispensador lento en modo frío"],
    "problemasEstructurales": [],
    "observaciones": "Se lubricaron rodamientos. Revisión adicional recomendada próximo mes.",
    "fotosUrls": ["https://storage.example.com/maint/photo1.jpg"]
  }'

{
  "id": "maint-sched-002",
  "dispenserId": "DISP-099",
  "scheduledMonth": "2024-06",
  "status": "COMPLETED",
  "createdAt": "2024-06-01T00:00:00.000Z"
}

Error cases

Status	Description
`400`	`condicionGeneral` is missing, or the schedule is already `COMPLETED`.
`401`	Missing or invalid authentication session.
`403`	Caller lacks `maintenance:write`.
`404`	Schedule not found.

GET /api/maintenance/approvals

Returns all maintenance approvals that carry a digital signature (signatureData or signatureHash is present), ordered newest-first. Each approval includes the linked technician and all associated maintenance schedules with their dispenser and location data. Required permission: maintenance:read

Query parameters

plantId

string

Filter approvals where at least one linked schedule belongs to a dispenser at the given plant.

startDate

string

ISO 8601 date — returns approvals created on or after this date.

endDate

string

ISO 8601 date — returns approvals created on or before this date (time is set to 23:59:59.999).

string

Case-insensitive search across customerName, customerIdentity, and linked dispenserId values.

Response fields

(root)

MaintenanceApproval[]

Array of approval objects. Each object contains:

string

Approval ID (CUID).

customerName

string | null

Name of the customer representative who signed.

customerIdentity

string | null

DNI or identification number of the signer.

signatureHash

string | null

SHA-512 hex digest (128 characters) of the signature payload.

signedAt

string | null

ISO 8601 timestamp of the signing event.

technician

object

Technician who created the approval: nombre, email.

schedules

MaintenanceSchedule[]

Associated schedules, each with the full dispenser and location tree.

createdAt

string

ISO 8601 creation timestamp.

Example

curl -X GET "https://your-domain.com/api/maintenance/approvals?plantId=plant-abc&startDate=2024-06-01" \
  -H "Cookie: sb-access-token=<token>"

[
  {
    "id": "approval-xyz",
    "customerName": "María Rodríguez",
    "customerIdentity": "28345678",
    "signatureHash": "a3f9b2c1...",
    "signedAt": "2024-06-15T11:30:00.000Z",
    "createdAt": "2024-06-15T11:00:00.000Z",
    "technician": {
      "nombre": "Carlos López",
      "email": "carlos@empresa.com"
    },
    "schedules": [
      {
        "id": "maint-sched-001",
        "dispenserId": "DISP-042",
        "scheduledMonth": "2024-06",
        "status": "SIGNED",
        "dispenser": {
          "id": "DISP-042",
          "marca": "Acuaservice",
          "modelo": "Pro 600",
          "location": {
            "nombre": "Comedor",
            "plant": { "nombre": "Planta Norte" }
          }
        }
      }
    ]
  }
]

Error cases

Status	Description
`401`	Missing or invalid authentication session.
`403`	Caller lacks `maintenance:read`.

POST /api/maintenance/approvals

Creates a new maintenance approval record grouping one or more completed maintenance schedules under a single digital signature session. The approval is created with an empty signature and must be subsequently signed by the customer representative on the technician’s device. Required permission: maintenance:write

All schedule IDs listed in scheduleIds must already have COMPLETED status. Passing any schedule that is not COMPLETED returns 400.

Request body

scheduleIds

string[]

required

Non-empty array of MaintenanceSchedule IDs to group under this approval. All referenced schedules must be in COMPLETED status.

Response fields

string

The newly created MaintenanceApproval ID. Pass this to the signing UI and then to the verify endpoint.

Example

curl -X POST "https://your-domain.com/api/maintenance/approvals" \
  -H "Cookie: sb-access-token=<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduleIds": ["maint-sched-001", "maint-sched-002"]
  }'

{ "id": "approval-xyz" }

Error cases

Status	Description
`400`	`scheduleIds` is missing, empty, or one or more schedules are not in `COMPLETED` status.
`401`	Missing or invalid authentication session.
`403`	Caller lacks `maintenance:write`.

POST /api/maintenance/approvals/{id}/verify

Verifies the cryptographic integrity of a maintenance approval signature. The endpoint retrieves the stored encryptedHash and hashPayload, decrypts the hash with AES-256-GCM, recomputes the SHA-512 digest from the raw payload, and compares both using a timing-safe equality check. This endpoint requires maintenance:read permission to prevent unauthenticated enumeration. Required permission: maintenance:read

This endpoint is designed to support quick digital signature checks from the approvals list. The valid flag tells the caller whether the signature payload was cryptographically intact and untampered.

Request body

This endpoint does not accept a request body. The approval is identified by {id} in the URL path.

Response fields

valid

boolean

true if the decrypted stored hash matches the recomputed SHA-512 digest of the raw payload; false if the signature has been tampered with or decryption fails.

hash

string

The SHA-512 hex digest recovered by decrypting the stored encryptedHash. Empty string on verification failure.

computedHash

string

The SHA-512 hex digest freshly computed from the stored hashPayload. Compare with hash to manually audit the match. Empty string on decryption error.

Example

curl -X POST "https://your-domain.com/api/maintenance/approvals/approval-xyz/verify" \
  -H "Cookie: sb-access-token=<token>"

{
  "valid": true,
  "hash": "a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
  "computedHash": "a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
}

Error cases

Status	Description
`400`	The approval exists but does not have a valid digital certificate (missing `signatureHash`, `encryptedHash`, or `hashPayload`).
`401`	Missing or invalid authentication session.
`403`	Caller lacks `maintenance:read`.
`404`	No approval found with the given ID.

Overview

Endpoints

Maintenance API — Schedules, Checklists, and Approvals

GET /api/maintenance

Query parameters

Response fields

Example

Error cases

POST /api/maintenance/generate

Request body

Response fields

Example

Error cases

POST /api/maintenance/{id}/checklist

Request body

Response fields

Example

Error cases

POST /api/maintenance/{id}/complete

Request body

Response fields

Example

Error cases

GET /api/maintenance/approvals

Query parameters

Response fields

Example

Error cases

POST /api/maintenance/approvals

Request body

Response fields

Example

Error cases

POST /api/maintenance/approvals/{id}/verify

Request body

Response fields

Example

Error cases

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/maintenance

​Query parameters

​Response fields

​Example

​Error cases

​POST /api/maintenance/generate

​Request body

​Response fields

​Example

​Error cases

​POST /api/maintenance/{id}/checklist

​Request body

​Response fields

​Example

​Error cases

​POST /api/maintenance/{id}/complete

​Request body

​Response fields

​Example

​Error cases

​GET /api/maintenance/approvals

​Query parameters

​Response fields

​Example

​Error cases

​POST /api/maintenance/approvals

​Request body

​Response fields

​Example

​Error cases

​POST /api/maintenance/approvals/{id}/verify

​Request body

​Response fields

​Example

​Error cases

Build docs developers (and LLMs) love

GET /api/maintenance

Query parameters

Response fields

Example

Error cases

POST /api/maintenance/generate

Request body

Response fields

Example

Error cases

POST /api/maintenance/{id}/checklist

Request body

Response fields

Example

Error cases

POST /api/maintenance/{id}/complete

Request body

Response fields

Example

Error cases

GET /api/maintenance/approvals

Query parameters

Response fields

Example

Error cases

POST /api/maintenance/approvals

Request body

Response fields

Example

Error cases

POST /api/maintenance/approvals/{id}/verify

Request body

Response fields

Example

Error cases