Entender la API de Business Central y no morir en el intento (Parte I)

por | 22 julio, 2020

Como muchos tendréis leído, está a disposición de los programadores una API para poder integrar los datos de nuestro Business Central con otras aplicaciones. Esto es algo que todo el mundo sabe pero a veces no se llega a entender del todo su funcionamiento, sobre todo, cuando entramos en las variantes de los entornos SaaS y On-Premises.

Pues bien, he decidido crear una serie de entradas en este blog en las cuales trataré de explicar las diferencias entre consultar la API en diferentes entornos y además las distintas formas de autenticación que hay para ello. Quizás, la parte más fácil sea la On-Premise dado a que la consulta al dato es algo que venimos heredando de otras versiones más antiguas (conexiones OData) pero si es cierto que es en el SaaS donde se añaden factores como la consulta de la API en Microsoft Graph o las distintas formas de autenticarse (AAD y Basic Auth).

Con las consultas a través de la API , aparte de obtener y modificar datos podremos hacer uso de diversos namespaces para la gestión y administración tanto de los entornos como de las empresas. Así como poder automatizar una carga de paquetes de Rapid a la hora de crear una nueva empresa (por ejemplo), esto lo veremos más adelante 🙂

Pues bien, manos a la obra… El primer paso que tenemos que conocer (y creo que fundamental 🙂 ) es saber donde se configura la activación de los servicios de la API. Este proceso (como imaginaréis) es diferente en un entorno On-Premise que un Online.

Configuración

Para On-Premise:

  • Abrir la consola de administración de Business Central
  • Desplegar la pestaña de OData Services y marcar el check «Enable OData Services» y a continuación marcar «Enable API Services».
  • Comprobar que la URL del campo OData Base URL y el puerto son correctos (recordar habilitar las reglas en el firewall(s) para el puerto configurado)
  • Abrir Business Central con un usuario con permisos y buscar «Configuración de API»
  • En este apartado, deberemos de seleccionar la acción «Integrar las APIS» para publicar todas las tablas de integración de las diferentes APIS publicadas. Ten en cuenta que este proceso puede durar varios minutos.

Para la versión SaaS no tendremos que activarla ya que el servicio viene activado por defecto, sea el entorno de producción como un sandbox para pruebas.

Métodos de conexión

Para conectarnos a la API de Business Central tenemos que tener en cuenta un par de factores: Tipo de despliegue (On-Premise o SaaS) y que dentro del SaaS hay que tener en cuenta el tipo de entorno (Producción o Sandbox)

Para los entornos On-Premise la autenticación tendrá que ser «Basic«, conectándonos a través de un usuario y su Web Service Access Key como contraseña. Para esto deberemos tener en cuenta que el servicio de BC (Server Instance) tendrá que esta configurado como NavUserPassword o AccessControlService en el apartado de autentificación para los usuarios.

Para entornos SaaS tendremos las siguientes opciones:

  • Producción
    • Microsoft Graph (Autentificación por Azure Active Directory)
    • Common endpoint service (Autentificación por AAD)
  • Sandbox
    • Conexión directa (Basic: Username y Web Service Access Key)

Como veis para acceder a producción la buena práctica es autenticarse a través del Azure Active Directory de nuestro tenant.

Endpoints de conexión

Como vimos antes, según el tipo de entorno los endpoints de conexión para la API se construyen de diferente forma.

SaaS Producción

  • Microsoft Graph
    • https://graph.microsoft.com/beta/financials/
  • Common endpoint service
    • En el caso de tener más de un entorno debemos usar la v2.0 de la API y especificar en endpoint el nombre del entorno al cual queremos acceder:
      https://api.businesscentral.dynamics.com/v2.0/<ENTORNO>/api/v1.0
    • Si sólo tenemos un entorno, podemos acceder a el directamente por la v1.0 de la API ya que en este caso no es necesario indicar el nombre del entorno.
      https://api.businesscentral.dynamics.com/v1.0/api/v1.0

SaaS Sandbox (desarrollo y pruebas)

En este caso recordemos que las peticiones se hacen de forma directa al tenant y usando Basic Authentification. Para ello, tenemos los siguientes endpoints:

  • Múltiples entornos (v2.0)
    https://api.businesscentral.dynamics.com/v2.0/<TENANT>/<ENTORNO>/api/v1.0
  • Sin múltiples entornos (v1.0)
    https://api.businesscentral.dynamics.com/v1.0/<TENANT>/api/v1.0

On-Premise

Para On-Premise sólo tendremos una forma de acceder y es haciendo la consulta a través del protocolo de los servicios web de OData.

https://<URL Base>:<Puerto>/<Instancia>/api/<API Version/
Ejemplo: https://localhost:7048/bc/api/v1.0

Para las APIS personalizadas que tengamos en nuestras extensiones:
https://<URL base>:<Puerto>/<Instancia>/api/<API publisher>/<API group>/<API version>

Basic Authentification

Tenemos claro que, tanto para SaaS (recomendados sandbox de desarrollo o pruebas) y para entornos On-Premise el método de autentificación con la API es a través de la autentificación básica. Para ello, al usuario con el que decidamos conectar deberemos de generar su Web Service Access Key. Para configurar este valor, nos basta con dirigirnos a la lista de Usuario y en las acciones seleccionamos Cambiar clave de servicio web.

Esto nos preguntará cuando deseamos que expire (en el caso de no expirar marcar el check) y al aceptar nos generará un valor en el campo correspondiente. Es esta clave junto con el nombre de usuario lo que vamos a necesitar para autentificarnos en la API 🙂

Consultando la API en Business Central On-Premise

Pues bien, tenemos endpoint y tenemos credenciales, ya tenemos todo para poder conectarnos a la API de nuestra instalación On-Premise. Para ello, deberemos de componer nuestro endpoint como vimos anteriormente y hacer un GET autenticando con el usuario y clave de servicio.

https://<URL Base>:<Puerto>/<Instancia>/api/<API Version/

La autentificación en Postman la configuramos en la pestaña de «Authorization«. Ahí seleccionamos Basic Auth e indicamos el usuario y la clave de servicio que generamos anteriormente.

De cara a la implementación de la autentificación básica en otro entorno que no sea Postman, deberemos de tener en cuenta que lo que ahí configuramos en una pestaña de forma amigable al final se transforma en una cabecera que se enviará en la petición. Esta cabecera se compone de la siguiente forma:

Authorization: Basic <credentials>

Siendo <credentials> el nombre de usuario y la clave de servicio web separado por : y todo eso codificado en Base64

Tras realizar el GET a la URL anterior obtenemos la lista de las API estándar que ofrece Business Central.

Aquí os dejo el enlace donde podeis consultar el listado de todas las APIS estándar así como los métodos que tienen cada una API(v1.0) for Dynamics 365 Business Central En esta página de Microsoft docs, en el menú de la izquierda se pueden consultar la lista y ejemplos de como se debe llamar para obtener, crear y modificar registros en las diferentes APIS. Así como información adicional que tienen las pages del estándar.

En el ejemplo anterior, vemos que uno de las APIS se la de companies. Haciendo un GET al endpoint https://<URL Base>:<Puerto>/<Instancia>/api/<API Version/companies nos devolverá un listado con todas las empresas que tengamos en esa base de datos.

Este es un dato clave que vamos a necesitar para realizar consultas a otras apis, como por ejemplo Customers, ya que en el endpoint deberemos de indicar a que empresa estamos consultando.

En la documentación indica que el endpoint para consultar la API de customers tiene el formato
GET businesscentralPrefix/companies({id})/customers({id})

Como ya tenemos los id de las empresas, bastará con hacer un GET a ese endpoint para obtener la lista de todos los clientes. En el caso de necesitar consultar los detalles de un cliente específico, con el id de la consulta podremos hacer un GET a ese registro individual.
GET endpoint/companies({id})/customers({id})

Recordad que para las consultas de la API también podemos hacer uso de filtros en la URL a la cual hacemos la petición.
Por ejemplo, si queremos sólo clientes que en su displayName contengan el valor «GDE» lo podremos hacer con la siguiente URL
http://host:7048/BC160_CU3/api/v1.0/companies(6d24fd10-5fb7-ea11-bb3d-001dd8b76905)/customers?$filter=displayName eq '*GDE*'

Hasta aquí la primera parte, en los próximos días veremos como consultar APIS personalizadas y como realizar las consultas en sandbox SaaS con uno y varios entornos

Que la fuerza os acompañe 🙂

2 pensamientos en “Entender la API de Business Central y no morir en el intento (Parte I)

  1. Pingback: Entender la API de Business Central y no morir en el intento (Parte II) | Dynamics 365 Business Central

  2. Pingback: Entender la API de Business Central y no morir en el intento (Parte II) - Microsoft Dynamics NAV Community

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *