Buscar
Mis Áreas
Ayuda

Guia de uso de API NosConecta

19-09-2024 21:15 (Actualizado 19-09-2024)
  • 0 Respuestas
  • 2 Me gusta
  • 400 Visitas

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

 

  1. Login para obtener token de API

  2. Portal de proveedores

    1. Dar de alta un usuario proveedor

    2. Cargar documentos

      1. Cuenta corriente

      2. Orden de pago

      3. Retenciones

      4. Orden Compra / Recepción

    3. Actualizar un documento ya cargado

      1. Ejemplo Orden de pago

  3. Gestión de facturas de proveedor

    1. Obtener las facturas disponibles para enviar a ERP

    2. Marcar documento como tomado por el ERP

    3. Generar una URL para visualizar la factura

  4. Portal de clientes

    1. Dar de alta un usuario cliente

    2. Cargar facturas al cliente

  5. Anexos

    1. Consultar la estructura de campos de aplicaciones

    2. Consultar cualquier documento disponible en las aplicaciones

    3. Editar un usuario proveedor o cliente

    4. Dar de baja un usuario proveedor o cliente

    5. Consultar usuarios creados

    6. Administrar maestro de proveedores

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



  1. 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.

    1. Endpoint: GET/auth

    2. Parámetros:

      1. user: *el usuario según el ambiente

      2. 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.



  1. Portal de proveedores: Esta solución permite publicar documentos para consulta por parte de proveedores a través de un portal.

    1. 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.

      1. idcompany: 1292

      2. perfil: 9809

    2. 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]

 

 

    1. Cargar documentos

      1. 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.

        1. idaplicacion: 2873 *Cuenta corriente

        2. idaplicacion: 2874 *Orden de pago

        3. idaplicacion: 2875 *Retenciones

        4. idaplicacion: 2877 *Orden de compra / recepción

      2. Cargar registros en la aplicación Cuenta Corriente

        1. Endpoint: POST/file

        2. Parámetros:

          1. idaplicacion: 2873

          2. archivo: no aplica*

          3. 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"}

 

      1. Cargar registros en la aplicación Orden de pago

        1. Endpoint: POST/file

        2. Parámetros:

          1. idaplicacion: 2874

          2. archivo: Archivo a cargar

          3. 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"}

 

 

      1. Cargar registros en la aplicación Retenciones

        1. Endpoint: POST/file

        2. Parámetros:

          1. idaplicacion: 2875

          2. archivo: Archivo a cargar

          3. 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"}

 

 

      1. Cargar registros en la aplicación Orden de compra / Recepción

        1. Endpoint: POST/file

        2. Parámetros:

          1. idaplicacion: 2877

          2. archivo: no aplica*

          3. 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"

}

 

 

    1. 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.

      1. Endpoint: PUT/metadata/{idapp}/{iddoc}

      2. Parámetros:

        1. idapp: 2874

        2. iddoc: ID del documento a actualizar.*

        3. 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

 

  1. Gestión de facturas de proveedor

    1. 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.

      1. idworkflow: 262

      2. idstate: 1440

      3. idtransition: 3568

 

    1. Obtener las facturas disponibles para enviar a ERP

      1. Endpoint: GET/workflows/{idworkflow}/documents

      2. Parámetros

        1. idworkflow: 262

        2. 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)

 

    1. Marcar documento como tomado por el ERP

      1. Endpoint: POST/workflows/{idworkflow}/transition/{iddoc}

      2. Parámetros:

        1. idworkflow: 262

        2. iddoc: Id del documento a mover

        3. idtransition: 3568

        4. description: Opcional, permite dejar una observación al realizar la transición

 

    1. Generar una URL para visualizar la factura: Para visualizar un documento mediante un navegador se deben realizar los siguientes pasos

      1. Consultar hash de un documento:

        1. Endpoint: POST/hash

        2. Parámetros

          1. iddoc: Id del documento a visualizar

          2. 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.

      1. Armar URL: A continuación los datos para armar la URL:

        1. https://{dominio_web}/visor.documento.php?hash={token}&mostrar=0&wf=1

        2. dominio_web: Según el ambiente se deberá indicar el dominio correspondiente:

          1. Producción: https://www.tsdocs.com.ar/

          2. Homologación: https://homologacion2hl.tsdocs.com.ar/

          3. token: El token se conforma de la unión de la key y el hash devuelto por el endpoint. token = key + hash

          4. mostrar: Permite definir si se muestra solo el PDF o si se muestra el PDF y la metadata

            1. mostrar=0 (PDF + metadata)

            2. mostrar=1 (Solo PDF)

            3. wf=1 Muestra el historial de aprobaciones en el workflow. Solo se muestra si mostrar=0

 

 

  1. Portal de clientes

    1. Dar de alta un usuario cliente

      1. 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.

        1. idcompany: 1292

        2. perfil: 10539

      2. 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.

 

    1. Cargar facturas al cliente

      1. Endpoint: POST/file

      2. Parámetros:

        1. idaplicacion: 3093

        2. 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"

}

 

  1. Anexos

    1. Consultar la estructura de campos de aplicaciones

      1. Endpoint: GET/metadata/{idact}/structure

      2. Parámetros

        1. 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

 

    1. Consultar cualquier documento disponible en las aplicaciones

      1. Endpoint: GET/search/{idapp}

      2. Parámetros

        1. idapp: Id aplicación a consultar

        2. filter: [{"key":"cuit","value":"","operator":"="},{"key":"numero_de_factura","value":"","operator":"="}, { "key": "cuit", "value": "123", "operator": "=", "operador_superior": "and" }]*

        3. 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

 

    1. Editar datos de usuario: A continuación se detallan los pasos requeridos para actualizar los datos de un usuario:

      1. Endpoint: PUT/user

      2. Parámetros:

        1. iduser: ID unico de usuario*

        2. name: Nombre del usuario

        3. lastname: Apellido del usuario

        4. mail: Correo electrónico del usuario

        5. portal: 2*

        6. pass:**

        7. repass:**

        8. 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.

 

    1. Dar de baja un usuario: A continuación se detallan los pasos requeridos para dar de baja un usuario de la plataforma:

      1. Endpoint: DELETE/user/{iduser}

      2. Parámetros:

        1. iduser: Id del usuario a dar de baja

        2. 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

    1. Consultar usuario creados:

      1. Endpoint: GET/user/search

      2. Parámetros:

        1. 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

 

    1. 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.

 

      1. Agregar datos del proveedor al maestro de proveedores:

        1. Endpoint: POST/autocomplete

        2. Parámetros:

        3. valueToSearch: CUIT del proveedor

        4. assocValue: JSON con datos del proveedor*

        5. field: ID campo**

        6. 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

 

      1. Editar registro maestro de proveedores: A continuación se detallan los pasos modificar un registro del maestro de proveedores:

        1. Endpoint: PUT/autocomplete/{idapp}

        2. Parámetros:

          1. idapp: Id de la aplicación

          2. valueToSearch: CUIT del proveedor

          3. assocValue: JSON con datos del proveedor

          4. field: *ID campo: 21263

 

      1. Consultar documentos cargados en una aplicación

        1. Endpoint: GET/search/{idapp}

        2. Parámetros

          1. idapp: Id aplicación a consultar

          2. filter: [{"key":"cuit","value":"","operator":"="},{"key":"numero_de_factura","value":"","operator":"="}, { "key": "cuit", "value": "123", "operator": "=", "operador_superior": "and" }]*

          3. 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
Colaboradores
Tablero de base de conocimientos
Choose your region:
Choose your Region
Go