openapi: 3.1.0 info: title: HS Code description: '# API de Búsqueda de Códigos HS - Transcend ## 🎯 Propósito Principal Este API es parte de la plataforma **Transcend** y proporciona acceso completo a la jerarquía del Sistema Armonizado (HS Code) utilizado en comercio internacional. Permite a desarrolladores integrar búsquedas de códigos aduaneros en sus aplicaciones. ## 📊 Estructura Jerárquica El sistema organiza los códigos HS en 4 niveles anidados: 1. **Secciones** - Nivel más alto (21 secciones totales, ej. "Sección XI - Textiles") 2. **Capítulos** - Dentro de secciones (99 capítulos, ej. "Capítulo 52 - Algodón") 3. **Partidas** - Dentro de capítulos (ej. "Algodón") 4. **Subpartidas** - Nivel más granular (ej. "Algodón sin cardar ni peinar") ## 🔐 Autenticación Dual **IMPORTANTE**: Esta API acepta **DOS métodos de autenticación** (usa solo uno): - **Método 1**: Token JWT (para usuarios humanos) - **Método 2**: API Key (para integraciones automáticas) ## 🚀 Casos de Uso Comunes - Integración en sistemas de facturación electrónica - Automatización de declaraciones aduaneras - Búsqueda de códigos para cotizaciones internacionales - Validación de clasificación arancelaria ## 📋 Requisitos Técnicos - Todas las respuestas son en formato JSON - Codificación: UTF-8 - Timeout recomendado: 30 segundos - Rate limiting: 100 requests/minuto por cliente ' version: 1.304.310937 contact: email: support@cargoffer.com name: Equipo de Soporte Transcend license: name: Private API - Access by agreement only url: https://transcend.cargoffer.com/terms servers: - url: https://api.pro.cargoffer.com description: Producción components: schemas: SubheadingResult: type: object description: "## \U0001F4CB Subpartida HS (Nivel más granular)\nRepresenta una\ \ subpartida específica del código HS, que es el nivel más detallado de la\ \ clasificación arancelaria. Cada subpartida pertenece exactamente a una partida.\n\ \n### \U0001F4DD Campos Principales\n- `_id`: Identificador único en la base\ \ de datos\n- `title`: Descripción completa de la subpartida\n- `label`: Array\ \ de etiquetas descriptivas (puede incluir información técnica adicional)\n\ \n### \U0001F3AF Cuándo usar este nivel\n- Para declaraciones aduaneras precisas\n\ - Cuando se necesita la clasificación más específica\n- Para cálculos de aranceles\ \ exactos\n\n### \U0001F4CA Ejemplo Real\n```json\n{\n \"_id\": \"6502e99101515afda2dbd5c1\"\ ,\n \"title\": \"0302.31 - Albacora o atún de aleta larga\",\n \"label\"\ : [\n \"-- albacore or longfinned tunas (thunnus alalunga)\",\n \"Código\ \ HS: 0302.31.00\",\n \"Arancel: 5%\"\n ]\n}\n```\n" properties: _id: type: string description: '**Identificador único MongoDB** de la subpartida. **Formato**: ObjectId hexadecimal de 24 caracteres **Ejemplo**: `507f1f77bcf86cd799439011` **IMPORTANTE**: Este ID es persistente y no cambia entre versiones de la base de datos. ' example: 6501a2b3c4d5e6f7a8b9c0d1 title: type: string description: '**Nombre descriptivo completo** de la subpartida según la nomenclatura HS oficial. **Contenido típico**: - Código numérico de la subpartida - Descripción en español - Información técnica relevante **Formato**: `"Código - Descripción"` **Ejemplo**: `"0302.31 - Albacora o atún de aleta larga"` ' example: Algodón sin cardar ni peinar label: type: array description: '**Array de etiquetas descriptivas** que proporcionan información adicional. **Contenido común**: - Descripciones en otros idiomas (inglés, francés, etc.) - Notas técnicas específicas - Información sobre restricciones o requisitos - Referencias a regulaciones **IMPORTANTE**: Este campo puede estar vacío (`[]`) si no hay etiquetas adicionales. ' items: type: string example: - -- albacore or longfinned tunas (thunnus alalunga) - Fresh or chilled required: - _id - title HeadingResult: type: object description: "## \U0001F4CB Partida HS (Nivel intermedio)\nRepresenta una partida\ \ del código HS, que agrupa subpartidas relacionadas técnicamente. Cada partida\ \ pertenece exactamente a un capítulo.\n\n### \U0001F4DD Campos Principales\n\ - `_id`: Identificador único en la base de datos\n- `title`: Descripción de\ \ la partida\n- `label`: Array de etiquetas descriptivas\n- `subheadings`:\ \ Lista de subpartidas hijas (puede estar vacía)\n\n### \U0001F3AF Cuándo\ \ usar este nivel\n- Para búsquedas generales de productos\n- Cuando se necesita\ \ una clasificación menos específica\n- Para análisis estadísticos por categoría\n\ \n### \U0001F4CA Ejemplo Real\n```json\n{\n \"_id\": \"6502e99001515afda2dbd5bf\"\ ,\n \"title\": \"0302.3 - Atunes (género thunnus)\",\n \"label\": [\n \ \ \"- tunas (of the genus thunnus), skipjack tuna (stripe-bellied bonito)\ \ (katsuwonus pelamis), excluding edible fish offal of subheadings 0302.91\ \ to 0302.99 :\",\n \"Sección: III - Pescados y crustáceos\"\n ],\n \"\ subheadings\": [\n {\n \"_id\": \"6502e99101515afda2dbd5c1\",\n \ \ \"title\": \"0302.31 - Albacora o atún de aleta larga\",\n \"label\"\ : [\n \"-- albacore or longfinned tunas (thunnus alalunga)\"\n \ \ ]\n }\n ]\n}\n```\n" properties: _id: type: string description: '**Identificador único MongoDB** de la partida. **Formato**: ObjectId hexadecimal de 24 caracteres **Persistencia**: Este ID no cambia entre versiones ' example: 6501a2b3c4d5e6f7a8b9c0d2 title: type: string description: '**Nombre descriptivo** de la partida según la nomenclatura HS. **Formato**: `"Código - Descripción"` **Ejemplo**: `"0302.3 - Atunes (género thunnus)"` ' example: Algodón label: type: array description: '**Array de etiquetas descriptivas** con información adicional. **Contenido común**: - Descripciones técnicas detalladas - Exclusiones o inclusiones específicas - Referencias a otras partidas/subpartidas ' items: type: string example: - '- tunas (of the genus thunnus), skipjack tuna (stripe-bellied bonito) (katsuwonus pelamis)' subheadings: type: array description: '**Lista de subpartidas** asociadas a esta partida. **IMPORTANTE**: - Puede estar vacía (`[]`) si la partida no tiene subpartidas - El orden no tiene significado especial - Cada subpartida es única y no se repite en otras partidas ' items: $ref: '#/components/schemas/SubheadingResult' required: - _id - title - subheadings ChapterResult: type: object description: "## \U0001F4CB Capítulo HS (Nivel de agrupación)\nRepresenta un\ \ capítulo del código HS, que agrupa partidas relacionadas por tipo de producto.\ \ Cada capítulo pertenece exactamente a una sección.\n\n### \U0001F4DD Campos\ \ Principales\n- `_id`: Identificador único en la base de datos\n- `title`:\ \ Título completo del capítulo (incluye número)\n- `label`: Array de etiquetas\ \ descriptivas\n- `headings`: Lista de partidas hijas (puede estar vacía)\n\ \n### \U0001F3AF Cuándo usar este nivel\n- Para navegación por categorías\ \ de productos\n- Para análisis por sector económico\n- Para estadísticas\ \ de comercio por capítulo\n\n### \U0001F4CA Ejemplo Real\n```json\n{\n \"\ _id\": \"6502e99001515afda2dbd5bf\",\n \"title\": \"Capítulo 03 - Pescados\ \ y crustáceos, moluscos y otros invertebrados acuáticos\",\n \"label\":\ \ [\n \"Sección: III - Productos del reino animal\",\n \"Notas: Incluye\ \ pescados vivos, frescos, refrigerados, congelados, etc.\"\n ],\n \"headings\"\ : [\n {\n \"_id\": \"6502e99001515afda2dbd5bf\",\n \"title\"\ : \"0302 - Pescados, frescos o refrigerados, excluyendo los filetes y demás\ \ carne de la partida 0304\",\n \"label\": [\n \"- Pescados de\ \ la especie Oncorhynchus spp.\"\n ],\n \"subheadings\": [\n \ \ {\n \"_id\": \"6502e99101515afda2dbd5c1\",\n \"title\"\ : \"0302.11 - Truchas (Oncorhynchus spp.)\",\n \"label\": [\n \ \ \"-- Salmo trutta\"\n ]\n }\n ]\n }\n ]\n\ }\n```\n" properties: _id: type: string description: '**Identificador único MongoDB** del capítulo. **Formato**: ObjectId hexadecimal de 24 caracteres **Persistencia**: Este ID no cambia entre versiones ' example: 6501a2b3c4d5e6f7a8b9c0d3 title: type: string description: '**Título completo del capítulo** incluyendo número y descripción oficial. **Formato**: `"Capítulo XX - Descripción completa"` **Ejemplo**: `"Capítulo 52 - Algodón"` **IMPORTANTE**: El número del capítulo (01-99) indica la categoría general del producto. ' example: Capítulo 52 - Algodón label: type: array description: '**Array de etiquetas descriptivas** con información contextual. **Contenido común**: - Referencia a la sección padre - Notas generales sobre el capítulo - Información sobre alcances y exclusiones ' items: type: string example: - 'Sección: XI - Textiles y sus manufacturas' headings: type: array description: '**Lista de partidas** asociadas a este capítulo. **IMPORTANTE**: - Puede estar vacía (`[]`) si el capítulo no tiene partidas definidas - Cada partida es única dentro del capítulo - El orden generalmente sigue la numeración HS ' items: $ref: '#/components/schemas/HeadingResult' required: - _id - title - headings SearchResult: type: object description: "## \U0001F4CB Sección HS (Nivel más alto)\nRepresenta una sección\ \ del código HS, que es el nivel más alto de la jerarquía. Cada sección contiene\ \ uno o más capítulos relacionados por sector económico.\n\n### \U0001F4DD\ \ Campos Principales\n- `_id`: Identificador único en la base de datos\n-\ \ `title`: Título completo de la sección (incluye número romano)\n- `label`:\ \ Array de etiquetas descriptivas\n- `chapters`: Lista de capítulos hijos\ \ (siempre tiene al menos uno)\n\n### \U0001F3AF Cuándo usar este nivel\n\ - Para navegación de alto nivel\n- Para análisis macroeconómico\n- Para agrupación\ \ por sectores industriales\n\n### \U0001F4CA Ejemplo Real\n```json\n{\n \ \ \"_id\": \"6502e98f01515afda2dbd5a1\",\n \"title\": \"Sección XI - Textiles\ \ y sus manufacturas\",\n \"label\": [\n \"Alcance: Incluye fibras textiles,\ \ hilados, tejidos, prendas de vestir, etc.\",\n \"Exclusiones: Productos\ \ de cuero (Sección VIII)\"\n ],\n \"chapters\": [\n {\n \"_id\"\ : \"6502e98f01515afda2dbd5a2\",\n \"title\": \"Capítulo 50 - Seda\",\n\ \ \"label\": [\n \"Sección: XI - Textiles y sus manufacturas\"\ \n ],\n \"headings\": [\n {\n \"_id\": \"6502e98f01515afda2dbd5a3\"\ ,\n \"title\": \"5001 - Capullos de seda aptos para el devanado\"\ ,\n \"label\": [\n \"- Crudos (sin blanquear)\"\n \ \ ],\n \"subheadings\": [\n {\n \"_id\"\ : \"6502e98f01515afda2dbd5a4\",\n \"title\": \"5001.00 - Capullos\ \ de seda aptos para el devanado\",\n \"label\": [\n \ \ \"-- De Bombyx mori\"\n ]\n }\n \ \ ]\n }\n ]\n }\n ]\n}\n```\n" properties: _id: type: string description: '**Identificador único MongoDB** de la sección. **Formato**: ObjectId hexadecimal de 24 caracteres **Persistencia**: Este ID no cambia entre versiones ' example: 6501a2b3c4d5e6f7a8b9c0d4 title: type: string description: '**Título completo de la sección** incluyendo número romano y descripción. **Formato**: `"Sección XX - Descripción"` **Ejemplo**: `"Sección XI - Textiles y sus manufacturas"` **IMPORTANTE**: Hay 21 secciones en total (I a XXI). ' example: Sección XI - Textiles label: type: array description: '**Array de etiquetas descriptivas** con información general. **Contenido común**: - Alcance general de la sección - Exclusiones importantes - Notas sobre productos incluidos ' items: type: string example: - 'Alcance: Productos textiles y sus manufacturas' - 'Exclusiones: Calzado (Sección XII)' chapters: type: array description: '**Lista de capítulos** asociados a esta sección. **IMPORTANTE**: - Siempre contiene al menos un capítulo - Los capítulos están ordenados por número (01-99) - Cada capítulo pertenece a una sola sección ' items: $ref: '#/components/schemas/ChapterResult' required: - _id - title - chapters Error: type: object description: '## ⚠️ Estructura de Error Formato estándar para respuestas de error en toda la API. ### 📝 Campos - `message`: Descripción humana del error - `code` (opcional): Código interno de error - `details` (opcional): Información técnica adicional ### 🎯 Propósito - **Consistencia**: Mismo formato en todos los endpoints - **Debugging**: Información suficiente para diagnóstico - **Localización**: Mensajes claros para usuarios finales ' properties: message: type: string description: '**Mensaje descriptivo del error** en lenguaje humano. **Características**: - En español (predeterminado) o inglés según header Accept-Language - Explicación clara del problema - Sugerencia de solución cuando aplica **Ejemplos**: - `"Authentication required: provide valid token or API key"` - `"Search query is required"` - `"Internal server error - please try again later"` ' code: type: string description: "**Código interno de error** para referencia técnica.\n\n**Formato**:\ \ `\"ERROR_TYPE_SUBTYPE\"`\n**Ejemplos**: \n- `\"AUTH_TOKEN_EXPIRED\"\ `\n- `\"VALIDATION_SEARCH_REQUIRED\"`\n- `\"DB_CONNECTION_FAILED\"`\n\n\ **Uso**: Para debugging y logs del sistema.\n" details: type: object description: '**Información técnica adicional** para debugging. **Contenido común**: - Timestamp del error - Request ID para tracking - Stack trace (solo en desarrollo) - Parámetros específicos que causaron el error ' required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: '## 🔐 Autenticación con Token JWT **Para usuarios humanos** que acceden a través de interfaces web o móviles. ### 📋 Cómo obtener un token 1. Autenticarse en el servicio IAM de Transcend 2. Obtener token JWT válido 3. Incluirlo en el header `Authorization` ### 📝 Formato del header ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### ⚠️ Consideraciones - Los tokens expiran después de 24 horas - Se requiere refrescar el token cuando expire - No usar para integraciones automatizadas (usa API Key) ### 🚨 Errores comunes - `401 Unauthorized`: Token inválido o expirado - `400 Bad Request`: Formato incorrecto del header ' apiKeyAuth: type: apiKey in: header name: X-API-Key description: '## 🔑 Autenticación con API Key **Para integraciones automatizadas** entre sistemas. ### 📋 Cómo obtener una API Key 1. Solicitar en el panel de administración de Transcend 2. La key se genera con permisos específicos 3. Se puede revocar en cualquier momento ### 📝 Formato del header ``` X-API-Key: sk_live_abc123def456ghi789jkl012 ``` ### ⚠️ Consideraciones de seguridad - **NUNCA** commits API Keys en código fuente - Usar variables de entorno o secret managers - Rotar keys periódicamente (cada 90 días recomendado) - Cada key tiene límites de rate específicos ### 🚨 Errores comunes - `401 Unauthorized`: Key inválida o revocada - `403 Forbidden`: Key no tiene permisos para este endpoint - `429 Too Many Requests`: Excedido el límite de rate ' tags: - name: HS Code description: Operaciones relacionadas con la jerarquía completa de códigos HS - name: Búsqueda description: Operaciones de búsqueda en la estructura de códigos HS paths: /: get: tags: - HS Code summary: Obtener estructura completa del Sistema Armonizado description: '## 📊 Obtener Jerarquía Completa HS Este endpoint devuelve **toda la estructura jerárquica** del Sistema Armonizado en una sola llamada. ### 🎯 Casos de Uso - **Inicialización de aplicación**: Cargar toda la estructura al iniciar - **Navegación completa**: Permitir explorar todos los niveles - **Cache local**: Descargar datos para uso offline - **Análisis completo**: Procesar toda la jerarquía localmente ### ⚡ Consideraciones de Performance - **Tamaño de respuesta**: ~2-5MB (depende de la complejidad) - **Tiempo de respuesta**: 1-3 segundos - **Recomendado**: Cachear la respuesta por 24 horas ### 🔐 Autenticación Requerida Usa **cualquiera** de estos métodos: - Token JWT: `Authorization: Bearer {token}` - API Key: `X-API-Key: {key}` ### 📋 Estructura de Respuesta La respuesta es un **array de secciones**, cada una con: - Sección → Capítulos → Partidas → Subpartidas - Todos los niveles están completamente poblados - Mantiene relaciones padre-hijo ### 🚨 Limitaciones - No incluye filtros o paginación - Para búsquedas específicas, usar `/search` - La respuesta puede ser grande, considerar compresión ' operationId: getAll security: - bearerAuth: [] - apiKeyAuth: [] responses: '200': description: '## ✅ Éxito - Estructura Completa Devuelve un array JSON con todas las secciones y su jerarquía completa. ### 📊 Características de la Respuesta - **Formato**: Array de objetos `SearchResult` - **Orden**: Secciones en orden numérico (I-XXI) - **Completitud**: Todos los niveles están presentes - **Consistencia**: IDs únicos en toda la jerarquía ### ⏱️ Consideraciones - **Primera llamada**: Puede tomar 2-3 segundos - **Subsecuentes**: Cache del servidor acelera respuesta - **Actualizaciones**: La estructura cambia anualmente con actualizaciones HS ' content: application/json: schema: type: array items: $ref: '#/components/schemas/SearchResult' example: - _id: 6501a2b3c4d5e6f7a8b9c0d4 title: Sección XI - Textiles y sus manufacturas label: - 'Alcance: Fibras textiles, hilados, tejidos, prendas de vestir' chapters: - _id: 6501a2b3c4d5e6f7a8b9c0d3 title: Capítulo 52 - Algodón label: - 'Sección: XI - Textiles y sus manufacturas' headings: - _id: 6501a2b3c4d5e6f7a8b9c0d2 title: 5201 - Algodón sin cardar ni peinar label: - '- Algodón en rama' subheadings: - _id: 6501a2b3c4d5e6f7a8b9c0d1 title: 5201.00 - Algodón sin cardar ni peinar label: - -- Conteniendo una longitud de fibra inferior a 28,575 mm '401': description: '## 🔒 Error de Autenticación No se pudo autenticar la solicitud. ### 🚨 Causas Comunes 1. **Token JWT inválido o expirado** 2. **API Key incorrecta o revocada** 3. **Header de autenticación faltante** 4. **Formato incorrecto del token** ### 🛠️ Soluciones - **Para tokens JWT**: Renovar el token en el servicio IAM - **Para API Keys**: Verificar la key en el panel de administración - **General**: Asegurar formato correcto del header ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingAuth: value: message: 'Authentication required: provide valid token or API key' invalidToken: value: message: Invalid or expired token invalidApiKey: value: message: Invalid or inactive API key '500': description: '## ⚠️ Error Interno del Servidor Ocurrió un error inesperado al procesar la solicitud. ### 🔍 Posibles Causas - Problemas de conexión a la base de datos - Error en el procesamiento de datos - Sobrecarga del servidor ### 🛠️ Acciones Recomendadas 1. **Reintentar** después de 30 segundos 2. **Verificar logs** del servidor 3. **Contactar soporte** si persiste ### 📞 Soporte Técnico - Email: support@cargoffer.com - Response ID: Incluido en headers de respuesta ' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Internal server error - please try again later /search: get: tags: - Búsqueda summary: Buscar en la estructura HS description: '## 🔍 Búsqueda en Tiempo Real Realiza una **búsqueda textual** en todos los niveles de la jerarquía HS y devuelve solo los elementos que coinciden, manteniendo la estructura jerárquica. ### 🎯 Casos de Uso - **Búsqueda de productos**: Encontrar códigos por descripción - **Navegación asistida**: Sugerencias mientras el usuario escribe - **Validación**: Verificar que un código existe - **Traducción**: Buscar términos en múltiples idiomas ### 🔧 Características de Búsqueda - **Case-insensitive**: No distingue mayúsculas/minúsculas - **Coincidencias parciales**: Encuentra "alg" en "algodón" - **Búsqueda en todos los campos**: Title y label - **Jerarquía preservada**: Muestra contexto completo ### ⚡ Performance - **Tiempo de respuesta**: < 500ms - **Resultados limitados**: Máximo 50 elementos - **Cache**: Resultados cacheados por 5 minutos ### 🔐 Autenticación Requerida Usa **cualquiera** de estos métodos: - Token JWT: `Authorization: Bearer {token}` - API Key: `X-API-Key: {key}` ' operationId: search security: - bearerAuth: [] - apiKeyAuth: [] parameters: - name: search in: query description: '## 🔎 Término de Búsqueda **Requerido**: Texto a buscar en la estructura HS. ### 📝 Formatos Aceptados - **Números HS**: `"52"`, `"0302"`, `"5201.00"` - **Descripciones**: `"algodón"`, `"tuna"`, `"textiles"` - **Combinaciones**: `"52 algodón"`, `"capítulo 3 pescado"` - **Inglés/Español**: Funciona en ambos idiomas ### 🎯 Ejemplos Prácticos - `"algodón"` → Encuentra todo relacionado con algodón - `"52"` → Encuentra Capítulo 52 y sus subniveles - `"fresh fish"` → Encuentra pescado fresco - `"0302.31"` → Encuentra subpartida específica ### ⚠️ Consideraciones - **Mínimo 1 carácter** (el código actual no valida longitud) - **Sin caracteres especiales** recomendado - **Búsqueda AND implícita**: `"algodón textil"` busca ambos términos ' required: true schema: type: string example: algodón responses: '200': description: '## ✅ Éxito - Resultados de Búsqueda Devuelve un array de secciones que contienen **al menos un elemento coincidente**, con la estructura jerárquica completa desde la sección hasta el elemento encontrado. ### 📊 Características de la Respuesta - **Filtrado inteligente**: Solo niveles con coincidencias - **Contexto completo**: Jerarquía padre-hijo preservada - **Orden relevancia**: Resultados más específicos primero ### 🎯 Comportamiento de Búsqueda 1. **Búsqueda en todos los niveles simultáneamente** 2. **Coincidencias en `title` o `label`** 3. **Resultados agrupados por sección** 4. **Estructura mínima necesaria mostrada** ' content: application/json: schema: type: array items: $ref: '#/components/schemas/SearchResult' example: - _id: 6501a2b3c4d5e6f7a8b9c0d4 title: Sección XI - Textiles y sus manufacturas label: - 'Alcance: Fibras textiles, hilados, tejidos' chapters: - _id: 6501a2b3c4d5e6f7a8b9c0d3 title: Capítulo 52 - Algodón label: - 'Sección: XI - Textiles y sus manufacturas' headings: - _id: 6501a2b3c4d5e6f7a8b9c0d2 title: 5201 - Algodón sin cardar ni peinar label: - '- Algodón en rama' subheadings: [] '400': description: '## ⚠️ Parámetros Inválidos El parámetro de búsqueda no cumple con los requisitos. ### 🚨 Causas Comunes 1. **Parámetro `search` faltante** 2. **Valor vacío o nulo** 3. **Tipo de dato incorrecto** (debe ser string) ### 🛠️ Soluciones - **Asegurar** que el parámetro `search` esté presente - **Verificar** que tenga un valor no vacío - **Codificar** correctamente si contiene espacios ' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Search query is required '401': description: '## 🔒 Error de Autenticación No se pudo autenticar la solicitud. ### 🚨 Causas Comunes 1. **Token JWT inválido o expirado** 2. **API Key incorrecta o revocada** 3. **Header de autenticación faltante** ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingAuth: value: message: 'Authentication required: provide valid token or API key' invalidToken: value: message: Invalid or expired token '500': description: '## ⚠️ Error Interno del Servidor Ocurrió un error inesperado al procesar la búsqueda. ### 🔍 Posibles Causas - Problemas de conexión a la base de datos - Error en el índice de búsqueda - Timeout en la consulta ### 🛠️ Acciones Recomendadas 1. **Reintentar** después de 10 segundos 2. **Simplificar** el término de búsqueda 3. **Contactar soporte** si persiste ' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Internal server error during search