Referencia API — Madsjeez Marketplace
Documentación interactiva (sitio): Abrir /docs/api — misma guía con navegación lateral estilo portal de desarrolladores.
Documentación orientada a desarrolladores, en el espíritu de los portales tipo Mercado Libre Developers: recursos agrupados por dominio, métodos HTTP, autenticación y convenciones de respuesta.
Base URL:
{NEXT_PUBLIC_APP_URL}en producción (ej.https://www.madsjeez.com.ar). En local:http://localhost:3000.
Prefijo API: todas las rutas documentadas viven bajo/api/....
Contenido
| Documento | Contenido |
|---|---|
| Introducción y convenciones | URL, JSON, cookies de sesión, idempotencia, versionado |
| Listo para producción (requisitos doc) | Checklist: índice, recurso, .env.example, errores, deploy |
| Errores y códigos HTTP | Patrones 4xx / 5xx, cuerpo de error típico |
| Índice maestro (tabla) | Listado de handlers con métodos (actualizar al agregar rutas) |
| Autenticación | NextAuth, registro, usuario actual |
| Productos y catálogo | CRUD, variaciones, mayorista, carrusel |
| Pedidos, carrito y checkout | Órdenes, carrito, checkout MP |
| Zipnova Envíos | Cotización envío, env vars, checkout MP + metadata orden |
| Dashboard | Métricas, productos panel, soporte, favoritos |
| Reclamos, envíos, reputación | Claims, shipments, reputation |
| Preguntas y notificaciones | Q&A, uploads, notificaciones |
| Marketing: campañas, cupones, ofertas | Campaigns, coupons, offers |
| Mercado Libre (integración) | OAuth, import, PADS, promos |
| Vendedor — Mercado Pago | Conexión OAuth vendedor, preferencias |
| Búsqueda | Listings, sugerencias, smart, imagen |
| IA | Endpoints bajo /api/ai/* |
| Meta / WhatsApp | Webhook, envío, conexión |
| Administración | Bootstrap admin, seeds (entornos controlados) |
| Webhooks y salud | Mercado Pago webhook, health |
| Suscripciones, importación, chat | Subscriptions, import-products, chat |
| Prueba / utilidades | Endpoints solo para desarrollo |
Código fuente
La implementación vive en src/app/api/**/route.ts (App Router de Next.js). Esta documentación no sustituye el contrato exacto de cada cuerpo JSON: ante dudas, el código es la fuente de verdad hasta que exista esquema OpenAPI generado automáticamente.
Mantenimiento
Al agregar o renombrar rutas:
- Cumplir el checklist listo para producción si el cambio se publica a usuarios reales.
- Actualizar la tabla en índice maestro.
- Ajustar el archivo de recurso correspondiente bajo
docs/api/recursos/.