------------------------------------------------------------------------------------------------------------------------
title: "Introducción"
description: "Bienvenido a la documentación de la API de Rueda Lens. Aprende a integrar identificación de neumáticos y vehículos con IA en tu aplicación."
section: "guide"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es"
------------------------------------------------------------------------------------------------------------------------

# Introducción

Rueda Lens es un servicio de API B2B que ofrece **identificación de neumáticos y vehículos mediante IA** a partir de imágenes de neumáticos. Está construido con tecnologías líderes del sector para ofrecer el máximo rendimiento, fiabilidad y escalabilidad.

<Callout title="Inicio rápido">
  Empieza con nuestra [Guía de primeros pasos](/getting-started) para realizar tu primera llamada a la API en cuestión de minutos.
</Callout>

## Funcionalidades clave

* **Reconocimiento mediante IA** — IA avanzada que analiza imágenes de neumáticos y vehículos para una identificación precisa
* **Datos completos** — Devuelve marca del vehículo, modelo, acabados, rango de años, especificaciones del neumático y recomendaciones de presión
* **Procesamiento rápido** — Normalmente entre 7 y 15 segundos por solicitud
* **API REST** — Endpoints JSON sencillos y bien documentados
* **Autenticación segura** — Autenticación mediante clave de API con almacenamiento cifrado
* **Seguimiento de uso** — Monitorización de cuotas en tiempo real y notificaciones por correo electrónico
* **Facturación flexible** — Planes de suscripción con soporte de excedentes para empresas en crecimiento

## Casos de uso

| Industria                   | Aplicación                                                                        |
| --------------------------- | --------------------------------------------------------------------------------- |
| **Comercio electrónico**    | Identificar vehículos compatibles a partir de fotos de neumáticos de los clientes |
| **Servicios de automoción** | Optimizar los flujos de identificación de vehículos                               |
| **Seguros**                 | Automatizar los procesos de verificación de vehículos                             |
| **Gestión de inventario**   | Catalogar rápidamente datos de neumáticos y vehículos                             |

## URL base

```
https://api.ruedalens.com
```

## Próximos pasos

<Cards>
  <Card title="Primeros pasos" href="/getting-started" description="Realiza tu primera llamada a la API en minutos" />
  <Card title="Autenticación" href="/authentication" description="Aprende a gestionar las claves de la API" />
  <Card title="Referencia de la API" href="/api-reference/analyze" description="Explora los endpoints y parámetros" />
  <Card title="Gestión de errores" href="/error-handling" description="Gestiona los errores de forma adecuada" />
</Cards>


------------------------------------------------------------------------------------------------------------------------
title: "LLM Full"
description: "Accede a toda la documentación en formato de texto plano para consumo por LLMs."
section: "resources"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es/resources/llms-full"
------------------------------------------------------------------------------------------------------------------------

# LLM Full

Esta página proporciona una versión en texto plano de toda la documentación de Rueda Lens, optimizada para el consumo por Modelos de Lenguaje Grande (LLMs) como ChatGPT, Claude y otros.

## ¿Qué es LLM Full?

LLM Full es un archivo de texto plano consolidado que contiene todas las páginas de documentación en un formato fácil de procesar para asistentes de IA. Esto te permite:

- Proporcionar toda la documentación a tu LLM preferido para asistencia contextual
- Obtener respuestas precisas sobre Rueda Lens sin que la IA invente información
- Trabajar con asistentes de IA que tienen conocimiento completo de todas las características y mejores prácticas de la API

## Cómo usar

### Opción 1: Acceso directo

Accede a la documentación en texto plano directamente en:

- **Inglés**: [https://docs.ruedalens.com/en/llms-full.txt](https://docs.ruedalens.com/en/llms-full.txt)
- **Español**: [https://docs.ruedalens.com/es/llms-full.txt](https://docs.ruedalens.com/es/llms-full.txt)

### Opción 2: Con ChatGPT, Claude u otras herramientas de IA

1. Copia la URL de arriba
2. En el chat, pega: "Por favor lee y analiza la documentación en [URL]"
3. Haz tus preguntas sobre la API de Rueda Lens

## Especificación del Formato

El archivo de texto plano sigue esta estructura:

```txt
--------------------------------------------------------------------------------
title: "Título de la Página"
description: "Descripción de la página"
section: "guide | api-reference | resources"
last_updated: "2026-02-09T12:00:00.000Z"
source: "https://docs.ruedalens.com/es/slug-pagina"
--------------------------------------------------------------------------------

# Título de la página

[Contenido markdown completo de la página]

```

Cada página está separada por líneas horizontales (`---`) e incluye metadatos que ayudan a los LLMs a entender el contexto y la fuente de cada sección.

## Mejores prácticas

Al trabajar con LLMs usando esta documentación:

1. **Sé específico**: Haz preguntas precisas referenciando endpoints o características específicas de la API
2. **Verifica el código**: Siempre prueba los ejemplos de código proporcionados por la IA en un entorno de desarrollo
3. **Busca actualizaciones**: La documentación se actualiza regularmente, así que verifica la información para los últimos cambios
4. **Usa comillas**: Referencia partes específicas de la documentación al hacer preguntas de seguimiento

## Ejemplos de prompts

Aquí hay algunas formas efectivas de usar la documentación LLM Full:

**Configuración**:
```
Estoy proporcionando la documentación completa de la API de Rueda Lens. Por favor léela con cuidado.

[Pega el contenido de llms-full.txt]

¿Listo para responder mis preguntas?
```

**Comenzando**:
```
Basándote en la documentación de Rueda Lens, muéstrame cómo:
1. Autenticarme con la API
2. Hacer mi primera solicitud de reconocimiento de vehículo
3. Manejar el límite de peticiones
```

**Resolución de Problemas**:
```
Estoy recibiendo un error 401 al llamar a /v1/analyze. Basándote en la documentación,
¿cuáles son las posibles causas y cómo las soluciono?
```

## Comentarios

¿Encontraste un problema con el formato LLM Full o tienes sugerencias de mejora? Por favor [contacta a nuestro equipo de soporte](mailto:support@ruedalens.com) o envía un issue en nuestro repositorio de GitHub.


------------------------------------------------------------------------------------------------------------------------
title: "POST /v1/analyze"
description: "Analiza imágenes de neumáticos y vehículos para identificar información del neumático y del vehículo."
section: "api-reference"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es/api-reference/analyze"
------------------------------------------------------------------------------------------------------------------------

# POST /v1/analyze

Analiza imágenes de neumáticos y vehículos mediante IA avanzada para identificar la marca, el modelo, el año, los acabados (trims) y las especificaciones de los neumáticos del vehículo.

## Endpoint

```
POST https://api.ruedalens.com/v1/analyze
```

## Autenticación

Requiere una clave de API válida en la cabecera `Authorization`.

```
Authorization: Bearer rdlns_sk_...
```

## Solicitud

### Cabeceras

| Cabecera        | Valor                 | Requerida |
| --------------- | --------------------- | --------- |
| `Authorization` | `Bearer rdlns_sk_...` | Sí        |
| `Content-Type`  | `application/json`    | Sí        |

### Parámetros del cuerpo

| Parámetro   | Tipo     | Requerido | Descripción                               |
| ----------- | -------- | --------- | ----------------------------------------- |
| `tireImage` | `string` | Sí        | Imagen del neumático codificada en Base64 |
| `carImage`  | `string` | Sí        | Imagen del vehículo codificada en Base64  |

### Ejemplo de solicitud

```bash
curl -X POST https://api.ruedalens.com/v1/analyze \
  -H "Authorization: Bearer rdlns_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tireImage": "/9j/4AAQSkZJRg...",
    "carImage": "/9j/4AAQSkZJRg..."
  }'
```

## Respuesta

### Éxito — `200 OK`

```json
{
  "success": true,
  "requestId": "cmlecazi4000111qu590n9v6i",
  "data": {
    "vehicles": [
      {
        "confidence": 0.98,
        "brand": "Lexus",
        "model": "NX",
        "trims": ["300h", "300"],
        "start_year": 2017,
        "end_year": 2021,
        "current_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": null,
          "xl": null
        },
        "oe_front_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": false,
          "xl": false
        },
        "oe_rear_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": false,
          "xl": false
        },
        "pressure_front": 2.2,
        "pressure_rear": 2.2
      }
    ]
  },
  "metrics": {
    "executionTimeMs": 10364
  },
  "timestamp": "2026-02-08T22:54:03.962Z"
}
```

### Campos de la respuesta

| Campo                            | Tipo       | Descripción                                                                 |
| -------------------------------- | ---------- | --------------------------------------------------------------------------- |
| `success`                        | `boolean`  | Indica si la solicitud fue exitosa                                          |
| `requestId`                      | `string`   | Identificador único de la solicitud para seguimiento y depuración           |
| `data.vehicles`                  | `array`    | Lista de coincidencias de vehículos identificados (ordenadas por confianza) |
| `data.vehicles[].confidence`     | `number`   | Nivel de confianza de la IA (0.0 a 1.0)                                     |
| `data.vehicles[].brand`          | `string`   | Fabricante del vehículo                                                     |
| `data.vehicles[].model`          | `string`   | Modelo base del vehículo                                                    |
| `data.vehicles[].trims`          | `string[]` | Niveles de acabado disponibles para este modelo                             |
| `data.vehicles[].start_year`     | `number`   | Primer año de producción de esta generación                                 |
| `data.vehicles[].end_year`       | `number`   | Último año de producción de esta generación                                 |
| `data.vehicles[].current_tire`   | `object`   | Especificación del neumático detectada en el flanco                         |
| `data.vehicles[].oe_front_tire`  | `object`   | Especificación del neumático original (OE) delantero                        |
| `data.vehicles[].oe_rear_tire`   | `object`   | Especificación del neumático original (OE) trasero                          |
| `data.vehicles[].pressure_front` | `number`   | Presión recomendada del neumático delantero (bar)                           |
| `data.vehicles[].pressure_rear`  | `number`   | Presión recomendada del neumático trasero (bar)                             |
| `metrics.executionTimeMs`        | `number`   | Tiempo total de procesamiento en milisegundos                               |
| `timestamp`                      | `string`   | Marca temporal ISO 8601 de la respuesta                                     |

### Estructura del objeto de neumático

Cada objeto de neumático (`current_tire`, `oe_front_tire`, `oe_rear_tire`) contiene:

| Campo          | Tipo            | Descripción                                                 |
| -------------- | --------------- | ----------------------------------------------------------- |
| `width`        | `number`        | Ancho del neumático en milímetros (p. ej., 225)             |
| `aspect_ratio` | `number`        | Altura del perfil como porcentaje del ancho (p. ej., 60)    |
| `diameter`     | `number`        | Diámetro de la llanta en pulgadas (p. ej., 18)              |
| `load_index`   | `string`        | Índice de carga (p. ej., "100")                             |
| `speed_index`  | `string`        | Índice de velocidad máxima (p. ej., "H")                    |
| `structure`    | `string`        | Tipo de construcción del neumático (normalmente "R" radial) |
| `runflat`      | `boolean\|null` | Indica si el neumático es run-flat                          |
| `xl`           | `boolean\|null` | Indica si el neumático es de carga extra (XL)               |

### Comprendiendo los campos de neumáticos

La respuesta incluye tres especificaciones de neumáticos con distintos propósitos:

* **`current_tire`**: Especificación leída del flanco del neumático mediante OCR. Representa lo que está montado actualmente. Puede contener valores `null` si el texto no es legible.
* **`oe_front_tire`**: Especificación original de fábrica (OE) del eje delantero según el fabricante.
* **`oe_rear_tire`**: Especificación original de fábrica (OE) del eje trasero. En la mayoría de vehículos coincide con la delantera salvo configuraciones escalonadas.

<Callout type="info" title="Neumático actual vs. OE">
  El neumático actual puede diferir del especificado de fábrica si el propietario ha cambiado las medidas. Usa `current_tire` para saber qué lleva el vehículo y `oe_front_tire` / `oe_rear_tire` para sugerir reemplazos compatibles.
</Callout>

### Comprendiendo los niveles de confianza

El campo `confidence` (0.0 a 1.0) indica el grado de certeza de la IA en la identificación del vehículo:

| Rango de confianza | Interpretación     | Recomendación                                          |
| ------------------ | ------------------ | ------------------------------------------------------ |
| **0.95 - 1.0**     | Confianza muy alta | Apto para procesamiento automático                     |
| **0.85 - 0.94**    | Confianza alta     | Generalmente fiable, se recomienda verificación ligera |
| **0.70 - 0.84**    | Confianza moderada | Se recomienda verificación manual                      |
| **< 0.70**         | Confianza baja     | Requiere revisión manual                               |

<Callout type="warn" title="Resultados de baja confianza">
  Cuando la confianza es inferior a 0.70, recomendamos mostrar los resultados al usuario para verificación manual. Esto suele ocurrir con imágenes poco claras, modelos poco comunes o marcajes ambiguos.
</Callout>

### Comprendiendo el array de acabados (trims)

El array `trims` está ordenado por probabilidad, siendo el primero el más probable:

```json
"trims": ["300h", "300", "200t"]
```

Esto indica que el vehículo es más probablemente un "300h", aunque también podría ser un "300" o un "200t". Usa el primer valor como coincidencia principal.

## Respuestas de error

### `400` Bad Request

```json
{
  "success": false,
  "error": {
    "code": "INVALID_IMAGE",
    "message": "Invalid request body",
    "details": {
      "field": "tireImage",
      "issue": "Must be a valid base64-encoded image"
    }
  }
}
```

### `401` Unauthorized

```json
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}
```

### `429` Too Many Requests

Se devuelve como `RATE_LIMIT_EXCEEDED` para límites de ráfaga, o `QUOTA_EXCEEDED` para agotamiento de cuota mensual (plan Sandbox):

```json
{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded"
  }
}
```

## Requisitos de las imágenes

| Propiedad                  | Requisito                                                        |
| -------------------------- | ---------------------------------------------------------------- |
| **Formato**                | JPEG o PNG                                                       |
| **Codificación**           | Cadena Base64 (sin prefijo data URL)                             |
| **Tamaño máximo**          | 10 MB por imagen                                                 |
| **Resolución recomendada** | 1920x1080 o superior (las imágenes se optimizan automáticamente) |

### Guías de calidad de imagen

La calidad de las imágenes de entrada afecta directamente a la precisión. Sigue estas recomendaciones para obtener los mejores resultados:

#### Buenas prácticas para la imagen del neumático

* **Iluminación**: Luz uniforme sin sombras duras sobre el texto del flanco
* **Ángulo**: Foto perpendicular a la rueda (frontal, sin inclinación)
* **Enfoque**: Todo el texto del flanco debe verse nítido y legible
* **Cobertura**: Captura completa del marcado del neumático (p. ej., "225/60 R18 100H")
* **Evitar**: Imágenes borrosas, ángulos extremos, sombras intensas o texto obstruido

#### Buenas prácticas para la imagen del vehículo

* **Encuadre**: Incluye el vehículo completo (frontal tres cuartos, lateral o trasero funcionan mejor)
* **Distancia**: Colócate a 3–5 metros para un encuadre óptimo
* **Claridad**: El diseño y las líneas de la carrocería deben verse claramente
* **Evitar**: Primeros planos extremos, vehículos cortados o imágenes muy recortadas

<Callout type="info" title="Resolución vs. tamaño de archivo">
  Aunque una mayor resolución mejora la precisión, imágenes de más de ~2MP ofrecen rendimientos decrecientes. Recomendamos 1920x1080 como equilibrio entre calidad y velocidad de subida. Las imágenes se reducen automáticamente a 1500px durante el procesamiento.
</Callout>

### Ejemplos visuales

A continuación se muestran ejemplos reales que demuestran una captura adecuada para obtener resultados óptimos.

#### Ejemplo 1: Condiciones estándar

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mb-8">
  <div>
    <img src="/images/examples/tire-clean.jpg" alt="Ejemplo de neumático limpio con texto del flanco visible" className="w-full rounded-lg border border-border" />
    <p className="mt-2 text-sm text-muted-foreground">Imagen del neumático: ángulo perpendicular, iluminación uniforme y texto legible</p>
  </div>
  <div>
    <img src="/images/examples/car-clean.jpg" alt="Ejemplo de vehículo con vista clara en tres cuartos" className="w-full rounded-lg border border-border" />
    <p className="mt-2 text-sm text-muted-foreground">Imagen del vehículo: vista completa con líneas y elementos de diseño claros</p>
  </div>
</div>

#### Ejemplo 2: Condiciones difíciles

Nuestro sistema mantiene alta precisión incluso en condiciones menos ideales:

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mb-8">
  <div>
    <img src="/images/examples/tire-muddy.jpg" alt="Ejemplo de neumático con barro" className="w-full rounded-lg border border-border" />
    <p className="mt-2 text-sm text-muted-foreground">Neumático con barro: el sistema extrae correctamente las especificaciones</p>
  </div>
  <div>
    <img src="/images/examples/car-muddy.jpg" alt="Vehículo en condiciones difíciles" className="w-full rounded-lg border border-border" />
    <p className="mt-2 text-sm text-muted-foreground">Imagen del vehículo: condiciones exigentes que demuestran la robustez del reconocimiento</p>
  </div>
</div>

<Callout type="success" title="Capacidades avanzadas de IA">
  Nuestro motor de reconocimiento está entrenado para manejar condiciones reales como suciedad, barro, desgaste e iluminación subóptima. Aunque las imágenes limpias ofrecen los mejores resultados, el sistema mantiene alta precisión en escenarios diversos.
</Callout>

## Rendimiento y facturación

### Tiempo de procesamiento

**Tiempo de respuesta típico de extremo a extremo: 7–15 segundos**

Incluye:

* **Tiempo de red**: Subida de imágenes a nuestros servidores (~1–3 s según conexión y tamaño)
* **Procesamiento en servidor**: Análisis y enriquecimiento mediante IA (~7–10 s)
* **Tiempo de red**: Descarga de la respuesta (&lt;1s)

**Factores que afectan al tiempo de procesamiento:**

| Factor             | Impacto                              | Optimización                                 |
| ------------------ | ------------------------------------ | -------------------------------------------- |
| Tamaño de imagen   | Archivos grandes tardan más en subir | Redimensionar a 1920x1080 antes de codificar |
| Resolución         | Impacto mínimo (auto-reducción)      | No superar 2MP                               |
| Latencia de red    | Variable según ubicación             | Usar CDN o ubicaciones edge                  |
| Carga del servidor | Mínima (auto-escalado)               | No requiere acción                           |

**El métrico `executionTimeMs`:**

* Refleja **solo el tiempo de procesamiento en servidor** (excluye red)
* Útil para monitorizar tendencias de rendimiento
* Suele oscilar entre 7.000 ms y 12.000 ms

<Callout type="info" title="Consejo de optimización">
  Para minimizar el tiempo total de la solicitud, comprime y redimensiona las imágenes antes de codificarlas en Base64. Un JPEG 1920x1080 al 85% de calidad ofrece excelentes resultados con cargas inferiores a 500 KB.
</Callout>

### Cuota y facturación

* Cada solicitud cuenta para tu cuota mensual, tenga éxito o falle
* Pueden devolverse múltiples coincidencias cuando la confianza se reparte entre modelos similares
* La API procesa ambas imágenes simultáneamente para máxima precisión


------------------------------------------------------------------------------------------------------------------------
title: "GET /v1/health"
description: "Comprueba el estado de salud de la API de Rueda Lens."
section: "api-reference"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es/api-reference/health"
------------------------------------------------------------------------------------------------------------------------

# GET /v1/health

Devuelve el estado de salud actual de la API. Este endpoint realiza comprobaciones ligeras para verificar que la API está operativa.

## Endpoint

```
GET https://api.ruedalens.com/v1/health
```

## Autenticación

**No requerida.** Este es un endpoint público.

## Solicitud

```bash
curl https://api.ruedalens.com/v1/health
```

## Respuesta

### Operativa — `200 OK`

```json
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-02-08T12:00:00.000Z"
}
```

### No operativa — `503 Service Unavailable`

```json
{
  "status": "unhealthy",
  "version": "1.0.0",
  "timestamp": "2026-02-08T12:00:00.000Z"
}
```

### Campos de la respuesta

| Campo       | Tipo     | Descripción                                          |
| ----------- | -------- | ---------------------------------------------------- |
| `status`    | `string` | `"healthy"` o `"unhealthy"`                          |
| `version`   | `string` | Versión actual de la API                             |
| `timestamp` | `string` | Marca temporal ISO 8601 de la comprobación de estado |

## Casos de uso

### Monitorización

```bash
# Comprobar el estado de salud cada 60 segundos
*/1 * * * * curl -sf https://api.ruedalens.com/v1/health || echo "API caída"
```

### Comprobación previa

```javascript
async function isApiAvailable() {
  try {
    const res = await fetch('https://api.ruedalens.com/v1/health');
    const data = await res.json();
    return res.ok && data.status === 'healthy';
  } catch (error) {
    return false;
  }
}
```

## Notas

* Este endpoint **no** consume cuota de la API
* Tiempo de respuesta habitual: < 500 ms
* Devuelve `200 OK` cuando todos los sistemas están operativos
* Devuelve `503 Service Unavailable` cuando dependencias críticas no están disponibles


------------------------------------------------------------------------------------------------------------------------
title: "Primeros pasos"
description: "Realiza tu primera llamada a la API de Rueda Lens en minutos."
section: "guide"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es/getting-started"
------------------------------------------------------------------------------------------------------------------------

# Primeros pasos

Esta guía te acompaña paso a paso para realizar tu primera llamada a la API de Rueda Lens.

<Steps>

<Step>

### Crear una cuenta

1. Visita [dashboard.ruedalens.com](https://dashboard.ruedalens.com)
2. Regístrate con tu dirección de correo electrónico
3. Verifica tu correo mediante el código OTP enviado a tu bandeja de entrada

</Step>

<Step>

### Generar una clave de API

1. Accede a la página **API Keys** en tu panel
2. Haz clic en **Create New Key**
3. Asigna a la clave un nombre descriptivo (por ejemplo, "Producción", "Pruebas")
4. Copia y guarda tu clave de API de forma segura — comienza por `rdlns_sk_`

<Callout type="warn" title="Importante">
  Las claves de API solo se muestran una vez durante su creación. Guárdalas de forma segura.
</Callout>

</Step>

<Step>

### Realizar tu primera solicitud

<Tabs items={['cURL', 'Node.js', 'Python']}> <Tab value="cURL">

```bash
curl -X POST https://api.ruedalens.com/v1/analyze \
  -H "Authorization: Bearer rdlns_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tireImage": "/9j/4AAQSkZJRg...",
    "carImage": "/9j/4AAQSkZJRg..."
  }'
```

  </Tab>
  <Tab value="Node.js">
```javascript
const response = await fetch('https://api.ruedalens.com/v1/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rdlns_sk_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tireImage: '/9j/4AAQSkZJRg...',
    carImage: '/9j/4AAQSkZJRg...',
  }),
});

const result = await response.json();
console.log(result);

````
  </Tab>
  <Tab value="Python">
```python
import requests

response = requests.post(
    'https://api.ruedalens.com/v1/analyze',
    headers={
        'Authorization': 'Bearer rdlns_sk_your_api_key_here',
        'Content-Type': 'application/json',
    },
    json={
        'tireImage': '/9j/4AAQSkZJRg...',
        'carImage': '/9j/4AAQSkZJRg...',
    }
)

result = response.json()
print(result)
````

  </Tab>
</Tabs>

</Step>

<Step>

### Entender la respuesta

Una respuesta correcta tiene este aspecto:

```json
{
  "success": true,
  "requestId": "cmlecazi4000111qu590n9v6i",
  "data": {
    "vehicles": [
      {
        "confidence": 0.98,
        "brand": "Lexus",
        "model": "NX",
        "trims": ["300h", "300"],
        "start_year": 2017,
        "end_year": 2021,
        "current_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": null,
          "xl": null
        },
        "oe_front_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": false,
          "xl": false
        },
        "oe_rear_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": false,
          "xl": false
        },
        "pressure_front": 2.2,
        "pressure_rear": 2.2
      }
    ]
  },
  "metrics": {
    "executionTimeMs": 10364
  },
  "timestamp": "2026-02-08T22:54:03.962Z"
}
```

La respuesta incluye:

* **vehicles**: array de coincidencias de vehículos identificados (ordenados por nivel de confianza)
* **requestId**: identificador único para el seguimiento de esta solicitud
* **metrics**: información de rendimiento, incluido el tiempo de ejecución

</Step>

</Steps>

## Próximos pasos

* [Aprende sobre la autenticación:](/authentication) gestión de claves de API y buenas prácticas
* [Explora la referencia de la API:](/api-reference/analyze) documentación completa de los endpoints
* [Entiende la limitación de solicitudes:](/rate-limiting) planes, cuotas y facturación por excedentes

## Herramientas para desarrolladores

### Colección de Postman

Descarga nuestra colección oficial de Postman para probar la API rápidamente:

**[Descargar colección de Postman](/Rueda-Lens-API.postman_collection.json)**

**Incluye:**

* Solicitudes preconfiguradas para todos los endpoints
* Ejemplos de cuerpos de solicitud y respuesta
* Tests automatizados para validar las respuestas
* Configuración de variables de entorno

**Configuración:**

1. Importa la colección en Postman
2. Configura tu `RUEDA_LENS_API_KEY` en las variables de la colección
3. Empieza a probar inmediatamente


------------------------------------------------------------------------------------------------------------------------
title: "Autenticación"
description: "Aprende a autenticar tus solicitudes a la API de Rueda Lens."
section: "guide"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es/authentication"
------------------------------------------------------------------------------------------------------------------------

# Autenticación

Rueda Lens utiliza **autenticación mediante clave de API** usando tokens Bearer para un acceso seguro a la API.

## Formato de la clave de API

```
rdlns_sk_<cadena_de_36_caracteres>
```

* **Prefijo**: `rdlns_sk_` identifica las claves secretas de Rueda Lens
* **Longitud total**: 44 caracteres
* **Almacenamiento**: Las claves se almacenan cifradas con bcrypt en nuestra base de datos; nunca se guardan en texto plano

## Realizar solicitudes autenticadas

Incluye tu clave de API en la cabecera `Authorization` usando el esquema `Bearer`:

```bash
curl -X POST https://api.ruedalens.com/v1/analyze \
  -H "Authorization: Bearer rdlns_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tireImage": "/9j/4AAQSkZJRg...",
    "carImage": "/9j/4AAQSkZJRg..."
  }'
```

## Crear una clave de API

1. Inicia sesión en tu [panel](https://dashboard.ruedalens.com)
2. Accede a **API Keys**
3. Haz clic en **Create New Key**
4. Asigna un nombre descriptivo
5. Copia y guarda la clave de forma segura

<Callout type="warn" title="Advertencia de seguridad">
  Las claves de API otorgan acceso completo a tu cuenta. Nunca las incluyas en repositorios de código ni las compartas públicamente.
</Callout>

## Buenas prácticas

### Usar variables de entorno

Guarda las claves de API en variables de entorno; nunca las incrustes directamente en el código:

```bash title=".env"
RUEDA_LENS_API_KEY=rdlns_sk_your_api_key_here
```

```javascript title="app.js"
const apiKey = process.env.RUEDA_LENS_API_KEY;
```

### Rotar las claves periódicamente

La rotación periódica de claves es una buena práctica de seguridad. Así puedes hacerlo sin interrupciones del servicio:

1. **Crea una nueva clave** en el panel manteniendo activa la anterior
2. **Despliega la nueva clave** en tu aplicación (mediante variables de entorno o un gestor de secretos)
3. **Verifica** que la nueva clave funciona realizando una solicitud de prueba
4. **Supervisa** durante un periodo de gracia (por ejemplo, 24–48 horas) para asegurarte de que todos los servicios se han actualizado
5. **Revoca la clave antigua** una vez confirmado que la nueva funciona en todos los entornos

<Callout title="Rotación sin interrupciones">
  Este enfoque con solapamiento garantiza la continuidad del servicio durante la rotación de claves. Ambas claves permanecen válidas durante el periodo de transición, evitando interrupciones.
</Callout>

### Usar claves separadas por entorno

| Entorno    | Nombre de la clave   |
| ---------- | -------------------- |
| Desarrollo | `dev-server`         |
| Staging    | `staging-ci`         |
| Producción | `production-primary` |

### Proteger tu API con filtrado por IP

Para una mayor seguridad, recomendamos encarecidamente implementar filtrado por IP a nivel de infraestructura:

**Por qué es importante el filtrado por IP:**

* Evita usos no autorizados incluso si una clave de API se ve comprometida
* Añade una capa adicional de seguridad en profundidad
* Ayuda a detectar y prevenir robos o filtraciones de credenciales

**Formas de implementación:**

1. **Filtrado a nivel de aplicación** (recomendado en la mayoría de casos):

   ```javascript
   const ALLOWED_IPS = ['203.0.113.42', '198.51.100.0/24'];

   function isAllowedIP(requestIP) {
     return ALLOWED_IPS.some(allowedIP => {
       // Implementa tu lógica de coincidencia de IP
       return requestIP === allowedIP || matchesCIDR(requestIP, allowedIP);
     });
   }

   // Comprobación antes de realizar llamadas a la API
   if (!isAllowedIP(clientIP)) {
     throw new Error('IP no autorizada');
   }
   ```

2. **Filtrado a nivel de infraestructura**:

   * **AWS**: Usa Security Groups o reglas de WAF
   * **Cloudflare**: Configura reglas de acceso por IP
   * **Nginx**: Usa las directivas `allow` y `deny`
   * **Balanceadores de carga en la nube**: Configura rangos de IP de origen permitidos

3. **VPN o red privada**:

   * Enruta el tráfico hacia la API a través de una VPN con IPs estáticas
   * Utiliza redes privadas del proveedor cloud (AWS PrivateLink, Azure Private Link)

<Callout type="warn" title="Despliegue en producción">
  Combina siempre el filtrado por IP con la autenticación mediante clave de API. El filtrado por IP por sí solo no es suficiente, y las claves de API por sí solas son vulnerables. Utiliza ambos para una protección máxima.
</Callout>

## Gestión de claves

En el panel puedes ver el **nombre**, la **fecha de creación**, la **fecha de último uso** y el **prefijo** de cada clave (por ejemplo, `rdlns_sk_abc...xyz`).

<Callout title="Privacidad">
  Por seguridad, en el panel solo se muestran los 3 primeros y los 3 últimos caracteres de cada clave.
</Callout>

### Revocar claves

Para revocar una clave comprometida o que ya no se utilice:

1. Accede a **API Keys** en tu panel
2. Localiza la clave y haz clic en **Revoke**
3. Confirma la acción

<Callout type="error" title="Acción irreversible">
  La revocación de una clave es inmediata y permanente. Todas las solicitudes que usen esa clave fallarán al instante.
</Callout>

## Errores de autenticación

| Código de estado | Código de error       | Descripción                                                                   |
| ---------------- | --------------------- | ----------------------------------------------------------------------------- |
| `401`            | `MISSING_API_KEY`     | Cabecera Authorization ausente o sin esquema Bearer                           |
| `401`            | `INVALID_API_KEY`     | Clave de API inválida, revocada o caducada                                    |
| `429`            | `RATE_LIMIT_EXCEEDED` | Demasiadas solicitudes — consulta [limitación de solicitudes](/rate-limiting) |

```json title="Ejemplo de respuesta de error"
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}
```


------------------------------------------------------------------------------------------------------------------------
title: "Limitación de solicitudes"
description: "Entiende los límites de uso, la gestión de cuotas y la facturación por excedentes en Rueda Lens."
section: "guide"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es/rate-limiting"
------------------------------------------------------------------------------------------------------------------------

# Limitación de solicitudes

Rueda Lens aplica políticas de uso justo mediante cuotas basadas en suscripción y facturación por excedentes.

## Planes de suscripción

Los planes incluyen distintos niveles de cuota y funcionalidades. Para consultar los precios actuales y los detalles de cada plan, visita el [panel de facturación](https://dashboard.ruedalens.com/billing).

### Funcionalidades de los planes

* **Sandbox**: Cuota limitada para pruebas y desarrollo (sin soporte de excedentes)
* **Starter**: Plan listo para producción con cuota moderada y soporte de excedentes
* **Pro**: Plan de alto volumen con una cuota generosa y tarifas de excedentes competitivas
* **Enterprise**: Cuotas y precios personalizados para despliegues a gran escala

<Callout title="Actualiza tu plan en cualquier momento">
  Puedes subir o bajar de plan en cualquier momento desde el [panel de facturación](https://dashboard.ruedalens.com/billing). Los cambios se aplican de forma inmediata.
</Callout>

## Cómo funcionan las cuotas

### Reinicio del periodo de facturación

Las cuotas se reinician en función de tu **periodo de facturación de la suscripción** (normalmente mensual desde la fecha de inicio de la suscripción).

Por ejemplo, si te suscribiste el día 15, tu cuota se reinicia el día 15 de cada mes.

### Qué cuenta para tu cuota

| Solicitud                     | ¿Cuenta? |
| ----------------------------- | -------- |
| `POST /v1/analyze` (correcta) | Sí       |
| `POST /v1/analyze` (fallida)  | Sí       |
| `GET /v1/health`              | No       |

<Callout type="info" title="Las solicitudes fallidas cuentan">
  Tanto las solicitudes de análisis correctas como las fallidas cuentan para la cuota, ya que consumen recursos de procesamiento.
</Callout>

### Facturación por excedentes

Los planes con soporte de excedentes (Starter, Pro, Enterprise) permiten superar la cuota base:

1. Superas la cuota de tu suscripción durante el periodo de facturación
2. Las solicitudes adicionales se cobran según la tarifa de excedente del plan
3. Los cargos por excedentes aparecen en la siguiente factura

<Callout type="warn" title="Plan Sandbox">
  Sandbox no admite excedentes. Las solicitudes a la API devuelven un error 429 una vez agotada la cuota.
</Callout>

## Respuestas por límite de uso

### Agotamiento de cuota (Sandbox)

Cuando superas tu cuota mensual (solo en el plan Sandbox, ya que los planes de pago admiten excedentes):

```json
{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded"
  },
  "timestamp": "2026-02-08T12:00:00.000Z"
}
```

### Límite de ráfaga

Cuando envías demasiadas solicitudes en un periodo corto:

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  },
  "timestamp": "2026-02-08T12:00:00.000Z"
}
```

<Callout type="info" title="Supervisión del uso">
  Puedes seguir tu consumo en tiempo real desde el [panel](https://dashboard.ruedalens.com). El panel muestra el uso del periodo actual, la cuota restante y las fechas del periodo de facturación.
</Callout>

## Notificaciones por correo electrónico

Recibirás alertas automáticas por correo cuando te acerques o superes tu cuota:

| Umbral   | Notificación                                      |
| -------- | ------------------------------------------------- |
| **80%**  | Aviso — te estás acercando al límite de cuota     |
| **90%**  | Aviso urgente — la cuota está a punto de agotarse |
| **100%** | Cuota agotada (solo plan Sandbox)                 |

## Buenas prácticas

### Supervisar el uso en el panel

Controla tu consumo en tiempo real desde la [página de analítica del panel](https://dashboard.ruedalens.com/analytics):

* Uso del periodo de facturación actual
* Cuota restante
* Tendencias de uso a lo largo del tiempo
* Fechas del periodo de facturación

### Implementar gestión de errores

```javascript
async function analyzeVehicle(tireImage, carImage, apiKey) {
  try {
    const response = await fetch('https://api.ruedalens.com/v1/analyze', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ tireImage, carImage }),
    });

    const data = await response.json();

    if (response.status === 429) {
      // Quota exceeded - notify user or queue for later
      console.error('Quota exceeded:', data.error.message);
      return null;
    }

    if (!response.ok) {
      throw new Error(data.error?.message || 'Analysis failed');
    }

    return data;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}
```

### Cachear resultados

Evita solicitudes redundantes almacenando en caché los resultados de los análisis. Por ejemplo, guarda los resultados usando un hash de la imagen como clave:

```javascript
import crypto from 'crypto';

function hashImage(imageBuffer) {
  return crypto.createHash('sha256').update(imageBuffer).digest('hex');
}

// Use a cache (Redis, in-memory, etc.) to avoid duplicate analyses
const cache = new Map();

async function cachedAnalyze(tireImage, carImage, apiKey) {
  const cacheKey = `${hashImage(tireImage)}_${hashImage(carImage)}`;

  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const result = await analyzeVehicle(tireImage, carImage, apiKey);
  cache.set(cacheKey, result);

  return result;
}
```


------------------------------------------------------------------------------------------------------------------------
title: "Gestión de errores"
description: "Entiende las respuestas de error y cómo gestionarlas de forma eficaz."
section: "guide"
last_updated: "2026-02-09T18:49:45.162Z"
source: "https://docs.ruedalens.com/es/error-handling"
------------------------------------------------------------------------------------------------------------------------

# Gestión de errores

Rueda Lens proporciona mensajes de error coherentes y accionables para ayudarte a diagnosticar problemas rápidamente.

## Formato de respuesta de error

Todos los errores siguen una estructura JSON coherente:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "timestamp": "2026-02-08T12:00:00.000Z"
}
```

Nota: El campo `details` solo se incluye cuando hay contexto adicional disponible.

## Códigos de estado HTTP

| Estado | Significado                | ¿Reintentar?     | Causas comunes                              |
| ------ | -------------------------- | ---------------- | ------------------------------------------- |
| `400`  | Solicitud incorrecta       | No               | Imagen inválida, campos faltantes, formato no soportado |
| `401`  | No autorizado              | No               | Clave de API ausente o inválida             |
| `404`  | No encontrado              | No               | Endpoint inválido                           |
| `422`  | Entidad no procesable      | No               | La IA no pudo analizar las imágenes         |
| `429`  | Demasiadas solicitudes     | Tras reinicio    | Límite de uso o cuota superados             |
| `500`  | Error interno del servidor | Sí               | Error inesperado del servidor               |
| `503`  | Servicio no disponible     | Sí               | Interrupción temporal del servicio          |

<Callout type="info" title="Estrategia de reintentos">
  - **Errores 4xx (400-499)**: No reintentar. Corrige la solicitud y vuelve a intentarlo  
  - **429 (límite de uso)**: Espera a que se reinicie tu cuota (consulta tu periodo de facturación en el panel)  
  - **Errores 5xx (500-599)**: Seguro reintentar con backoff exponencial
</Callout>

## Referencia de códigos de error

### `MISSING_API_KEY`

La cabecera `Authorization` está ausente o no usa el esquema `Bearer`.

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Missing API key"
  }
}
```

**Solución**: Incluye tu clave de API como `Authorization: Bearer rdlns_sk_...` en las cabeceras de la solicitud.

### `INVALID_API_KEY`

La clave de API tiene un formato inválido, no existe, ha sido revocada o ha caducado.

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}
```

**Solución**: Verifica que tu clave de API sea correcta y esté activa. Si fue revocada o caducó, genera una nueva en tu [panel](https://dashboard.ruedalens.com).

### `INVALID_IMAGE`

La imagen proporcionada es inválida. Cubre todos los errores de validación de imagen: campos faltantes, formatos no soportados, base64 corrupto y archivos demasiado grandes.

```json
{
  "error": {
    "code": "INVALID_IMAGE",
    "message": "Invalid request body",
    "details": {
      "field": "tireImage",
      "issue": "Must be a valid base64-encoded image"
    }
  }
}
```

**Problemas comunes**:

* Campos obligatorios faltantes: `tireImage` y `carImage`
* Codificación base64 inválida
* La imagen supera el límite de 10 MB
* Formato no soportado (solo se aceptan JPEG y PNG)

### `RATE_LIMIT_EXCEEDED`

Límite de solicitudes por minuto superado.

**Solución**: Espera un momento y reintenta. Este límite previene solicitudes excesivas en un periodo corto.

### `QUOTA_EXCEEDED`

Cuota mensual agotada (solo plan Sandbox, ya que los planes de pago permiten excedentes). Consulta [limitación de solicitudes](/rate-limiting).

```json
{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded"
  }
}
```

**Solución**: Actualiza tu plan en el [panel de facturación](https://dashboard.ruedalens.com/billing), o espera a que tu cuota se reinicie al inicio del siguiente periodo de facturación.

### `RECOGNITION_FAILED`

El análisis con IA no pudo completarse. Suele ocurrir cuando las imágenes no son lo suficientemente claras para identificar el vehículo o leer las especificaciones del neumático.

**Causas comunes**:

* Imágenes borrosas o desenfocadas
* Iluminación deficiente o sombras intensas
* Texto del neumático oculto o desgastado
* Marcajes de neumáticos inusuales o aftermarket

**Solución**: Vuelve a tomar las imágenes siguiendo las [guías de calidad de imagen](/api-reference/analyze#image-quality-guidelines). Asegúrate de que el texto del flanco del neumático sea claramente legible y que el vehículo esté bien encuadrado.

### `SERVICE_UNAVAILABLE`

La API no está disponible temporalmente por mantenimiento o alta carga.

**Solución**: Reintenta con backoff exponencial. Normalmente se resuelve en minutos.

### `INTERNAL_ERROR`

Se ha producido un error inesperado durante el procesamiento.

**Solución**: Reintenta la solicitud. Si el error persiste, contacta con soporte en **[support@ruedalens.com](mailto:support@ruedalens.com)** incluyendo el `requestId` de la respuesta.

## Buenas prácticas

### Gestión completa de errores

```javascript
async function analyzeVehicle(tireImage, carImage) {
  const response = await fetch('https://api.ruedalens.com/v1/analyze', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.RUEDA_LENS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tireImage, carImage }),
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'MISSING_API_KEY':
        throw new Error('API key is missing. Add Authorization header.');
      case 'INVALID_API_KEY':
        throw new Error('Invalid API key. Check your credentials.');
      case 'INVALID_IMAGE':
        throw new Error(`Invalid image: ${data.error.message}`);
      case 'QUOTA_EXCEEDED':
        throw new Error('Monthly quota exceeded. Upgrade your plan or wait for reset.');
      case 'RATE_LIMIT_EXCEEDED':
        throw new Error('Rate limit exceeded. Wait a moment and retry.');
      case 'RECOGNITION_FAILED':
        throw new Error('Could not analyze images. Ensure tire text and vehicle are clearly visible.');
      default:
        throw new Error(data.error.message);
    }
  }

  return data.data;
}
```

### Backoff exponencial para reintentos

```javascript
async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const delay = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}
```

<Callout title="Consejo de depuración">
  Todos los errores se registran con un `requestId` único. Incluye este ID al contactar con soporte para una resolución más rápida.
</Callout>

## Obtener ayuda

Si encuentras errores persistentes:

1. Comprueba el endpoint de salud de la API: `GET /v1/health`
2. Revisa tus [logs de solicitudes](https://dashboard.ruedalens.com) en el panel
3. Contacta con soporte en **[support@ruedalens.com](mailto:support@ruedalens.com)** con el código de error, el ID de la solicitud y la marca temporal