> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/enterprise-applications/dynamics-365-finance-and-operations.md). # Dynamics 365 Finance & Operations O conector **Dynamics 365 Finance & Operations** permite integrações com o [Microsoft Dynamics 365 Finance & Operations](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/) (F\&O), também conhecido como Finance and Supply Chain Management. Ele lê e grava as **OData data entities** públicas do app, como `CustomersV3`, `VendorsV2`, `SalesOrderHeadersV2` e `ReleasedProductsV2`. As operações suportadas incluem CRUD, query options, bound e unbound actions e functions, acesso cross-company e `$batch`. É uma especialização da integração OData genérica, usando o service root `/data`, chaves compostas `dataAreaId` e autenticação Azure AD (Azure Key). As entidades são descobertas automaticamente a partir do `$metadata` do ambiente, e o acesso cross-company é suportado. {% hint style="info" %} #### **Qual conector Dynamics devo usar?** Use o **Dynamics 365 Finance & Operations** para Finance and Supply Chain (`*.operations.dynamics.com`, entidades `/data`). Use o [**Dynamics 365**](/documentation/connectors-and-triggers/pt-br/connectors/enterprise-applications/dynamics-365.md) para Customer Engagement, Dataverse e CRM (`*.crm.dynamics.com`, `/api/data/v9.x`). Use o conector [**OData**](/documentation/connectors-and-triggers/pt-br/connectors/web-protocols/odata.md) genérico para qualquer outro serviço OData. {% endhint %} ## **Configure a autenticação (Azure AD)** O conector autentica como um **service principal** do Azure AD (OAuth 2.0 client credentials). Essa configuração é feita apenas uma vez. Veja abaixo os passos relevantes para a Digibee. Para os cliques exatos no portal, siga a documentação vinculada da Microsoft, já que a interface deles muda com o tempo. 1. **Registre um app** no Microsoft Entra ID. No Entra admin center, acesse **App registrations** e depois **New registration**. Copie o **Application (client) ID** e o **Directory (tenant) ID**. Consulte [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) para o procedimento completo. 2. **Crie um client secret.** Acesse **Certificates & secrets**, depois **Client secrets** e **New client secret**. Copie o **value** do secret imediatamente, pois ele só é exibido uma vez. Consulte [Add and manage app credentials](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials) para o procedimento completo. 3. **Conceda acesso ao app dentro do Finance & Operations.** No app F\&O, acesse **System administration**, depois **Setup** e **Microsoft Entra ID applications**. Adicione uma linha com o **Client ID** do app, um nome e um **User ID** vinculado a um usuário cuja **security role** conceda acesso às entidades que você vai usar. {% hint style="warning" %} **O passo 3 é obrigatório.** Se ele for ignorado, as requisições ainda vão **autenticar** (um token válido é emitido), mas serão **rejeitadas** com `401`/`403`, porque o service principal não está autorizado no F\&O. {% endhint %} 4. **Crie a conta Azure Key na Digibee** usando os valores dos passos 1 e 2: | Campo da conta Azure Key | Valor | | ------------------------ | --------------------------------- | | Client ID | Application (client) ID (passo 1) | | Client Secret | O **value** do secret (passo 2) | | Tenant ID | Directory (tenant) ID (passo 1) | O conector solicita o token para o scope `https://{your-env}.operations.dynamics.com/.default`. Só substitua esse valor usando **OAuth Scope** se o seu resource for diferente. Consulte [Contas](/documentation/developer-guide/pt-br/development-cycle/build-overview/accounts.md). {% hint style="info" %} Client secrets expiram. A Microsoft define um limite de 24 meses e recomenda um período menor. Renove o secret e atualize a conta Azure Key antes do vencimento, ou a descoberta de entidades e as requisições vão começar a falhar com erros de autenticação. {% endhint %} Você também vai precisar da **environment URL**, por exemplo `https://myenv.operations.dynamics.com`. ## **Conceitos** Os termos abaixo aparecem ao longo dos parâmetros do conector, por isso é importante entendê-los antes de configurar uma requisição. Cada conceito corresponde a um campo específico que você vai preencher mais adiante.
TermoSignificado
Data entityA coleção OData com a qual você está trabalhando, por exemplo CustomersV3. Caminho: /data/CustomersV3.
Composite keyAs chaves do F&O geralmente são compostas e incluem dataAreaId (a legal entity, ou empresa), por exemplo dataAreaId='usmf',CustomerAccount='US-001'.
Cross-companyPor padrão, uma query retorna apenas a empresa padrão do usuário. Ative Cross-company para abranger todas as legal entities (cross-company=true).
$metadataO F&O expõe metadados de entidades e campos em /data/$metadata. O conector usa esses metadados para viabilizar o seletor guiado de Entity Set e o editor de campos.
## **Parâmetros** A tabela abaixo lista todos os parâmetros de configuração do conector. Os parâmetros que suportam [expressões Double Braces](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md) estão marcados com ✅ na coluna **Suporta DB**. {% tabs %} {% tab title="General" %}
ParâmetroDescriçãoTipoSuporta DBPadrão
AliasUm nome para a saída deste conector, para que você possa referenciá-la depois no fluxo com Double Braces.String✅dynamics-finops-01
Fail On Client Error (4xx)Interrompe o pipeline em uma resposta 4xx.Boolean❌false
Fail On Server Error (5xx)Interrompe o pipeline em uma resposta 5xx.Boolean❌false
{% endtab %} {% tab title="Authentication" %}
ParâmetroDescriçãoTipoSuporta DBPadrãoVisível quando
Environment URLURL raiz do ambiente Finance & Operations.String✅https://myenv.operations.dynamics.com—
Use Dynamic AccountSe ativado, o conector resolve a conta em tempo de execução. Se desativado, usa a conta configurada estaticamente abaixo.Boolean❌falseUse Dynamic Account está ativado
ScopedSe ativado, isola a conta armazenada de outros subprocessos. Não disponível para contas referenciadas em headers ou no corpo da requisição. Para saber mais, leia a documentação de Dynamic Accounts.Boolean❌falseUse Dynamic Account está ativado
Account NameNome da conta definida no conector Store Account.String✅N/AUse Dynamic Account está desativado
AccountConta contendo as credenciais do Azure AD (client ID, secret e tenant). Tipo suportado: Azure Key. Saiba mais sobre Contas.Account—N/A
{% hint style="info" %} A autenticação usa o fluxo OAuth 2.0 client-credentials com o Azure AD (Microsoft Entra ID) e injeta o token resultante em um header `Bearer`. O token é armazenado em cache por combinação de client, tenant e scope. O OData v4 é usado e fixo para o Finance & Operations. {% endhint %} {% endtab %} {% tab title="Dynamics API" %} ### **Parâmetro Operation**
ParâmetroDescriçãoTipoSuporta DBPadrão
OperationA ação a ser executada. Ela define o formato da requisição. Veja as operações suportadas abaixo.Select❌Query
#### **Operações suportadas** O parâmetro **Operation** mapeia para uma requisição OData sob o service root `/data`:
OperationHTTPPathBodyObservações
BatchPOST/data/$batchmultipart/JSONAgrupa várias operações em uma única requisição.
CreatePOST/data/{EntitySet}JSONCria um registro.
Custom QueryGET/data/{EntitySet}?{$query}—Equivalente a Query. Use quando combinar parâmetros de query brutos e estruturados.
DeleteDELETE/data/{EntitySet}({key})—Exclui um registro.
Get by IDGET/data/{EntitySet}({key})—Lê um único registro pela chave.
Invoke ActionPOST/data/{EntitySet}({key})/{Action} ou /data/{Action}JSONInvoca uma bound action (com key e entity set) ou uma unbound action.
Invoke FunctionGET/data/{EntitySet}({key})/{Function} ou /data/{Function}—Invoca uma bound ou unbound function.
QueryGET/data/{EntitySet}?{$query}—Lê a coleção com query options.
UpdatePATCH/PUT/data/{EntitySet}({key})JSONAtualiza um registro, parcialmente (PATCH) ou totalmente (PUT).
### **Parâmetros comuns** Estes parâmetros se aplicam independentemente da operação escolhida. Eles são agrupados aqui por clareza, mesmo que a posição deles nas configurações do conector varie.
ParâmetroDescriçãoTipoSuporta DBPadrão
Cross-companyRetorna registros de todas as legal entities, em vez de apenas da empresa padrão (cross-company=true).Boolean❌false
Output FormatControla o formato da resposta retornada ao pipeline. Values Only desempacota e retorna apenas o array value. Full Response retorna a resposta completa, incluindo os campos @odata.*. Single Entity retorna a primeira ou única entidade.Select❌Values Only
HeadersHeaders adicionais da requisição, como pares chave/valor.Key/Value✅N/A
### **Parâmetros específicos por operação** Os parâmetros restantes aparecem apenas para determinadas operações, agrupados abaixo por finalidade. **Entity Key** — usado por **Delete**, **Get by ID**, **Invoke Action**, **Invoke Function** e **Update**.
ParâmetroDescriçãoTipoSuporta DBPadrão
Entity KeyChave simples ou composta. As chaves do F&O geralmente são compostas, por exemplo dataAreaId='usmf',CustomerAccount='US-001'.String✅N/A
**Action / Function Name** — usado por **Invoke Action** e **Invoke Function**.
ParâmetroDescriçãoTipoSuporta DBPadrão
Action / Function NameNome da action ou function OData. Bound quando um Entity Set é definido, unbound caso contrário.String✅N/A
**Body** — usado por **Batch**, **Create**, **Invoke Action** e **Update**.
ParâmetroDescriçãoTipoSuporta DBPadrão
BodyPayload JSON para Create e Update, parâmetros da action para Invoke Action, ou o payload do $batch.JSON✅{}
**Interactive Mode** — usado por **Create** e **Update**.
ParâmetroDescriçãoTipoSuporta DBPadrão
Interactive ModeSe ativado, o conector exibe os campos do payload para você editar. Caso contrário, forneça um body JSON bruto.Boolean❌false
**Query parameters** — usado por **Custom Query** e **Query**.
ParâmetroDescriçãoTipoSuporta DBPadrão
Filter ($filter)Expressão de filtro OData, por exemplo CustomerGroupId eq '10'.String✅N/A
Select ($select)Lista de campos separados por vírgula a incluir na resposta.String✅N/A
Order By ($orderby)Ordena os resultados por uma ou mais propriedades, em ordem crescente ou decrescente, por exemplo CustomerAccount asc.String✅N/A
Expand ($expand)Entidades relacionadas a incluir inline.String✅N/A
Top ($top)Número máximo de registros a retornar.Number✅N/A
Skip ($skip)Registros a pular, para paginação.Number✅N/A
Include Count ($count)Inclui a contagem total na resposta.Boolean❌false
{% endtab %} {% tab title="Advanced Settings" %}
ParâmetroDescriçãoTipoSuporta DBPadrãoVisível quando
Request Timeout (seconds)Tempo máximo para a requisição HTTP.Integer❌30
Custom Query StringParâmetros de query extras, adicionados literalmente.String✅N/A
Update MethodPATCH para uma atualização parcial, ou PUT para uma substituição completa.Select❌PATCHOperation é Update
{% endtab %} {% tab title="Documentation" %}
ParâmetroDescriçãoTipoSuporta DBPadrão
DocumentationCampo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.String❌N/A
{% endtab %} {% endtabs %} ## **Exemplos** ### **Consultar clientes em uma empresa** ``` Environment URL = https://myenv.operations.dynamics.com Entity Set = CustomersV3 Operation = Query Select = CustomerAccount,OrganizationName Filter = CustomerGroupId eq '10' Top = 2 ``` **Requisição resultante:** {% code overflow="wrap" %} ```html GET /data/CustomersV3?$select=CustomerAccount,OrganizationName&$filter=CustomerGroupId eq '10'&$top=2 ``` {% endcode %} **Saída** (quando **Output Format** está definido como `Values Only`): ```json [ { "CustomerAccount": "US-001", "OrganizationName": "Contoso Retail" }, { "CustomerAccount": "US-004", "OrganizationName": "Fabrikam" } ] ``` ### **Obter um registro pela chave composta** ``` Entity Set = CustomersV3 Operation = Get by ID Entity Key = dataAreaId='usmf',CustomerAccount='US-001' ``` **Requisição resultante:** ```html GET /data/CustomersV3(dataAreaId='usmf',CustomerAccount='US-001') ``` ### **Consultar em todas as empresas** ``` Entity Set = SalesOrderHeadersV2 Operation = Query Cross-company = true ``` **Requisição resultante:** ```html GET /data/SalesOrderHeadersV2?cross-company=true ``` ## **Limitações conhecidas** * Apenas OData v4. O Finance & Operations não expõe a v2. * Sem FetchXML. Isso é exclusivo do Dataverse e do CRM. Use o conector [**Dynamics 365**](/documentation/connectors-and-triggers/pt-br/connectors/enterprise-applications/dynamics-365.md) para esses casos. * Sem paginação automática. Siga o `@odata.nextLink` manualmente, ou controle a paginação usando `$top` e `$skip`. * A descoberta guiada de entidades e campos exige um ambiente acessível e uma conta Azure Key válida. Se a descoberta não conseguir acessar o ambiente, você ainda pode informar o Entity Set por meio de uma expressão Double Braces. * Chaves compostas, lookups `@odata.bind` para navigation properties, e valores de enum e option são os pontos mais propensos a erro. Valide contra o `$metadata` da entidade. ## **Erros comuns**
StatusCausa
400Sintaxe malformada de chave composta ou de expressão $filter.
401 / 403O app não está registrado como um Application User do F&O, não tem a security role necessária, ou o scope do token está incorreto.
404Nome de entity set incorreto.
Ative **Fail On Client Error (4xx)** ou **Fail On Server Error (5xx)** para que o conector interrompa o pipeline quando esses erros ocorrerem. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/enterprise-applications/dynamics-365-finance-and-operations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.