Cómo usar APIs en Finnegans

AcademiaFinnegans
Mon, 07 Oct 2024 19:39:35 +0000
CORE

Conocimientos básicos

¿Qué es una API?

Una API (Application Programming Interface) es el mecanismo más útil para conectar dos softwares entre sí para el intercambio de mensajes o datos en un formato estándar.

Son valiosas, ante todo, porque permiten hacer uso de funciones ya existentes en otro software, reutilizando así código que se sabe que está probado y que funciona correctamente.

¿Qué es un JSON?

Un JSON (JavaScript Object Notation)es un formato de texto para el intercambio de datos.

El principio básico es con pares atributo-valor, éstos deben estar encerrados entre llaves { , } que es lo que definen el inicio y el fin del objeto.

La simplicidad de JSON ha dado lugar a la generalización de su uso, especialmente como alternativa a XML.

Cómo se crean APIs de usuario

Para adaptar una API estándar a los requerimientos de cada organización, existen las APIs de usuario. Cada uno puede realizar las modificaciones que sean necesarias teniendo en cuenta que un mal uso de las mismas, puede generar inconsistencia de datos en la empresa.

Para diferenciar las APIs estándar de las de usuario, recomendamos utilizar el prefijo USR delante del código.

Entidad

Como ejemplo, te mostramos cómo se configura una API de maestro.

En el diccionario de APIs (App Builder → Diccionarios → Diccionario de APIs) presioná el botón Nuevo.

Completás los campos con los datos correspondientes a la API que estás creando.

Tené en cuenta que el campo Nombre api no admite espacios.

En el campo Tipo seleccionás Entidad.

Indicás qué métodos soporta, tildando cada uno de ellos.

En el campo Diccionario, tenés que seleccionar el diccionario de datos del maestro o de la transacción.

Una vez completos los campos en la solapa general, guardás la API.

Luego, en la solapa Definición se muestran todos los campos que componen el maestro o transacción indicada en el campo Diccionario.

En esta solapa podés agregar o quitar campos, completar una descripción para que el JSON ejemplo detalle cómo completar el campo, por ejemplo:

En alias, podés indicar cómo se llama el campo que vas a completar, por ejemplo (se muestra como ejemplo un campo de la API de transportes)

Luego de guardar, al presionar el botón se muestra:

Una vez creada la API, vas a encontrar la URL y un JSON ejemplo en la documentación.

Si tenés que agregar algún campo o modificar una API estándar, se recomienda duplicarla y realizar los cambios en la nueva.

En caso de cometer algún error u omitir algún campo necesario, existe la opción de regenerar el xml por medio del botón .

Viewer

Para crear una API de este tipo, en el campo tipo tenés que seleccionar la opción Viewer. Esto habilita el campo Viewer y oculta los campos Diccionario (ya que no se usa ningún diccionario) y la posibilidad de indicar los métodos que soporta (ya que sólo soporta el GET)./8*8

Al presionar el botón se muestran los parámetros del informe.

¿Cómo acceder a la documentación de una API?

Para acceder a la documentación que te brindamos desde Finnegans, tenés que ingresar desde el menú App Builder → Diccionario de APIs y una vez ahí, presionar el botón Documentación ubicado en la barra de herramientas.

Al querer abrir la Documentación, es posible que el navegador requiera que permitas las ventanas emergentes.

Tené en cuenta que cada base tiene su propia documentación.

Dentro de la documentación vas a encontrar las url de las diferentes APIs, JSON de ejemplo de cada una y los distintos métodos para enviar (Read, Post, Put, Delete, List).

Te mostramos cómo tenés que enviar el JSON y qué esperar como respuesta.

Credenciales de usuario

Para utilizar las APIs, es necesario identificar el usuario y la base. Esto se informa mediante un Token de acceso.

Para identificar el usuario, existen las credenciales. Para obtenerlas, ingresá al maestro de Usuarios, buscá tu usuario y presioná el botón .

Al realizarlo por primera vez, los campos se van a mostrar vacíos. Al presionar el botón Generar keys, se completan los campos Client id y secret key.

Estos datos, vas a utilizarlos luego para la obtención del token.

Podés regenerar las credenciales si presionás nuevamente el botón Generar keys.

Token de autenticación

El Token es un código alfanumérico que sirve de autenticación en el momento de realizar una solicitud a las APIs. Se usa para reforzar la seguridad de las transacciones y por lo tanto es obligatorio. Se genera de forma aleatoria, es irrepetible y tiene una vigencia definida.

Para obtenerlo, ingresá a la documentación. En la solapa OAuth 2.0, tenés la obtención y la revalidación del Token.

Al presionar el botón GET se muestra la URL y un ejemplo de respuesta.

Postman

Hay una gran variedad de aplicaciones para la prueba de APIs, nosotros te recomendamos Postman ya que tiene una interfaz amigable y es bastante intuitivo.

Podés descargarla desde Download Postman | Get Started for Free

Ya en la aplicación, copiá la URL que te mostramos anteriormente en la Documentación:

Y reemplazá los campos que te indicamos en azul con las credenciales obtenidas previamente en el usuario.

El Postman te permite indicar las credenciales de usuario en los campos que señalamos en la imagen, para evitar errores al modificar la URL.

Luego presioná SEND y vas a obtener el Token.

El Token obtenido lo vas a utilizar para utilizar las distintas APIs. Tené en cuenta el token tiene vencimiento. Para refrescarlo, podés presionar nuevamente SEND y el Postman te devuelve uno nuevo.

También podés refrescarlo si utilizás la URL de revalidación. En este caso, además de las credenciales de usuario, tenés que indicar también el Token anterior.

Todas las llamadas a las APIs deben hacerse a: https://api.teamplace.finneg.com/api/ más alla de que esté disponible la posibilidad de hacerlo a cada servidor.

Tipos de APIs

En la documentación del sistema, en la solapa APIs vas a encontrar todas las APIs disponibles, tanto las estándar como las de usuario. Podés utilizar el buscador para encontrar más rápido la que buscás.

APIs Estándar

Son las APIs que te brindamos desde Finnegans. Estamos continuamente trabajando para incluir nuevas.

Estas APIs se actualizan siempre que se instala un Hotfix, por lo que cualquier particularización que se realice, se perderá.

A continuación te mostramos un ejemplo de cada tipo de API y los diferentes métodos posibles.

Entidad

Hay dos tipos, transacciones y maestros.

Te mostramos como ejemplo un Pedido de Venta. Buscamos el ejemplo en la documentación.

En la documentación vas a encontrar, para todas las APIs, las distintas opciones que podés realizar.

Además, vas a disponer de la URL, un ejemplo de JSON a enviar y la respuesta de cada caso.

Read → Método GET

Para este método, sólo tenés que enviar el código de identificación de la transacción que querés consultar.

Nuevamente reemplazas los campos que te indicamos en azul, en este caso con el código (identificación) de la transacción que queres leer y el Token obtenido.

Código de identificación

El campo de identificación es obligatorio para poder identificar unívocamente cada registro.

Maestros: Para el caso de los maestros, la identificación resulta sencilla, ya que se diferencian por el campo código.

Transacciones: En el caso de las transacciones, el código no existe. Para poder identificar las transacciones y referir a cada una de las operaciones que se cargan a partir de una API, existe el campo Identificación externa. En este campo podés indicar la numeración correspondiente al sistema externo.

Al presionar SEND, se muestran los datos del pedido como respuesta.

Insert → Método POST

Por medio de este método podés insertar transacciones y maestros en el sistema.

Como siempre, en la documentación encontrás la URL y un ejemplo de JSON y en este caso la respuesta informa si se creó correctamente o si hubo algún error.

Para evitar crear el JSON, podés hacer un GET primero, para obtener de esta forma el JSON y luego para el POST simplemente reemplazas los datos por los de la nueva transacción.

En este caso, para enviarlo con la aplicación Postman, hay que seguir una serie de pasos que te detallamos a continuación.

￼En el JSON que se muestra de ejemplo, tenés toda la información que necesitas para completar los campos.

Es fundamental completar los campos que son obligatorios.

Nuevamente reemplazas el Token y al presionar SEND vas a obtener la respuesta.

Update → Método PUT

Con este método podés actualizar una transacción o maestro cargado previamente.

En este caso, es necesario que envíes en la URL el código de la transacción o maestro que vas a actualizar.

Para este método también tenés que seguir los pasos del POST, pero seleccionando la opción PUT.

Delete → Método DELETE

Este método es similar al GET.

Reemplazás el código por la identificación de la transacción o maestro que querés eliminar, seleccionás la opción DELETE y al presionar SEND, obtenés la respuesta.

List → Método GET

Este método sólo está disponible para maestros.

Por medio de este método podés listar todos los registros de determinado maestro.

Te mostramos como ejemplo el maestro de monedas.

En este caso, tenés que indicar desde qué fecha querés que te muestre los registros de ese maestro.

Recordá indicar la fecha con el mismo formato que se indica: yyyy-mm-dd.

Reemplazás nuevamente el Token y en este caso, como respuesta obtenés un listado de todas las monedas cargadas en la base.

Viewer

Este tipo de APIs se utiliza para informes, por lo que sólo se puede obtener información a por medio del método GET.

En la URL podés ingresar de los parámetros que sean necesarios para poder filtrar la información y la cantidad de registros.

Mostramos como ejemplo, el informe análisis de facturación.

Como se observa en la imagen, la URL contiene todos los parámetros para que puedas filtrar bien la información a mostrar.

Podés solamente reemplazar el Token sin incluir ningún parámetro, incluir todos o bien, incluir algunos.

La aplicación Postman te permite, desde la pestaña Params seleccionar qué parámetros incluir y cuáles no por medio de las casillas de selección.

Si utilizás otra aplicación, recordá que si no vas a utilizar algún parámetro, es necesario borrar la parte que indicamos en azul.

Como respuesta obtenemos todas las facturas de venta realizadas dentro del rango de fechas indicado en los parámetros.

Errores frecuentes

Token Invalido

Es posible que el Token que estabas usando, de pronto deje de funcionar. Esto es porque el Token tiene una corta vigencia, por lo que luego de unos minutos, tenés que refrescarlo.

Errores de configuración

Errores de este tipo pueden ser muchos. Te mostramos algunos ejemplos y te comentamos el por qué y cómo solucionarlos:

1. “Falta especificar la organización”

2. “Los conceptos calculados de la operación no coinciden con la definición."

3. “El valor del atributo FechaBaseVencimiento (FechaBaseVencimiento) es null y la entidad lo define como requerido.”

4. “No se encontró la Secondary Key asociada, con los valores: Tabla: BSProducto, campoPK: ProductoID, campoSk: Codigo, valorSk: xxxx.”

5. “No hay stock disponible a la fecha yyyy-mm-dd para el producto xxx”

6. “Debe especificar el precio para el producto XXXXXX”

7. No se está enviando en el JSON el código del Cliente/Proveedor.

8. Los conceptos calculados se configuran en el tipo de documento. Si los códigos de los conceptos calculados enviados en el JSON no coinciden con los configurados en el tipo de documento, al enviar una API, devuelve este error.

9. Este error ocurre cuando el tipo de documento tiene una configuración diferente al pensado cuando se definió la API estándar. Las APIs estándar están pensadas para una determinada configuración. En caso que la configuración sea diferente, hay que modificar la definición.

10. Se está enviando en el JSON un código de producto erróneo. Esto puede ocurrir con cualquier maestro, por ejemplo, cuentas contables.

11. Se está intentando descontar stock de un producto en un depósito en el que no hay disponible.

12. El precio en una factura, por ejemplo, es obligatorio y por tanto, debe incluirse en el JSON.

Campo empresa

Un error muy frecuente es: “El usuario xxx sólo tiene permisos de consulta sobre esta empresa.”

Esto ocurre porque en el campo “empresa” se debe indicar el código de la sucursal y no el de la empresa.

Como particulizar una API de tipo ENTIDAD

Introducción

Con el objetivo de otorgar una mayor flexibilidad y control sobre la información que se consume a través de las APIs estándar de tipo entidad, se ha implementado una nueva funcionalidad que permite particularizar la definición de la API. Esto implica que los usuarios podrán seleccionar y configurar con precisión los atributos y las subentidades adicionales que desean incluir en la respuesta de su llamada a la API.

Esta capacidad de particularización se aplica a las APIs estándar y permite optimizar el rendimiento y el tamaño de la respuesta, al obtener solo los datos estrictamente necesarios.

Detalles de la Funcionalidad

La particularización se realiza a nivel de la definición de la API de tipo entidad, permitiendo modificar los atributos que se obtienen de la entidad principal y adjuntar, si es necesario, subentidades relacionadas.

Impacto y Beneficios

1. Optimización de Respuestas: Al limitar los datos a los requeridos, se reduce el tamaño del payload de la respuesta, mejorando los tiempos de transferencia y procesamiento.

2. Flexibilidad: Permite adaptar una API estándar a necesidades específicas del negocio o de la integración.

3. Mantenimiento Sencillo: La configuración se mantiene centralizada y es visible desde la propia definición de la API.

Configuración (Paso a Paso)

La configuración de los atributos y subentidades adicionales se realiza desde la interfaz de administración de la API de tipo entidad, en el área de Definición.

1. Acceso a la Configuración Adicional:

Acceda a la definición de la API de tipo entidad que desea particularizar.

En la barra de herramientas superior, localice y haga clic en el icono de engranaje ( )

2. Ventana de Configuración Adicional:

Al seleccionar el icono, se abrirá la ventana modal de Configuración con la sección Adicionales activa.

3. Definición del XML Adicional:

Dentro de esta ventana, se debe configurar un fragmento de código XML que contendrá la definición de los elementos a adicionar o particularizar.

Para Atributos Adicionales: Si desea incluir un atributo de la entidad que no está en la definición estándar, o un atributo personalizado, debe definirlo dentro de la etiqueta principal.

<entidad id="main"> <atributo nombre="USR_noelia1" alias="USR_noelia1" descripcion="test" requerido="False"/> </entidad>

(Se añade el atributo USR_noelia1 a la respuesta del main)

Para Subentidades Adicionales: Defina la subentidad como un elemento anidado dentro de la etiqueta principal.

Ejemplo de Subentidad Adicional: Para adjuntar una subentidad relacionada, debe definirse la relación en la entidad principal (main) y luego definir los atributos que se desean obtener de esa subentidad en un bloque de entidad aparte.

Ejemplo:

<?xml version="1.0" encoding="UTF-8"?>

<root>

    <entidad id="main">

        <atributo nombre="USR_Noe_SEA" alias="USR_Noe_SEA" descripcion="SubEntidad Adicional" requerido="false"/>

    </entidad>




    <entidad id="USR_Noe_SEA">

        <atributo nombre="USR_ClaForaneaAEntMadre" alias="USR_ClaForaneaAEntMadre" descripcion="" requerido="false"/>

        <atributo nombre="USR_CampoCodigo" alias="USR_CampoCodigo" descripcion="" requerido="false"/>

        <atributo nombre="USR_CampoNombre" alias="USR_CampoNombre" descripcion="" requerido="false"/>

    </entidad>

</root>

4. Guardar Configuración:

Una vez definida la estructura XML, guarde la configuración. Esta definición adicional se consolidará con la definición estándar de la API.

Consideraciones Clave (Impacto)

Es fundamental comprender cómo interactúan las dos secciones de configuración: la estándar y la adicional.

1. Configuración Base de la API Estándar:

Las APIs estándar (sin particularizar) mantendrán siempre la configuración definida originalmente en la sección “Estándar” (visible en la pestaña Definición de la entidad). Su objetivo es proporcionar una respuesta base consistente para la entidad.

2. Uso de Atributos y Subentidades Adicionales:

APIs Sin Particularizar: Cuando no se realiza ninguna configuración manual en la sección de adicionales, la API opera bajo su comportamiento estándar.

APIs Particularizadas: Para que la API considere atributos y subentidades específicos a una necesidad particular, deben ser configurados explícitamente en la sección Atributos Adicionales (mediante el icono del engranaje).

La configuración ingresada en la sección “Adicionales” actúa como un complemento a la configuración “Estándar”, permitiendo al usuario personalizar la estructura de la respuesta para una integración o consumo específico.