Admin stations

Back-office management of filling stations (water and fuel): listing, CRUD, status toggling, report/comment moderation, and bulk CSV import. Paths are relative to the /api/v1 prefix; these are back-office endpoints that require an admin token.

Requires an admin bearer token (see Admin auth). Admin only.

The admin station API speaks Spanish: tipo is AGUA/GASOLINA, estado is ACTIVA/INACTIVA (the list filter accepts lowercase activa/inactiva/todas), and report colors are verde/amarillo/rojo/cerrada.

See Common errors and the public Stations endpoints.

Endpoints

GET /admin/stations/bulk-import/template

Downloads the CSV import template (text/csv, plantilla_estaciones.csv); there is no JSON body. The header row is name, address, latitude, longitude, tipo, description, landmark, city, opening_time, closing_time (the first five are required). Pass con_ejemplos=true to include three sample rows.

Query

Response 200 — a text/csv stream.

POST /admin/stations/bulk-import

Uploads a CSV (multipart/form-data) to create or update stations. Up to 100 rows return a report (200); larger files (up to 2,000 rows) return a job id (202) to poll.

Request body

Response 200 (≤ 100 rows)

{
  "report": {
    "processed": 80,
    "created": 72,
    "updated": 5,
    "skipped": 3,
    "skipped_rows": [
      { "line": 14, "reason": "Coordenadas fuera de Venezuela." }
    ]
  }
}

Response 202 (more than 100 rows)

{ "job_id": 9, "status": "PENDING", "total_rows": 540 }

Errors

GET /admin/stations/bulk-import/{jobId}

Polls the status of an import job. Only the admin who launched the job may read it.

Response 200

{
  "job_id": 9,
  "status": "COMPLETED",
  "total_rows": 540,
  "report": {
    "processed": 540,
    "created": 500,
    "updated": 30,
    "skipped": 10,
    "skipped_rows": [ { "line": 22, "reason": "Tipo inválido: 'X' (use AGUA o GASOLINA)." } ]
  },
  "error": null,
  "created_at": "2026-06-26T12:00:00+00:00",
  "updated_at": "2026-06-26T12:01:10+00:00"
}

report and error are null until the job finishes.

Errors

GET /admin/stations

Cursor-paginated station list, newest first. See Pagination → cursor-based.

Query

Response 200

{
  "items": [
    {
      "id": 5,
      "name": "Pozo La Trinidad",
      "address": "Av. Principal, Caracas",
      "tipo": "AGUA",
      "estado": "ACTIVA",
      "last_report_at": "2026-06-26T11:00:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6NH0",
  "has_more": true
}

POST /admin/stations

Creates a station. Coordinates must fall within Venezuela, and a station with the same name within 50 m is rejected as a duplicate. New stations start ACTIVA.

Request body

Response 201 — { "station": { … } } (the detail object, see below).

Errors

GET /admin/stations/{stationId}

Station detail with its reports from the last 30 days and an aggregate summary.

Response 200

{
  "station": {
    "id": 5,
    "name": "Pozo La Trinidad",
    "address": "Av. Principal, Caracas",
    "description": "Pozo comunitario",
    "landmark": "Frente a la plaza",
    "latitude": 10.4806,
    "longitude": -66.9036,
    "city": "Caracas",
    "tipo": "AGUA",
    "estado": "ACTIVA",
    "is_verified": true,
    "opening_time": "06:00",
    "closing_time": "18:00",
    "created_at": "2026-06-01T08:00:00+00:00",
    "updated_at": "2026-06-26T11:00:00+00:00"
  },
  "reports": [
    {
      "id": 31,
      "color": "verde",
      "wait_minutes": 10,
      "comment": "Cola corta",
      "reporter": "Carlos Rodríguez",
      "created_at": "2026-06-26T11:00:00+00:00"
    }
  ],
  "summary": {
    "total_reports_30d": 12,
    "avg_wait_minutes": 18,
    "color_breakdown": { "verde": 7, "amarillo": 3, "rojo": 2, "cerrada": 0 }
  }
}

reporter is null for reports with no identifiable author.

Errors

PATCH /admin/stations/{stationId}

Partial update. Any omitted field is left unchanged. Moved coordinates must fall within Venezuela.

Request body

Response 200 — { "station": { … } } (the detail object).

Errors

PATCH /admin/stations/{stationId}/status

Activates or deactivates a station.

Request body

Response 200

{ "id": 5, "estado": "INACTIVA", "updated_at": "2026-06-29T10:00:00+00:00" }

Errors

DELETE /admin/stations/{stationId}

Deletes a station. Blocked when the station has any report in the last 7 days — deactivate it instead.

Response 200

{ "deleted": true }

Errors

GET /admin/stations/{stationId}/reports

Cursor-paginated report history for a station, newest first. See Pagination → cursor-based.

Query

Response 200

{
  "items": [
    {
      "id": 31,
      "color": "verde",
      "wait_minutes": 10,
      "comment": "Cola corta",
      "reporter": "Carlos Rodríguez",
      "created_at": "2026-06-26T11:00:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6MzB9",
  "has_more": true
}

Errors

GET /admin/stations/{stationId}/comments

Cursor-paginated comment wall for a station (for moderation), newest first. See Pagination → cursor-based.

Query

Response 200

{
  "items": [
    {
      "id": 12,
      "author": { "id": 3, "name": "Carlos Rodríguez", "role": "DRIVER" },
      "content": "El pozo cerró temprano hoy.",
      "created_at": "2026-06-26T11:30:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6MTF9",
  "has_more": true
}

Errors

DELETE /admin/stations/{stationId}/comments/{commentId}

Moderation: deletes any comment on the station's wall.

Response 200

{ "ok": true }

Errors