Saltar al contenido principal

API YiQi

La especificación vigente está publicada en el portal oficial de API. Esta página explica cómo orientarse allí y muestra únicamente rutas compatibles con el catálogo OpenAPI publicado.

Importante: apidoc.yiqi.com.ar es el portal de documentación y Swagger. No es la base URL para ejecutar requests.

Bases URL oficiales​

UsoBase URL
Seguridad y autenticaciónhttps://api.yiqi.com.ar
Módulos ERPhttps://api.yiqi.com.ar/api/public
Portal Swagger y catálogohttps://apidoc.yiqi.com.ar/

El catálogo machine-readable de módulos está disponible en modules.json.

Recorrido recomendado​

  1. Obtener un token desde el módulo Seguridad.
  2. Ejecutar GetLoginInformation como healthcheck posterior al login.
  3. Tomar schemaId de esa respuesta. GetAvailable sirve como complemento cuando el usuario tiene acceso a más de un esquema.
  4. Elegir el módulo que corresponda y abrir su Swagger desde el índice oficial.
  5. Expandir la operación concreta y validar allí parámetros obligatorios, body y respuesta.

Autenticación​

La operación oficial es:

POST https://api.yiqi.com.ar/token
Content-Type: application/x-www-form-urlencoded

El formulario requiere username, password y grant_type=password.

curl -X POST "https://api.yiqi.com.ar/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=usuario@ejemplo.com" \
  --data-urlencode "password=SU_CONTRASEÑA" \
  --data-urlencode "grant_type=password"

La respuesta exitosa contiene un access_token, un token_type y la expiración. En las operaciones siguientes se envía:

Authorization: Bearer {ACCESS_TOKEN}

Actualmente no hay refresh token documentado: cuando vence el token, se vuelve a autenticar con /token.

Obtener información de sesión y esquemas​

Una vez autenticado:

GET https://api.yiqi.com.ar/api/accountapi/GetLoginInformation
GET https://api.yiqi.com.ar/api/schemasapi/GetAvailable

Ambas operaciones usan el header Authorization. Usá GetLoginInformation como fuente primaria del schemaId para las consultas posteriores.

Patrón de endpoints por entidad​

Los módulos ERP publican sus rutas bajo https://api.yiqi.com.ar/api/public y usan el nombre técnico de la entidad, normalmente en mayúsculas. Por ejemplo, para FACTURA:

GET    https://api.yiqi.com.ar/api/public/FACTURA/search
POST   https://api.yiqi.com.ar/api/public/FACTURA/query
GET    https://api.yiqi.com.ar/api/public/FACTURA/smartie
POST   https://api.yiqi.com.ar/api/public/FACTURA
GET    https://api.yiqi.com.ar/api/public/FACTURA/{id}
PUT    https://api.yiqi.com.ar/api/public/FACTURA/{id}
DELETE https://api.yiqi.com.ar/api/public/FACTURA/{id}
POST   https://api.yiqi.com.ar/api/public/FACTURA/changestate
GET    https://api.yiqi.com.ar/api/public/FACTURA/file
PUT    https://api.yiqi.com.ar/api/public/FACTURA/file
GET    https://api.yiqi.com.ar/api/public/FACTURA/report

Estas rutas son un patrón documentado, no una garantía de que todas las operaciones existan para todas las entidades. El Swagger de cada módulo es la autoridad: algunas entidades no exponen changestate, file, report o determinadas operaciones de escritura.

Listados: search, query y smartie​

  • /search: búsqueda rápida con filtros de la entidad; puede limitar la cantidad de resultados, por ejemplo a 50.
  • /query: consulta dinámica para listados productivos, integraciones y sincronizaciones. Permite controlar paginado, filtros y columnas según el contrato de la entidad.
  • /smartie: vista guardada/paginada. El Swagger de la entidad indica sus parámetros, normalmente smartieId, schemaId, page y, cuando corresponde, search.

Para alto volumen, la documentación oficial recomienda preferir /query y pedir solamente las columnas necesarias. Para smartie, comenzar en page=1 e incrementar de a una página.

Ejemplo validado de Smartie​

El ejemplo siguiente muestra el formato general de una operación publicada para una entidad; reemplazá FACTURA por una entidad y un smartieId disponibles en su Swagger:

curl -X GET "https://api.yiqi.com.ar/api/public/FACTURA/smartie?schemaId={SCHEMA_ID}&smartieId={SMARTIE_ID}&page=1" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

No se deben inventar nombres de entidades, smartieId, filtros ni campos de respuesta. Esos valores dependen de la especificación OpenAPI del módulo y del esquema consultado.

Archivos, reportes y estados​

Cuando el Swagger de una entidad los expone:

  • /file usa attributeName, instanceId y schemaId; los métodos permitidos y el contentType se detallan en la operación.
  • /report usa reportName, instanceId y schemaId; los nombres válidos dependen de la entidad.
  • /changestate usa id, schemaId y state; los estados válidos dependen de la entidad.

Buenas prácticas de consumo​

  • Obtener primero schemaId desde GetLoginInformation.
  • Preferir /query para procesos recurrentes, batch o exportaciones grandes.
  • En Smarties, ordenar por fecha de modificación descendente cuando el reporte lo permita.
  • Detener el paginado al alcanzar la última fecha ya sincronizada, evitando recorrer histórico innecesariamente.
  • Usar una cuenta técnica con los permisos mínimos necesarios.
  • Registrar request y respuesta sin guardar credenciales ni tokens.

Diagnóstico​

Ante un error, conservar:

  • operación y URL exacta;
  • módulo y entidad técnica;
  • schemaId y smartieId utilizados, si aplica;
  • código y cuerpo de respuesta;
  • cURL sanitizado, sin contraseña ni token.

Primero verificá el contrato de la operación en el Swagger oficial. Si una ruta aparece en una guía antigua pero no aparece en el Swagger del módulo, debe considerarse no confirmada y no utilizarse como integración.

Enlaces oficiales​