pakAGdocs
pakAGdocs

API erreferentzia

Endpoint guztien base URL-a: /api/* (backend-js, 3001 portua garapenean).

Autentikatutako endpoint guztiek Authorization: Bearer <access_token> goiburua behar dute, kontrakoa adierazten ez bada. Erroreek beti { "error": "message string" } itzultzen dute.

[!NOTE] Request eta response formak DTO iturrietatik, repository motetatik eta frontend bezeroaren motetatik egiaztatu dira. Paginazio default-ak eta admin-only endpoint-en response-ak Needs verification gisa markatuta daude frontend bezeroek estaltzen ez dituztenean.

Error response formatua

Endpoint guztiek errore egituratuak itzultzen dituzte:

{ "error": "Human-readable error message" }

Erabilitako HTTP kodeak: 400 (balidazioa), 401 (autentikatu gabe), 403 (rol debekatua), 404 (ez aurkitua), 409 (gatazka), 500 (zerbitzari errorea).

Auth endpoint-ak

POST /api/auth/login

Publikoa. Erabiltzailea autentikatzen du, access token-a ematen du eta refresh token cookiea ezartzen du.

Request body

{ "email": "user@example.com", "password": "secret" }

Response 200

{
  "user": {
    "id": 1,
    "name": "Maria Garcia",
    "email": "user@example.com",
    "role": "distributor",
    "is_active": true
  },
  "access_token": "<JWT>"
}

Set-Cookie: refresh_token=...; HttpOnly; SameSite=Lax ezartzen du (dev) / SameSite=None; Secure (prod).

POST /api/auth/refresh

Refresh token cookiea erabiltzen du. Token-a biratzen du eta access token berria ematen du.

Request: body-rik gabe, cookiea automatikoki bidaltzen da.

Response 200

{ "access_token": "<new JWT>" }

refresh_token cookie berria ezartzen du. Token zaharra ezeztatzen da.

POST /api/auth/logout

Uneko refresh token-a ezeztatzen du eta cookiea garbitzen du.

Request: body-rik gabe.

Response 200

{ "message": "Logged out" }

GET /api/auth/me

Autentikatutako erabiltzailearen profila itzultzen du. Bearer token-a behar du.

Response 200

{
  "id": 1,
  "name": "Maria Garcia",
  "email": "user@example.com",
  "role": "distributor",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00.000Z"
}

POST /api/auth/forgotPassword

Publikoa. Password reset emaila bidaltzen du. Beti arrakasta itzultzen du email enumerazioa saihesteko.

Request body

{ "email": "user@example.com" }

Response 200

{ "message": "If that email is registered, a reset link has been sent." }

PATCH /api/auth/changePwd

Token bidezko endpoint publikoa. Bi modu ditu body edukiaren arabera.

1. modua - token-a bakarrik egiaztatu (new_password gabe):

{ "reset_pwd_token": "<token>" }

Response 200: { "valid": true }

2. modua - password berria ezarri:

{ "reset_pwd_token": "<token>", "new_password": "newSecret123" }

Response 200: { "message": "Password changed successfully" }

new_password gutxienez 6 karakterekoa izan behar da. Token-a erabileraren ondoren ezeztatzen da.

POST /api/auth/activateAccount

Token bidezkoa. Sortu berri den kontua aktibatzen du eta bere password-a ezartzen du.

Request: ?token=<activate_account_token> (query param) - Needs verification body eta query param banaketa zehatzari buruz.

User endpoint-ak (admin bakarrik)

Talde honetako endpoint guztiek role: admin behar dute.

POST /api/users/create

Erabiltzaile berria sortzen du eta aktibazio emaila bidaltzen du.

Request body

{ "name": "Jon Doe", "email": "jon@example.com", "role": "distributor" }

role "admin" edo "distributor" izan behar da. Erabiltzailea inaktibo sortzen da; aktibazio emaila emandako emailera bidaltzen da.

Response 201 - Needs verification forma zehatzerako; sortutako user objektua espero da.

GET /api/users/list

Query params

ParamMotaDefaultDeskribapena
pagenumber1Orrialde zenbakia
limitnumber20Gehienez 100
role"admin" | "distributor"-Rolaren arabera filtratu
is_active"true" | "false"-Egoera aktiboaren arabera filtratu

Response 200 - Needs verification paginazio envelope-aren forma zehatzerako.

GET /api/users/getById?id=<number>

Response 200 - user objektua. 404 aurkitzen ez bada.

PATCH /api/users/update

Request body - Needs verification onartutako field-etarako; espero dena { name?, email?, role?, is_active? }.

DELETE /api/users/remove?id=<number>

Erabiltzailea ezabatzen du. Erabiltzaile batek ezin du bere burua ezabatu.

Response 200 edo 403 bere burua ezabatzen saiatuz gero.

PATCH /api/users/changeMyPwd

Autentikatutako edozein rol. Norberaren password-a aldatzen du.

Request body

{ "current_password": "oldSecret", "new_password": "newSecret123" }

Response 200

{ "message": "Password updated successfully" }

Package endpoint-ak

POST /api/packages/create - admin

Paketea sortzen du, helbidea geokodetzen du, tracking token-a sortzen du eta tracking emaila bidaltzen du.

Request body

{
  "packageInfo": {
    "recipient_name": "Ane Etxeberria",
    "recipient_email": "ane@example.com",
    "assigned_to": null,
    "created_by": 1,
    "status": "pending",
    "weight_kg": 2.5,
    "description": "Fragile"
  },
  "address_info": {
    "street": "Kale Nagusia 12",
    "city": "Tolosa",
    "postal_code": "20400"
  }
}

assigned_to null (esleitu gabe) edo user ID baliozko bat izan daiteke. description aukerakoa da.

Response 201 - Needs verification paketearen forma zehatzerako.

GET /api/packages/list - admin

Query params - Needs verification filtro multzo osoa eta paginazio envelope-a egiaztatzeko.

GET /api/packages/getById?id=<number> - admin

Response 200 - PackageWithAddress:

{
  "id": 42,
  "tracking_code": "PAK-20260001",
  "recipient_name": "Ane Etxeberria",
  "recipient_email": "ane@example.com",
  "weight_kg": 2.5,
  "description": "Fragile",
  "status": "pending",
  "estimated_delivery": "2026-05-01",
  "address_id": 7,
  "assigned_to": null,
  "created_by": 1,
  "created_at": "2026-04-26T10:00:00.000Z",
  "updated_at": "2026-04-26T10:00:00.000Z",
  "street": "Kale Nagusia 12",
  "city": "Tolosa",
  "postal_code": "20400",
  "latitude": 43.1298,
  "longitude": -2.0773,
  "country": "Espana"
}

GET /api/packages/getMyPackages - distributor

Autentikatutako banatzaileari esleitutako pakete guztiak itzultzen ditu.

Response 200 - PackageWithAddress array-a.

PATCH /api/packages/updateStatus - distributor

Pakete baten edo batzuen egoera eguneratzen du. package_id edo package_ids bakarrik eman behar da, ez biak.

Request body (banakakoa)

{ "package_id": 42, "new_status": "in_transit" }

Request body (batch)

{ "package_ids": [42, 43, 44], "new_status": "delivered" }

new_status pakete egoera baliozkoa izan behar da: "pending" | "assigned" | "in_transit" | "delivered" | "undelivered" | "failed".

Response 200 - PackageWithAddress bakarra (banakako update-a) edo PackageWithAddress[] (batch).

Egoera log txertaketa eta email albo-efektuak eragiten ditu (ikusi Domeinu eredua).

PATCH /api/packages/update?id=<number> - admin

Pakete informazioa eta helbidea eguneratzen ditu. Needs verification onartutako field-etarako.

DELETE /api/packages/delete?id=<number> - admin

Response 200 - Needs verification.

GET /api/packages/getDailySummary - admin

Gaurko pakete kopurua egoeraka itzultzen du.

Response 200 - Needs verification forma zehatzerako; espero dena { pending: n, assigned: n, ... }.

Routes eta stops endpoint-ak

POST /api/routes/create - admin

Banatzaile baterako entrega ruta optimizatua sortzen du data batean.

Request body

{ "user_id": 3, "date": "2026-05-02", "package_ids": [10, 11, 12] }
  • date YYYY-MM-DD formatuan egon behar da eta gutxienez biharkoa izan behar da.
  • package_ids ez da hutsik egon behar, ez du bikoizturik izan behar, eta ID guztiak baliozko package ID-ak izan behar dira.

Response 200 - Needs verification ruta+stops envelope-aren forma zehatzerako.

GET /api/routes/getByUserAndDate - admin

Query params: user_id, date - Needs verification.

GET /api/routes/getMyDaily - distributor

Autentikatutako banatzailearen gaurko ruta eta stops itzultzen ditu.

Response 200

{
  "route": { "id": 5, "route_date": "2026-04-26", "status": "in_progress" },
  "stops": [
    {
      "id": 21,
      "stop_order": 1,
      "estimated_arrival": "09:30:00",
      "actual_arrival": "09:28:00",
      "package": {
        "id": 42,
        "recipient_name": "Ane Etxeberria",
        "status": "delivered",
        "address": {
          "street": "Kale Nagusia 12",
          "city": "Tolosa",
          "lat": 43.1298,
          "lng": -2.0773
        }
      }
    }
  ]
}

PATCH /api/routes/updateStatus/:id - admin edo distributor (mugatua)

Request body

{ "status": "in_progress" }

status "in_progress" edo "completed" izan behar da.

Response 200

{ "message": "Route status updated" }

GET /api/routes/continueFromPast - distributor

Banatzaileak aurreko ruta batean stop pendienteak dituen egiaztatzen du.

Response 200

{
  "pending": {
    "route_id": 3,
    "route_date": "2026-04-25",
    "status": "in_progress",
    "pending_count": 2,
    "route_count": 5
  }
}

pending null da aurreko ruta pendienterik ez badago.

POST /api/routes/continueFromPast - distributor

Aurreko ruta pendiente bateko stop pendienteak gaurko rutara migratzen ditu.

Request: body-rik gabe.

Response 200

{
  "route_id": 6,
  "new_route_date": "2026-04-26",
  "migrated_stops": 2
}

PATCH /api/stops/reorder - admin

Ruta barruko stop-ak berrordenatzen ditu. Needs verification body formari buruz.

PATCH /api/stops/updateArrival - distributor

Stop batera iristeko benetako ordua erregistratzen du.

Request body

{ "stop_id": 21 }

Response 200

{
  "id": 21,
  "route_id": 5,
  "package_id": 42,
  "stop_order": 1,
  "estimated_arrival": "09:30:00",
  "actual_arrival": "09:28:00"
}

Logs endpoint-ak

GET /api/logs/listByPackage - admin

Query params: packageId (required), page, limit.

Response 200

{
  "logs": [
    {
      "id": 1,
      "packageId": 42,
      "oldStatus": "assigned",
      "newStatus": "in_transit",
      "changedBy": 3,
      "notes": null,
      "changedAt": "2026-04-26T09:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

GET /api/logs/listAll - admin

Pakete guztietako egoera log guztiak zerrendatzen ditu. Needs verification filtro eta paginazio envelope-rako.

Tracking endpoint-a (publikoa)

GET /api/tracking/:trackingToken

Publikoa. Ez du auth behar. Token-a 32 byte-ko hex string-a da.

Response 200

{
  "tracking_code": "PAK-20260001",
  "recipient_name": "Ane Etxeberria",
  "status": "in_transit",
  "estimated_delivery": "2026-05-01",
  "address": {
    "street": "Kale Nagusia 12",
    "city": "Tolosa",
    "postal_code": "20400"
  },
  "last_update": "2026-04-26T09:00:00.000Z"
}

Token-a TRACKING_EXPIRES_DAYS egun ondoren iraungitzen da (default 30). 404 itzultzen du token-a ezezaguna edo iraungita badago.