Dynamics 365 Finance & Operations
Saiba mais sobre o conector Dynamics 365 Finance & Operations e como usá-lo na Digibee Integration Platform.
O conector Dynamics 365 Finance & Operations permite integrações com o Microsoft Dynamics 365 Finance & Operations (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.
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 para Customer Engagement, Dataverse e CRM (*.crm.dynamics.com, /api/data/v9.x). Use o conector OData genérico para qualquer outro serviço OData.
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.
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 para o procedimento completo.
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 para o procedimento completo.
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.
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.
Crie a conta Azure Key na Digibee usando os valores dos passos 1 e 2:
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.
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.
Data entity
A coleção OData com a qual você está trabalhando, por exemplo CustomersV3. Caminho: /data/CustomersV3.
Composite key
As chaves do F&O geralmente são compostas e incluem dataAreaId (a legal entity, ou empresa), por exemplo dataAreaId='usmf',CustomerAccount='US-001'.
Cross-company
Por 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).
$metadata
O 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 estão marcados com ✅ na coluna Suporta DB.
Alias
Um 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
Environment URL
URL raiz do ambiente Finance & Operations.
String
✅
https://myenv.operations.dynamics.com
—
Use Dynamic Account
Se ativado, o conector resolve a conta em tempo de execução. Se desativado, usa a conta configurada estaticamente abaixo.
Boolean
❌
false
Use Dynamic Account está ativado
Scoped
Se 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
❌
false
Use Dynamic Account está ativado
Account Name
Nome da conta definida no conector Store Account.
String
✅
N/A
Use Dynamic Account está desativado
Account
Conta contendo as credenciais do Azure AD (client ID, secret e tenant). Tipo suportado: Azure Key. Saiba mais sobre Contas.
Account
—
N/A
Parâmetro Operation
Operation
A 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:
Batch
POST
/data/$batch
multipart/JSON
Agrupa várias operações em uma única requisição.
Create
POST
/data/{EntitySet}
JSON
Cria um registro.
Custom Query
GET
/data/{EntitySet}?{$query}
—
Equivalente a Query. Use quando combinar parâmetros de query brutos e estruturados.
Delete
DELETE
/data/{EntitySet}({key})
—
Exclui um registro.
Get by ID
GET
/data/{EntitySet}({key})
—
Lê um único registro pela chave.
Invoke Action
POST
/data/{EntitySet}({key})/{Action} ou /data/{Action}
JSON
Invoca uma bound action (com key e entity set) ou uma unbound action.
Invoke Function
GET
/data/{EntitySet}({key})/{Function} ou /data/{Function}
—
Invoca uma bound ou unbound function.
Query
GET
/data/{EntitySet}?{$query}
—
Lê a coleção com query options.
Update
PATCH/PUT
/data/{EntitySet}({key})
JSON
Atualiza 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.
Cross-company
Retorna registros de todas as legal entities, em vez de apenas da empresa padrão (cross-company=true).
Boolean
❌
false
Output Format
Controla 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
Headers
Headers 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.
Entity Key
Chave 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.
Action / Function Name
Nome 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.
Body
Payload 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.
Interactive Mode
Se 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.
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
Request Timeout (seconds)
Tempo máximo para a requisição HTTP.
Integer
❌
30
Custom Query String
Parâmetros de query extras, adicionados literalmente.
String
✅
N/A
Update Method
PATCH para uma atualização parcial, ou PUT para uma substituição completa.
Select
❌
PATCH
Operation é Update
Documentation
Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.
String
❌
N/A
Exemplos
Consultar clientes em uma empresa
Requisição resultante:
Saída (quando Output Format está definido como Values Only):
Obter um registro pela chave composta
Requisição resultante:
Consultar em todas as empresas
Requisição resultante:
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 para esses casos.
Sem paginação automática. Siga o
@odata.nextLinkmanualmente, ou controle a paginação usando$tope$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.bindpara navigation properties, e valores de enum e option são os pontos mais propensos a erro. Valide contra o$metadatada entidade.
Erros comuns
400
Sintaxe malformada de chave composta ou de expressão $filter.
401 / 403
O 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.
404
Nome 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.
Atualizado
Isto foi útil?