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
... View more