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.
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:
-
“Falta especificar la organización”
-
“Los conceptos calculados de la operación no coinciden con la definición."
-
“El valor del atributo FechaBaseVencimiento (FechaBaseVencimiento) es null y la entidad lo define como requerido.”
-
“No se encontró la Secondary Key asociada, con los valores: Tabla: BSProducto, campoPK: ProductoID, campoSk: Codigo, valorSk: xxxx.”
-
“No hay stock disponible a la fecha yyyy-mm-dd para el producto xxx”
-
“Debe especificar el precio para el producto XXXXXX”
-
No se está enviando en el JSON el código del Cliente/Proveedor.
-
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.
-
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.
-
Se está enviando en el JSON un código de producto erróneo. Esto puede ocurrir con cualquier maestro, por ejemplo, cuentas contables.
-
Se está intentando descontar stock de un producto en un depósito en el que no hay disponible.
-
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.