# Importar hojas, PDF e imágenes

Prepara datos, corrige lo incierto y recupera trabajos sin volver a empezar el documento entero.

Página: https://zoydelivery.com/docs/importar-documentos

## Elige la herramienta según la fuente

| Fuente | Herramienta | Límite |
| --- | --- | --- |
| CSV UTF-8 / Excel .xlsx | document_prepare, sin IA | 5 MiB; primera hoja; hasta 500 filas |
| Google Sheets o Drive público CSV/XLSX | document_prepare con url | Export público admitido; no URLs arbitrarias |
| PDF | document_job_create con IA | 20 MiB, 20 páginas, hasta 500 productos |
| PNG / JPEG / WebP | document_job_create con IA | 20 MiB; imagen válida |
| Texto UTF-8 | document_job_create con IA | 200 KB de texto |

La extracción con IA requiere el proveedor configurado para el negocio y puede enviarle el archivo y generar consumo. Para documentos privados de Google Docs/Drive, exporta un PDF o una hoja autorizada y sube el archivo. El servidor no inicia sesión en cuentas del proveedor.

## Hojas: conserva los códigos del sistema

### CSV mínimo de ejemplo

```csv
codigo,nombre,grupo,precio,presentaciones,inventario,stock
00012,Plato de ejemplo,Platos,12.50,Individual,made_to_order,1
```

En CSV/XLSX los importes se expresan como decimales; el preparador los convierte a centavos. Los argumentos JSON de catalog_preview usan enteros en centavos. Descarga la plantilla del catálogo desde Menú → Importar para usar los encabezados y IDs actuales.

Una fila con un ID exportado conserva el código del producto actual. Una fuente sin código puede proponer coincidencias por nombre y grupo o un código DOC estable; revisa cada vínculo. Varios candidatos requieren un código explícito.

## Documentos: inicia una vez y guarda jobId

### Argumentos de document_job_create; base64 es un marcador

```json
{
  "name": "menu.pdf",
  "mimeType": "application/pdf",
  "dataBase64": "BASE64_DEL_ARCHIVO",
  "idempotencyKey": "menu-proveedor-2026-10-lote-01"
}
```

1. Guarda el jobId devuelto y consulta document_job_get con una espera razonable entre lecturas.
2. queued/processing informan completedPages y totalPages; salir del cliente no cancela el trabajo.
3. completed incluye result.rows, result.warnings y result.sourceDocument. Revísalos contra la fuente.
4. Envía esas filas a catalog_preview conservando sourceDocument completo. Corrige errores y pide confirmación antes de catalog_apply.

> **Sube el archivo por un canal privado**
>
> El valor base64 puede ocupar decenas de MiB. No lo pegues en una conversación ni en logs. Usa un cliente con capacidad de enviar archivos o la API HTTP desde un proceso privado.

## Recuperación, cancelación y vencimiento

- Hay como máximo dos trabajos queued/processing por negocio. document_jobs_list permite recuperar los 20 más recientes.
- failed/cancelled pueden reanudarse con document_job_retry si canRetry es true; se conserva cada checkpoint confirmado.
- Los archivos del trabajo vencen a las 24 horas. Si venció, necesitas la fuente otra vez.
- document_job_cancel detiene las siguientes páginas. Una llamada IA en vuelo puede generar consumo; cancelar no revierte productos publicados.
- Si pierdes la respuesta de creación, reutiliza la misma idempotencyKey y archivo. Si pierdes una aplicación, consulta import_get antes de decidir otro intento.

- [Referencia de las herramientas](https://zoydelivery.com/docs/herramientas#document_job_create)
- [Errores y operación](https://zoydelivery.com/docs/operacion)