Saltar al contenido principal

6. Maestros relacionados

Es la razón de ser de la API. Las relaciones que el ERP ya tiene definidas entre maestros se exponen como navigation properties, y hay tres formas de usarlas.

a. Traer el relacionado junto con el principal: $expand​

# el cliente con su localidad completa
?$expand=Localidad

# solo el nombre de la localidad
?$expand=Localidad($select=name)

# todas las navegaciones de un nivel
?$expand=*

# varias a la vez
?$expand=Localidad($select=name),Vendedor($select=name)
{
  "code": "C0001",
  "name": "Molinos del Sur SA",
  "city_code": "ROS",
  "Localidad": { "code": "ROS", "name": "Rosario" }
}

Si la FK está en null, la propiedad expandida vale null:

{ "code": "C0002", "city_code": null, "Localidad": null }

b. Traer los hijos: $expand de una colección​

Sobre una navegación de uno a muchos, $expand acepta además $filter, $orderby, $top, $skip y $count anidados:

?$expand=Comprobantes($select=number,total;$filter=total gt 1000;$orderby=date desc;$top=5;$count=true)
{
  "code": "C0001",
  "Comprobantes@odata.count": 312,
  "Comprobantes": [
    { "number": "A-0001-00004821", "total": 185400.00 },
    { "number": "A-0001-00004733", "total": 97250.50 }
  ]
}
nota

Las opciones anidadas se separan con ;, no con &. Y Comprobantes@odata.count es el total de hijos, independiente del $top anidado.

En una navegación de muchos a uno, en cambio, solo se aceptan $select y $expand anidados. $filter y los demás devuelven 501: según la especificación un $filter anidado sobre una entidad única no filtra el padre sino que anula la entidad expandida, así que implementarlo como filtro del padre daría resultados silenciosamente equivocados.

c. Navegar por URL​

# la localidad de un cliente
/o_customers('C0001')/Localidad

# los clientes de una localidad, filtrados y contados
/o_cities('ROS')/Clientes?$top=20&$count=true

# un hijo puntual
/o_cities('ROS')/Clientes('C0001')

# cuantos hijos tiene
/o_cities('ROS')/Clientes/$count

# solo las referencias, sin los datos
/o_cities('ROS')/Clientes/$ref

Después del último segmento de navegación valen las mismas query options que en una colección normal: $select, $filter, $orderby, $top, $expand y $count.

Límites de las relaciones​

  • Profundidad máxima: 2 — Tanto en la URL como en $expand anidado. Más niveles devuelven 501 PathTooDeep o 501 ExpandDepthExceeded. El valor real por entidad está en Capabilities.ExpandRestrictions/MaxLevels.
  • Expandir una ruta no se escribe con / — $expand=Localidad/Provincia devuelve 501; la forma correcta es $expand=Localidad($expand=Provincia).
  • Los nombres salen de la etiqueta de la relación en el ERP — Y por lo tanto pueden cambiar si el administrador la renombra. Leé el $metadata al arrancar en vez de hardcodear los nombres de navegación.
  • Solo aparecen las relaciones hacia maestros que tenés habilitados — Si no ves una navegación que esperabas, lo más probable es que el maestro destino no esté habilitado para tu cliente.