Tickets API - Alternativa Verde

List Tickets

GET /api/tickets Retrieve a paginated list of tickets with optional filtering and sorting.

Query Parameters

collectionCenterId

string

Filter tickets by collection center ID. If not provided, uses the active center from configuration.

limit

number

default:"50"

Number of tickets to return per page (max: 200)

offset

number

default:"0"

Number of tickets to skip for pagination

string

Search term to filter by generator name or ticket number (case-insensitive)

date

string

Filter tickets by date (partial match supported)

sortKey

string

Field to sort by: ticketNumber, date, center, generatorName, quantity, or collectorName

sortDir

string

default:"DESC"

Sort direction: ASC or DESC

Response

items

array

Array of ticket objects

Show Ticket Object

string

Unique ticket identifier (UUID)

ticket_number

string

Auto-generated ticket number (format: AV---)

date

string

Collection date (DD/MM/YYYY or YYYY-MM-DD)

generator_id

string

ID of the generator (waste oil producer)

generator_name

string

Cached name of the generator

material_type

string

Type of material collected

quantity

number

Quantity collected (in liters)

material_state

string

State of material: “Filtrado”, “Bruto”, or “Mezcla”

collection_center_id

string | null

Associated collection center ID

collector_member_id

string | null

ID of the collection center member who collected

collector_name

string

Name of the collector

vehicle_plate

string

License plate of collection vehicle

created_at

string

Timestamp when ticket was created

total

number

Total count of tickets matching the filters

Example Request

curl "http://localhost:4000/api/tickets?limit=10&offset=0&search=Restaurant&sortKey=date&sortDir=DESC"

Example Response

{
  "items": [
    {
      "id": "ticket-123",
      "ticket_number": "AV-ARA-2026-0001",
      "date": "09/03/2026",
      "generator_id": "gen-456",
      "generator_name": "Restaurant El Sabor",
      "material_type": "Aceite Vegetal Usado",
      "quantity": 45.5,
      "material_state": "Filtrado",
      "collection_center_id": "center-1",
      "collector_member_id": "member-1",
      "collector_name": "Juan Pérez",
      "vehicle_plate": "ABC-123",
      "created_at": "2026-03-09T10:30:00Z"
    }
  ],
  "total": 1
}

Get Ticket Count

GET /api/tickets/count Retrieve the total count of tickets.

Query Parameters

collectionCenterId

string

Filter count by collection center ID. If not provided, uses the active center from configuration.

Response

total

number

Total number of tickets

Example Request

curl "http://localhost:4000/api/tickets/count?collectionCenterId=center-1"

Example Response

{
  "total": 42
}

Preview Next Ticket Number

GET /api/tickets/preview-number Preview the next ticket number that will be generated without creating a ticket. Useful for displaying to users before they save.

Query Parameters

collectionCenterId

string

Collection center ID. If not provided, uses the active center from configuration.

date

string

required

Ticket date (DD/MM/YYYY or YYYY-MM-DD) - used to determine year in ticket number

Response

expectedTicketNumber

string

The next ticket number that will be generated (format: AV---)

Example Request

curl "http://localhost:4000/api/tickets/preview-number?date=09/03/2026&collectionCenterId=center-1"

Example Response

{
  "expectedTicketNumber": "AV-ARA-2026-0042"
}

Error Response

{
  "error": "No hay centro de acopio activo configurado"
}

Get Ticket by ID

GET /api/tickets/:id Retrieve a single ticket by its ID.

Path Parameters

string

required

Ticket ID

Response

Returns a single ticket object (see List Tickets for structure) or null if not found.

Example Request

curl http://localhost:4000/api/tickets/ticket-123

Create Ticket

POST /api/tickets Create a new collection ticket. The ticket number is automatically generated based on the collection center’s state and the ticket date.

Request Body

string

required

Unique ticket identifier (UUID)

date

string

required

Collection date (DD/MM/YYYY or YYYY-MM-DD)

generatorId

string

required

ID of the generator (waste oil producer)

generatorName

string

required

Name of the generator (cached for historical records)

materialType

string

required

Type of material collected

quantity

number

required

Quantity collected in liters

materialState

string

required

State of material: “Filtrado”, “Bruto”, or “Mezcla”

collectorName

string

required

Name of the person who collected

vehiclePlate

string

required

License plate of collection vehicle

collectionCenterId

string

Collection center ID. If not provided, uses the active center from configuration.

collectorMemberId

string

ID of the collection center member who collected

Response

Returns the created ticket object with the auto-generated ticket_number and created_at fields.

Example Request

curl -X POST http://localhost:4000/api/tickets \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ticket-new-123",
    "date": "09/03/2026",
    "generatorId": "gen-456",
    "generatorName": "Restaurant El Sabor",
    "materialType": "Aceite Vegetal Usado",
    "quantity": 45.5,
    "materialState": "Filtrado",
    "collectorName": "Juan Pérez",
    "vehiclePlate": "ABC-123",
    "collectionCenterId": "center-1",
    "collectorMemberId": "member-1"
  }'

Error Responses

{
  "error": "No hay centro de acopio activo configurado"
}

{
  "error": "DB insert error"
}

Update Ticket

PUT /api/tickets/:id Update an existing ticket. Unlike creation, this allows manual editing of the ticket number.

Path Parameters

string

required

Ticket ID

Request Body

ticketNumber

string

required

Ticket number (can be manually edited)

date

string

required

Collection date

generatorId

string

required

Generator ID

generatorName

string

required

Generator name

materialType

string

required

Material type

quantity

number

required

Quantity in liters

materialState

string

required

Material state

collectorName

string

required

Collector name

vehiclePlate

string

required

Vehicle plate

collectionCenterId

string

Collection center ID

collectorMemberId

string

Collector member ID

Response

Returns the updated ticket object.

Example Request

curl -X PUT http://localhost:4000/api/tickets/ticket-123 \
  -H "Content-Type: application/json" \
  -d '{
    "ticketNumber": "AV-ARA-2026-0001",
    "date": "09/03/2026",
    "generatorId": "gen-456",
    "generatorName": "Restaurant El Sabor",
    "materialType": "Aceite Vegetal Usado",
    "quantity": 50.0,
    "materialState": "Filtrado",
    "collectorName": "Juan Pérez",
    "vehiclePlate": "ABC-123",
    "collectionCenterId": "center-1"
  }'

Delete Ticket

DELETE /api/tickets/:id Delete a ticket by its ID.

Path Parameters

string

required

Ticket ID

Response

boolean

Returns true if deletion was successful

Example Request

curl -X DELETE http://localhost:4000/api/tickets/ticket-123

Example Response

{
  "ok": true
}

Get Tickets Report

GET /api/tickets/report Retrieve all tickets matching the given filters, sorted by date ascending. Designed for generating reports.

Query Parameters

collectionCenterId

string

Filter by collection center ID

dateFrom

string

Start date filter (DD/MM/YYYY format)

dateTo

string

End date filter (DD/MM/YYYY format)

month

number

Filter by month (1-12)

year

number

Filter by year

generatorId

string

Filter by single generator ID

generatorIds

string

Filter by multiple generator IDs (comma-separated)

Response

Returns an array of ticket objects sorted by date ascending.

Example Request

curl "http://localhost:4000/api/tickets/report?dateFrom=01/01/2026&dateTo=31/03/2026&collectionCenterId=center-1"

Example Response

[
  {
    "id": "ticket-1",
    "ticket_number": "AV-ARA-2026-0001",
    "date": "01/01/2026",
    "quantity": 30.5,
    ...
  },
  {
    "id": "ticket-2",
    "ticket_number": "AV-ARA-2026-0002",
    "date": "05/01/2026",
    "quantity": 42.0,
    ...
  }
]

Overview

Endpoints

​List Tickets

​Query Parameters

​Response

​Example Request

​Example Response

​Get Ticket Count

​Query Parameters

​Response

​Example Request

​Example Response

​Preview Next Ticket Number

​Query Parameters

​Response

​Example Request

​Example Response

​Error Response

​Get Ticket by ID

​Path Parameters

​Response

​Example Request

​Create Ticket

​Request Body

​Response

​Example Request

​Error Responses

​Update Ticket

​Path Parameters

​Request Body

​Response

​Example Request

​Delete Ticket

​Path Parameters

​Response

​Example Request

​Example Response

​Get Tickets Report

​Query Parameters

​Response

​Example Request

​Example Response

Build docs developers (and LLMs) love

List Tickets

Query Parameters

Response

Example Request

Example Response

Get Ticket Count

Query Parameters

Response

Example Request

Example Response

Preview Next Ticket Number

Query Parameters

Response

Example Request

Example Response

Error Response

Get Ticket by ID

Path Parameters

Response

Example Request

Create Ticket

Request Body

Response

Example Request

Error Responses

Update Ticket

Path Parameters

Request Body

Response

Example Request

Delete Ticket

Path Parameters

Response

Example Request

Example Response

Get Tickets Report

Query Parameters

Response

Example Request

Example Response