> 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/web-protocols/odata.md).

# OData

O conector **OData** permite integrações com qualquer serviço compatível com [OData](https://www.odata.org/) (v4 ou v2), como SAP, Microsoft Dynamics 365, Business Central, Salesforce e feeds OData públicos, estendendo o REST engine da plataforma.

Ele monta requisições baseadas em padrões para consultar e manipular um **entity set** (coleção) OData, incluindo CRUD, query options server-driven (`$filter`, `$select`, `$orderby`, `$top`, `$skip`, `$expand`, `$count`), **actions e functions** bound/unbound e `$batch`.

Use este conector quando:

* Você precisa ler ou gravar dados em um serviço OData que não tem um conector dedicado na Digibee.
* Você quer controle explícito sobre a requisição OData (entity set, key, query options, actions, `$batch`).
* Você está integrando SAP OData / SAP S/4HANA, Business Central, ou uma API OData personalizada.

{% hint style="info" %}

#### **OData vs. conectores específicos de fornecedor**

Para o Microsoft Dynamics 365, use o conector [**Dynamics 365**](/documentation/connectors-and-triggers/pt-br/connectors/enterprise-applications/dynamics-365.md) (Customer Engagement/Dataverse) ou [**Dynamics 365 Finance & Operations**](/documentation/connectors-and-triggers/pt-br/connectors/enterprise-applications/dynamics-365-finance-and-operations.md). Ambos são versões especializadas do OData engine, com valores padrão específicos do produto e descoberta guiada de entidades.
{% endhint %}

## **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.

<table><thead><tr><th width="160">Termo</th><th>Significado</th></tr></thead><tbody><tr><td><strong>Entity Set</strong></td><td>A coleção que você está endereçando, por exemplo <code>Customers</code>. Ela se torna o primeiro segmento do path: <code>/Customers</code>.</td></tr><tr><td><strong>Entity Key</strong></td><td>Identifica um único registro. Pode ser um valor único (<code>42</code>, <code>guid'…'</code>) ou uma chave <strong>composta</strong> (<code>id1=val1,id2=val2</code>). Representada como <code>/Customers(42)</code> ou <code>/Customers(id1=val1,id2=val2)</code>.</td></tr><tr><td><strong>Query options</strong></td><td>Parâmetros server-driven: <code>$filter</code>, <code>$select</code>, <code>$orderby</code>, <code>$top</code>, <code>$skip</code>, <code>$expand</code> e <code>$count</code>.</td></tr><tr><td><strong>Action / Function</strong></td><td>Operações do lado do servidor. Uma operação <strong>bound</strong> tem como destino uma entidade ou coleção específica; uma operação <strong>unbound</strong> se aplica ao serviço como um todo. Actions usam <code>POST</code>; functions usam <code>GET</code>.</td></tr><tr><td><strong>OData version</strong></td><td><code>4.0</code> (padrão) ou <code>2.0</code>. Determina os headers da requisição e como a resposta é interpretada: <code>value</code>, <code>@odata.count</code> e <code>@odata.nextLink</code> para a v4, ou <code>d</code> e <code>d.results</code> para a v2.</td></tr></tbody></table>

## **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" %}

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="150">Padrão</th></tr></thead><tbody><tr><td><strong>Alias</strong></td><td>Um nome para a saída deste conector, para que você possa referenciá-la depois no fluxo com <a href="/pages/CNhjMiHwGiGjmVcUAGvL#referenciando-etapas-anteriores-usando-o-previous-steps-access">Double Braces</a>.</td><td>String</td><td>✅</td><td><code>odata-01</code></td></tr><tr><td><strong>Fail On Client Error (4xx)</strong></td><td>Interrompe o pipeline em uma resposta 4xx.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Fail On Server Error (5xx)</strong></td><td>Interrompe o pipeline em uma resposta 5xx.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Authentication" %}

<table><thead><tr><th width="112">Parâmetro</th><th width="200">Descrição</th><th width="83">Tipo</th><th width="83">Suporta DB</th><th width="120">Padrão</th><th width="125">Visível quando</th></tr></thead><tbody><tr><td><strong>Base URL</strong></td><td>URL raiz do serviço OData. A barra final é normalizada.</td><td>String</td><td>✅</td><td><code>https://services.odata.org/V4/Northwind/Northwind.svc</code></td><td>—</td></tr><tr><td><strong>Use Dynamic Account</strong></td><td>Se ativado, o conector resolve a conta em tempo de execução. Se desativado, usa a conta configurada estaticamente abaixo.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Scoped</strong></td><td>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 <a href="https://docs.digibee.com/documentation/developer-guide/development-cycle/overview/runtime/dynamic-accounts">Dynamic Accounts</a>.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td><strong>Use Dynamic Account</strong> está ativado</td></tr><tr><td><strong>Account Name</strong></td><td>Nome da conta definida no conector <a href="https://docs.digibee.com/documentation/connectors-and-triggers/connectors/tools/store-account"><strong>Store Account</strong></a>.</td><td>String</td><td>✅</td><td>N/A</td><td><strong>Use Dynamic Account</strong> está ativado</td></tr><tr><td><strong>Account</strong></td><td>Conta usada para autenticar a requisição. Tipos suportados: <strong>Azure Key</strong>, <strong>Basic</strong>, <strong>API Key</strong>, <strong>OAuth Bearer</strong>, <strong>OAuth 2.0</strong>, <strong>AWS V4</strong>, <strong>custom auth header</strong> (e outros disponíveis na plataforma). Saiba mais sobre <a href="https://docs.digibee.com/documentation/developer-guide/development-cycle/build-overview/accounts">Contas</a>.</td><td>Account</td><td>—</td><td>N/A</td><td><strong>Use Dynamic Account</strong> está desativado</td></tr></tbody></table>

{% hint style="info" %}
O **Azure Key** executa 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.
{% endhint %}
{% endtab %}

{% tab title="OData API" %}

### **Parâmetros base**

Estes parâmetros formam a base da requisição: Entity Set, OData Version e Operation. A Operation escolhida aqui determina quais parâmetros adicionais aparecem a seguir.

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="141">Padrão</th></tr></thead><tbody><tr><td><strong>OData Version</strong></td><td><code>4.0</code> ou <code>2.0</code>. Determina os headers da requisição e a interpretação da resposta.</td><td>Select</td><td>❌</td><td><code>4.0</code></td></tr><tr><td><strong>Entity Set</strong></td><td>Nome da coleção OData, como <code>Customers</code>.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Operation</strong></td><td>A ação a ser executada. Ela define o formato da requisição. Veja as operações suportadas abaixo.</td><td>Select</td><td>❌</td><td><code>Query</code></td></tr></tbody></table>

#### **Operações suportadas**

O parâmetro **Operation** mapeia para uma requisição OData da seguinte forma:

<table><thead><tr><th width="112">Operation</th><th width="112">HTTP</th><th>Path</th><th width="141">Body</th><th width="182">Observações</th></tr></thead><tbody><tr><td><strong>Batch</strong></td><td><code>POST</code></td><td><code>/$batch</code></td><td>multipart/JSON</td><td>Agrupa várias operações em uma única requisição.</td></tr><tr><td><strong>Create</strong></td><td><code>POST</code></td><td><code>/{EntitySet}</code></td><td>JSON</td><td>Cria um registro.</td></tr><tr><td><strong>Custom Query</strong></td><td><code>GET</code></td><td><code>/{EntitySet}?{$query}</code></td><td>—</td><td>Equivalente a Query. Use quando combinar parâmetros de query brutos e estruturados.</td></tr><tr><td><strong>Delete</strong></td><td><code>DELETE</code></td><td><code>/{EntitySet}({key})</code></td><td>—</td><td>Exclui um registro.</td></tr><tr><td><strong>Get by ID</strong></td><td><code>GET</code></td><td><code>/{EntitySet}({key})</code></td><td>—</td><td>Lê um único registro pela chave.</td></tr><tr><td><strong>Invoke Action</strong></td><td><code>POST</code></td><td><code>/{EntitySet}({key})/{Action}</code> ou <code>/{Action}</code></td><td>JSON</td><td>Invoca uma bound action (com key e entity set) ou uma unbound action.</td></tr><tr><td><strong>Invoke Function</strong></td><td><code>GET</code></td><td><code>/{EntitySet}({key})/{Function}</code> ou <code>/{Function}</code></td><td>—</td><td>Invoca uma bound ou unbound function.</td></tr><tr><td><strong>Query</strong></td><td><code>GET</code></td><td><code>/{EntitySet}?{$query}</code></td><td>—</td><td>Lê a coleção com query options.</td></tr><tr><td><strong>Update</strong></td><td><code>PATCH</code>/<code>PUT</code></td><td><code>/{EntitySet}({key})</code></td><td>JSON</td><td>Atualiza um registro, parcialmente (<code>PATCH</code>) ou totalmente (<code>PUT</code>).</td></tr></tbody></table>

### **Parâmetros comuns**

Assim como os parâmetros base, estes se aplicam independentemente da operação escolhida. Eles são agrupados aqui por clareza, mesmo aparecendo depois dos campos específicos da operação nas configurações do conector.

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="150">Padrão</th></tr></thead><tbody><tr><td><strong>Output Format</strong></td><td>Controla o formato da resposta retornada ao pipeline. <strong>Values Only</strong> desempacota e retorna apenas o array <code>value</code>. <strong>Full Response</strong> retorna a resposta completa, incluindo os campos <code>@odata.*</code>. <strong>Single Entity</strong> retorna a primeira ou única entidade.</td><td>Select</td><td>❌</td><td><code>Values Only</code></td></tr><tr><td><strong>Headers</strong></td><td>Headers adicionais da requisição, como pares chave/valor.</td><td>Key/Value</td><td>✅</td><td>N/A</td></tr></tbody></table>

### **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**.

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="150">Padrão</th></tr></thead><tbody><tr><td><strong>Entity Key</strong></td><td>Chave simples ou composta.</td><td>String</td><td>✅</td><td>N/A</td></tr></tbody></table>

**Action / Function Name** — usado por **Invoke Action** e **Invoke Function**.

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="150">Padrão</th></tr></thead><tbody><tr><td><strong>Action / Function Name</strong></td><td>Nome da action ou function OData. Bound quando um <strong>Entity Set</strong> é definido, unbound caso contrário.</td><td>String</td><td>✅</td><td>N/A</td></tr></tbody></table>

**Body** — usado por **Batch**, **Create**, **Invoke Action** e **Update**.

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="150">Padrão</th></tr></thead><tbody><tr><td><strong>Body</strong></td><td>Payload JSON para Create e Update, parâmetros da action para Invoke Action, ou o payload do <code>$batch</code>.</td><td>JSON</td><td>✅</td><td><code>{}</code></td></tr></tbody></table>

**Query parameters** — usado por **Custom Query** e **Query**.

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="150">Padrão</th></tr></thead><tbody><tr><td><strong>Filter (<code>$filter</code>)</strong></td><td>Expressão de filtro OData, por exemplo <code>Age gt 18 and City eq 'NY'</code>.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Select (<code>$select</code>)</strong></td><td>Campos separados por vírgula a incluir na resposta.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Order By (<code>$orderby</code>)</strong></td><td>Ordena os resultados por uma ou mais propriedades, em ordem crescente ou decrescente. Por exemplo, <code>Name asc, Created desc</code>.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Expand (<code>$expand</code>)</strong></td><td>Entidades relacionadas a incluir inline.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Top (<code>$top</code>)</strong></td><td>Número máximo de registros a retornar. Sem limite artificial.</td><td>Number</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Skip (<code>$skip</code>)</strong></td><td>Registros a pular (paginação).</td><td>Number</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Include Count (<code>$count</code>)</strong></td><td>Inclui a contagem total na resposta.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Advanced Settings" %}

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="83">Tipo</th><th width="81">Suporta DB</th><th width="100">Padrão</th><th width="125">Visível quando</th></tr></thead><tbody><tr><td><strong>Request Timeout (seconds)</strong></td><td>Tempo máximo para a requisição HTTP.</td><td>Number</td><td>❌</td><td><code>30</code></td><td>—</td></tr><tr><td><strong>Custom Query String</strong></td><td>Parâmetros de query extras, adicionados literalmente (por exemplo, <code>cross-company=true</code>).</td><td>String</td><td>✅</td><td>N/A</td><td>—</td></tr><tr><td><strong>Update Method</strong></td><td><code>PATCH</code> para uma atualização parcial, ou <code>PUT</code> para uma substituição completa.</td><td>Select</td><td>❌</td><td><code>PATCH</code></td><td>Operation é <strong>Update</strong></td></tr></tbody></table>
{% endtab %}

{% tab title="Documentation" %}

<table><thead><tr><th width="112">Parâmetro</th><th width="231">Descrição</th><th width="100">Tipo</th><th width="110">Suporta DB</th><th width="150">Padrão</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.</td><td>String</td><td>❌</td><td>N/A</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## **Tratamento da resposta**

* **OData v4:** O conector lê a coleção a partir de `value`, a contagem total a partir de `@odata.count`, e os links de paginação a partir de `@odata.nextLink`.
* **OData v2:** O conector lê a coleção a partir de `d.results` (ou `d`).
* **Output Format:** Determina qual parte dessa resposta chega ao pipeline. Veja o parâmetro [**Output Format**](#parametros-comuns) em OData API para os valores disponíveis.

## **Exemplos**

### **Consulta com filter e select (v4)**

**Entrada** (parâmetros do conector):

```
Base URL   = https://services.odata.org/V4/Northwind/Northwind.svc
Entity Set = Products
Operation  = Query
Select     = ProductName,UnitPrice
Filter     = UnitPrice gt 20
Top        = 2
```

**Saída** (quando **Output Format** está definido como `Values Only`):

```json
[
  { "ProductName": "Chai", "UnitPrice": 21.0 },
  { "ProductName": "Chang", "UnitPrice": 25.0 }
]
```

### **Create**

```
Entity Set = Customers
Operation  = Create
Body       = { "CompanyName": "Acme", "Country": "US" }
```

### **Invocar uma bound action**

```
Entity Set  = accounts
Entity Key  = 00000000-0000-0000-0000-000000000001
Operation   = Invoke Action
Action Name = Recalculate
Body        = { }
```

**Requisição resultante:**

```html
POST /accounts(00000000-0000-0000-0000-000000000001)/Recalculate
```

## **Limitações conhecidas**

* O conector não pagina automaticamente. Para obter páginas adicionais, siga o `@odata.nextLink` manualmente (por exemplo, com um Loop) ou controle a paginação usando `$top` e `$skip`.
* Os payloads do `$batch` precisam estar bem formados de acordo com a versão OData do serviço de destino.
* A descoberta automática de entidades e campos a partir do `$metadata` está disponível apenas nos conectores Dynamics guiados. No conector OData genérico, o Entity Set é um campo de texto livre.

## **Erros comuns**

<table><thead><tr><th width="145">Status</th><th>Causa</th></tr></thead><tbody><tr><td><code>400</code></td><td>Expressão <code>$filter</code> malformada ou sintaxe de key inválida.</td></tr><tr><td><code>401</code> / <code>403</code></td><td>Credenciais de conta ausentes ou inválidas, ou scope insuficiente para a requisição.</td></tr><tr><td><code>404</code></td><td>Nome de entity set ou key incorretos.</td></tr></tbody></table>

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/web-protocols/odata.md?ask=<question>&goal=<endgoal>
```

`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.