Documentacion para Desarrolladores

API de Autos TREFA

Integra tu aplicacion o herramienta de IA con nuestro inventario de vehiculos seminuevos. API RESTful publica y servidor MCP para asistentes de inteligencia artificial.

API REST Servidor MCP

Inventario

Lista de vehiculos

Busqueda

Texto completo

Estadisticas

Datos agregados

MCP Tools

Para asistentes IA

Descripcion General

La API de Autos TREFA proporciona acceso programatico de solo lectura al inventario de vehiculos seminuevos. Puedes consultar vehiculos disponibles, buscar por criterios especificos y obtener estadisticas del inventario.

API RESTful

Endpoints HTTP con respuestas JSON estandarizadas.

Servidor MCP

Protocolo MCP para integracion con Claude, GPT y otros LLMs.

Sin Autenticacion

API publica, no requiere API keys ni tokens.

Alto Rendimiento

Respuestas cacheadas con TTL de 5-10 minutos.

Base URL: https://trefa.mx/api/public

Formato: JSON

Metodos: GET (solo lectura)

Autenticacion

La API publica de inventario no requiere autenticacion. Todos los endpoints estan disponibles sin necesidad de API keys, tokens o headers especiales.

Acceso libre: Los datos expuestos son informacion publica del inventario de vehiculos. Puedes integrar la API directamente en tu aplicacion.

CORS y Limites

CORS esta habilitado para todos los origenes, permitiendo llamadas desde cualquier dominio.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Cache-Control: public, s-maxage=300, stale-while-revalidate=600

http

Rate Limiting

Actualmente no hay limites estrictos de rate limiting, pero recomendamos:

Maximo 100 requests por minuto por IP
Usar cache del lado del cliente cuando sea posible
Respetar los headers Cache-Control en las respuestas

Manejo de Errores

Todos los endpoints retornan errores en formato consistente:

{
  "success": false,
  "data": null,
  "error": "Descripcion del error"
}

json

Parametro	Tipo	Descripcion
`400`	Bad Request	Parametros invalidos o faltantes
`404`	Not Found	Recurso no encontrado
`500`	Server Error	Error interno del servidor

API REST

Todos los endpoints retornan respuestas JSON con la siguiente estructura:

{
  "success": true,
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

json

success(boolean)Indica si la peticion fue exitosa

data(array | object)Datos solicitados

meta(object)Metadatos de paginacion (cuando aplica)

error(string)Mensaje de error (solo cuando success=false)

Listar Vehiculos

GET/api/public/inventory

Obtiene una lista paginada de vehiculos disponibles con filtros opcionales.

Parametros de Query

Parametro	Tipo	Descripcion
`marca`	string	Filtrar por marca (ej: Toyota, Honda, Mazda)
`modelo`	string	Filtrar por modelo (ej: Corolla, Civic)
`ano_min`	number	Ano minimo del vehiculo
`ano_max`	number	Ano maximo del vehiculo
`precio_min`	number	Precio minimo en MXN
`precio_max`	number	Precio maximo en MXN
`carroceria`	string	SUV, Sedan, Hatchback, Pickup, Van
`transmision`	string	Automatica o Manual
`combustible`	string	Gasolina, Diesel, Hibrido, Electrico
`km_max`	number	Kilometraje maximo
`con_oferta`	boolean	Solo vehiculos en oferta/promocion
`ubicacion`	string	Filtrar por ubicacion/sucursal
`page`	number	Numero de pagina (default: 1)
`per_page`	number	Resultados por pagina (default: 20, max: 100)

Ejemplo de Request

curl "https://trefa.mx/api/public/inventory?marca=Toyota&precio_max=400000&per_page=10"

bash

Ejemplo de Response

{
  "success": true,
  "data": [
    {
      "id": 1234,
      "slug": "toyota-corolla-2022-abc123",
      "titulo": "Toyota Corolla 2022",
      "marca": "Toyota",
      "modelo": "Corolla",
      "ano": 2022,
      "precio": 389000,
      "oferta": 375000,
      "kilometraje": 25000,
      "transmision": "Automatica",
      "combustible": "Gasolina",
      "carroceria": "Sedan",
      "imagen": "https://r2.trefa.mx/...",
      "disponible": true,
      "url": "https://trefa.mx/autos/toyota-corolla-2022-abc123"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 10,
    "total_pages": 5
  }
}

json

Detalle de Vehiculo

GET/api/public/inventory/{slug}

Obtiene informacion detallada de un vehiculo especifico por su slug o ID numerico.

Parametros de Ruta

Parametro	Tipo	Descripcion
`slug`requerido	string	Slug URL o ID numerico del vehiculo

Ejemplo de Request

curl "https://trefa.mx/api/public/inventory/toyota-corolla-2022-abc123"

bash

Response

Incluye informacion completa del vehiculo:

Especificaciones tecnicas (motor, cilindros, transmision)
Precios y ofertas vigentes
Galeria de imagenes (exterior e interior)
Informacion de garantia y factura
Opciones de financiamiento estimadas
Estado de disponibilidad

Busqueda de Texto

GET/api/public/inventory/search

Realiza busqueda de texto completo en el inventario. Busca en marca, modelo, titulo y tipo de carroceria.

Parametros

Parametro	Tipo	Descripcion
`q`requerido	string	Termino de busqueda (minimo 2 caracteres)
`limit`	number	Maximo de resultados (default: 20, max: 50)

Ejemplo

curl "https://trefa.mx/api/public/inventory/search?q=suv+toyota&limit=10"

bash

Response

{
  "success": true,
  "data": [...],
  "meta": {
    "query": "suv toyota",
    "total": 8,
    "tiempo_ms": 45
  }
}

json

Estadisticas del Inventario

GET/api/public/inventory/stats

Obtiene estadisticas agregadas del inventario disponible. Util para mostrar resumen general, filtros disponibles o dashboards.

Ejemplo de Response

{
  "success": true,
  "data": {
    "total_vehiculos": 156,
    "vehiculos_disponibles": 148,
    "vehiculos_en_oferta": 23,
    "rango_precios": {
      "minimo": 159000,
      "maximo": 890000,
      "promedio": 342000
    },
    "rango_anos": {
      "minimo": 2018,
      "maximo": 2024
    },
    "por_marca": [
      { "marca": "Toyota", "cantidad": 28 },
      { "marca": "Honda", "cantidad": 22 },
      { "marca": "Mazda", "cantidad": 19 }
    ],
    "por_carroceria": [
      { "carroceria": "SUV", "cantidad": 65 },
      { "carroceria": "Sedan", "cantidad": 48 }
    ],
    "por_transmision": [
      { "transmision": "Automatica", "cantidad": 132 },
      { "transmision": "Manual", "cantidad": 24 }
    ]
  }
}

json

Servidor MCP

El servidor MCP (Model Context Protocol) permite que asistentes de IA como Claude, ChatGPT o aplicaciones personalizadas accedan al inventario de TREFA de forma nativa.

Que es MCP?

MCP es un protocolo abierto desarrollado por Anthropic que permite a los modelos de lenguaje conectarse con fuentes de datos externas de forma segura y estructurada. El servidor MCP de TREFA expone herramientas especializadas para:

Buscar y filtrar vehiculos con criterios naturales
Obtener detalles y comparar opciones
Calcular financiamientos y mensualidades
Consultar informacion del negocio y FAQs

Nombre del servidor: trefa-mcp-server
Version: 1.0.0
Transporte: stdio
Herramientas: 18 tools

Instalacion del Servidor MCP

Requisitos

Node.js 18 o superior
npm o pnpm
Acceso a las variables de entorno de Supabase (contacta a [email protected])

Clonar e Instalar

# Clonar el repositorio
git clone https://github.com/autostrefa/trefa-mcp-server.git
cd trefa-mcp-server

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

bash

Configuracion en Claude Desktop

Agrega la siguiente configuracion en tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "trefa": {
      "command": "node",
      "args": ["/ruta/completa/trefa-mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "tu-supabase-url",
        "SUPABASE_ANON_KEY": "tu-anon-key"
      }
    }
  }
}

json

Verificar Instalacion

Reinicia Claude Desktop y verifica que el servidor este activo. Deberas ver las herramientas de TREFA disponibles en el menu de herramientas.

Herramientas MCP

El servidor MCP expone las siguientes herramientas organizadas por categoria:

Inventario

buscar_vehiculos(marca, modelo, precio_min, precio_max, carroceria, ...)

Busca vehiculos con multiples filtros. Retorna lista con precio, ano, km y URL.

obtener_vehiculo(id | slug)

Obtiene todos los detalles de un vehiculo especifico.

buscar_alternativas(marca_original, presupuesto, prioridad)

Encuentra vehiculos similares cuando no hay el modelo exacto.

comparar_vehiculos(vehiculo_ids[])

Compara 2-4 vehiculos lado a lado con analisis.

estadisticas_inventario

Resumen del inventario: totales, rangos de precio, marcas disponibles.

Financiamiento

calcular_financiamiento(precio_vehiculo, enganche_porcentaje, plazo_meses)

Calcula mensualidades estimadas con diferentes plazos.

obtener_solicitud_financiamiento(application_id | user_id)

Consulta el estado de una solicitud de financiamiento.

verificar_documentos(application_id)

Verifica que documentos ha subido el cliente y cuales faltan.

obtener_perfil_bancario(user_id)

Obtiene el resultado de perfilacion y banco recomendado.

Perfiles de Usuario

buscar_usuario(email | telefono | nombre)

Busca un usuario por diferentes criterios.

obtener_perfil_completo(user_id)

Obtiene toda la informacion del usuario: perfil, solicitudes, favoritos.

verificar_completitud_perfil(user_id)

Verifica si el perfil esta completo para solicitar financiamiento.

Informacion del Negocio

buscar_informacion(pregunta, categoria)

Busca en la base de conocimiento de TREFA.

obtener_info_negocio(tema)

Informacion especifica: horarios, garantias, proceso de compra, etc.

obtener_faqs(categoria?)

Preguntas frecuentes, opcionalmente filtradas por categoria.

Prompts Predefinidos

El servidor incluye prompts predefinidos para consultas comunes:

Consultas de Inventario

listar-suvsTodas las SUVs

listar-ofertasEn promocion

listar-economicosMenos de $250k

listar-recientes2022 o mas nuevo

listar-pickupsCamionetas

listar-automaticosTransmision auto

Consultas por Marca

listar-toyotaToyota

listar-hondaHonda

listar-mazdaMazda

listar-nissanNissan

listar-volkswagenVW

listar-kiaKia

Financiamiento e Informacion

calcular-mensualidadCalculadora

requisitos-financiamientoDocumentos

horarios-atencionHorarios

info-garantiaGarantias

resumen-inventarioEstadisticas

Ejemplo en JavaScript

// Usando fetch nativo
async function buscarVehiculos(marca, precioMax) {
  const params = new URLSearchParams({
    marca,
    precio_max: precioMax,
    per_page: 10
  });

  const response = await fetch(
    `https://trefa.mx/api/public/inventory?${params}`
  );

  const { success, data, meta } = await response.json();

  if (success) {
    console.log(`Encontrados ${meta.total} vehiculos`);
    data.forEach(v => {
      console.log(`${v.titulo} - $${v.precio.toLocaleString()}`);
    });
  }
}

// Buscar SUVs Toyota menores a 500k
buscarVehiculos('Toyota', 500000);

javascript

Ejemplo en Python

import requests

def buscar_vehiculos(marca, precio_max):
    """Busca vehiculos en el inventario de TREFA"""

    response = requests.get(
        "https://trefa.mx/api/public/inventory",
        params={"marca": marca, "precio_max": precio_max, "per_page": 10}
    )

    data = response.json()

    if data["success"]:
        print("Encontrados", data["meta"]["total"], "vehiculos")
        for v in data["data"]:
            print(v["titulo"], "-", v["precio"])

    return data

# Buscar Hondas menores a 400k
vehiculos = buscar_vehiculos("Honda", 400000)

python

Ejemplos con cURL

Listar vehiculos con filtros

curl -X GET "https://trefa.mx/api/public/inventory?marca=Mazda&carroceria=SUV&precio_max=450000" \
  -H "Accept: application/json"

bash

Busqueda de texto

curl -X GET "https://trefa.mx/api/public/inventory/search?q=camioneta%20familiar" \
  -H "Accept: application/json"

bash

Obtener estadisticas

curl -X GET "https://trefa.mx/api/public/inventory/stats" \
  -H "Accept: application/json" | jq

bash

Necesitas ayuda?

Si tienes preguntas sobre la API o necesitas acceso a funcionalidades adicionales, contactanos.

[email protected]Ver FAQs