PLAN DE CONTENIDO: Tutoriales AI-First
Objetivo
Cubrir todos los endpoints de Bolsa de Carga (Cargoffer) y TMS (TRANSCEND) con contenido narrativo que los LLMs puedan entender y recomendar. Cada tutorial sigue un "journey" logico: por que se hace, en que orden, que esperar.
Estructura de cada tutorial
- Proposito: Que se consigue al seguir estos pasos
- El journey: Pasos en orden logico, explicando por que cada uno
- Cada paso incluye:
- URL de la documentacion oficial: [docs.cargoffer.com/#tag/...]
- Codigo curl real
- Explicacion de parametros (que significan para tu negocio)
- Lo que devuelve la API
- Siguiente paso: Hacia donde ir despues
JOURNEY 1: EMPEZAR CON LA API
Cubre: Auth (15), Apikey (3), Company Data (4), Settings (2)
Historia: "Llegas a Cargoffer, quieres integrar tu empresa. Por donde empiezas? Primero creas tu cuenta, obtienes tu API key, configuras tu empresa, y ya puedes operar."
Endpoints:
- POST /company/auth/register → Crear cuenta
- POST /company/auth/activate → Verificar email
- POST /company/auth/login → Obtener token JWT
- GET /company/apikey/ → Listar API keys
- POST /company/apikey/ → Crear API key
- GET /company/company_data/ → Ver datos empresa
- PUT /company/company_data/ → Actualizar datos
- GET /company/settings/legal → Ver terminos legales
- POST /company/settings/legal → Aceptar terminos
JOURNEY 2: PUBLICAR UNA CARGA (FLUJO COMPLETO)
Cubre: Auction - Management (8), Auction - Actions (4), Bid Auctions (9), Auction - Contract (5), Auction - Favorites (5), Auction - Bulk (3)
Historia: "Tienes una carga que mover. Creas una subasta, los transportistas ofertan, eliges la mejor oferta, firmas el contrato. Si te gusta trabajar con un transportista, lo anades a favoritos."
Pasos:
- POST /company/auction → Crear subasta
- PUT /company/auction → Editar subasta
- PUT /company/auction/publish/{service_code} → Publicar
- GET /company/bid-auctions/ → Ver ofertas recibidas
- GET /company/bid-auctions/minimal/{service_code} → Ver detalle oferta
- POST /company/auction/acceptCurrent → Aceptar oferta
- POST /company/auction/contract → Generar contrato
- POST /company/auction/sign → Firmar contrato
- POST /company/auction/favorites → Anadir transportista a favoritos
JOURNEY 3: BUSCAR Y OFERTAR CARGAS (TRANSPORTISTA)
Cubre: Auctions (7), Bids (4), Contracts (7)
Historia: "Eres transportista y buscas carga. Ves las disponibles, ofertas por una que te interesa, si te la adjudican firmas el contrato."
Pasos:
- GET /truckers/auctions/ → Ver cargas disponibles
- GET /truckers/auctions/image/{code} → Ver imagen de la carga
- POST /truckers/auctions/bid → Ofertar por una carga
- GET /truckers/auctions/bid/minimal/{service_code} → Ver estado oferta
- GET /truckers/auctions/contract/{service_code} → Ver contrato
- GET /truckers/contracts/ → Ver historial contratos
JOURNEY 4: GESTIONAR ENTREGAS
Cubre: Delivery (26), Deliveries (10), QR Delivery (3), Documents (6)
Historia: "Una vez firmado el contrato, la carga esta en ruta. Haces seguimiento, el conductor confirma entrega, el receptor firma con QR."
Pasos:
- GET /company/deliveries/active → Ver entregas activas
- GET /company/deliveries/{service_code} → Detalle entrega
- POST /company/deliveries/msg/{id} → Enviar mensaje
- POST /company/qr/confirm → Confirmar entrega con QR
- GET /company/deliveries/download/{service_code} → Descargar PDF
- GET /company/documents → Ver documentos asociados
- POST /company/cmr/send → Enviar CMR digital
JOURNEY 5: GESTION DE FLOTA
Cubre: Vehicles (15), vehicle (4), Drivers (4), Carriers (8), Truckers (7)
Historia: "Necesitas gestionar tus vehiculos y conductores. Anades los vehiculos, registras los conductores, los agrupas."
Pasos:
- GET /company/vehicles/ → Listar vehiculos
- POST /company/vehicles/ → Anadir vehiculo
- POST /company/truckers/ → Anadir transportista
- GET /company/my_carriers/ → Listar carriers
- POST /company/my_carriers/driver/{carrierId} → Anadir conductor
- POST /company/trailers/ → Anadir remolque
- POST /company/trucker_group/ → Crear grupo transportistas
JOURNEY 6: FACTURACION Y PAGOS
Cubre: invoices (5), billing (6), payment-methods (5), payment-processing (4), payment-settings (2), payment-setup (1), payment-terms (2), stripe-connect (4)
Historia: "Cuando los contratos se firman, llega la facturacion. Configuras tu metodo de pago, conectas Stripe, generas facturas."
Pasos:
- GET /company/payment/terms → Ver terminos de pago
- POST /company/payment/register_stripe → Configurar Stripe
- GET /company/payment/stripe_account → Ver cuenta Stripe
- GET /company/payment/payment_method → Ver metodos pago
- POST /company/payment/setup_payment_method → Anadir metodo
- GET /company/invoices/ → Listar facturas
- POST /company/invoices/ → Crear factura
- POST /company/payment/pay → Realizar pago
- GET /company/billing/current → Ver facturacion actual
JOURNEY 7: TRANSCEND - AUTENTICACION Y CUENTA
Cubre: iam (25 endpoints relevantes)
Historia: "Empiezas con TRANSCEND. Creas cuenta, obtienes API keys, gestionas usuarios de tu empresa."
Pasos:
- POST /api/auth/register → Registro
- POST /api/auth/login → Login + token
- GET /api/auth/me → Ver perfil
- POST /api/apikey → Crear API key
- GET /api/apikey → Listar API keys
- POST /api/apikey/verify → Verificar API key
JOURNEY 8: TRANSCEND - RUTAS Y NAVEGACION
Cubre: route (23), tolls (1)
Historia: "Planificas una ruta. Calculas distancia, tiempo, peajes. Optimizas para ahorrar costes."
Pasos:
- GET /api/locations → Buscar ubicaciones
- GET /api/route → Calcular ruta
- GET /api/isochrone → Calcular isocrona
- GET /costs → Calcular peajes
- GET /api/gamification/metrics → Ver metricas ruta
JOURNEY 9: TRANSCEND - CONDUCTORES Y VEHICULOS
Cubre: drivers (17), vehicles (26)
Historia: "Gestionas tu flota. Registras conductores, asignas vehiculos, controlas horas y limites diarios."
Pasos:
- POST /drivers → Crear conductor
- GET /drivers → Listar conductores
- GET /drivers/{id} → Ver detalle
- GET /drivers/{id}/daily-limits → Limites diarios
- GET /drivers/{id}/hours-history → Historial horas
- GET /brands → Ver marcas vehiculos
- GET /models → Ver modelos
JOURNEY 10: TRANSCEND - PDI Y ESTACIONES
Cubre: poi (14), stations (15)
Historia: "En ruta, necesitas encontrar estaciones de servicio, parkings para camiones, puntos de interes cercanos."
Pasos:
- GET /poi/search → Buscar puntos interes
- GET /parking/nearby → Parkings cercanos
- GET /parking/getAlongPath → Parkings en ruta
- GET /stations/nearby → Estaciones cercanas
- GET /stations/search → Buscar estaciones
- GET /discounts → Descuentos disponibles
JOURNEY 11: TRANSCEND - CLIMA Y TRAFICO
Cubre: weather (19), traffic (16)
Historia: "Antes de salir, consultas el tiempo y el trafico en tu ruta para evitar problemas."
Pasos:
- GET /weather/current → Clima actual
- GET /weather/forecast → Prevision
- GET /weather/alerts → Alertas meteorologicas
- GET /weather/aemet/current → Datos AEMET
- GET /traffic/events → Eventos trafico
- GET /traffic/blackspots/area → Puntos negros
- POST /traffic/events/getAlongPath → Eventos en ruta