API AgroMarket - Documentación

Bienvenido a la documentación de la API de AgroMarket. Esta documentación proporciona información detallada sobre todos los endpoints disponibles en el sistema.

Descripción General

AgroMarket es una plataforma de comercio electrónico especializada en productos agrícolas que permite a los usuarios comprar y vender productos frescos de manera local.

Características Principales

• Autenticación JWT: Sistema seguro de autenticación con tokens
• Gestión de Productos: CRUD completo para productos agrícolas
• Carrito de Compras: Gestión de carritos de compra
• Sistema de Órdenes: Procesamiento de pedidos con estados
• Créditos Virtuales: Sistema de moneda interna
• Transacciones: Historial de movimientos financieros
• Búsqueda por Ubicación: Productos y vendedores cercanos
• Categorías y Unidades: Sistema de clasificación de productos

Base URL

http://localhost:3000/api/v1

Autenticación

La mayoría de endpoints requieren autenticación mediante token JWT. Para autenticarte:

1. Registra un usuario usando POST /auth/register
2. Inicia sesión usando POST /auth/login
3. Usa el token recibido en el header Authorization: Bearer <token>

Módulos Disponibles

🔐 Autenticación

• Registro de usuarios
• Inicio de sesión
• Renovación de tokens
• Cierre de sesión

👤 Usuarios

• Información del perfil
• Actualización de datos
• Cambio de contraseña
• Cambio de imagen
• Búsqueda de vendedores cercanos

🛍️ Productos

• Creación de productos
• Listado de productos
• Búsqueda por categoría
• Productos cercanos
• Actualización y eliminación
• Compra directa

🛒 Carrito de Compras

• Agregar productos
• Remover productos
• Actualizar cantidades
• Limpiar carrito
• Ver carrito actual

📦 Órdenes

• Crear órdenes desde el carrito
• Ver historial de órdenes
• Actualizar estados
• Eliminar órdenes
• Gestión de estados

💰 Créditos

• Consultar saldo
• Agregar créditos
• Restar créditos
• Gestión de saldo

📊 Transacciones

• Crear transacciones
• Ver historial
• Tipos de transacción

📋 Datos

• Categorías de productos
• Unidades de medida
• Listado de productos

🔧 Carga de Datos

• Datos de muestra para desarrollo
• Categorías de ejemplo
• Unidades de medida
• Productos de prueba

Códigos de Estado HTTP

Código	Descripción
200	OK - Solicitud exitosa
201	Created - Recurso creado
400	Bad Request - Error en los datos
401	Unauthorized - No autenticado
403	Forbidden - No autorizado
404	Not Found - Recurso no encontrado
500	Internal Server Error - Error del servidor

Formato de Respuesta

Todas las respuestas siguen un formato JSON consistente:

Respuesta Exitosa

{
  "data": "contenido de la respuesta",
  "message": "mensaje descriptivo"
}

Respuesta de Error

{
  "message": "descripción del error",
  "error": "detalles adicionales"
}

Ejemplos de Uso

1. Registro de Usuario

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario123",
    "email": "usuario@ejemplo.com",
    "address": "Calle Principal 123",
    "phone": "1234567890",
    "password": "contraseña123"
  }'

2. Inicio de Sesión

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario123",
    "password": "contraseña123"
  }'

3. Crear Producto

curl -X POST http://localhost:3000/api/v1/products/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Manzanas Rojas",
    "description": "Manzanas frescas del valle",
    "price": 2.50,
    "quantity": 100,
    "category": "507f1f77bcf86cd799439014"
  }'