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:
- Registra un usuario usando
POST /auth/register
- Inicia sesión usando
POST /auth/login
- 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"
}'