Introducción

Este documento es una guía API, anexa al Manual de configuración y uso técnico del Portal de Proveedores Nos Conecta, de Corporate ERP. También se encuentra en formato Word en este link. 

En su uso, tener en cuenta:

• Fue desarrollado a partir de la estructura original de Nos Conecta, a la cual se le agregó una sección correspondiente a su aplicación en Corporate. Por este motivo, se sugiere siempre verificar su vigencia.
• Si bien el mismo detalla los pasos a seguir, no reemplaza el manual de la API disponible en: https://{URL DEL AMBIENTE}/reference/ al que podrá acceder con los siguientes datos de usuario y contraseña:

Datos necesarios para el uso de la API de NosConecta

Nota: El manual online es interactivo y permite la realización de pruebas, devolviendo por cada petición un CURL para uso con cualquier lenguaje. Para avanzar con el desarrollo de la interfaz, VISMA disponibiliza un ambiente de homologación para que se puedan realizar las pruebas pertinentes.

_____________________________________________________________________________________________________________________

Visión general

La API está construida respetando la arquitectura RESTFul, lo cual significa que toda la comunicación se basa en el protocolo HTTP. En la misma, se realizan distintas peticiones que se encargarán de responder el servidor, proporcionando una respuesta con un formato específico. 

El formato de respuesta respeta las cabeceras propias del protocolo, que varían según sea un resultado positivo o negativo, y el mensaje en el cuerpo del mismo tendrá formato JSON, con la codificación UTF-8.

Configuración inicial

1. Loguearse para obtener el token para utilizar la API

• Enpoint: GET/auth
• Parámetros:

• user: api_calipso_demo
• password: *la clave del usuario según el ambiente.

El endpoint devolverá un JWT con vigencia de 12hs, que deberá ser utilizado para realizar todas las peticiones requeridas.

2. Consultar y descargar documentos disponibles para ingresar al ERP 

Se trata de documentos que se encuentran en el estado Listo para SAP del Workflow.

• 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 SAP del Workflow, incluido el ID único por documento. El mismo es necesario para las acciones posteriores.

Con los datos devueltos se debe armar la URL de consulta del PDF del documento. (Ver punto 4)

3. Mover los documentos de Listo para SAP a Archivo

Esto tiene el objetivo de marcar los documentos procesados correctamente:

• 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

4. Generar la URL para visualizar un documento

A) Consultar hash de un documento:

• Endpoint: POST/hash
• Parámetros

• iddoc: Id del documento a visualizar
• appid: 2876
• A continuación los datos para armar la URL:

*Este endpoint consulta y (de existir) devuelve un hash y una key única por documento que permite consultar el documento requerido a través del visualizador del documento, consultar el documento requerido.

B) Armar URL: https://{dominio_web}/v/visor_documentos?hash={token}&mostrar=0&wf=1

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

• Producción: https://admin.nosconecta.com
• Stage: https://web.stage.tsdocs.com.ar/

• token: El token se conforma de la unión de la key y el hash devuelto por el endpoint.
• 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 los el historial de aprobaciones en el workflow. Solo se muestra si mostrar=0

5. Cargar Orden de Compra general

A continuación se detallan, a modo de ejemplo, los datos requeridos para la carga de datos en la aplicación Orden de Compra general: 

• Endpoint: POST/file
• Parámetros:

• idaplicacion: 2877
• archivo: Archivo a cargar
• datos: JSON con los nombres de los campos y los valores a cargar. 

JSON de ejemplo:  

{

    "cuit": "",

    "fecha_de_orden_de_compra": "",

    "orden_de_compra": "",

    "linea_orden_compra": "",

    "descripcion": "",

    "codigo_de_material": "",

    "descripcion_material": "",

    "monto_oc": "",

    "moneda": "ARG, USD, EUR",

    "nro_certificado_recepcion": "",

    "cantidad_entregada": "",

    "pendiente_a_facturar": "",

    "saldo_pendiente": "",

    "estado": "Disponible, Facturado o Anulada según corresponda",

    "centro_de_costos": "",

    "condicion_de_pago": "Anticipo, Contado, 30 días, 60 días, 90 días",

    "fecha_de_actualizacion": "",

    "identificador": ""

}

*El anterior JSON es de referencia y es funcional. Para conocer todos los campos disponibles para carga en las aplicaciones, consultar el endpoint  indicado en el anexo 1 de este documento.

6. Actualizar Orden de Compra general

A continuación se detallan, a modo de ejemplo, los datos requeridos para la actualización de datos en la aplicación Orden de Compra general: 

• Endpoint: PUT/metadata/{idapp}/{iddoc}
• Parámetros:

• idapp: 2877
• 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 enpoint de búsqueda indicado en el punto 2 de los anexos del siguiente apartado.

Anexos

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

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

_____________________________________________________________________________________________________________________

Configuración en Calipso

Descargar documentos 

A) Función

fSincronizarComprobNosConecta

Uso de la función

Esta función se utiliza para la descarga de los comprobantes disponibles para el ERP:

Argumentos 

1. CUENTAECOMERCE: se debe enviar la cuenta de ecommerce que contiene los datos de conexión.
2. CODIGOCONFIGURACION: string: indica el código de configuración auxiliar en el que se encuentran los datos del endpoint de consulta. El campo url debe contener la url con todos los datos para realizar el get. 
3. CODIGOMARCARDOCUMENTO: string: debe indicar el código de la configuración auxiliar donde se indiquen los valores del endPoint:

• Código Externo: Id de aplicación de Nos Conecta. 
• URL Externa: se indica el endPoint a ejecutar donde el “{iddoc}” es comodín que la función reemplazará por el Identificador del comprobante de Nos Conecta. Ejemplo “/workflows/262/transition/{iddoc}” 

4. CODIGOLINKVISOR: string: se indica el código del configurador auxiliar con la configuración del endpoint para generar el link de visualización:

• Código Externo: se indica el ID de aplicación de Nos Conecta. 
• Url Externa:  se indica la url del endPoint donde el comodín “{token}” será el valor a reemplazar en la url según el valor del comprobante. Ejemplo: “/v/visor_documentos?hash={token}&mostrar=0&wf=1”, la url final será guardado en “trextension.firmafiscal”, pudiendo ser recuperado por la función javascript “JSGetVisorNosConecta”

B) Tipos de transacciones

Debe tener configurado “Tipos de transacciones”, para saber el tipo de transacciones a crear en Calipso:

1. Código: código del tipo de documento en Nos Conecta. 

2. Descripción: informativo. 

3. Tipo de Transacción: el tipo de transacción (OTE) que se va a crear para el tipo de comprobante que se especifique en el código. 

4. Unidad Operativa: se indicará la unidad operativa donde se creará la transacción.

5. Datos adicionales: no se usa en esta interfaz.

Ejemplo de llamado a la función y configuración 

call fSincronizarComprobNosConecta( oCuenta, "01", "02", "03")

Ejemplo de configuración de tipos de transacciones

Importante: Deben configurarse todos los tipos de transacciones que se utilicen. 

____________________________________

#CorporateERP #NosConecta