> ## 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 Finance & Operations

> Guía de integración y requisitos técnicos para conectar Dynamics 365 F&O con Payana a través de OData

Esta guía detalla los requisitos y pasos necesarios para conectar tu instancia de **Dynamics 365 Finance & Operations** con Payana a través de la API **OData**.

La integración requiere configurar una identidad de aplicación en Microsoft Entra ID (Azure AD) y asignarle los permisos adecuados dentro de Dynamics 365 F\&O.

## 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 Dynamics. |
| **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 App y secretos).
    * Permiso de **Key Vault Contributor** (para configurar el almacenamiento seguro de webhooks).

    **2. Dynamics 365 F\&O**

    * Usuario con el rol **System Administrator** en el entorno **Sandbox** (y eventualmente en Producción para el despliegue final).

    **3. Power Platform Admin Center**

    * Permiso para crear el **Usuario de Aplicación** y asignar la Unidad de Negocio correspondiente.
  </Accordion>

  <Accordion title="Información de Entorno">
    * URL de la instancia de Dynamics 365 F\&O.
    * Nombres técnicos de las **Entidades Legales (DataAreaId)** donde se operará.
  </Accordion>

  <Accordion title="Mantenimiento Previo Requerido">
    Antes de iniciar, ejecuta el proceso **"Refresh entity list"** en el espacio de trabajo de **Gestión de Datos** para asegurar la visibilidad de todas las entidades, especialmente las localizadas para LATAM.
  </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

El sistema externo requiere una identidad digital para autenticarse de forma segura.

<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:** `Single tenant`
  </Step>

  <Step title="Copiar los identificadores">
    Una vez creada la aplicación, copia y guarda:

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

  <Step title="Crear el secreto de cliente">
    Ve a **Certificates & secrets** > **New Client Secret** y crea un secreto.

    <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** > **Dynamics ERP** y selecciona los siguientes permisos de aplicación:

    * `Odata.FullAccess`
    * `CustomService.FullAccess`
    * `AX.Full.Access`

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

### Paso 2: Creación del Usuario de Aplicación en Power Platform

Este paso es obligatorio para que la integración no consuma licencias de usuario físico y sea compatible con las políticas de Microsoft.

<Steps>
  <Step title="Acceder al Power Platform Admin Center">
    Ingresa al [Power Platform Admin Center](https://admin.powerplatform.microsoft.com/).
  </Step>

  <Step title="Seleccionar el entorno">
    Selecciona la instancia de Dynamics 365 F\&O que deseas integrar.
  </Step>

  <Step title="Crear el usuario de aplicación">
    Ve a **Settings** > **Users + permissions** > **Application users** y haz clic en **+ New app user**.

    * **App:** Selecciona la aplicación `Integracion_Payana` registrada en el Paso 1.
    * **Business Unit:** Selecciona la unidad de negocio raíz.
    * **Security Roles:** Asigna un rol temporal (se ajustará con permisos granulares en el Paso 4).
  </Step>
</Steps>

### Paso 3: Vinculación de Identidad en Dynamics 365 F\&O

Este proceso mapea la identidad de Azure con el contexto de seguridad interno del ERP.

<Steps>
  <Step title="Acceder a la configuración de aplicaciones">
    En Dynamics 365 F\&O, ve a **Administración del sistema > Configuración > Aplicaciones de Microsoft Entra ID**.
  </Step>

  <Step title="Registrar la aplicación">
    Haz clic en **Nuevo** e ingresa:

    * **ID de cliente:** El Application ID obtenido en el Paso 1.
    * **Nombre:** `Integración Payana`
    * **ID de usuario:** Selecciona un ID de usuario interno dedicado.

    <Note>
      Se recomienda crear un usuario interno llamado `PayanaSvc` para facilitar la auditoría y traza de transacciones.
    </Note>
  </Step>
</Steps>

### Paso 4: Configuración de Roles y Permisos

Crea un **Rol de Seguridad Personalizado** (ej. `PayanaIntegrationRole`) y asigna los privilegios necesarios.

<Warning>
  Asegúrate de que la propiedad **Integration Mode** de los privilegios esté configurada en **"All"** o **"Data Services"** para permitir el acceso tanto por API síncrona como masiva.
</Warning>

#### 4.1 Creación del Privilegio de Seguridad

<Steps>
  <Step title="Acceder a la configuración de seguridad">
    Ve a **System administration > Security > Security configuration**.
  </Step>

  <Step title="Crear el privilegio">
    En la pestaña **Privileges**, selecciona **Create new** y nómbralo (ej. `Integracion_Payana`).
  </Step>

  <Step title="Añadir las entidades de datos">
    Selecciona el nuevo privilegio y busca el nodo **Permissions > Data Entities** en el panel lateral. Añade las entidades listadas en la tabla de la siguiente sección.
  </Step>

  <Step title="Configurar el modo de integración">
    Para cada entidad añadida, establece la propiedad **Integration Mode** en **Data Services** (o **All**).
  </Step>

  <Step title="Establecer niveles de acceso">
    Configura el **Access Level** según se indica en la tabla (Read para consultas, Create para registros).
  </Step>
</Steps>

#### 4.2 Lista de Entidades Requeridas

| Concepto Funcional                           | Nombre OData (Colección)                          | Nivel de Acceso |
| :------------------------------------------- | :------------------------------------------------ | :-------------- |
| Maestros de Proveedores                      | `VendorsV3` (o `VendorV2`)                        | Read            |
| Maestros de Productos                        | `ProductsV2`, `ProcurementProductCategories`      | Read            |
| Cabeceras de Orden de Compra                 | `PurchaseOrderHeadersV2`                          | Read            |
| Líneas de Orden de Compra                    | `PurchaseOrderLinesV2`                            | Read            |
| Recepciones de Producto (Header)             | `ProductReceiptHeaders`                           | Read            |
| Recepciones de Producto (Lines)              | `ProductReceiptLines`                             | Read            |
| Cuentas Contables (Plan de Cuentas)          | `MainAccounts`                                    | Read            |
| Facturas Pendientes (Header)                 | `VendorInvoiceHeaders`                            | Read / Create   |
| Facturas Pendientes (Lines)                  | `VendorInvoiceLines`                              | Read / Create   |
| Diarios de Factura Directa (Header)          | `VendInvoiceJournalHeaders`                       | Read / Create   |
| Diarios de Factura Directa (Lines)           | `VendInvoiceJournalLines`                         | Read / Create   |
| Diarios de Pagos (Header)                    | `VendorPaymentJournalHeaders`                     | Read / Create   |
| Diarios de Pagos (Lines)                     | `VendorPaymentJournalLines`                       | Read / Create   |
| Asociación de Pago a Factura                 | `VendorPaymentJournalLineSettledInvoices`         | Read / Create   |
| Facturas/Pagos Registrados                   | `VendTransBiEntities`                             | Read            |
| Asociación de Pagos a Facturas (Registrados) | `VendSettlementBiEntities`                        | Read            |
| Métodos y Términos de Pago                   | `VendorPaymentMethods`, `PaymentTerms`            | Read            |
| Cuentas Bancarias (Pagos)                    | `BankAccounts`, `BankTransactionTypes`            | Read            |
| Diarios                                      | `LedgerJournalNames`                              | Read            |
| Divisas                                      | `Currencies`                                      | Read            |
| Dimensiones Financieras                      | `FinancialDimensionValues`                        | Read            |
| Almacenes e Inventario                       | `Warehouses`, `OperationalSitesV2`                | Read            |
| Gestión de Proyectos                         | `ProjectsV2`                                      | Read            |
| Impuestos                                    | `TaxCodes`, `TaxItemGroups`, `TaxGroups`          | Read            |
| Retenciones en la Fuente                     | `WithholdingTaxCodes`, `WithholdingTaxCodeValues` | Read            |

#### 4.3 Publicar los Cambios

<Warning>
  Tras configurar el privilegio y asignarlo al rol de la aplicación, **debes** ir a la pestaña **Unpublished Objects** y pulsar **Publish all**. De lo contrario, los nuevos permisos no surtirán efecto en la API.
</Warning>

***

## 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-...`                         |
| **resource**       | URL base de tu entorno F\&O (sin "/" al final) | `https://tuempresa.operations.dynamics.com` |

<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 de API correctos (Paso 1).
* Has creado el **Usuario de Aplicación** en Power Platform Admin Center (Paso 2).
* Has vinculado la **identidad de la aplicación** en Dynamics 365 F\&O (Paso 3).
* Has creado y publicado el **Privilegio de Seguridad** con las entidades requeridas (Paso 4).
* Tienes las 4 credenciales necesarias: `client_id`, `client_secret`, `tenant_id` y `resource`.