Documentación API

Guía completa para integrar AhorraPar con tu sistema

Introducción

Esta documentación describe la estructura de datos y endpoints de la plataforma AhorraPar. Está diseñada para facilitar la integración con sistemas backend como Laravel, permitiendo replicar la funcionalidad completa.

Base URL: https://api.ahorrapar.com

Esquema de Base de Datos

Tabla: users

Gestiona la autenticación y roles de usuarios

Campo Tipo Descripción
idINT (PK)ID único del usuario
emailVARCHAR(320)Email del usuario
passwordVARCHAR(255)Contraseña hasheada
nameTEXTNombre completo
roleENUM'user', 'company', 'admin'
createdAtTIMESTAMPFecha de creación
updatedAtTIMESTAMPÚltima actualización

Tabla: companies

Información de empresas registradas

Campo Tipo Descripción
idINT (PK)ID único de la empresa
userIdINT (FK)ID del usuario propietario
companyNameVARCHAR(255)Nombre de la empresa
descriptionTEXTDescripción
contactEmailVARCHAR(320)Email de contacto
contactPhoneVARCHAR(50)Teléfono
websiteVARCHAR(500)Sitio web
logoTEXTURL del logo (S3)
isActiveBOOLEANEstado activo/inactivo
createdAtTIMESTAMPFecha de creación

Tabla: promotions

Promociones creadas por empresas

Campo Tipo Descripción
idINT (PK)ID único de la promoción
companyIdINT (FK)ID de la empresa
productNameVARCHAR(255)Nombre del producto
descriptionTEXTDescripción
productImageTEXTURL de imagen (S3)
regularPriceDECIMAL(10,2)Precio normal
specialPriceDECIMAL(10,2)Precio especial
isActiveBOOLEANEstado activo/inactivo
createdAtTIMESTAMPFecha de creación

Endpoints API

Autenticación

POST /api/auth/register

Registrar nuevo usuario

{ "name": "Juan Pérez", "email": "juan@example.com", "password": "password123" }
POST /api/auth/login

Iniciar sesión

{ "email": "juan@example.com", "password": "password123" }
GET /api/auth/me

Obtener usuario autenticado

Requiere autenticación
POST /api/auth/logout

Cerrar sesión

Requiere autenticación

Empresas

POST /api/company

Crear perfil de empresa

Requiere autenticación
{ "companyName": "Joyería Elegancia", "description": "Joyería fina desde 1990", "contactEmail": "contacto@joyeriaelegancia.com", "contactPhone": "+595 21 123 4567", "website": "https://joyeriaelegancia.com", "logo": "https://s3.amazonaws.com/..." }
GET /api/company/mine

Obtener empresa propia

Rol: company, admin
PUT /api/company

Actualizar empresa propia

Rol: company, admin
GET /api/admin/companies

Listar todas las empresas

Rol: admin

Promociones

GET /api/promotions

Listar todas las promociones activas (público)

Público
GET /api/promotions/{id}

Obtener detalle de una promoción

Público
POST /api/promotions

Crear nueva promoción

Rol: company, admin
{ "productName": "Collar de Plata 925", "description": "Hermoso collar...", "productImage": "https://s3.amazonaws.com/...", "regularPrice": 450000, "specialPrice": 315000 }
PUT /api/promotions/{id}

Actualizar promoción propia

Rol: company, admin
DELETE /api/promotions/{id}

Eliminar promoción propia

Rol: company, admin

Ejemplo de Implementación Laravel

Controlador de promociones:

// app/Http/Controllers/PromotionController.php class PromotionController extends Controller { public function index() { return Promotion::with('company') ->where('isActive', true) ->orderBy('createdAt', 'desc') ->get(); } public function store(Request $request) { $validated = $request->validate([ 'productName' => 'required|string|max:255', 'description' => 'required|string', 'productImage' => 'required|url', 'regularPrice' => 'required|numeric|min:0', 'specialPrice' => 'required|numeric|min:0' ]); $company = auth()->user()->company; return $company->promotions()->create($validated); } }