API YIQI

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.

1) Glosario rápido

• 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.).

2) Requisitos de acceso

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

1. Obtener token (Bearer):
   
   
   

   • Iniciar sesión con las credenciales de usuario de YiQi mediante el endpoint correspondiente.
     
     

   • La respuesta devolverá un access token.
     
     

2. 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.

4) Estructura de endpoints

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.
  
  

Headers

Authorization: Bearer {TOKEN}

Content-Type: application/json

Ejemplo (cURL)

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"

5) Paginación y consultas incrementales

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.
  
  

Parámetros útiles

• 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.

6) Ejemplos rápidos por entidad

Cambie {ENTIDAD} y {SMARTIE_ID} según su caso; conserve siempre schemaId.

Ventas (incremental del día)

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"

Stock disponible

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"

Compras / OC en tránsito

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"

7) Respuestas típicas

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).

8) Permisos y troubleshooting

1. Token/Permisos
   
   
   

   • Verificar que el usuario obtenga token correctamente.
     
     

   • Corroborar permisos mínimos sobre las áreas a consultar (clientes, proveedores, compras, stock, ventas, etc.).
     
     

2. Parámetros obligatorios
   
   
   

   • Confirmar que siempre se envía schemaId.
     
     

   • Confirmar que el smartieId corresponde al reporte correcto.
     
     

3. Volumen
   
   
   

   • Evitar consultas masivas repetidas: usar incrementales y ordenamiento por fecha desc.
     
     

4. Registro de errores
   
   
   

   • Enviar a soporte un cURL o equivalente con headers (enmascarando credenciales) y la respuesta completa del error.
     
     

9) Buenas prácticas

• 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.
  
  

10) Plantillas listas para pegar

a) cURL genérico por entidad

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"

b) Incremental por fecha

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"

11) Soporte

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:

1. Contar con usuario de YiQi con permisos activos.
   
   

2. Autenticar → Bearer {TOKEN}.
   
   

3. Llamar a {BASE_URL}/api/{ENTIDAD}/smartie?schemaId={SCHEMA_ID}&smartieId={SMARTIE_ID}&page=....
   
   

4. Ordenar Smarties por fecha desc → incrementales.
   
   

5. Verificar permisos y parámetros si parece token inválido/usuario denegado.

6. Adjuntar URL y respuesta al escalar a soporte.