Institutions API — manage food recipient organizations

The Institutions API handles the lifecycle of organizations — such as soup kitchens, snack bars, and schools — that receive food donations through the Banco Alimentos network. Institution records are identified by a UUID (externalId) rather than a numeric ID, and all mutating endpoints require the ROLE_USER_INSTITUCIONAL role. Read access is available to the deposit, treasury, and institutional roles.

Base URL

/api/instituciones

Path parameters and request-body IDs use UUID format (e.g. 3fa85f64-5717-4562-b3fc-2c963f66afa6), not a plain numeric Long.

Endpoints

List all institutions (paginated)

Authorization

string

required

Bearer token with one of: ROLE_USER_DEPOSITO, ROLE_USER_TESORERIA, or ROLE_USER_INSTITUCIONAL.

page

integer

Zero-based page index. Default: 0.

size

integer

Number of records per page. Default: 10.

sort

string

Field and direction, e.g. nombre,asc. Default: nombre.

GET /api/instituciones

Response — 200 OK — Spring Page<InstitucionDTO> envelope.

{
  "content": [
    {
      "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "nombre": "Escuela Nuestra Señora de Fátima",
      "tipo": "ESCUELA",
      "telefono": "01112345678",
      "email": "contacto@example.com",
      "estado": "AL_DIA"
    }
  ],
  "pageable": { "pageNumber": 0, "pageSize": 10 },
  "totalElements": 42,
  "totalPages": 5
}

Get institution by ID

Authorization

string

required

Bearer token with one of: ROLE_USER_DEPOSITO, ROLE_USER_TESORERIA, or ROLE_USER_INSTITUCIONAL.

externalId

UUID

required

UUID of the institution.

GET /api/instituciones/{externalId}

Response — 200 OK — single InstitucionDTO object.

Get institution by name

Authorization

string

required

Bearer token with one of: ROLE_USER_DEPOSITO, ROLE_USER_TESORERIA, or ROLE_USER_INSTITUCIONAL.

nombre

string

required

Exact name of the institution.

GET /api/instituciones/nombre/{nombre}

Response — 200 OK — single InstitucionDTO object.

Filter by institution type (paginated)

Authorization

string

required

Bearer token with one of: ROLE_USER_DEPOSITO, ROLE_USER_TESORERIA, or ROLE_USER_INSTITUCIONAL.

tipo

tipoInstitucion

required

One of the tipoInstitucion enum values (see table below).

page

integer

Zero-based page index. Default: 0.

size

integer

Page size. Default: 10.

sort

string

Sort field and direction. Default: nombre.

GET /api/instituciones/tipo/{tipo}

Response — 200 OK — paginated Page<InstitucionDTO>.

Filter by payment status (paginated)

Authorization

string

required

Bearer token with one of: ROLE_USER_DEPOSITO, ROLE_USER_TESORERIA, or ROLE_USER_INSTITUCIONAL.

estado

estadoPago

required

One of the estadoPago enum values (see table below).

page

integer

Zero-based page index. Default: 0.

size

integer

Page size. Default: 10.

sort

string

Sort field and direction. Default: nombre.

GET /api/instituciones/estado-pago/{estado}

Response — 200 OK — paginated Page<InstitucionDTO>.

Create institution

Authorization

string

required

Bearer token with the ROLE_USER_INSTITUCIONAL role.

POST /api/instituciones

Request body — NuevaInstitucionDTO

nombre

string

required

Institution name. At least 3 characters.

tipo

tipoInstitucion

required

Institution type. Must be a valid tipoInstitucion enum value.

direccion

string

required

Physical address of the institution.

telefono

string

Contact phone number.

string

Contact email address. Must be a valid email format.

estado

estadoPago

required

Current payment/subscription status. Must be a valid estadoPago enum value.

Response — 201 Created — returns the newly created InstitucionDTO.

Full update

Authorization

string

required

Bearer token with the ROLE_USER_INSTITUCIONAL role.

externalId

UUID

required

UUID of the institution to update.

PUT /api/instituciones/{externalId}

Request body uses InstitucionDTO fields (see Data models below). Response — 200 OK — returns the updated InstitucionDTO.

Partial update

Authorization

string

required

Bearer token with ROLE_USER_INSTITUCIONAL or ROLE_USER_TESORERIA.

externalId

UUID

required

UUID of the institution to partially update.

PATCH /api/instituciones/{externalId}

Request body uses ActualizarInstitucionParcialDTO (all fields optional except externalId). Only supplied fields are updated. Response — 200 OK — returns the updated InstitucionDTO.

Delete institution

Authorization

string

required

Bearer token with the ROLE_USER_INSTITUCIONAL role.

externalId

UUID

required

UUID of the institution to delete.

DELETE /api/instituciones/{externalId}

Response — 204 No Content

Get audit history

Authorization

string

required

Valid Bearer token.

externalId

UUID

required

UUID of the institution whose history to retrieve.

GET /api/instituciones/{externalId}/historial

Returns a list of historical Institucion snapshots representing every revision stored for this institution. Response — 200 OK — JSON array of institution snapshots.

Data models

NuevaInstitucionDTO

Field	Type	Required	Constraints
`nombre`	`string`	✅	Not blank; min 3 characters
`tipo`	`tipoInstitucion`	✅	Valid enum value
`direccion`	`string`	✅	Not blank
`telefono`	`string`		Optional contact phone
`email`	`string`		Optional; must be a valid email
`estado`	`estadoPago`	✅	Valid enum value

InstitucionDTO

externalId

UUID

Unique identifier of the institution.

nombre

string

Institution name (min 3 characters).

tipo

tipoInstitucion

Type of institution.

telefono

string

Contact phone number (10–11 digits when provided).

string

Contact email address.

estado

estadoPago

Current payment status of the institution’s subscription.

ActualizarInstitucionParcialDTO

Field	Type	Required	Constraints
`externalId`	`UUID`	✅	Must match the path parameter
`nombre`	`string`		Min 3 characters if provided
`tipo`	`tipoInstitucion`		Valid enum value if provided
`direccion`	`string`		Optional
`telefono`	`string`		10–11 digits if provided
`email`	`string`		Valid email format if provided
`estado`	`estadoPago`		Valid enum value if provided

Enum: tipoInstitucion

Value	Description
`COMEDOR`	Community soup kitchen
`MERENDERO`	Afternoon snack bar
`ESCUELA`	School
`OTRO`	Other organization

Enum: estadoPago

Value	Description
`AL_DIA`	Subscription payments are current
`DEUDOR`	Institution has outstanding dues
`EXCEPCIONAL`	Exceptional / waived payment arrangement

Pagination

All list endpoints use Spring’s Pageable mechanism. The response is a standard Spring Page<T> envelope containing:

Field	Description
`content`	Array of items for the current page
`pageable`	Pagination metadata (`pageNumber`, `pageSize`)
`totalElements`	Total number of matching records
`totalPages`	Total number of pages

Query parameters:

Param	Default	Description
`page`	`0`	Zero-based page number
`size`	`10`	Number of items per page
`sort`	`nombre`	Sort field and optional direction (`asc`/`desc`)

Authentication

Donors & Donations

Products & Inventory

Institutions & Distribution

Billing

Institutions API — manage food recipient organizations

Base URL

Endpoints

List all institutions (paginated)

Get institution by ID

Get institution by name

Filter by institution type (paginated)

Filter by payment status (paginated)

Create institution

Full update

Partial update

Delete institution

Get audit history

Data models

NuevaInstitucionDTO

InstitucionDTO

ActualizarInstitucionParcialDTO

Enum: tipoInstitucion

Enum: estadoPago

Build docs developers (and LLMs) love

Authentication

Donors & Donations

Products & Inventory

Institutions & Distribution

Billing

Documentation Index

​Base URL

​Endpoints

​List all institutions (paginated)

​Get institution by ID

​Get institution by name

​Filter by institution type (paginated)

​Filter by payment status (paginated)

​Create institution

​Full update

​Partial update

​Delete institution

​Get audit history

​Data models

​NuevaInstitucionDTO

​InstitucionDTO

​ActualizarInstitucionParcialDTO

​Enum: tipoInstitucion

​Enum: estadoPago

​Pagination

Build docs developers (and LLMs) love

Base URL

Endpoints

List all institutions (paginated)

Get institution by ID

Get institution by name

Filter by institution type (paginated)

Filter by payment status (paginated)

Create institution

Full update

Partial update

Delete institution

Get audit history

Data models

NuevaInstitucionDTO

InstitucionDTO

ActualizarInstitucionParcialDTO

Enum: tipoInstitucion

Enum: estadoPago

Pagination