Objetos, consultas y cambios

Descubrir antes de consultar

GET /objects devuelve records con apiName, etiquetas y capacidades. GET /objects/{objectApiName}/describe devuelve los campos legibles y su propiedad editable, además de las capacidades del objeto. Ambos requieren data:read.

Las capacidades combinan publicación del objeto, permisos del usuario y scopes de la conexión. Con sólo data:read, creatable, updateable, deletable y editable son false. MCP aplica además las limitaciones de escritura de su versión.

Las rutas de esta guía son relativas a /api/v1. Usá siempre apiName; las etiquetas pueden variar o traducirse. Los campos custom suelen terminar en __c. No supongas que un objeto o campo existe en otro tenant.

Filtros y paginación

GET /data/{objectApiName} devuelve {records, total, nextCursor}. Empezá con take=5; el máximo efectivo es 200. Para obtener el total calculado enviá includeTotal=true.

Parámetro	Formato
where	Objeto JSON serializado: igualdad de campos
whereIn	Objeto JSON serializado con listas de valores
filters	Grupo JSON con logic y hasta 10 conditions
sort	Lista JSON de hasta 2 objetos {id, desc}
orderBy, orderDirection	Campo y asc/desc, alternativa a sort
search, searchFields	Texto y nombres de campos separados por comas
cursor	Valor opaco de nextCursor, sin modificarlo

Ejemplo de filters antes de codificarlo en la URL, suponiendo que descubriste un campo legible llamado name:

{ "logic": "and", "conditions": [{ "id": "f1", "field": "name", "operator": "contains", "value": "Ejemplo" }] }

Ejemplo de sort:

[{ "id": "name", "desc": false }]

Cada condición necesita id. No hay grupos anidados. Los operadores incluyen eq, neq, contains, not_contains, starts_with, is_blank, is_not_blank, gt, gte, lt, lte, between, in, not_in e in_related. between usa value y valueTo; in y not_in usan una lista. Consultá el contrato antes de usar filtros de relaciones.

Para la página siguiente mantené el mismo objeto, token, filtros, tamaño y orden; agregá cursor=nextCursor. No combines cursor con skip. Terminá cuando nextCursor sea null; un cursor no representa una instantánea inmutable si los registros cambian durante el recorrido.

Interpretar datos comerciales

Un campo como Product.unitPrice representa el valor guardado en ese registro; no demuestra por sí solo el precio vigente para un cliente, una lista, una cantidad o una moneda. Revisá el estado activo, la moneda y las reglas de precios disponibles antes de presentarlo como cotización. Si faltan esos datos, informá el valor como precio base registrado y explicitá lo que no se pudo verificar. Un cero no significa necesariamente que el producto sea gratuito.

Intención	Operación	Scope
Crear	POST /data/{objectApiName}	data:write
Modificar campos enviados	PATCH /data/{objectApiName}/{id}	data:write
Eliminar	DELETE /data/{objectApiName}/{id}	data:delete

La entrada es un objeto JSON con nombres API de campos editables. No existe un esquema fijo para todos los tenants: combiná OpenAPI con el describe autorizado. No envíes campos que una IA haya deducido de una descripción informal.

Las mutaciones requieren Idempotency-Key: 8 a 200 caracteres de letras, números, punto, guion, guion bajo o dos puntos. Conservá la misma clave y el mismo cuerpo al reintentar la misma intención; usá otra clave para una operación distinta. La retención es de 24 horas.

Para cambiar un registro, leelo primero y enviá su cabecera ETag como If-Match. Ante 412, volvé a leer y conciliá los cambios; no elimines la condición para forzar la escritura. Las respuestas de create/get/update incluyen el ETag vigente.

Las reglas de validación y duplicados siguen activas. Una advertencia de duplicado no es permiso para ignorarla: revisá el error DUPLICATE_RULE, presentá la coincidencia al usuario y usá el mecanismo de confirmación sólo si autoriza continuar.

Acciones de negocio

Las transiciones se descubren con GET /data/{objectApiName}/{id}/transitions y requieren actions:read. Su ejecución requiere actions:execute, permisos y una clave de idempotencia. Una acción custom debe estar registrada en el ERP; la API no acepta código arbitrario para ejecutarlo como administrador.