# Integrar directamente con REST

Usa la misma autorización y las mismas propuestas revisadas desde tu POS o adaptador HTTP.

Página: https://zoydelivery.com/docs/api-rest

## Base y equivalencias con MCP

### Base REST autenticada

```text
https://zoydelivery.com/api/integrations/v1
```

| Método y ruta relativa | Operación MCP |
| --- | --- |
| GET /schema | catalog_schema |
| GET /catalog?limit=100&offset=0 | catalog_read |
| GET /menu/library?q= | catalog_library_read |
| POST /menu/library | catalog_library_update |
| POST /catalog/preview | catalog_preview |
| POST /catalog/bulk/preview | catalog_bulk_preview |
| POST /catalog/configuration/analyze | catalog_migration_analyze |
| POST /catalog/configuration/preview | catalog_configuration_preview |
| POST /catalog/apply | catalog_apply |
| GET /imports y GET /imports/:importId | imports_list / import_get |
| POST /documents/prepare | document_prepare |
| POST /documents/jobs | document_job_create |
| GET /documents/jobs y GET /documents/jobs/:jobId | document_jobs_list / document_job_get |
| POST /documents/jobs/:jobId/retry o /cancel | document_job_retry / document_job_cancel |

Envía Authorization: Bearer y Content-Type: application/json en las escrituras. REST responde JSON HTTP; /api/mcp espera mensajes JSON-RPC del protocolo MCP. No intercambies los cuerpos ni añadas un tenant al payload para cambiar de negocio.

## Guarda un plan antes de aplicar

### Terminal privada; lote.json contiene el ejemplo de catálogo

```bash
umask 077
curl --fail-with-body \
  https://zoydelivery.com/api/integrations/v1/catalog/preview \
  -H "Authorization: Bearer ${ZOY_MENU_TOKEN:?Define la clave privada}" \
  -H "Content-Type: application/json" \
  --data-binary @lote.json \
  --output plan.json
```

plan.json incluye datos privados del catálogo. Comprueba errors, before/after, moneda y disponibilidad. Conserva importId y revision del plan que revisaste; no sustituyas la revisión por una más reciente sin volver a preparar el cambio.

- [Formato de lote y reglas de campos](https://zoydelivery.com/docs/catalogo#lote)

## Aplicación e idempotencia

### aplicar.json: sustituye los valores por los del plan revisado

```json
{
  "importId": "UUID_DEL_PLAN_REVISADO",
  "expectedRevision": "REVISION_DEL_PLAN"
}
```

### Ejecuta solo después de autorizar el cambio

```bash
curl --fail-with-body \
  https://zoydelivery.com/api/integrations/v1/catalog/apply \
  -H "Authorization: Bearer ${ZOY_MENU_TOKEN:?Define la clave privada}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-export-2026-10-lote-01" \
  --data-binary @aplicar.json \
  --output recibo.json
```

En MCP idempotencyKey es un argumento de catalog_apply y document_job_create; en REST viaja en la cabecera Idempotency-Key. Usa 8–128 caracteres alfanuméricos con : . _ - y conserva la clave y el cuerpo para reintentos del mismo intento lógico.

> **Comprueba después de aplicar**
>
> Consulta /imports/:importId y vuelve a leer /catalog?code=00012. Conserva el recibo privado; no declares una migración completa solo porque recibiste HTTP 200.