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
Ver artículo completo
Visma Dinamarca
Visma Finlandia
Visma Letonia
Visma Países Bajos - Holanda
Visma Noruega
Visma Suecia
Visma Desarrolladores & Partners
Visma Latinoamérica