Link de API: Apidoc.yiqi.com.ar
Esta guía se centra en cómo usarla: autenticación, armado de endpoints, paginado, consultas incrementales y resolución de errores frecuentes.
Usuario de YiQi: cuenta activa del sistema con permisos sobre los módulos que se quieran consultar. Es obligatoria para acceder a la API.
Smartie: reporte predefinido dentro del sistema YiQi (ej.: ventas, stock, compras). Cada uno tiene un identificador único smartieId.
Esquema (schema): entorno o tenant del cliente. Se identifica por schemaId, visible en la URL general.
Entidad: módulo o recurso de negocio (ventas, compras, stock, clientes, proveedores, etc.).
Para acceder a la API de YiQi es obligatorio contar con un usuario válido de YiQi con permisos sobre los módulos que se deseen consultar (ventas, stock, compras, etc.).
Cada request se valida contra las credenciales de ese usuario, por lo que si el usuario no tiene acceso o el token está vencido, las consultas serán rechazadas.
3) Autenticación
Obtener token (Bearer):
Iniciar sesión con las credenciales de usuario de YiQi mediante el endpoint correspondiente.
La respuesta devolverá un access token.
Usar token en cada request:
Header: Authorization: Bearer {TOKEN}
Header recomendado: Content-Type: application/json
Si el token es válido y el usuario tiene permisos, la autenticación no debería fallar. Si recibe token inválido o usuario denegado, ver Sección 8.
La extracción de datos con Smarties sigue un esqueleto consistente:
GET {BASE_URL}/api/{ENTIDAD}/smartie
?schemaId={SCHEMA_ID}
&smartieId={SMARTIE_ID}
&page={PAGE}
[&pageSize={PAGE_SIZE}]
[&fromDate=AAAA-MM-DDTHH:mm:ss]
[&toDate=AAAA-MM-DDTHH:mm:ss]
{BASE_URL}: URL base de la API (ej.: https://apidoc.yiqi.com.ar o la que corresponda a su entorno).
{ENTIDAD}: ventas, compras, stock, clientes, proveedores, etc.
{SCHEMA_ID}: ID de esquema desde la URL general.
{SMARTIE_ID}: ID del reporte (Smartie).
{PAGE} / {PAGE_SIZE}: paginado.
Filtros opcionales típicos: rango de fechas, estado, etc., según el Smartie.
Authorization: Bearer {TOKEN}
Content-Type: application/json
Reemplace placeholders antes de ejecutar.
curl -X GET "{BASE_URL}/api/ventas/smartie?schemaId={SCHEMA_ID}&smartieId={SMARTIE_ID}&page=1&pageSize=200" \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json"
Estrategia sugerida:
Configure el Smartie de su consulta ordenado por fecha_modificacion descendente (o el campo equivalente) para que la página 1 devuelva lo más reciente.
Primer extracción: recupere el histórico (todas las páginas) una sola vez.
Extracciones periódicas: consulte solo lo del día/últimas horas (página 1, y avanzar páginas si el volumen lo requiere), evitando saturar el sistema.
page y pageSize para navegar por lotes.
Filtros por fecha (fromDate/toDate) para acotar la ventana de datos.
Para stock en tránsito (órdenes de compra) y fecha estimada de entrega, utilice la entidad y/o Smartie correspondiente siguiendo la misma estructura de llamado.
Cambie {ENTIDAD} y {SMARTIE_ID} según su caso; conserve siempre schemaId.
curl -X GET "{BASE_URL}/api/ventas/smartie?schemaId={SCHEMA_ID}&smartieId={SMARTIE_ID}&page=1&fromDate={HOY_T_00_00_00}" \
-H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json"
curl -X GET "{BASE_URL}/api/stock/smartie?schemaId={SCHEMA_ID}&smartieId={SMARTIE_ID}&page=1" \
-H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json"
curl -X GET "{BASE_URL}/api/compras/smartie?schemaId={SCHEMA_ID}&smartieId={SMARTIE_ID}&page=1" \
-H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json"
Respuesta exitosa (200):
{
"page": 1,
"pageSize": 200,
"totalPages": 5,
"totalRecords": 1000,
"data": [
{ /* registro 1 */ },
{ /* registro 2 */ }
]
}
Errores comunes:
401/403: token inválido / usuario denegado / permisos insuficientes.
400: parámetros faltantes o inválidos (frecuente: falta schemaId o smartieId).
429: límite de peticiones (aplique backoff y reduzca pageSize).
Token/Permisos
Verificar que el usuario obtenga token correctamente.
Corroborar permisos mínimos sobre las áreas a consultar (clientes, proveedores, compras, stock, ventas, etc.).
Parámetros obligatorios
Confirmar que siempre se envía schemaId.
Confirmar que el smartieId corresponde al reporte correcto.
Volumen
Evitar consultas masivas repetidas: usar incrementales y ordenamiento por fecha desc.
Registro de errores
Enviar a soporte un cURL o equivalente con headers (enmascarando credenciales) y la respuesta completa del error.
Idempotencia de extracciones: guarde last_modified del último registro procesado y úselo como fromDate en la siguiente corrida.
Backoff y límites: ante 429, implemente espera exponencial y reduzca pageSize.
Tiempos: programe consultas incrementales en ventanas de minutos u horas, según el negocio.
Observabilidad: loguee request/response (sin credenciales) y métricas de latencia/errores.
BASE_URL="https://{SU_BASE}" \
SCHEMA_ID="{SCHEMA_ID}" \
SMARTIE_ID="{SMARTIE_ID}" \
TOKEN="{TOKEN}" \
curl -X GET "$BASE_URL/api/{ENTIDAD}/smartie?schemaId=$SCHEMA_ID&smartieId=$SMARTIE_ID&page=1&pageSize=200" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"
FROM_DATE="2025-11-13T00:00:00" # ejemplo
curl-XGET"$BASE_URL/api/{ENTIDAD}/smartie?schemaId=$SCHEMA_ID&smartieId=$SMARTIE_ID&page=1&fromDate=$FROM_DATE" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"
Ante un error en la API, enviar a soporte:
Descripción breve del objetivo (qué entidad/Smartie consultan).
Captura/pega del cURL o equivalente (oculte credenciales).
schemaId utilizado y smartieId consultado.
Códigos y cuerpo de respuesta del error.
Resumen:
Contar con usuario de YiQi con permisos activos.
Autenticar → Bearer {TOKEN}.
Llamar a {BASE_URL}/api/{ENTIDAD}/smartie?schemaId={SCHEMA_ID}&smartieId={SMARTIE_ID}&page=....
Ordenar Smarties por fecha desc → incrementales.
Verificar permisos y parámetros si parece token inválido/usuario denegado.
Adjuntar URL y respuesta al escalar a soporte.