Retrieve, validate y deploy

La Metadata API administra configuración: objetos, campos, layouts, reglas, permisos y otros componentes. La API de datos administra registros de negocio. Ambas usan OAuth y permisos del tenant; un despliegue de metadata no equivale a importar ventas o clientes.

Seleccionar un componente

Podés recuperar, validar y desplegar un solo miembro con un manifiesto package. Consultá los tipos soportados. Este ejemplo es ficticio: reemplazá los nombres por componentes reales de tu ambiente.

{ "package": { "version": 1, "types": [{ "name": "CustomField", "members": ["Pedido__c.observaciones__c"] }] } }

Enviá ese cuerpo a POST /api/v1/metadata/retrieve con setup:read y permiso de lectura sobre metadata. Recibirás files (mapa de ruta relativa a contenido YAML), manifestHash, generatedAt y datos del manifiesto cuando corresponda. El retrieve público no actualiza el seguimiento de origen.

La selección identifica componentes, no líneas de un archivo. Pueden incluirse archivos de configuración, manifiesto y cambios destructivos que el motor preserva. Revisá todo el árbol resultante. Seleccionar un componente no incorpora automáticamente todas sus dependencias ni autoriza borrar otros componentes.

Validar sin aplicar

Enviá a POST /api/v1/metadata/validate:

{
  "files": { "RUTA_DEVUELTA_POR_RETRIEVE.yml": "CONTENIDO_YAML_RECUPERADO_Y_REVISADO" },
  "package": { "version": 1, "types": [{ "name": "CustomField", "members": ["Pedido__c.observaciones__c"] }] },
  "allowDestructiveChanges": false
}

La ruta y el YAML del ejemplo son marcadores, no un proyecto desplegable. Usá el árbol devuelto por retrieve, conservando sus archivos de configuración. files contiene texto, no rutas locales para que el servidor lea tu disco.

Validar requiere metadata:deploy y permiso de lectura de metadata. Revisá valid, blocked, warnings, creates, updates, deletes y noops. valid: true indica que el plan pasa la validación; no indica que se haya aplicado.

Desplegar y comprobar

Después de revisar el plan y obtener autorización para el ambiente elegido, enviá el mismo proyecto a POST /api/v1/metadata/deploy, con metadata:deploy, permiso de gestión y Idempotency-Key.

La respuesta inicial contiene deploymentId y status: "QUEUED". Consultá GET /api/v1/metadata/deployments/{deploymentId} con setup:read hasta SUCCEEDED, FAILED o CANCELED. Un timeout del cliente no cancela el trabajo.

checkOnly: true en deploy ejecuta una validación registrada sin aplicar componentes. Un trabajo exitoso con checkOnly sigue siendo una validación. Quick deploy usa una validación elegible, cuya vigencia se comprueba en el servidor. Rollback revierte lo que admite el motor de metadata: no es una restauración universal de datos.

Los cambios destructivos necesitan un manifiesto explícito, allowDestructiveChanges: true y permisos. No habilites esa opción para resolver automáticamente un error de validación. No envíes propiedades internas como operationOverride, rollbackOf o un actor elegido por el cliente.

Por CLI

erp metadata retrieve --package ./package.yml --out ./mi-componente --json
erp metadata validate --project ./mi-componente --package ./package.yml --json
erp metadata deploy --project ./mi-componente --package ./package.yml --json

El último comando solicita confirmación y espera el estado terminal. Usá --yes --no-prompt sólo en una automatización ya autorizada. MCP permite retrieve, validate y consultar despliegues; no puede iniciarlos en esta versión.