11. Recetas por herramienta

curl

# comillas SIMPLES: en bash, "$filter" lo come la shell
curl -s -H "X-API-Key: TU_API_KEY" \
  'https://TU-HOST/synergy-server/jwt-odata-key/o_customers?$select=code,name&$filter=active%20eq%20true&$top=10'

Si preferís no escapar los espacios a mano, usá --get --data-urlencode:

curl -s -H "X-API-Key: TU_API_KEY" --get \
  --data-urlencode '$filter=contains(name,'"'"'molinos'"'"')' \
  --data-urlencode '$expand=Localidad($select=name)' \
  'https://TU-HOST/synergy-server/jwt-odata-key/o_customers'

Postman

1. Importá synergy-odata.postman_collection.json.
2. En la colección, pestaña Variables, completá serviceRoot y apiKey. Si vas por JWT, completá además user, password e idClient.
3. Para JWT: ejecutá primero Autenticación → Obtener token. El token se guarda solo en la variable token; el resto de los requests ya lo usan.
4. Empezá por Descubrimiento → Documento de servicio para ver tus entidades reales y reemplazar o_customers en el resto.

Excel

peligro

No sirve Datos → Desde fuente OData. Ese conector no permite agregar headers HTTP, y esta API necesita X-API-Key o Authorization. Hay que ir por Power Query, que es igual de simple una vez que sabés el camino.

1. Datos → Obtener datos → Desde otras fuentes → Consulta en blanco.
2. En el editor: Inicio → Editor avanzado.
3. Pegá el código de abajo, ajustá las dos primeras líneas y aceptá.
4. Si pide credenciales, elegí Anónimo: la autenticación va en el header, no en el diálogo.

let
    ServiceRoot = "https://TU-HOST/synergy-server/jwt-odata-key/",
    ApiKey      = "TU_API_KEY",

    Fuente = OData.Feed(
        ServiceRoot,
        null,
        [
            Headers        = [ #"X-API-Key" = ApiKey ],
            Implementation = "2.0"
        ]
    )
in
    Fuente

Eso te deja el navegador con todas las entidades. Para traer una consulta concreta —con filtros y relacionados, que es mucho más rápido que bajar todo y filtrar en Excel—:

let
    ServiceRoot = "https://TU-HOST/synergy-server/jwt-odata-key/",
    ApiKey      = "TU_API_KEY",

    Respuesta = Json.Document(
        Web.Contents(
            ServiceRoot,
            [
                RelativePath = "o_customers",
                Query = [
                    #"$select" = "code,name,city_code",
                    #"$filter" = "active eq true",
                    #"$expand" = "Localidad($select=name)",
                    #"$top"    = "1000"
                ],
                Headers = [ #"X-API-Key" = ApiKey ]
            ]
        )
    ),
    Filas  = Respuesta[value],
    Tabla  = Table.FromRecords(Filas)
in
    Tabla

El archivo power-query-odata.pq trae estas consultas más la variante con JWT y una función que sigue el @odata.nextLink para traer más de una página.

Power BI

Mismo camino que Excel y por el mismo motivo: Obtener datos → Consulta en blanco → Editor avanzado con el código de arriba. Una vez cargadas dos o más entidades relacionadas, Power BI lee los <ReferentialConstraint> del $metadata y propone las relaciones del modelo solo; conviene revisarlas en Modelo → Administrar relaciones antes de armar los visuales.

nota

Para una entidad grande, filtrá en la URL con $filter y $select en vez de cargar todo y filtrar en Power BI: el servidor pagina de 1000 en 1000 y traer una tabla completa puede llevar muchas vueltas.

Python

Con requests, sin librerías de OData:

import requests

ROOT = "https://TU-HOST/synergy-server/jwt-odata-key/"
H    = {"X-API-Key": "TU_API_KEY", "Accept": "application/json"}

def paginar(url, params=None):
    while url:
        r = requests.get(url, headers=H, params=params, timeout=60)
        r.raise_for_status()
        cuerpo = r.json()
        filas  = cuerpo.get("value", [])
        if not filas:
            break
        for fila in filas:
            yield fila
        url, params = cuerpo.get("@odata.nextLink"), None   # el nextLink ya trae todo

for c in paginar(ROOT + "o_customers", {
        "$select": "code,name",
        "$filter": "active eq true",
        "$expand": "Localidad($select=name)"}):
    print(c["code"], c["name"], (c.get("Localidad") or {}).get("name"))

El script completo está en ejemplo_odata.py: recorre el documento de servicio, baja el $metadata y lista una entidad con filtros.

C# / .NET

Con Simple.OData.Client, que lee el $metadata y tipa las consultas:

var settings = new ODataClientSettings(new Uri("https://TU-HOST/synergy-server/jwt-odata-key/"));
settings.BeforeRequest = req => req.Headers.Add("X-API-Key", "TU_API_KEY");

var client = new ODataClient(settings);

var clientes = await client
    .For("o_customers")
    .Select("code", "name")
    .Filter("active eq true")
    .Expand("Localidad")
    .Top(50)
    .FindEntriesAsync();