Endpoints - FactoriaF5-Asturias/project-p5-digital-academy-team3-restaurant-backend GitHub Wiki

Endpoints

La API de Giacobello usa el prefijo /api/v1, configurado en la propiedad api-endpoint.
En esta documentación se indican las respuestas más habituales de cada endpoint. Algunas respuestas de error las genera nuestro código y otras las genera Spring automáticamente, por ejemplo cuando faltan campos obligatorios en el body. Por eso el formato del JSON de error puede cambiar según el caso.

Pública significa que no requiere token. Las demás rutas requieren un JWT en Authorization: Bearer <token> y los roles indicados.

IMPORTANTE: Arrancar el backend con el boton Run Java desde GiacobelloApplication.java y asegurar que se ha iniciado.

1. En Postman seleccionar método POST y esta URL:

http://localhost:8080/api/v1/auth/token

2. En Headers, añadir Content-Type: application/json.
3. En Body, seleccionar raw y JSON, y enviar las credenciales:

{
  "username": "Kitchen",
  "password": "tu-contraseña"
}

4. Con credenciales válidas, la respuesta es 200 OK:

{
  "token": "eyJ..."
}

Si el usuario o la contraseña no son válidos, responde 401 Unauthorized. Los campos vacíos responden 400 Bad Request. No requiere autenticación previa.

Este endpoint se usa solo cuando una cuenta tiene pendiente cambiar su contraseña inicial. Antes de usarlo, POST /api/v1/auth/token debe responder 409 Conflict para esa cuenta.

1. En Postman seleccionar método POST y esta URL:

http://localhost:8080/api/v1/auth/change-password

2. En Headers, añadir Content-Type: application/json.
3. En Body, seleccionar raw y JSON, y enviar:

{
  "username": "Admin",
  "currentPassword": "contraseña-actual",
  "newPassword": "nueva-contraseña"
}

4. Si el cambio es correcto, responde 200 OK y devuelve un token JWT:

{
  "token": "eyJ..."
}

Si la contraseña actual no es correcta, responde 401 Unauthorized. Si la nueva contraseña no cumple la validación o es igual a la anterior, responde 400 Bad Request. Si la cuenta ya no tiene pendiente el cambio inicial, responde 409 Conflict y debe iniciar sesión en POST /api/v1/auth/token.

Para probar conexion y peticion a POST /api/v1/orders

1. Comprobar que el header de peticion contiene:

Content-Type: application/json

2. Enviar el body con los siguientes datos:

{
  "tabletId": 2,
  "orderTypeName": "DINE IN",
  "paymentMethodName": "CASH",
  "items": [
    {
      "productId": 4,
      "quantity": 2
    },
    {
      "productId": 7,
      "quantity": 1
    }
  ]
}

3. Respuesta tiene quer ser: 201 ok, significa que el order ha sido creado. Para verlo usar otro endpoint GET api/v1/orders o GET /api/orders/{id}.

1. Insertar id del pedido del que hay qie cambiar el status.

2. Enviar el body con los siguientes datos y eligiendo raw ->JSON:

{
  "statusName": "ACCEPTED"
}

3. Resultado esperado: 200 OK y el pedido con statusName: "ACCEPTED". Para verlo usar otro endpoint GET api/v1/orders o GET /api/orders/{id}.

Las rutas actuales usan el prefijo /api/v1. Estos endpoints devuelven datos JSON, no PDF. Para probar sin autenticación la factura de un pedido, arrancar con el perfil local.

Para probar conexión y petición a GET /api/v1/invoices:

1. En Postman seleccionar método GET, No Auth y esta URL:

http://localhost:8080/api/v1/invoices

2. No enviar body, se queda en vacio.

3. La respuesta tiene que ser 200 OK con una lista de facturas. Estos datos son un ejemplo:

[
  {
    "id": 3,
    "orderId": 5,
    "invoiceNumber": "TEST-5",
    "totalAmount": 25.0,
    "issuedAt": "2026-09-16T12:00:00"
  }
]

Si no hay facturas, devuelve 200 OK con []. El listado actualmente permite acceso sin autenticación también sin el perfil local.

Para probar conexión y petición a GET /api/v1/orders/{id}/invoice:

1. Consultar primero GET /api/v1/invoices y copiar el orderId de una factura. En Postman seleccionar método GET, No Auth y sustituir 5 por ese ID:

http://localhost:8080/api/v1/orders/5/invoice

2. No enviar body, se queda en vacio.

3. La respuesta tiene que ser 200 OK con [] si existe la factura o 404 si no existe(de momento es asi y es correcto ya que no tenemos facturas). Estos datos son un ejemplo:

{
  "id": 3,
  "orderId": 5,
  "invoiceNumber": "TEST-5",
  "totalAmount": 25.0,
  "issuedAt": "2026-09-16T12:00:00"
}

La URL usa el ID del pedido (5), no el ID de la factura (3). Si el pedido no existe o no tiene factura, devuelve 404 Not Found. Al crear un pedido válido mediante POST /api/v1/orders, el backend crea de forma atómica la factura asociada en invoices, con el total del pedido y su fecha de emisión. Por tanto, el orderId devuelto por el POST se puede usar directamente en este endpoint.

4. Si aparece 403, comprobar que el perfil local está activo y la ruta está permitida en SecurityConfig. Si aparece 404 en el listado, revisar la URL y reiniciar el backend después de los cambios. Si no conecta, comprobar que el backend está arrancado en el puerto 8080.

Se puede consultar la lista completa de los endpoins en los siguientes enlaces:

SWAGGER: http://localhost:8080/swagger-ui/index.html

JSON: http://localhost:8080/v3/api-docs

NOTA: Para visualizar estos datos el servicio backend debe estar activo.