Es mas que probable que si estas trabajando en expansiones de Business Central o en integraciones donde BC esté involucrado, en algún momento tengas que compartir o insertar datos desde un punto externo. Para ello, tenemos el objeto Page del tipo API, que nos permite exponer una API para consumir o insertar datos. Vamos a ver como consumir esta API.
Exponer los datos
Lo primero que tenemos que hacer es identificar la entidad de Business Central sobre la que queremos actuar y a partir de ahí crear una nueva API Page. No vamos a entrar en como crearla (si es necesario, haré otra entrada distinta para eso), pero si veremos un ejemplo de como quedaría la api page, ya que nos servirá para mas adelante ver como componer la URL del end-point que vamos a consumir.
Esta imagen muestra un ejemplo de cabecera de una pagina tipo API:
Aquí tenemos unos campos importantes para la creación de la URL del end-point:
- APIGroup: Aquí definiremos un nombre que nos permita agrupar nuestras apis por funcionalidad. Puedes poner el nombre que quieras.
- APIPublisher: Se suele poner el nombre de la empresa.
- APIVersion: Permite versionar la API, puedes definirlo tu.
- EntityName: El nombre con el que quieres que se exponga la entidad en la url.
- EntitySetName: El nombre que has definido anteriormente pluralizado. Es el que se suele usar en la API.
Con estos valores, se va a generar una URL que seguirá el siguiente formato:
Por lo tanto, una vez publicada la extensión con nuestra API Page, una URL como la anterior se expondrá para ser consumida. Pero por supuesto, este acceso esta protegido y tendremos que autenticarnos para poder acceder.
Autenticación y autorización de la API
La forma en la que tendremos que autenticarnos contra la api de Business Central es mediante OAuth, ya que Microsoft esta deprecando el resto de accesos, como se puede apreciar en el mensaje de la siguiente imagen:
Para ello, lo primero que tenemos que hacer es acceder a nuestro portal de Azure (con permisos de administrador), y en la sección de Azure Active Directory crear una nueva aplicación.
Ponle un nombre descriptivo y luego hay que ir a la sección de Autenticación y añadir una plataforma del tipo web y poner en la URI de redirección la siguiente URL: https://businesscentral.dynamics.com/OAuthLanding.htm
El siguiente paso es crear un secreto para la APP, que usaremos mas adelante para autenticarnos. En la sección de certificados y secretos selecciona «Nuevo secreto de cliente». Pon el nombre que quieras y genera el secreto, luego guárdalo bien, por que una vez refrescada la página, este no será visible.
Finalmente, en la sección de permisos de API añadiremos el permiso para acceder a Dynamics Business Central:
Una vez tenemos creada y configurada la aplicación de Azure Active Directory, ya podemos dirigirnos a Business Central y acceder a la sección de aplicaciones de Azure Active Directory (pon el el buscador aad)
En el listado que aparece, añade una nueva aplicación, que será la que acabamos de crear.
Informa el ID de cliente de la aplicación y configura los permisos que va a tener este cliente dentro de BC. Este será el usuario con el que la API accederá a Busines Central. Si has concedido los permisos en la configuración de Azure (en la sección de permisos que hemos visto hace un momento), no hará falta que lo hagas aquí.
Ahora ya lo tenemos todo listo para acceder a la API. Yo voy a usar Postman para mostrar el funcionamiento, pero vamos, es una API, por lo que accede a ella como mejor te convenga.
Consumiendo la API de Business Central
Ya tenemos nuestra API y la identidad para conectarnos creadas y configuradas. Ahora vamos a consumirla.
Lo primero que tenemos que hacer es obtener un token, recordad que vamos a usar OAuth para autenticarnos. Para ello hacemos una llamada a la siguiente URL:
POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Donde debéis indicar el Tenant de vuestro Business Central.
Tenéis que enviar los siguientes parámetros:
- grant_type = client_credentials
- scope = https://api.businesscentral.dynamics.com/.default
- client_id = El clientId de la aplicacion creada anteriormente en Azure Active Directory.
- client_secret = el secreto que hemos guardado anteriormente en la aplicación.
Os tiene que quedar algo como esto:
El resultado de esta llamada es un token, que es el que vamos a usar para autenticarnos en nuestra API.
Ahora ya estamos preparados para llamar a la API.
Para ello, con la URL (que ya hemos visto antes como formarla), podemos hacer la llamada, tanto GET como POST (si así lo hemos permitido en la definición de la API Page):
https://api.businesscentral.dynamics.com/v2.0/{entorno}/api/{publisher}/{grupo}/{versión}/{entitySetName}?company={Id de compañia}
Le definimos la autorización de tipo «Bearer token» y ponemos el token anteriormente obtenido. Si es un POST, en el body definiremos el objeto que enviamos en formato JSON.
Y con esto ya estaríamos consumiendo datos de nuestro Business Central. Hay varias formas en las que Business Central expone sus datos. Esta es una de ellas y una de las mas «customizables». Cada una de ellas tiene sus pros y sus contras. En una próxima entrada veremos los objteos tipo query, que son parecidas, pero tienen sus matices.
¡Nos leemos!