AndresJGM Posted July 9, 2020 Posted July 9, 2020 WebServices de SiReTT Online — Generalidades SiReTT Online publica un WebService SOAP que permite a aplicaciones de terceros (y a otros sistemas SiReTT) consultar inventario y existencias, registrar documentos de venta (preventas y órdenes) y consultar el estado de los documentos girados. Esta publicación cubre lo general: arquitectura, autenticación, licencias, estructura de las respuestas y el catálogo de códigos de resultado. En las otras dos publicaciones se detallan las operaciones de Proveedores y de Clientes. 1. Arquitectura y punto de acceso Es un endpoint SOAP RPC (no REST), implementado sobre nusoap. Las URLs son: Endpoint: https://TU-DOMINIO/webservice.php Contrato WSDL: https://TU-DOMINIO/webservice.php?wsdl Cualquier cliente SOAP estándar (PHP SoapClient, nusoap, Python zeep, etc.) puede consumir el servicio leyendo el WSDL. El endpoint es de acceso público a nivel de red; cada operación valida internamente la identidad y los permisos del actor (no se usa la sesión interactiva del sistema). 2. Roles y licenciamiento Existen dos licencias independientes. Un sistema puede tener una, otra o ambas: Licencia Rol Habilita WebServices Emisor (servidor SOAP) Que otros sistemas o aplicaciones consulten y giren documentos contra el suyo. WebServices Cliente Consumidor Que su sistema consuma el WebService de un proveedor remoto: sincronizar catálogo, girar pedidos y conciliar. Las licencias se administran en Inicio > Licencias Extras. 3. Autenticación Toda operación recibe como primeros parámetros la identidad del actor (ws_cid para Cliente o ws_pid para Proveedor) y una credencial en ws_passwd. 3.1 API Key (método recomendado) El método recomendado es una API Key larga, aleatoria y única que identifica y autentica al actor en un solo valor. La key: Tiene el formato sirett_cli_ (cliente) o sirett_prv_ (proveedor) seguido de 48 caracteres hexadecimales. Se genera desde la ficha del Cliente o del Proveedor (botón Generar / Regenerar) y se muestra una sola vez; guárdela en un lugar seguro. Se almacena en el servidor solo como hash SHA-256 (no es recuperable). En la interfaz queda una pista (prefijo + últimos 4 dígitos) para reconocerla. Viaja en el parámetro ws_passwd. Como el actor se resuelve por la propia key, ws_cid/ws_pid pueden ir en 0. El contrato del WSDL no cambia: la API Key reutiliza el campo ws_passwd existente. 3.2 Credencial heredada (ID + contraseña) — en desuso El método anterior (identificador numérico + contraseña en ws_passwd) sigue funcionando por compatibilidad, pero se considera obsoleto y será removido en una versión futura. Si está integrando hoy, use API Key. 4. Estructura de las respuestas Todas las operaciones devuelven un entero result con el estado. Las de lectura devuelven además data (colección de artículos); los _send_* devuelven en data el detalle por línea. Cada artículo (items_Row) incluye, entre otros campos: Campo Descripción codigo Código del artículo. cod_producto Código de barras / GTIN. descripcion Descripción del artículo. presentacion Presentación / variante. familia, marca, clase, modelo Clasificación. item_grupo_1..3 Grupos personalizados. precio Precio según el nivel del actor (IVA, descuentos y promociones ya aplicados). stock Existencia. image_url Ruta de la imagen de catálogo. El cálculo de precio contempla la normalización del IVA, los descuentos por artículo y por familia, las promociones y los "precios extra" multimoneda configurados para el actor. 5. Control de frecuencia (throttle) Para proteger el rendimiento, las consultas masivas (catálogo completo o por bodega) están limitadas a una cada cierto intervalo por actor (por defecto 60 minutos; configurable). Si se excede, la operación devuelve result = 20. No aplica a consultas de un solo artículo, por código de barras, ni a los _send_*. 6. Catálogo de códigos de resultado Autenticación (login) Código Significado 0 OK 1 La cuenta no existe 2 La cuenta no tiene acceso al WebService (sin credencial configurada) 3 Credencial incorrecta 4 Sin permiso para la operación solicitada 5 Licencia WebServices deshabilitada Lectura Código Significado 6 Artículo no encontrado 20 Límite de frecuencia entre consultas excedido (throttle) Documentos entrantes (_send_*) — resultado general Código Significado 7 Orden no recibida (falta el número de orden o datos del actor) 8 Documento con ese número (ws_orden_id) ya registrado 9 Bodega no encontrada o no vinculada al actor 10 Faltan datos requeridos del cliente — solo lado Proveedor 11 Tipo/formato de identificación erróneo — solo lado Proveedor 12 Formato de correo electrónico inválido — solo lado Proveedor 13 No se recibió detalle para procesar 17 Algunas líneas presentaron problemas (ver el resultado por línea) 19 Falló la reserva de existencias (preventa) Documentos entrantes — resultado por línea Código Significado 0 Línea aceptada 14 Línea mal definida (sin código o sin cantidad) 15 El artículo no existe en la base de datos 16 Cantidad no válida según la configuración de unidad del artículo 18 Sin existencias (reserva fallida) 7. Interconexión entre dos sistemas SiReTT Cuando el comprador y el vendedor usan ambos SiReTT, el sistema puede actuar como consumidor del WebService del otro: sincronizar el catálogo del proveedor remoto, girar pedidos automáticamente desde una compra y conciliar el documento cuando el proveedor lo factura. Esta cara consumidor requiere la licencia WebServices Cliente y se detalla en la publicación de Proveedores. Continúa en: "WebServices — Proveedores" y "WebServices — Clientes". Quote
AndresJGM Posted December 18, 2021 Author Posted December 18, 2021 WebServices de SiReTT Online — Proveedores El actor Proveedor (operaciones con prefijo wsp_) representa a una empresa que le vende a quien opera SiReTT. Sus operaciones permiten consultar el catálogo y existencias, y registrar documentos de venta en los que el proveedor indica el cliente final. Si ambas empresas usan SiReTT, esta misma configuración habilita la interconexión sistema↔sistema. Antes de continuar, revise la publicación de Generalidades (arquitectura, autenticación y códigos de resultado). 1. Configuración del proveedor Se configura en Proveeduría, editando el proveedor, en la pestaña de conectividad WebService. Campos clave: API Key — credencial de acceso (ver punto 2). Permisos — qué operaciones puede invocar el proveedor (ver tabla de la sección 4). Bodegas autorizadas — existencias de qué bodegas puede consultar. Nivel de precio (Precio Base) y precios extra — qué lista de precios se le expone. Datos para crear el cliente — caja, línea y tipo de factura, categoría y grupos que se asignan al cliente final cuando el proveedor envía un documento (wsp_send_*). 2. API Key del proveedor Genere la credencial con el botón Generar / Regenerar API Key. La key: Tiene el formato sirett_prv_ + 48 hexadecimales. Se muestra una sola vez: cópiela y entréguela al proveedor por un canal seguro. Se guarda solo como hash; en la ficha queda una pista (prefijo + últimos 4) para reconocerla. El proveedor la envía en ws_passwd (con ws_pid = 0). 3. Operaciones de lectura Todas reciben la identidad y la credencial como primeros parámetros. Las variantes _bodega_* restringen a una bodega bid; las _bodega_all_* ignoran el vínculo del actor y listan por existencia. Operación Parámetros Descripción wsp_request_items — Artículos vinculados al proveedor + existencias de las bodegas permitidas. wsp_request_bodega_items bid Igual, restringido a la bodega indicada. wsp_request_bodega_all_items bid Todos los artículos con existencia en la bodega (ignora el vínculo). wsp_request_item icodigo Un artículo por código. wsp_request_bodega_item bid, icodigo Un artículo por código en una bodega. wsp_request_bodega_all_item bid, icodigo Un artículo por código en una bodega, sin filtrar por vínculo. 3.1 Consulta por lista de códigos Punto intermedio entre consultar un artículo y todo el catálogo. Reciben icodigos = hasta 50 códigos separados por coma: Operación Parámetros Descripción wsp_request_bodega_items_list bid, icodigos Lista de artículos vinculados al proveedor, con existencias de la bodega. wsp_request_bodega_all_items_list bid, icodigos Lista del catálogo global, con existencias de la bodega. 3.2 Consulta por código de barras Operación Parámetros Descripción wsp_request_barcode icodigo Busca por código de barras (cod_producto). wsp_request_bodega_barcode bid, icodigo Variante por bodega. wsp_request_bodega_all_barcode bid, icodigo Variante por bodega, sin filtrar por vínculo. Por defecto solo se devuelven artículos con existencia mayor a cero, salvo que se consulte un artículo puntual o que el sistema esté configurado para incluir artículos sin existencia. 4. Permisos del proveedor Cada operación verifica su propio bit de permiso. Active solo lo que el proveedor necesite: Permiso Operación habilitada Consultar artículos wsp_request_items Consultar por bodega wsp_request_bodega_items Consultar bodega (todo) wsp_request_bodega_all_items Consultar un artículo wsp_request_item Consultar un artículo en bodega wsp_request_bodega_item (y la variante por lista) Consultar un artículo en bodega (todo) wsp_request_bodega_all_item (y la variante por lista) Registrar órdenes wsp_send_orden Registrar preventas wsp_send_preventa (y la consulta de estado) Consultar por código de barras wsp_request_barcode y sus variantes por bodega 5. Documentos entrantes El proveedor registra documentos de venta indicando, además del detalle, los datos del cliente final: Operación Parámetros Efecto wsp_send_preventa bid, ws_orden_id, cliente, detalle[] Crea una preventa reservando existencias y reconoce o crea al cliente final. wsp_send_orden bid, ws_orden_id, cliente, detalle[] Crea una orden y la aplica, reconociendo o creando al cliente final. Array de cliente (cliente): idtipo (1 Física, 2 Jurídica, 3 DIMEX, 4 NITE, 5 Otro, 6 Extranjero), identificacion, nombre, email, phone, provincia, ciudad, distrito, direccion. Array de detalle (detalle[]): por línea { codigo, cantidad, precio }. Si precio viene en 0, se usa el precio del nivel del proveedor. La respuesta devuelve, por línea, { codigo, reply } con el resultado individual. Idempotencia: el documento se identifica por ws_orden_id + el actor. Si se reenvía el mismo, se rechaza con result = 8 (ya registrado). Los documentos se crean con el usuario SIRETT_API. 6. Consulta de estado de preventas Operación Parámetros Descripción wsp_request_preventa_status ws_orden_ids Estado de una o varias preventas giradas (hasta 50 ids separados por coma). Por cada id devuelve estado (0 no existe o anulada · 1 vigente · 2 facturada), la currency_code del documento y, si está facturada, el numero, la fecha y el detalle[] real (montos gravado y descuento por línea totalizados). 7. Interconexión: su sistema como consumidor Cuando el proveedor también usa SiReTT, su sistema puede consumir el WebService de ese proveedor. Esta cara consumidor requiere la licencia WebServices Cliente. 7.1 Conexión saliente En la ficha del proveedor se configuran "URL SiReTT" (el WSDL del sistema remoto) y "API Key del sistema remoto" (la key que ese proveedor le entregó, guardada cifrada), además de la bodega de consignación. Dejar el campo de API Key vacío al editar conserva la credencial actual. 7.2 Sincronización de catálogo La pestaña "Catálogo Remoto" de la ficha del proveedor trae el catálogo remoto a una tabla espejo local: miniaturas, precio, existencia y estado de vínculo. Desde ahí puede vincular cada código remoto a un artículo local, crear el artículo (con los datos prellenados) o importar imágenes. El botón Sincronizar ahora actualiza el espejo. 7.3 Giro de pedidos desde la compra Al crear una compra a un proveedor configurado por WS, un banner muestra la última sincronización y la divisa de venta, y un selector "Giro WS" permite elegir entre No girar (flujo clásico), Orden (registro informal) o Pre-Venta (con seguimiento de estado). Al cerrar, el pedido se gira automáticamente al sistema del proveedor y los precios se reconcilian con la lista del proveedor. 7.4 Seguimiento y conciliación La pestaña "Pedidos Girados" lista las compras giradas como Pre-Venta y consulta su estado en lote. Cuando el proveedor factura el pedido, la opción "Conciliar y Convertir en Compra" trae el detalle real (número, fecha y líneas), permite vincular cualquier artículo nuevo y convierte la orden en compra con la fecha del documento del proveedor. Ver también: "WebServices — Generalidades" y "WebServices — Clientes". Quote
AndresJGM Posted December 21, 2021 Author Posted December 21, 2021 WebServices de SiReTT Online — Clientes El actor Cliente (operaciones con prefijo wsc_) representa a una empresa o aplicación que le compra a quien opera SiReTT. Sus operaciones son espejo de las del Proveedor, con una diferencia clave: los documentos que envía se aplican a su propia cuenta, no a un tercero. Antes de continuar, revise la publicación de Generalidades (arquitectura, autenticación y códigos de resultado). 1. Configuración del cliente Se configura en Clientes, editando el cliente, en la pestaña de conectividad WebService. Campos clave: API Key — credencial de acceso (ver punto 2). Permisos — qué operaciones puede invocar el cliente (ver tabla de la sección 4). Bodegas autorizadas — existencias de qué bodegas puede consultar. Nivel de precio — qué lista de precios se le expone. 2. API Key del cliente Genere la credencial con el botón Generar / Regenerar API Key. La key: Tiene el formato sirett_cli_ + 48 hexadecimales. Se muestra una sola vez: cópiela y entréguela al cliente por un canal seguro. Se guarda solo como hash; en la ficha queda una pista (prefijo + últimos 4) para reconocerla. El cliente la envía en ws_passwd (con ws_cid = 0). 3. Operaciones de lectura Reciben la identidad y la credencial como primeros parámetros. Las variantes _bodega_* restringen a una bodega bid; las _bodega_all_* ignoran el vínculo del actor y listan por existencia. Operación Parámetros Descripción wsc_request_items — Artículos vinculados al cliente + existencias de las bodegas permitidas. wsc_request_bodega_items bid Igual, restringido a la bodega indicada. wsc_request_bodega_all_items bid Todos los artículos con existencia en la bodega (ignora el vínculo). wsc_request_item icodigo Un artículo por código. wsc_request_bodega_item bid, icodigo Un artículo por código en una bodega. wsc_request_bodega_all_item bid, icodigo Un artículo por código en una bodega, sin filtrar por vínculo. 3.1 Consulta por lista de códigos Reciben icodigos = hasta 50 códigos separados por coma: Operación Parámetros Descripción wsc_request_bodega_items_list bid, icodigos Lista de artículos vinculados al cliente, con existencias de la bodega. wsc_request_bodega_all_items_list bid, icodigos Lista del catálogo global, con existencias de la bodega. 4. Permisos del cliente Permiso Operación habilitada Consultar artículos wsc_request_items Consultar por bodega wsc_request_bodega_items Consultar bodega (todo) wsc_request_bodega_all_items Consultar un artículo wsc_request_item Consultar un artículo en bodega wsc_request_bodega_item (y la variante por lista) Consultar un artículo en bodega (todo) wsc_request_bodega_all_item (y la variante por lista) Registrar órdenes wsc_send_orden Registrar preventas wsc_send_preventa (y la consulta de estado) Datos de cuenta wsc_account_info 5. Documentos entrantes A diferencia del proveedor, el cliente no envía datos de un tercero: el documento se aplica a su propia cuenta. Operación Parámetros Efecto wsc_send_preventa bid, ws_orden_id, detalle[] Crea una preventa reservando existencias de cada línea. wsc_send_orden bid, ws_orden_id, detalle[] Crea una orden y la aplica. Array de detalle (detalle[]): por línea { codigo, cantidad, precio }. Si precio viene en 0, se usa el precio del nivel del cliente. La respuesta devuelve, por línea, { codigo, reply } con el resultado individual. Idempotencia: el documento se identifica por ws_orden_id + el actor. Si se reenvía el mismo, se rechaza con result = 8 (ya registrado). Los documentos se crean con el usuario SIRETT_API. 6. Consulta de estado de preventas Operación Parámetros Descripción wsc_request_preventa_status ws_orden_ids Estado de una o varias preventas giradas (hasta 50 ids separados por coma). Por cada id devuelve estado (0 no existe o anulada · 1 vigente · 2 facturada), la currency_code del documento y, si está facturada, el numero, la fecha y el detalle[] real. 7. Datos de cuenta Operación Parámetros Descripción wsc_account_info — Devuelve los datos de cuenta del cliente y su nivel de precio asociado. Ver también: "WebServices — Generalidades" y "WebServices — Proveedores". Quote
Oscar Posted January 19, 2022 Posted January 19, 2022 Don Andrés, ojala en algún momento puedas hacer que el WebService - Proveedores de Sirett permita enlazar a proveedores, con el fin de que mi sistema pueda consultar o sincronizar los costos y el inventario en linea Quote
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.