diff --git a/README.md b/README.md
index e5009c3..c830553 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,120 @@
-
# Donaton
+
> [!IMPORTANT]
-> Plataforma de gestión de donaciones basada en microservicios.
+> Plataforma de gestión de donaciones basada en una arquitectura de microservicios.
+
+
+ 
+
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+---
+
+## Descripción
+
+Donatón es una plataforma diseñada para facilitar la gestión y distribución de donaciones, conectando usuarios, organizaciones y centros de acopio mediante una arquitectura basada en microservicios.
+
+La solución está compuesta por:
-
+* Un frontend desarrollado con React y TypeScript.
+* Un Backend For Frontend (BFF).
+* Un API Gateway para centralizar el acceso a los servicios.
+* Microservicios independientes encargados de autenticación, donaciones, necesidades y logística.
+
+---
## Tecnologías
-- Java Spring Boot
-- React + TypeScript
-- Docker Compose
-- JWT
-- OpenFeign
+
+* Java 21
+* Spring Boot
+* Spring Cloud Gateway
+* OpenFeign
+* JWT
+* React
+* TypeScript
+* Docker Compose
+* Maven
+
+---
## Arquitectura
-- Gateway
-- BFF
-- Auth Service
-- Donation Service
-- Needs Service
-- Logistics Service
-## Ejecutar proyecto
+| Componente | Descripción |
+| ------------------------------------------ | ----------------------------------------------- |
+| [Microservicios](microservicios/README.md) | Servicios principales del sistema. |
+| [BFF](bff/README.md) | Backend orientado al frontend. |
+| [Frontend](frontend/README.md) | Aplicación web para usuarios y administradores. |
+
+---
+
+## Flujo General
+
+```
+
+ Frontend
+ │
+ ▼
+ BFF
+ │
+ ▼
+ API Gateway
+ │
+ ┌──────────────┼──────────────┼──────────────┐
+ │ │ │ │
+ ▼ ▼ ▼ ▼
+ Auth Donation Logistics Needs
+ ```
+
+## Puesta en Marcha
+
+### Levantar todos los servicios
```bash
docker compose up --build
```
-## Servicios que encontraras
-- Servicios
-- Frontend
-- Gateway
-- BFF
-- Auth
-- Donation
-- Needs
-- Logistics
+### Detener los servicios
+
+```bash
+docker compose down
+```
+
+---
+
+## Estructura del Proyecto
+
+```text
+.
+├── frontend/
+├── bff/
+├── microservicios/
+│ ├── auth/
+│ ├── donation/
+│ ├── gateway/
+│ ├── logistics/
+│ └── needs/
+└── docker-compose.yml
+```
+
+---
+
+## Documentación
+
+Cada componente dispone de su propia documentación, incluyendo:
+
+* Descripción del servicio.
+* Endpoints disponibles.
+* Roles y permisos.
+* Ejemplos de solicitudes y respuestas.
+* Configuración y ejecución.
+
+> [!TIP]
+> Consulta los README de cada componente para obtener información detallada sobre su funcionamiento.
diff --git a/bff.zip b/bff.zip
new file mode 100644
index 0000000..5a8ccf6
Binary files /dev/null and b/bff.zip differ
diff --git a/bff/README.md b/bff/README.md
new file mode 100644
index 0000000..1054fe7
--- /dev/null
+++ b/bff/README.md
@@ -0,0 +1,95 @@
+# Backend For Frontend (BFF)
+
+> [!NOTE]
+> Este servicio actúa como capa de integración entre el frontend y los microservicios de Donatón.
+
+> [!IMPORTANT]
+> Todas las solicitudes del frontend deben realizarse a través del BFF.
+
+> [!TIP]
+> El BFF centraliza autenticación, validaciones, manejo de errores y comunicación con los distintos microservicios.
+
+> [!WARNING]
+> No se recomienda que el frontend consuma directamente los microservicios internos.
+
+---
+
+## Responsabilidades
+
+El BFF proporciona una interfaz única para el frontend y se encarga de:
+
+* Autenticar usuarios.
+* Gestionar tokens de acceso y refresco.
+* Centralizar las llamadas a los microservicios.
+* Unificar formatos de respuesta.
+* Manejar errores y excepciones.
+* Aplicar validaciones previas a las solicitudes.
+
+---
+
+## Servicios Integrados
+
+| Servicio | Descripción |
+| --------- | -------------------------------------------------- |
+| Auth | Autenticación, autorización y gestión de usuarios. |
+| Donation | Gestión de donaciones. |
+| Needs | Gestión de necesidades. |
+| Logistics | Gestión logística y seguimiento de envíos. |
+
+---
+
+## Endpoints Disponibles
+
+### Autenticación
+
+```text
+POST /api/v1/auth/login
+POST /api/v1/auth/register
+POST /api/v1/auth/refresh
+
+GET /api/v1/auth/users
+POST /api/v1/auth/users
+PUT /api/v1/auth/users/{id}/role
+DELETE /api/v1/auth/users/{id}
+```
+
+### Donaciones
+
+```text
+GET /api/v1/donations
+GET /api/v1/donations/{id}
+POST /api/v1/donations
+PUT /api/v1/donations/{id}
+DELETE /api/v1/donations/{id}
+```
+
+### Necesidades
+
+```text
+GET /api/v1/needs
+GET /api/v1/needs/{id}
+POST /api/v1/needs
+PUT /api/v1/needs/{id}
+PUT /api/v1/needs/{id}/receive
+DELETE /api/v1/needs/{id}
+```
+
+### Logística
+
+```text
+GET /api/v1/logistics
+POST /api/v1/logistics
+PUT /api/v1/logistics/{id}/estado
+```
+
+---
+
+## Seguridad
+
+Los endpoints protegidos requieren el encabezado:
+
+```http
+Authorization: Bearer
+```
+
+El token es validado antes de reenviar la solicitud al microservicio correspondiente.
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 81865dd..40be855 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -65,8 +65,7 @@ services:
build:
context: ./microservicios/auth
container_name: auth-service
- ports:
- - "8081:8080"
+
environment:
<<: *spring-env
JWT_SECRET: mi_clave_secreta_muy_larga_para_hs256_segura_12345
@@ -83,8 +82,7 @@ services:
build:
context: ./microservicios/donation
container_name: donation-service
- ports:
- - "8082:8080"
+
environment:
<<: *spring-env
depends_on:
@@ -100,8 +98,7 @@ services:
build:
context: ./microservicios/logistics
container_name: logistics-service
- ports:
- - "8083:8080"
+
environment:
<<: *spring-env
depends_on:
@@ -155,8 +152,6 @@ services:
build:
context: ./bff
container_name: bff-service
- ports:
- - "8085:8080"
environment:
SPRING_PROFILES_ACTIVE: docker
SPRING_APPLICATION_NAME: bff
diff --git a/frontend/README.md b/frontend/README.md
new file mode 100644
index 0000000..0868025
--- /dev/null
+++ b/frontend/README.md
@@ -0,0 +1,99 @@
+# Frontend
+
+> [!NOTE]
+> Aplicación web de Donatón desarrollada con React, TypeScript y Vite.
+
+---
+
+## Tecnologías
+
+- React
+- TypeScript
+- Vite
+- Tailwind CSS
+- Axios
+- React Router DOM
+- Chart.js
+- React Chartjs 2
+- Leaflet
+- React Leaflet
+
+---
+
+## Estructura del Proyecto
+
+```text
+src/
+├── assets/
+├── components/
+├── context/
+├── hooks/
+├── layouts/
+├── pages/
+├── services/
+├── types/
+├── utils/
+├── App.tsx
+└── main.tsx
+```
+
+---
+
+## Funcionalidades
+
+- Inicio de sesión y registro de usuarios.
+- Gestión de necesidades.
+- Registro y visualización de donaciones.
+- Seguimiento de envíos.
+- Panel administrativo.
+- Visualización de estadísticas mediante gráficos.
+- Gestión de usuarios y roles.
+
+---
+
+## Instalación
+
+### Instalar dependencias
+
+```bash
+npm install
+```
+
+### Ejecutar en modo desarrollo
+
+```bash
+npm run dev
+```
+
+### Generar versión de producción
+
+```bash
+npm run build
+```
+
+### Vista previa de producción
+
+```bash
+npm run preview
+```
+
+---
+
+## Variables de Entorno
+
+```env
+VITE_API_BASE_URL=/api/v1
+```
+
+---
+
+## Dependencias Principales
+
+| Librería | Propósito |
+|-----------|------------|
+| React Router DOM | Navegación entre páginas |
+| Axios | Comunicación con el BFF |
+| Tailwind CSS | Estilos |
+| Chart.js | Gráficos y estadísticas |
+| Leaflet | Mapas y geolocalización |
+| SweetAlert2 | Ventanas y alertas |
\ No newline at end of file
diff --git a/microservicios/README.md b/microservicios/README.md
new file mode 100644
index 0000000..e121a71
--- /dev/null
+++ b/microservicios/README.md
@@ -0,0 +1,21 @@
+# Donaton Backend
+
+> [!NOTE]
+> Este repositorio contiene la arquitectura basada en microservicios utilizada por Donaton.
+
+> [!TIP]
+> Cada servicio cuenta con su propia documentación detallada, incluyendo endpoints, permisos y ejemplos de uso.
+
+---
+
+## Microservicios
+
+| Servicio | Descripción |
+| -------------------------------- | ----------------------------------------------------- |
+| [Auth](auth/README.md) | Autenticación, autorización y gestión de usuarios. |
+| [Donation](donation/README.md) | Gestión de donaciones realizadas por los usuarios. |
+| [Gateway](gateway/README.md) | Punto de entrada único para todos los microservicios. |
+| [Logistics](logistics/README.md) | Administración y seguimiento de envíos logísticos. |
+| [Needs](needs/README.md) | Gestión de necesidades y solicitudes de ayuda. |
+
+
diff --git a/microservicios/auth/README.md b/microservicios/auth/README.md
new file mode 100644
index 0000000..399289d
--- /dev/null
+++ b/microservicios/auth/README.md
@@ -0,0 +1,212 @@
+# API de Autenticación y Gestión de Usuarios
+
+> [!NOTE]
+> **URL Base**
+>
+> ```text
+> http://localhost:8080/api/v1
+> ```
+
+> [!IMPORTANT]
+> Los endpoints protegidos requieren un token de acceso válido en el encabezado:
+>
+> ```http
+> Authorization: Bearer
+> ```
+
+> [!TIP]
+> Obtén el `access_token` mediante el endpoint `/auth/login` y úsalo para acceder a los recursos protegidos.
+
+> [!WARNING]
+> Las operaciones de administración de usuarios requieren el rol **ADMIN**.
+
+---
+
+## Roles Disponibles
+
+* `USER`
+* `ONG`
+* `ADMIN`
+
+---
+
+## Endpoints
+
+| Método | Endpoint | Cuerpo (Body) | Respuesta | Requiere Token | Rol Requerido |
+| ------ | ------------------------- | -------------------------------------------- | -------------------------- | -------------- | ------------- |
+| POST | `/auth/login` | `email`, `password` | Token de acceso y refresco | No | Ninguno |
+| POST | `/auth/register` | `name`, `email`, `phone`, `password` | Datos del usuario creado | No | Ninguno |
+| GET | `/auth/users` | Ninguno | Lista de usuarios | Sí | ADMIN |
+| POST | `/auth/users` | `name`, `email`, `phone`, `password`, `role` | Usuario creado | Sí | ADMIN |
+| PUT | `/auth/users/{id}/{role}` | Ninguno | Usuario actualizado | Sí | ADMIN |
+| DELETE | `/auth/users/{id}` | Ninguno | `200 OK` | Sí | ADMIN |
+
+---
+
+## Ejemplos
+
+### Iniciar Sesión
+
+**Solicitud**
+
+```http
+POST /auth/login
+```
+
+```json
+{
+ "email": "admin@donaton.test",
+ "password": "admin123"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "tokenType": "Bearer",
+ "accessToken": "",
+ "refreshToken": "",
+ "accessExpiresIn": 3600,
+ "refreshExpiresIn": 604800
+}
+```
+
+---
+
+### Registro de Usuario
+
+**Solicitud**
+
+```http
+POST /auth/register
+```
+
+```json
+{
+ "name": "Usuario 2",
+ "email": "usuario2@donaton.test",
+ "password": "usuario234",
+ "phone": "123456789"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 2,
+ "name": "Usuario 2",
+ "email": "usuario2@donaton.test",
+ "phone": "123456789",
+ "role": "USER"
+}
+```
+
+---
+
+### Crear Usuario desde el Panel de Administración
+
+**Solicitud**
+
+```http
+POST /auth/users
+```
+
+```json
+{
+ "name": "Usuario 2",
+ "email": "usuario2@donaton.test",
+ "password": "usuario234",
+ "phone": "123456789",
+ "role": "USER"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 2,
+ "name": "Usuario 2",
+ "email": "usuario2@donaton.test",
+ "phone": "123456789",
+ "role": "USER"
+}
+```
+
+---
+
+### Obtener Usuarios
+
+**Solicitud**
+
+```http
+GET /auth/users
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": 2,
+ "name": "user",
+ "email": "user@donaton.test",
+ "phone": null,
+ "role": "USER"
+ },
+ {
+ "id": 3,
+ "name": "ong",
+ "email": "ong@donaton.test",
+ "phone": null,
+ "role": "ONG"
+ },
+ {
+ "id": 1,
+ "name": "admin",
+ "email": "admin@donaton.test",
+ "phone": null,
+ "role": "ADMIN"
+ }
+]
+```
+
+---
+
+### Actualizar Rol de Usuario
+
+**Solicitud**
+
+```http
+PUT /auth/users/2/ADMIN
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 2,
+ "name": "Usuario 2",
+ "email": "usuario2@donaton.test",
+ "phone": "123456789",
+ "role": "ADMIN"
+}
+```
+
+---
+
+### Eliminar Usuario
+
+**Solicitud**
+
+```http
+DELETE /auth/users/2
+```
+
+**Respuesta**
+
+```http
+200 OK
+```
diff --git a/microservicios/donation/README.md b/microservicios/donation/README.md
new file mode 100644
index 0000000..01e2d30
--- /dev/null
+++ b/microservicios/donation/README.md
@@ -0,0 +1,183 @@
+# API de Gestión de Donaciones
+
+> [!NOTE]
+> **URL Base**
+>
+> ```text
+> http://localhost:8080/api/v1
+> ```
+
+> [!IMPORTANT]
+> Los endpoints protegidos requieren un token de acceso válido en el encabezado:
+>
+> ```http
+> Authorization: Bearer
+> ```
+
+> [!TIP]
+> Este servicio permite registrar y administrar donaciones realizadas por los usuarios para cubrir necesidades registradas en el sistema.
+
+> [!WARNING]
+> La eliminación de una donación puede afectar procesos logísticos y necesidades asociadas.
+
+---
+
+## Roles Disponibles
+
+* `USER`
+* `ONG`
+* `ADMIN`
+
+---
+
+## Endpoints
+
+| Método | Endpoint | Cuerpo (Body) | Respuesta | Requiere Token | Rol Requerido |
+| ------ | ----------------- | -------------------- | -------------------- | -------------- | ------------- |
+| GET | `/donations` | Ninguno | Lista de donaciones | Sí | USER |
+| GET | `/donations/{id}` | Ninguno | Detalle de donación | Sí | USER |
+| POST | `/donations` | Datos de la donación | Donación creada | Sí | USER |
+| PUT | `/donations/{id}` | Datos actualizados | Donación actualizada | Sí | USER |
+| DELETE | `/donations/{id}` | Ninguno | `204 No Content` | Sí | USER |
+
+---
+
+## Ejemplos
+
+### Obtener Donaciones
+
+**Solicitud**
+
+```http
+GET /donations
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": 1,
+ "descripcion": "10 cajas de leche",
+ "cantidad": 10,
+ "tipo": "ALIMENTOS",
+ "direccion": "Av. Principal 123",
+ "needId": "need-001",
+ "donorEmail": "user@donaton.test",
+ "unit": "cajas"
+ }
+]
+```
+
+---
+
+### Obtener Donación por ID
+
+**Solicitud**
+
+```http
+GET /donations/1
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 1,
+ "descripcion": "10 cajas de leche",
+ "cantidad": 10,
+ "tipo": "ALIMENTOS",
+ "direccion": "Av. Principal 123",
+ "needId": "need-001",
+ "donorEmail": "user@donaton.test",
+ "unit": "cajas"
+}
+```
+
+---
+
+### Crear Donación
+
+**Solicitud**
+
+```http
+POST /donations
+```
+
+```json
+{
+ "descripcion": "10 cajas de leche",
+ "cantidad": 10,
+ "tipo": "ALIMENTOS",
+ "direccion": "Av. Principal 123",
+ "needId": "need-001",
+ "unit": "cajas"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 1,
+ "descripcion": "10 cajas de leche",
+ "cantidad": 10,
+ "tipo": "ALIMENTOS",
+ "direccion": "Av. Principal 123",
+ "needId": "need-001",
+ "donorEmail": "user@donaton.test",
+ "unit": "cajas"
+}
+```
+
+---
+
+### Actualizar Donación
+
+**Solicitud**
+
+```http
+PUT /donations/1
+```
+
+```json
+{
+ "descripcion": "15 cajas de leche",
+ "cantidad": 15,
+ "tipo": "ALIMENTOS",
+ "direccion": "Av. Principal 456",
+ "needId": "need-001",
+ "unit": "cajas"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 1,
+ "descripcion": "15 cajas de leche",
+ "cantidad": 15,
+ "tipo": "ALIMENTOS",
+ "direccion": "Av. Principal 456",
+ "needId": "need-001",
+ "donorEmail": "user@donaton.test",
+ "unit": "cajas"
+}
+```
+
+---
+
+### Eliminar Donación
+
+**Solicitud**
+
+```http
+DELETE /donations/1
+```
+
+**Respuesta**
+
+```http
+200 OK
+```
diff --git a/microservicios/gateway/README.md b/microservicios/gateway/README.md
new file mode 100644
index 0000000..de5fba7
--- /dev/null
+++ b/microservicios/gateway/README.md
@@ -0,0 +1,162 @@
+# API Gateway
+
+> [!NOTE]
+> **URL Base**
+>
+> ```text
+> http://localhost:8080
+> ```
+
+> [!IMPORTANT]
+> El Gateway es el punto de entrada único para todos los microservicios de Donatón.
+
+> [!TIP]
+> Los clientes externos solo necesitan comunicarse con el Gateway; éste se encarga de redirigir las solicitudes al servicio correspondiente.
+
+> [!WARNING]
+> Los endpoints protegidos requieren un token de acceso válido en el encabezado:
+>
+> ```http
+> Authorization: Bearer
+> ```
+
+---
+
+## Servicios Disponibles
+
+| Servicio | Ruta | Descripción |
+| --------- | ---------------------- | -------------------------------------------------- |
+| Auth | `/api/v1/auth/**` | Autenticación, autorización y gestión de usuarios. |
+| Donation | `/api/v1/donations/**` | Gestión de donaciones. |
+| Needs | `/api/v1/needs/**` | Gestión de necesidades y solicitudes. |
+| Logistics | `/api/v1/envios/**` | Gestión y seguimiento de envíos. |
+
+---
+
+## Ejemplos
+
+### Iniciar Sesión
+
+**Solicitud**
+
+```http
+POST /api/v1/auth/login
+```
+
+```json
+{
+ "email": "admin@donaton.test",
+ "password": "admin123"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "tokenType": "Bearer",
+ "accessToken": "",
+ "refreshToken": "",
+ "accessExpiresIn": 3600,
+ "refreshExpiresIn": 604800
+}
+```
+
+---
+
+### Obtener Donaciones
+
+**Solicitud**
+
+```http
+GET /api/v1/donations
+Authorization: Bearer
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": 1,
+ "descripcion": "10 cajas de leche",
+ "cantidad": 10,
+ "tipo": "ALIMENTOS",
+ "direccion": "Av. Principal 123",
+ "needId": "need-001",
+ "donorEmail": "user@donaton.test",
+ "unit": "cajas"
+ }
+]
+```
+
+---
+
+### Obtener Necesidades
+
+**Solicitud**
+
+```http
+GET /api/v1/needs
+Authorization: Bearer
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": "need-001",
+ "productName": "Leche",
+ "category": "ALIMENTOS",
+ "quantityRequired": 100,
+ "quantityReceived": 25,
+ "unit": "cajas",
+ "priority": "ALTA",
+ "status": "PENDIENTE"
+ }
+]
+```
+
+---
+
+### Obtener Envíos
+
+**Solicitud**
+
+```http
+GET /api/v1/envios
+Authorization: Bearer
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": 1,
+ "donacionId": 1,
+ "estado": "pendiente_acopio"
+ }
+]
+```
+
+---
+
+## Arquitectura
+
+```text
+ Cliente
+ │
+ ▼
+ API Gateway
+ │
+ ┌────────────┼────────────┬────────────┐
+ ▼ ▼ ▼ ▼
+ Auth Donation Needs Logistics
+```
+
+---
+
+> [!CAUTION]
+> El Gateway no almacena información de negocio. Su única responsabilidad es enrutar y centralizar el acceso a los microservicios.
\ No newline at end of file
diff --git a/microservicios/logistics/README.md b/microservicios/logistics/README.md
new file mode 100644
index 0000000..507bc85
--- /dev/null
+++ b/microservicios/logistics/README.md
@@ -0,0 +1,169 @@
+# API de Gestión Logística
+
+> [!NOTE]
+> **URL Base**
+>
+> ```text
+> http://localhost:8080/api/v1
+> ```
+
+> [!IMPORTANT]
+> Los endpoints protegidos requieren un token de acceso válido en el encabezado:
+>
+> ```http
+> Authorization: Bearer
+> ```
+
+> [!TIP]
+> Este servicio se encarga de gestionar el traslado de donaciones desde el donante hacia los centros de acopio y posteriormente hacia su destino final.
+
+> [!WARNING]
+> La actualización de estados impacta directamente el flujo logístico de una donación.
+
+---
+
+## Roles Disponibles
+
+* `USER`
+* `ONG`
+* `ADMIN`
+
+---
+
+## Estados Disponibles
+
+* `pendiente_acopio`
+* `recibida`
+* `en_camino`
+* `entregado`
+* `inexistente`
+
+---
+
+## Endpoints
+
+| Método | Endpoint | Cuerpo (Body) | Respuesta | Requiere Token | Rol Requerido |
+| ------ | ------------------------------------- | ------------- | ----------------- | -------------- | ------------- |
+| POST | `/envios` | `donacionId` | Envío creado | Sí | USER |
+| GET | `/envios` | Ninguno | Lista de envíos | Sí | USER |
+| PUT | `/envios/{id}/estado?estado={estado}` | Ninguno | Envío actualizado | Sí | ADMIN |
+
+---
+
+## Ejemplos
+
+### Crear Envío
+
+**Solicitud**
+
+```http
+POST /envios
+```
+
+```json
+{
+ "donacionId": 1
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 1,
+ "donacionId": 1,
+ "needId": "need-001",
+ "direccion": "Av. Principal 123",
+ "acopioCenterId": "center-001",
+ "acopioCenterName": "Centro Santiago",
+ "estado": "pendiente_acopio",
+ "createdAt": "2026-06-20T18:00:00Z",
+ "acopioDeadline": "2026-06-27T18:00:00Z",
+ "cantidadDonada": 10.0
+}
+```
+
+---
+
+### Obtener Envíos
+
+**Solicitud**
+
+```http
+GET /envios
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": 1,
+ "donacionId": 1,
+ "needId": "need-001",
+ "direccion": "Av. Principal 123",
+ "acopioCenterId": "center-001",
+ "acopioCenterName": "Centro Santiago",
+ "estado": "pendiente_acopio",
+ "createdAt": "2026-06-20T18:00:00Z",
+ "acopioDeadline": "2026-06-27T18:00:00Z",
+ "cantidadDonada": 10.0
+ }
+]
+```
+
+---
+
+### Obtener Envíos por Centro de Acopio
+
+**Solicitud**
+
+```http
+GET /envios?acopioCenterId=center-001
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": 1,
+ "donacionId": 1,
+ "needId": "need-001",
+ "direccion": "Av. Principal 123",
+ "acopioCenterId": "center-001",
+ "acopioCenterName": "Centro Santiago",
+ "estado": "pendiente_acopio",
+ "createdAt": "2026-06-20T18:00:00Z",
+ "acopioDeadline": "2026-06-27T18:00:00Z",
+ "cantidadDonada": 10.0
+ }
+]
+```
+
+---
+
+### Actualizar Estado de Envío
+
+**Solicitud**
+
+```http
+PUT /envios/1/estado?estado=en_camino
+```
+
+**Respuesta**
+
+```json
+{
+ "id": 1,
+ "donacionId": 1,
+ "needId": "need-001",
+ "direccion": "Av. Principal 123",
+ "acopioCenterId": "center-001",
+ "acopioCenterName": "Centro Santiago",
+ "estado": "en_camino",
+ "createdAt": "2026-06-20T18:00:00Z",
+ "acopioDeadline": "2026-06-27T18:00:00Z",
+ "cantidadDonada": 10.0
+}
+```
diff --git a/microservicios/needs/README.md b/microservicios/needs/README.md
new file mode 100644
index 0000000..1a18fc9
--- /dev/null
+++ b/microservicios/needs/README.md
@@ -0,0 +1,226 @@
+# API de Gestión de Necesidades
+
+> [!NOTE]
+> **URL Base**
+>
+> ```text
+> http://localhost:8080/api/v1
+> ```
+
+> [!IMPORTANT]
+> Los endpoints protegidos requieren un token de acceso válido en el encabezado:
+>
+> ```http
+> Authorization: Bearer
+> ```
+
+> [!TIP]
+> Las necesidades representan productos o recursos solicitados por centros de acopio u organizaciones para cubrir una necesidad específica.
+
+> [!WARNING]
+> Algunas operaciones pueden afectar directamente el stock recibido y el estado de una necesidad.
+
+---
+
+## Roles Disponibles
+
+* `USER`
+* `ONG`
+* `ADMIN`
+
+---
+
+## Endpoints
+
+| Método | Endpoint | Cuerpo (Body) | Respuesta | Requiere Token | Rol Requerido |
+| ------ | ---------------------------------------- | --------------------- | --------------------- | -------------- | ------------- |
+| GET | `/needs` | Ninguno | Lista de necesidades | Sí | USER |
+| GET | `/needs/{id}` | Ninguno | Detalle de necesidad | Sí | USER |
+| POST | `/needs` | Datos de la necesidad | Necesidad creada | Sí | ONG |
+| PUT | `/needs/{id}` | Datos actualizados | Necesidad actualizada | Sí | ONG |
+| PUT | `/needs/{id}/receive?amount={cantidad}` | Ninguno | Necesidad actualizada | Sí | ADMIN |
+| PUT | `/needs/{id}/rollback?amount={cantidad}` | Ninguno | Necesidad actualizada | Sí | ADMIN |
+| DELETE | `/needs/{id}` | Ninguno | `200 OK` | Sí | ONG |
+
+---
+
+## Ejemplos
+
+### Obtener Necesidades
+
+**Solicitud**
+
+```http
+GET /needs
+```
+
+**Respuesta**
+
+```json
+[
+ {
+ "id": "need-001",
+ "productName": "Leche",
+ "category": "ALIMENTOS",
+ "quantityRequired": 100,
+ "quantityReceived": 25,
+ "unit": "cajas",
+ "priority": "ALTA",
+ "status": "PENDIENTE"
+ }
+]
+```
+
+---
+
+### Obtener Necesidad por ID
+
+**Solicitud**
+
+```http
+GET /needs/need-001
+```
+
+**Respuesta**
+
+```json
+{
+ "id": "need-001",
+ "productName": "Leche",
+ "category": "ALIMENTOS",
+ "quantityRequired": 100,
+ "quantityReceived": 25,
+ "unit": "cajas",
+ "priority": "ALTA",
+ "status": "PENDIENTE",
+ "region": "Metropolitana",
+ "address": "Av. Principal 123",
+ "description": "Leche para familias afectadas"
+}
+```
+
+---
+
+### Crear Necesidad
+
+**Solicitud**
+
+```http
+POST /needs
+```
+
+```json
+{
+ "productName": "Leche",
+ "category": "ALIMENTOS",
+ "quantityRequired": 100,
+ "unit": "cajas",
+ "priority": "ALTA",
+ "region": "Metropolitana",
+ "address": "Av. Principal 123",
+ "description": "Leche para familias afectadas"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "id": "need-001",
+ "productName": "Leche",
+ "category": "ALIMENTOS",
+ "quantityRequired": 100,
+ "quantityReceived": 0,
+ "unit": "cajas",
+ "priority": "ALTA",
+ "status": "PENDIENTE"
+}
+```
+
+---
+
+### Actualizar Necesidad
+
+**Solicitud**
+
+```http
+PUT /needs/need-001
+```
+
+```json
+{
+ "quantityRequired": 150,
+ "priority": "MEDIA"
+}
+```
+
+**Respuesta**
+
+```json
+{
+ "id": "need-001",
+ "productName": "Leche",
+ "quantityRequired": 150,
+ "quantityReceived": 0,
+ "priority": "MEDIA",
+ "status": "PENDIENTE"
+}
+```
+
+---
+
+### Registrar Recepción de Donaciones
+
+**Solicitud**
+
+```http
+PUT /needs/need-001/receive?amount=20
+```
+
+**Respuesta**
+
+```json
+{
+ "id": "need-001",
+ "quantityRequired": 100,
+ "quantityReceived": 45,
+ "status": "PENDIENTE"
+}
+```
+
+---
+
+### Revertir Recepción
+
+**Solicitud**
+
+```http
+PUT /needs/need-001/rollback?amount=10
+```
+
+**Respuesta**
+
+```json
+{
+ "id": "need-001",
+ "quantityRequired": 100,
+ "quantityReceived": 35,
+ "status": "PENDIENTE"
+}
+```
+
+---
+
+### Eliminar Necesidad
+
+**Solicitud**
+
+```http
+DELETE /needs/need-001
+```
+
+**Respuesta**
+
+```http
+200 OK
+```