Sabías que?

Vision General   Sobre VISMA NosConecta   NosConecta.com es una plataforma tipo SaaS y “multi-tenant” que ofrece soluciones tecnológicas e innovadoras que ayudan a las empresas a gestionar sus documentos con proveedores y clientes de forma eficaz.   VISMA NosConecta dispone de una API cuyo propósito es servir como una interfaz con la cual integrarse y así permitir conectar directamente con el repositorio de datos, facilitando la integración con otros sistemas.   Introducción   El presente documento es una guía general que detalla los pasos a seguir para la integración a través de la API, no reemplaza el manual de la API disponible online a través: https://{URL DEL AMBIENTE}/reference/ para acceder al mismo es necesario un usuario y clave el cual se indica a continuación.   El manual online es interactivo y permite la realización de pruebas devolviendo por cada petición un CURL para uso con cualquier lenguaje.   Importante: El manual online contiene todos los detalles de los endpoint, esta guía solo contiene lo necesario para operar, si se requiere alguna funcionalidad adicional, recurrir al manual online para verificar su disponibilidad   Para avanzar con el desarrollo de interfaces VISMA pone a disposición un ambiente de pruebas para realizar los desarrollos pertinentes.   El presente documento ofrece un usuario y parámetros para una empresa de pruebas con el que se podrán realizar testeos de los procesos disponibles para integrar con la API, para el uso productivo se deberá solicitar un usuario y los parámetros correspondientes una vez realizada la implementación de la plataforma a nuestro equipo de consultoría y/o soporte.     Aspectos Técnicos   La API está construida respetando la arquitectura RESTFul, esto quiere decir que toda la comunicación se basa en el protocolo HTTP. En dicha comunicación, se realizan distintas peticiones, que se encargará de responder el servidor, proporcionando una respuesta con un formato específico. El formato de respuesta respeta las cabeceras propias del protocolo, que variarán según un resultado positivo o negativo, y el mensaje en el cuerpo del mismo tendrá formato JSON, con la codificación UTF-8.   Toda la documentación técnica que un desarrollador necesita para poder consumir los servicios está publicada en las URL del manual indicado en la introducción del presente documento. Esta documentación es auto-generada cada vez que se despliega una nueva versión de la API, por lo que se garantiza que la información allí provista siempre estará al día y consistente.   El manual online contiene todo el detalle de uso de los endpoint disponibles, además de dar ejemplos de las posibles respuestas a peticiones.   Login   La API requiere que el usuario que desee usarla realice un Login, previo al posterior consumo de los servicios. Esto se debe a que al proveer las credenciales (usuario y password) la API determina los roles y permisos del usuario y así permitirá o denegará las peticiones a ciertos servicios, en función de si el usuario tiene suficientes permisos. Por lo tanto, el primer servicio a consumir es el del Login, una vez hecho esto la API devuelve un Token que tiene vigencia de 12 hs y deberá ser utilizado para realizar todas las peticiones requeridas al resto de los servicios   Procesos disponibles a través de la API   Login para obtener token de API Portal de proveedores Dar de alta un usuario proveedor Cargar documentos Cuenta corriente Orden de pago Retenciones Orden Compra / Recepción Actualizar un documento ya cargado Ejemplo Orden de pago Gestión de facturas de proveedor Obtener las facturas disponibles para enviar a ERP Marcar documento como tomado por el ERP Generar una URL para visualizar la factura Portal de clientes Dar de alta un usuario cliente Cargar facturas al cliente Anexos Consultar la estructura de campos de aplicaciones Consultar cualquier documento disponible en las aplicaciones Editar un usuario proveedor o cliente Dar de baja un usuario proveedor o cliente Consultar usuarios creados Administrar maestro de proveedores Consultar documentos cargado en una aplicación   Datos de acceso   Ambiente URL Usuario Clave Stage   https://api.stage.nosconecta.com.ar/reference/ api_calipso_demo   admin4744   * Para el uso productivo de la API se deberán solicitar los datos de acceso y parámetros una vez realizada la implementación de la plataforma a nuestro equipo de consultoría.   Pasos para realizar los procesos disponibles a través de la API   Esta guía detalla los pasos a seguir para la integración con nuestra API a través de los distintos endpoints disponibles para cada proceso. Para obtener mayor detalle de los endpoints utilizados en casa proceso nuestro manual online contiene todo el detalle de uso de los endpoint disponibles, además de dar ejemplos de las posibles respuestas a peticiones. * Los parámetros utilizados a continuación son de ejemplo, para el uso productivo se deberán solicitar los datos de acceso y parámetros una vez realizada la implementación de la plataforma a nuestro equipo de consultoría. Login: Es el primer paso antes de realizar cualquier acción vía API, en este caso solo se envían los datos de usuario y clave. Endpoint: GET/auth Parámetros: user: *el usuario según el ambiente password: *la clave del usuario según el ambiente El endpoint devolverá un JWT que tiene vigencia de 12 hs y deberá ser utilizado para realizar todas las peticiones requeridas. Portal de proveedores: Esta solución permite publicar documentos para consulta por parte de proveedores a través de un portal. Parámetros: A continuación los parámetros necesarios para dar de alta usuarios proveedor en la plataforma* Los parámetros a continuación son de ejemplo. idcompany: 1292 perfil: 9809 Dar de alta un usuario proveedor: A continuación se detallan los pasos requeridos para dar de alta un usuario nuevo: 2.1. Primer paso crear el usuario: 2.1.1. Endpoint: POST/user 2.1.2. Parámetros: 2.1.2.1. user: login de usuario* 2.1.2.2. name: Nombre del usuario 2.1.2.3. lastname: Apellido del usuario 2.1.2.4. mail: Correo electrónico del usuario 2.1.2.5. portal: 2 2.1.2.6. idcompany: 1292 2.1.2.7. pass: Clave de usuario** 2.1.2.8. repass: Confirmar la contraseña 2.1.2.9. passActual: La contraseña del usuario logueado con la API que está creando el usuario   * Para NosConecta el CUIT es obligatorio como nombre de usuario ** Largo mínimo de 8 caracteres. Deberá contener letras y números. No se admiten números consecutivos.   Al confirmar la creación del usuario el endpoint devolverá un ID único de usuario necesario para posteriores operaciones con el usuario.   2.2. Segundo paso, asignar perfiles a el usuario: A continuación se detallan los datos requeridos para dar mediante uno o más perfiles acceso a las aplicaciones . 2.2.1. Endpoint: POST/user/{iduser}/profile 2.2.2. Parámetros: 2.2.2.1. iduser: Id del usuario a asignar el perfil 2.2.2.2. idprofile: [9809]   *El perfil a asignar al usuario se debe corresponder con el portal con el cual fue creado el usuario. ** Un usuario puede tener uno o más perfiles, en ese caso se deberá indicar todos los ID en json. Ejemplo [1234,5678]     Cargar documentos Parámetros: A continuación los parámetros necesarios para cargar los documentos a los proveedores en el portal *Los parámetros a continuación son de ejemplo. idaplicacion: 2873 *Cuenta corriente idaplicacion: 2874 *Orden de pago idaplicacion: 2875 *Retenciones idaplicacion: 2877 *Orden de compra / recepción Cargar registros en la aplicación Cuenta Corriente Endpoint: POST/file Parámetros: idaplicacion: 2873 archivo: no aplica* datos: JSON con los nombres de los campos y los valores a cargar   JSON de ejemplo de carga de una Cuenta corriente {"cuit": "01234567890","numero_de_documento": "1234A12341236","tipo_de_documento": "Factura","fecha_documento": "01/12/2020","importe": "111,22","moneda": "ARG","estado": "Aprobado para pago","numero_de_pago": "888"}   Cargar registros en la aplicación Orden de pago Endpoint: POST/file Parámetros: idaplicacion: 2874 archivo: Archivo a cargar datos: JSON con los nombres de los campos y los valores a cargar {"cuit": "01234567890","fecha_de_pago": "12/12/2020","importe": "111,22","moneda": "ARG","forma_de_pago": "Transferencia Bancaria","numero_de_pago": "889"}     Cargar registros en la aplicación Retenciones Endpoint: POST/file Parámetros: idaplicacion: 2875 archivo: Archivo a cargar JSON con los nombres de los campos y los valores a cargar {"cuit": "30691323958","numero_de_retencion": "0031-00002368","importe": "3287,56","moneda": "ARS","tipo": "Ingresos Brutos C.A.B.A.","numero_de_pago": "887"}     Cargar registros en la aplicación Orden de compra / Recepción Endpoint: POST/file Parámetros: idaplicacion: 2877 archivo: no aplica* datos: JSON con los nombres de los campos y los valores a cargar   { "cuit": "01234567890", "comprador": "Juan Pedro", "numero_de_pedido": "123456", "numero_de_linea": "1", "fecha_de_envio": "2021-07-05", "codigo_de_material": "12", "descripcion_material": "Tornillos", "cantidad_disponible_para_facturar": "20", "cantidad_pedida": "30", "tipo_operacion": "Mercaderia", "condicion_de_pago": "1", "cantidad_entregada": "30", "monto_disponible_para_facturar": "500", "cantidad_facturada": "10", "moneda": "ARG", "numero_recepcion": "789", "fecha_de_recepcion": "2021-07-08", "estado": "Disponible", "identificador": "123456-1-789" }     Actualizar un documento ya cargado: A continuación a modo de ejemplo se detallan los datos requeridos para la actualización de datos en la aplicación: Ejemplo Orden de pago. Endpoint: PUT/metadata/{idapp}/{iddoc} Parámetros: idapp: 2874 iddoc: ID del documento a actualizar.* Los datos a actualizar deben enviarse en el form de la petición en formato clave valor. A este documento se adjunta un ejemplo en Postman. * Para conocer el ID del documento se debe utilizar el endpoint de búsqueda indicado en el punto 5.2 de los anexos del presente documento   Gestión de facturas de proveedor Parámetros: A continuación los parámetros necesarios para consultar las facturas que están listas para ser procesadas por el ERP *Los parámetros a continuación son de ejemplo. idworkflow: 262 idstate: 1440 idtransition: 3568   Obtener las facturas disponibles para enviar a ERP Endpoint: GET/workflows/{idworkflow}/documents Parámetros idworkflow: 262 idstate: [1440]   El endpoint devolverá un JSON con los datos de todos los documentos que se encuentran en el estado Listo para ERP del Workflow, incluido el ID único por documento el cual es necesario para las posteriores acciones. Con los datos devueltos se debe armar la URL de consulta del PDF del documento. (Ver punto 3.4)   Marcar documento como tomado por el ERP Endpoint: POST/workflows/{idworkflow}/transition/{iddoc} Parámetros: idworkflow: 262 iddoc: Id del documento a mover idtransition: 3568 description: Opcional, permite dejar una observación al realizar la transición   Generar una URL para visualizar la factura: Para visualizar un documento mediante un navegador se deben realizar los siguientes pasos Consultar hash de un documento: Endpoint: POST/hash Parámetros iddoc: Id del documento a visualizar appid: 2876 *Este endpoint consulta y de existir devuelve un hash y una key única por documento que permite a través del visualizador del documento consultar el documento requerido. Armar URL: A continuación los datos para armar la URL: https://{dominio_web}/visor.documento.php?hash={token}&mostrar=0&wf=1 dominio_web: Según el ambiente se deberá indicar el dominio correspondiente: Producción: https://www.tsdocs.com.ar/ Homologación: https://homologacion2hl.tsdocs.com.ar/ token: El token se conforma de la unión de la key y el hash devuelto por el endpoint. token = key + hash mostrar: Permite definir si se muestra solo el PDF o si se muestra el PDF y la metadata mostrar=0 (PDF + metadata) mostrar=1 (Solo PDF) wf=1 Muestra el historial de aprobaciones en el workflow. Solo se muestra si mostrar=0     Portal de clientes Dar de alta un usuario cliente Parámetros: A continuación los parámetros necesarios para dar de alta usuarios cliente en la plataforma* Los parámetros a continuación son de ejemplo. idcompany: 1292 perfil: 10539 Para dar de alta al cliente se deben seguir los mismos pasos indicados en el punto 2.2, utilizando los parámetros para el cliente.   Cargar facturas al cliente Endpoint: POST/file Parámetros: idaplicacion: 3093 archivo: Archivo a cargar JSON con los nombres de los campos y los valores a cargar { "razon_social_cliente": "VISMA", "cuit": "30712207627", "numero_de_documento": "0001-12300542", "tipo_de_documento": "Factura", "fecha_documento": "2022-11-18", "fecha_de_vencimiento": "2022-12-19", "importe_neto": "45530,54", "importe": "45530,54", "moneda": "Pesos", "leido": "NO", "cotizacion_de_dolar": "", "mail": "test@correo.com", "telefono": "", "descripcion": "", "estado": "Pendiente" }   Anexos Consultar la estructura de campos de aplicaciones Endpoint: GET/metadata/{idact}/structure Parámetros idact : 3 El resultado de este GET será un json con la estructura de los campos de las aplicaciones a las que tiene acceso el usuario   Consultar cualquier documento disponible en las aplicaciones Endpoint: GET/search/{idapp} Parámetros idapp: Id aplicación a consultar filter: [{"key":"cuit","value":"","operator":"="},{"key":"numero_de_factura","value":"","operator":"="}, { "key": "cuit", "value": "123", "operator": "=", "operador_superior": "and" }]* allfields: true *Para conocer los nombres de los campos de búsqueda de cada aplicación se debe utilizar el endpoint indicado en el Anexo 5.1 El endpoint devolverá un JSON con los datos de todos los documentos que cumplan con la condición definida en los parámetros de la búsqueda. Además del identificador único del documento, campo id   Editar datos de usuario: A continuación se detallan los pasos requeridos para actualizar los datos de un usuario: Endpoint: PUT/user Parámetros: iduser: ID unico de usuario* name: Nombre del usuario lastname: Apellido del usuario mail: Correo electrónico del usuario portal: 2* pass:** repass:** passActual: La contraseña del usuario logueado con la API que está creando el usuario* * Parámetros obligatorios para editar un usuario **Si no requiere modificar la contraseña del usuario los parámetros pass y repass no deben ser enviados en el request. ** Si desea modificar la clave, debe enviar la nueva clave y confirmar en los parámetros pass y repass. La clave asignada es temporal, se enviará un correo electrónico al usuario con los datos de acceso para que ingrese y genere una nueva contraseña.   Dar de baja un usuario: A continuación se detallan los pasos requeridos para dar de baja un usuario de la plataforma: Endpoint: DELETE/user/{iduser} Parámetros: iduser: Id del usuario a dar de baja passActual: La contraseña del usuario logueado con la API que está creando el usuario *Esta acción es irreversible. Si desea activar nuevamente un usuario dado de baja se deberá crear un nuevo usuario con el mismo nombre de usuario dado de baja Consultar usuario creados: Endpoint: GET/user/search Parámetros: filter: json con filtros de usuario* * JSON de ejemplo para buscar por nombre de usuario: [{ "key": "usuario", "value": "123456", "operator": "=", "operador_superior":"AND" }] ** Las búsquedas se pueden realizar por cualquiera las siguientes key: "usuario": "", "nombre": "", "apellido": "", "mail": "" *** Si se lanza un request con el parámetro filtro vacío el endpoint devolverá todos los usuarios activos   Administrar el maestro de proveedores: Para el autocompletado de información a partir de un campo clave. Ejemplo: A partir del CUIT del proveedor se puede completar la razón social y el número de proveedor y el área a la que pertenece. Esta funcionalidad únicamente está disponible si se contrata la solución de gestión de facturas.   Agregar datos del proveedor al maestro de proveedores: Endpoint: POST/autocomplete Parámetros: valueToSearch: CUIT del proveedor assocValue: JSON con datos del proveedor* field: ID campo** idapp: Id de la aplicación facturas * JSON de ejemplo: {"razon_social":"VISMA LATAM","numero_proveedor":"778899"} **ID campo: 21263 *** El JSON con los valores de los proveedores depende de la estructura del maestro definida en el alcance de la implementación. Una vez definido el alcance se estará compartiendo el JSON definitivo   Editar registro maestro de proveedores: A continuación se detallan los pasos modificar un registro del maestro de proveedores: Endpoint: PUT/autocomplete/{idapp} Parámetros: idapp: Id de la aplicación valueToSearch: CUIT del proveedor assocValue: JSON con datos del proveedor field: *ID campo: 21263   Consultar documentos cargados en una aplicación Endpoint: GET/search/{idapp} Parámetros idapp: Id aplicación a consultar filter: [{"key":"cuit","value":"","operator":"="},{"key":"numero_de_factura","value":"","operator":"="}, { "key": "cuit", "value": "123", "operator": "=", "operador_superior": "and" }]* allfields: true   *Para conocer los nombres de los campos de búsqueda de cada aplicación se debe utilizar el endpoint indicado en el Anexo 5.1 El endpoint devolverá un JSON con los datos de todos los documentos que cumplan con la condición definida en los parámetros de la búsqueda. Además del identificador único del documento, campo id