> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payana.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamics 365 Business Central

> Guía de integración y requisitos técnicos para conectar Dynamics 365 Business Central con Payana a través de la API REST

Esta guía detalla los requisitos y pasos necesarios para conectar tu instancia de **Dynamics 365 Business Central** con Payana a través de la **API REST de Business Central**.

La integración requiere configurar una identidad de aplicación en Microsoft Entra ID (Azure AD) y registrarla dentro de Business Central para otorgarle los permisos adecuados.

## Opciones de Configuración

Existen dos formas de configurar la integración:

| Opción                                     | Descripción                                                                                                                                 |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| **Opción A: Configuración por Payana**     | El equipo técnico de Payana realiza la configuración completa. Requiere acceso temporal a tu tenant de Azure y entorno de Business Central. |
| **Opción B: Configuración por el Cliente** | Tu equipo realiza la configuración siguiendo esta guía y comparte las credenciales resultantes con Payana.                                  |

***

## Opción A: Configuración por Payana

Si prefieres que el equipo de Payana realice la configuración, necesitamos los siguientes accesos temporales:

<AccordionGroup>
  <Accordion title="Accesos Requeridos">
    **1. Microsoft Entra ID (Azure)**

    * Usuario con el rol **Application Developer** (para el registro de la aplicación y creación de secretos).

    **2. Dynamics 365 Business Central**

    * Usuario con el rol **SUPER** o **D365 BUS FULL ACCESS** en el entorno **Sandbox** (y eventualmente en Producción para el despliegue final).
    * Acceso a la página **Aplicaciones de Microsoft Entra** dentro de Business Central.
  </Accordion>

  <Accordion title="Información de Entorno">
    * Nombre del entorno de Business Central (ej. `production`, `sandbox`).
    * Nombre o ID de la **empresa (Company)** con la que se operará.
    * **Tenant ID** del directorio de Microsoft Entra ID.
  </Accordion>
</AccordionGroup>

***

## Opción B: Configuración por el Cliente

Si tu equipo realizará la configuración, sigue los pasos a continuación.

### Paso 1: Registro de la Aplicación en Microsoft Entra ID

La integración necesita una identidad de aplicación para autenticarse de forma segura sin intervención de un usuario.

<Steps>
  <Step title="Crear el registro de aplicación">
    Accede al [Portal de Azure](https://portal.azure.com) y ve a **App Registrations** > **New registration**.

    * **Nombre:** `Integracion_Payana`
    * **Tipo de cuenta:** `Accounts in this organizational directory only (Single tenant)`
  </Step>

  <Step title="Copiar los identificadores">
    Una vez creada la aplicación, en la página **Overview**, copia y guarda:

    * **Application (client) ID**
    * **Directory (tenant) ID**
  </Step>

  <Step title="Crear el secreto de cliente">
    Ve a **Certificates & secrets** > **New client secret**.

    * **Descripción:** `Payana Integration`
    * **Expiración:** Selecciona el período más largo disponible (máximo 2 años).

    <Warning>
      Copia el **Valor** del secreto inmediatamente. Microsoft lo ocultará permanentemente tras salir de la pantalla.
    </Warning>
  </Step>

  <Step title="Configurar permisos de API">
    Ve a **API permissions** > **Add a permission** > **Microsoft APIs** y selecciona **Dynamics 365 Business Central**.

    En **Application permissions**, selecciona:

    * `API.ReadWrite.All` — Acceso a APIs y servicios web
    * `Automation.ReadWrite.All` — Acceso a las APIs de automatización

    <Note>
      Usa **Application permissions** (no Delegated permissions), ya que la integración opera sin sesión de usuario.
    </Note>

    Haz clic en **"Grant admin consent for \[Nombre del Inquilino]"** para otorgar el consentimiento de administrador.
  </Step>
</Steps>

### Paso 2: Registro de la Aplicación en Business Central

Este paso vincula la identidad de Azure con Business Central y define los permisos que tendrá la integración dentro del ERP.

<Steps>
  <Step title="Acceder a la configuración de aplicaciones Entra">
    En Business Central, haz clic en el ícono de búsqueda (🔍) y escribe **"Microsoft Entra Applications"** (o **"Aplicaciones de Microsoft Entra"** en español).

    Abre la página correspondiente.
  </Step>

  <Step title="Crear la aplicación">
    Haz clic en **New** (Nuevo) para abrir la ficha de aplicación.
  </Step>

  <Step title="Ingresar el Client ID">
    En el campo **Client ID**, ingresa el **Application (client) ID** obtenido en el Paso 1.
  </Step>

  <Step title="Completar la descripción y activar">
    * **Description:** `Integración Payana`
    * **State:** `Enabled`
  </Step>

  <Step title="Asignar conjuntos de permisos">
    En la sección **User Permission Sets**, asigna los permisos necesarios para que la integración acceda a los datos requeridos.

    Consulta la sección [Permisos Requeridos](#permisos-requeridos) más abajo para la lista recomendada.

    <Warning>
      No asignes el permiso **SUPER**. Sigue el principio de mínimo privilegio y asigna únicamente los permisos que la integración necesita.
    </Warning>
  </Step>
</Steps>

### Paso 3: Publicar el Web Service

Por defecto, la API REST de Business Central no expone el detalle de saldos pendientes por factura ni los pagos aplicados a cada una. Para habilitar esta información hay que publicar un **Web Service** adicional desde la propia interfaz de Business Central — no requiere desarrollo.

<Steps>
  <Step title="Abrir la página Web Services">
    En Business Central, hacé clic en el ícono de búsqueda (🔍) y escribí **"Web Services"**. Abrí la página correspondiente.
  </Step>

  <Step title="Buscar o crear la línea de Vendor Ledger Entries">
    Muchas instancias de Business Central ya traen esta línea publicada por defecto (Object Type **Query**, caption "Vendor Ledger Entries"). Revisá si ya existe antes de crear una nueva.

    Si no existe, hacé clic en **Nuevo** y completá:

    * **Object Type:** `Query`
    * **Object ID:** usá el buscador (ícono de lupa) y escribí **"Vendor Ledger"** o **"Ledg."** para encontrarla — no ingreses el número directamente, puede variar según la versión de Business Central.
    * **Service Name:** `VendorLedgerEntries`.

    <Note>
      Es importante que el **Service Name** quede exactamente como `VendorLedgerEntries` — Payana consulta ese endpoint con ese nombre fijo. Si Business Central lo trunca o lo modifica al guardar, corregilo manualmente antes de publicar.
    </Note>
  </Step>

  <Step title="Publicar">
    Tildá la casilla **Published**. Business Central va a generar automáticamente la URL en la columna **OData V4 URL**.
  </Step>

  <Step title="Repetir para el detalle de pagos por factura">
    Repetí los mismos pasos para publicar una segunda línea:

    * **Object Type:** `Page`
    * **Object ID:** buscá por nombre **"Detailed Vendor Ledg"** o **"Ledg."** (caption: "Detailed Vendor Ledger Entries").
    * **Service Name:** `DetailedVendorLedgerEntries`.
    * Tildá **Published** y guardá.

    <Note>
      Es importante que el **Service Name** quede exactamente como `DetailedVendorLedgerEntries` — Payana consulta ese endpoint con ese nombre fijo. Si Business Central lo trunca o lo modifica al guardar, corregilo manualmente antes de publicar.
    </Note>
  </Step>

  <Step title="Verificar permisos">
    El usuario o aplicación que consuma estas URLs necesita permiso de **lectura** sobre las tablas "Vendor Ledger Entry" y "Detailed Vendor Ledg. Entry". Agregá ese permiso en el mismo permission set que le asignaste a la aplicación en el Paso 2.
  </Step>
</Steps>

<Note>
  Estos dos Web Services usan la **misma autenticación** que ya configuraste en el Paso 1 (mismo `client_id`, `client_secret` y token) — no hace falta crear una identidad ni un flujo de autenticación distinto.
</Note>

***

## Permisos Requeridos

Asigna los siguientes **Permission Sets** a la aplicación registrada en Business Central:

| Permission Set          | Descripción                                                         |
| :---------------------- | :------------------------------------------------------------------ |
| `D365 VENDOR DOCUMENTS` | Lectura y creación de facturas y documentos de proveedor            |
| `D365 BASIC`            | Acceso básico a tablas maestras (proveedores, artículos, etc.)      |
| `D365 PAYMENTS`         | Acceso a diarios de pago y liquidaciones                            |
| `D365 READ`             | Lectura de catálogos: plan de cuentas, divisas, condiciones de pago |
| `API.VENDOR`            | Acceso a los endpoints de proveedor en la API v2.0                  |

<Note>
  Si tu instancia utiliza conjuntos de permisos personalizados, trabaja con tu administrador de Business Central para verificar que cubren los endpoints de la API REST que Payana necesita consumir, además de lectura sobre "Vendor Ledger Entry" y "Detailed Vendor Ledg. Entry" (necesarios para los Web Services del Paso 3).
</Note>

#### Entidades de API Utilizadas

La integración accede a los siguientes recursos de la **Business Central API v2.0** (`/api/v2.0`):

| Concepto Funcional               | Endpoint API                    | Acceso        |
| :------------------------------- | :------------------------------ | :------------ |
| Empresas                         | `companies`                     | Read          |
| Maestros de Proveedores          | `vendors`                       | Read          |
| Artículos / Productos            | `items`                         | Read          |
| Órdenes de Compra (cabecera)     | `purchaseOrders`                | Read          |
| Líneas de Orden de Compra        | `purchaseOrderLines`            | Read          |
| Facturas de Compra Pendientes    | `purchaseInvoices`              | Read / Create |
| Líneas de Factura de Compra      | `purchaseInvoiceLines`          | Read / Create |
| Facturas de Compra Registradas   | `purchaseInvoices` (posted)     | Read          |
| Plan de Cuentas                  | `accounts`                      | Read          |
| Entradas de Libro de Proveedores | `vendorLedgerEntries`           | Read          |
| Métodos de Pago                  | `paymentMethods`                | Read          |
| Términos de Pago                 | `paymentTerms`                  | Read          |
| Cuentas Bancarias                | `bankAccounts`                  | Read          |
| Divisas                          | `currencies`                    | Read          |
| Dimensiones                      | `dimensions`, `dimensionValues` | Read          |

***

## Credenciales de Conexión

Una vez finalizada la configuración, comparte los siguientes parámetros con el equipo técnico de Payana a través de un canal seguro:

| Parámetro             | Descripción                                 | Ejemplo                  |
| :-------------------- | :------------------------------------------ | :----------------------- |
| **client\_id**        | Application ID de Azure                     | `a1b2c3d4-e5f6-...`      |
| **client\_secret**    | Valor del secreto de Azure                  | `abc123...`              |
| **tenant\_id**        | ID del directorio de Azure                  | `f1e2d3c4-b5a6-...`      |
| **environment\_name** | Nombre del entorno de Business Central      | `production` o `sandbox` |
| **company\_id**       | ID de la empresa en Business Central (GUID) | `11112222-3333-...`      |

<Note>
  El **company\_id** se puede obtener desde Business Central en **Configuración de Empresa** o a través del endpoint `GET https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environmentName}/api/v2.0/companies`.
</Note>

<Warning>
  El **client\_secret** es un valor sensible. Compártelo únicamente a través de canales seguros.
</Warning>

***

## Lista de Verificación Final

Antes de contactar al equipo de onboarding, verifica que tienes todo listo:

* Has registrado la **aplicación en Microsoft Entra ID** con los permisos `API.ReadWrite.All` y `Automation.ReadWrite.All` (Paso 1).
* Has creado y copiado el **secreto de cliente** antes de salir de la pantalla (Paso 1).
* Has registrado la **aplicación en Business Central** con el Client ID correcto y el estado en `Enabled` (Paso 2).
* Has asignado los **conjuntos de permisos** necesarios a la aplicación (Paso 2).
* Has publicado los **Web Services de Vendor Ledger Entries y Detailed Vendor Ledg. Entries** (Paso 3) y confirmado el Service Name final de cada uno.
* Tienes las 5 credenciales necesarias: `client_id`, `client_secret`, `tenant_id`, `environment_name` y `company_id`.