Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alvarezlautaro/BancoAlimentos/llms.txt

Use this file to discover all available pages before exploring further.

The Donaciones API is the core of the Banco Alimentos workflow. A donación represents a single donation event: a dated record linking a donor company to one or more item lines (items), carrying a supplier remittance number (nroRemitoProveedor), optional notes, and a lifecycle state. Donations begin in PENDIENTE state and must be explicitly confirmed via the /confirmar endpoint before downstream processes such as invoice generation can proceed. All endpoints require a valid JWT and enforce specific Spring Security authorities. Base URL: /api/donaciones

​
Endpoints

​
GET /api/donaciones

Returns the full list of donation records. Required authority: DONACION_VER

​
Response

Returns an array of DonacionResponseDTO objects with HTTP 200 OK. 
curl -s https://api.example.com/api/donaciones \
  -H 'Authorization: Bearer <token>'

[
  {
    "id": 1,
    "fecha": "2024-06-01",
    "estado": "PENDIENTE",
    "nroRemitoProveedor": 50012,
    "observaciones": "Entregar en depósito central",
    "items": []
  }
]

​
GET /api/donaciones/{id}

Returns a single donation by its numeric ID. Required authority: DONACION_VER

​
Path parameters

​
id
Long
required
The unique numeric identifier of the donation.

​
Response

Returns a single DonacionResponseDTO with HTTP 200 OK. Throws a runtime exception (404) if the donation does not exist. 
curl -s https://api.example.com/api/donaciones/1 \
  -H 'Authorization: Bearer <token>'

​
POST /api/donaciones

Creates a new donation record, including its initial set of line items. Required authority: DONACION_CREAR

​
Request body

​
fecha
string (LocalDate)
required
Donation date in YYYY-MM-DD format. Cannot be null.
​
estado
EstadoDonacion
required
Initial lifecycle state. Must be one of PENDIENTE, CONFIRMADA, or CANCELADA. Typically set to PENDIENTE on creation. Cannot be null.
​
nroRemitoProveedor
integer
required
Supplier remittance / delivery note number. Cannot be null.
​
observaciones
string
Optional free-text notes about the donation.
​
items
array of ItemDonacionRequestDTO
required
List of line items included in this donation. Must contain at least one item. Each item object requires:
  • fechaVencimiento (date, future) — product expiry date
  • valorUnitario (number, positive) — unit value
  • cantidad (integer, ≥ 1) — quantity
  • productoId (Long) — ID of the associated product
​
idDonante
Long
ID of the donor company associated with this donation.

​
Response

Returns the created DonacionResponseDTO with HTTP 201 Created. 
curl -s -X POST https://api.example.com/api/donaciones \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2024-06-15",
    "estado": "PENDIENTE",
    "nroRemitoProveedor": 50099,
    "observaciones": "Donación de invierno",
    "idDonante": 7,
    "items": [
      {
        "fechaVencimiento": "2025-12-31",
        "valorUnitario": 150.00,
        "cantidad": 50,
        "productoId": 3
      }
    ]
  }'

{
  "id": 12,
  "fecha": "2024-06-15",
  "estado": "PENDIENTE",
  "nroRemitoProveedor": 50099,
  "observaciones": "Donación de invierno",
  "items": [
    {
      "id": 44,
      "fechaVencimiento": "2025-12-31T00:00:00.000+00:00",
      "valorUnitario": 150.0,
      "cantidad": 50,
      "productoNombre": "Arroz",
      "donante": "Alimentos del Sur S.A."
    }
  ]
}

​
PUT /api/donaciones/{id}

Fully replaces an existing donation record. Provide all fields including the complete items list. Required authority: DONACION_ACTUALIZAR

​
Path parameters

​
id
Long
required
The unique numeric identifier of the donation to update.

​
Request body

Same structure as POST /api/donaciones. All required fields must be supplied.

​
Response

Returns the updated DonacionResponseDTO with HTTP 200 OK. 
curl -s -X PUT https://api.example.com/api/donaciones/12 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2024-06-15",
    "estado": "PENDIENTE",
    "nroRemitoProveedor": 50099,
    "observaciones": "Actualización de observaciones",
    "idDonante": 7,
    "items": [
      {
        "fechaVencimiento": "2025-12-31",
        "valorUnitario": 175.00,
        "cantidad": 60,
        "productoId": 3
      }
    ]
  }'

​
DELETE /api/donaciones/{id}

Permanently deletes a donation record and its associated items. Required authority: DONACION_ELIMINAR

​
Path parameters

​
id
Long
required
The unique numeric identifier of the donation to delete.

​
Response

Returns HTTP 200 OK with the plain-text body "Donación eliminada correctamente". 
curl -s -X DELETE https://api.example.com/api/donaciones/12 \
  -H 'Authorization: Bearer <token>'

​
PUT /api/donaciones/{id}/confirmar

Transitions a donation’s estado from PENDIENTE to CONFIRMADA. This action is required before the donation can be used for invoice generation or stock update processes. Required authority: DONACION_ACTUALIZAR
A donation must be confirmed via this endpoint before it is eligible for invoice generation or any downstream inventory workflow. Attempting to generate an invoice for a PENDIENTE or CANCELADA donation will fail.

​
Path parameters

​
id
Long
required
The unique numeric identifier of the donation to confirm.

​
Response

Returns the updated DonacionResponseDTO with estado set to CONFIRMADA and HTTP 200 OK. 
curl -s -X PUT https://api.example.com/api/donaciones/12/confirmar \
  -H 'Authorization: Bearer <token>'

{
  "id": 12,
  "fecha": "2024-06-15",
  "estado": "CONFIRMADA",
  "nroRemitoProveedor": 50099,
  "observaciones": "Donación de invierno",
  "items": [
    {
      "id": 44,
      "fechaVencimiento": "2025-12-31T00:00:00.000+00:00",
      "valorUnitario": 150.0,
      "cantidad": 50,
      "productoNombre": "Arroz",
      "donante": "Alimentos del Sur S.A."
    }
  ]
}

​
Schemas

​
EstadoDonacion

The estado field uses the following enumerated values:
ValueDescription
PENDIENTEDefault state when a donation is first created. Awaiting confirmation.
CONFIRMADADonation has been confirmed and is eligible for invoice generation.
CANCELADADonation has been cancelled and is no longer active.

​
Donacion request schema

​
fecha
string (LocalDate)
Donation date in YYYY-MM-DD format. Required; cannot be null.
​
estado
EstadoDonacion
Lifecycle state. One of PENDIENTE, CONFIRMADA, CANCELADA. Required; cannot be null.
​
nroRemitoProveedor
integer
Supplier remittance number. Required; cannot be null.
​
observaciones
string
Optional free-text notes.
​
items
array
List of ItemDonacionRequestDTO objects. At least one item is required.
​
idDonante
Long
ID of the associated donor company.

​
Donacion response schema

​
id
Long
Unique numeric identifier assigned by the server.
​
fecha
string (LocalDate)
Donation date in YYYY-MM-DD format.
​
estado
EstadoDonacion
Current lifecycle state: PENDIENTE, CONFIRMADA, or CANCELADA.
​
nroRemitoProveedor
integer
Supplier remittance number.
​
observaciones
string
Optional notes attached to the donation.
​
items
array of ItemDonacionResponseDTO
Line items included in this donation. See Items Donación for the full item schema.

​
Error responses

HTTP StatusCondition
400 Bad RequestValidation failure — e.g. null fecha, empty items array, invalid estado value.
401 UnauthorizedMissing or invalid JWT.
403 ForbiddenValid JWT but the user lacks the required authority.
404 Not FoundNo donation found for the supplied id.

Build docs developers (and LLMs) love

Get started for freeTalk to us