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. Usa 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; reemplaza 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.

Obtener los IDs de los campos que referencian a otra entidad​

Al crear o modificar un registro, los campos que apuntan a otra entidad (por ejemplo el Punto de venta, el Cliente o el Tipo de Factura de una factura) se completan con el ID del registro referenciado. Muchas de esas entidades son de configuración y solo las ven algunos perfiles: un usuario que puede crear facturas no siempre puede consultar la entidad de puntos de venta.

Para eso, cada entidad expone sus propias consultas de referencias. Solo piden permiso para ver la entidad que se está escribiendo, no la entidad referenciada:

GET https://api.yiqi.com.ar/api/public/FACTURA/rootdropdowns?schemaId={SCHEMA_ID}
GET https://api.yiqi.com.ar/api/public/FACTURA/fields/PUVE_ID_PUVE/search?schemaId={SCHEMA_ID}&term={TEXTO}
GET https://api.yiqi.com.ar/api/public/FACTURA/fields/TIFA_ID_TIFA/dropdown?schemaId={SCHEMA_ID}&dependValue={ID_CLIENTE}
  • /rootdropdowns devuelve de una vez las opciones de todos los combos que no dependen de otro campo, agrupadas por nombre de campo. Si un combo tiene demasiadas opciones no viaja en la respuesta: aparece en _searchable y se consulta con /search.
  • /fields/{campo}/search busca por texto los valores válidos de un campo de referencia. Sirve para cualquier referencia que no dependa de otro campo, y es la indicada para tablas grandes como clientes o artículos.
  • /fields/{campo}/dropdown devuelve las opciones de un campo que depende de otro, a partir del ID elegido en ese otro campo (dependValue). Por ejemplo, el Tipo de Factura válido según el Cliente.

Las tres responden pares value / title: value es el ID que se envía en el campo y title es el texto que ve el usuario. En el Swagger de cada entidad, la descripción de cada campo de referencia indica cuál de estas consultas corresponde.

Estas consultas devuelven solo el ID y el texto. Para leer otros datos de la entidad referenciada hace falta permiso sobre ella; en ese caso conviene asignar un perfil de solo lectura.

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 verifica 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​