Usar /search
- Búsqueda rápida con pocos filtros y validaciones puntuales.
- Escenarios exploratorios sin control fino de columnas, orden o paginado.
- Puede tener tope por request (por ejemplo, 50), según entidad.
Cómo usar esta documentación
Autenticación general: en Seguridad hay un único endpoint para obtener el token usando un usuario de YiQi. Este token se reutiliza en el resto de los módulos enviándolo como Bearer en el header Authorization.
Política de sesión: el login (grant_type=password) devuelve un access_token de vida corta y además un refresh_token. Cuando el access token expira, se pide uno nuevo con grant_type=refresh_token, sin volver a mandar usuario y contraseña. Guiate siempre por el expires_in de la respuesta en vez de hardcodear la duración.
El refresh token rota: cada uso devuelve uno nuevo y el anterior deja de servir, así que hay que persistir el último. Dura 14 días. Y tiene un límite importante: hay un solo refresh token vivo por usuario, o sea que un login nuevo invalida el anterior. Si varios procesos comparten el mismo usuario de integración se van a desloguear entre ellos — conviene un usuario por proceso.
En https://apilegacy.yiqi.com.ar esto no aplica: ahí no hay refresh token y el recambio es por relogin.
URLs base
| Módulo | Base URL |
|---|---|
Seguridad (/token, login) |
https://api.yiqi.com.ar |
| Todos los módulos ERP | https://api.yiqi.com.ar/api/public |
- Obtené el token desde el módulo Seguridad.
- Ejecutá GetLoginInformation como healthcheck canónico post-login.
- Tomá schemaId desde esa respuesta (método primario).
- Elegí un módulo desde el índice y abrí su Swagger.
- Dentro del Swagger, expandí tags y operaciones.
- Validá parámetros obligatorios, cuerpos de request y respuestas.
Estructura común de los Swagger: la mayoría de entidades siguen un formato homogéneo (operaciones list/get/create/update/delete, payloads con estructura repetida y respuestas paginadas o de detalle). Si entendés un módulo, la curva de adopción del resto suele ser mucho más rápida.
Novedades: consultá la bitácora de cambios de la API. Para bots/agentes, consumí modules.json para descubrir el catálogo de specs y cambios-api.json para leer la bitácora de manera estructurada.
Generalidades de endpoints por entidad
En los Swagger de YiQi, las entidades repiten un patrón de endpoints. Si aprendés el de una entidad, podés reutilizar el mismo enfoque en casi todas.
Resumen rápido: esta sección cubre Search vs Query, patrón común de endpoints, notas de smarties y recomendaciones de consumo responsable.
Search vs Query Cuándo conviene cada endpoint y recomendación para alto volumen.
Cómo elegir entre /search y /query
Usar
Usar /query
- Listados productivos en UI, integraciones y sincronizaciones.
- Paginado configurable (
page,pageSize) y mejor control de respuesta. - Permite pedir solo columnas necesarias para mejorar performance y payload.
- Recomendación: preferí
/querypara procesos recurrentes, alto volumen, batch o exportaciones grandes. - Compatibilidad: límites, filtros y columnas dependen de cada entidad; validalo siempre en su OpenAPI.
- Ejemplo: para listar artículos con SKU, nombre, stock y precio final, usar
/MATERIAL/querycon columnas explícitas.
Patrón de endpoints por entidad Listado típico (search, get, alta, update, delete, smartie, changestate, files y reportes).
Búsqueda filtrada por atributos de la entidad. Suele devolver hasta 50 registros máximo por request.
Detalle de una instancia puntual. Requiere el id en path.
Alta de instancia. El body incluye schemaId y un objeto data.
Actualización de instancia existente, con estructura similar al alta.
Baja lógica/física según comportamiento de la entidad y reglas de negocio.
Vista (smartie) paginada. Una smartie es un reporte/vista armado por usuarios sobre la entidad.
Cambio de estado de workflow (cuando la entidad maneja estados).
Descarga/carga de archivos asociados a atributos de tipo archivo.
Descarga de reportes predefinidos (por ejemplo PDFs) para una instancia.
- Smartie paginado: usar
smartieId,schemaIdypage(base 1). Empezar enpage=1e incrementar de a 1. - Filtro adicional en smartie: el parámetro
searchpermite acotar resultados dentro de la vista. - Particularidad de búsqueda: en
/searchlos filtros disponibles cambian por entidad y están tipados en el Swagger de cada módulo. - Particularidad de estados: no todas las entidades exponen
/changestate; cuando existe, los estados válidos están listados en la operación. - Particularidad de archivos/reportes: los valores permitidos de
attributeNameyreportNamevarían por entidad. - schemaId: es obligatorio en casi todas las operaciones, ya sea por query o dentro del body según el endpoint.
- Regla recomendada para integraciones: obtener
schemaIdprimero desdeGetLoginInformation; usarGetAvailableSchemascomo complemento cuando el usuario tenga acceso a más de un esquema.
Buenas prácticas de paginado Cómo consumir smarties de forma eficiente para reducir carga y tráfico.
Buena práctica para consumir smarties
- Orden recomendado: ordenar por fecha de modificación descendente para traer primero lo más reciente.
- Estrategia de paginado eficiente: paginar desde
page=1y detenerse cuando se alcance la última fecha ya sincronizada por tu proceso. - Objetivo: evitar paginado exhaustivo innecesario, reducir tráfico y proteger el rendimiento general del sistema.
Uso responsable de la API Riesgos operativos, mínimos privilegios y responsabilidad de implementación.
Uso responsable de la API
- Responsabilidad de uso: el consumo de la API debe realizarse con criterios de eficiencia, control de volumen y frecuencia de llamadas.
- Riesgos operativos: un uso intensivo o sin límites puede saturar tráfico, degradar tiempos de respuesta y afectar a otros usuarios.
- Cuenta técnica recomendada: utilizar usuarios de API con el menor privilegio posible, otorgando solo permisos estrictamente necesarios.
- Riesgo asumido por el integrador: la implementación, su impacto operativo y los riesgos asociados son responsabilidad del usuario que consume la API.
Módulos disponibles
Seguridad
Autenticación, tokens y control de acceso OAuth2.
Módulo Ventas
Pedidos, facturación, notas de crédito y remitos.
Módulo Stock
Depósitos, movimientos, inventarios y ajustes.
Clientes y Proveedores
Maestro de terceros, cuentas corrientes y condiciones comerciales.
Módulo Compras
Órdenes de compra, recepciones y acuerdos de precios.
Módulo Contabilidad
Asientos, mayores y centros de costo.
Módulo Finanzas
Tesorería, bancos, cobranzas y pagos.
Módulo Gestión
Parámetros generales y catálogos maestros.
Módulo Producción
Órdenes de producción, BOM y rutas.
Módulo Comercial / CRM
Oportunidades, actividades y pipeline comercial.
Módulo RRHH
Gestión de personal, legajos y novedades.
Módulo POS
Punto de venta, tickets y cobranzas en caja.
Módulo Calidad
Controles, no conformidades y acciones correctivas.
Módulo Editorial
Operaciones y catálogos del flujo editorial.
Módulo Mensajería
Envío y trazabilidad de mensajes/eventos.
Módulo Parámetros
Configuración transversal y valores del sistema.
No hay módulos que coincidan con tu búsqueda.