La API de EZDocu para desarrolladores

Con la API de EZDocu (v1) conectas tu propio sistema (CRM, ERP, web de pedidos) con EZDocu. Tu sistema sube el documento, crea la orden de traducción o de maquetación, se entera de cuándo terminó y descarga el resultado, sin entrar al panel. Son las mismas órdenes y el mismo saldo de créditos que usas en la web.

Quién puede crear claves

No depende del plan: depende del permiso Claves de API. Lo tienen siempre el propietario y, de fábrica, los gerentes. Revisor y Miembro lo traen apagado; el propietario puede encenderlo por persona en Equipo.

Con acceso de solo lectura no puedes ver, crear ni revocar claves. Cada clave trabaja con el acceso de quien la creó y nunca hace más que esa persona. Si esa persona queda desactivada en el equipo, su clave sale Suspendida.

Crear una clave

1. Entra en Ajustes › Claves de API.
2. Pulsa Crear clave.
3. Ponle un Nombre para reconocerla, por ejemplo Integración ERP.
4. Elige el Entorno: Staging para probar o Producción para trabajar de verdad.
5. Marca los Servicios: Traducción, Layout o los dos. Sin servicios, la clave solo consulta.
6. En Acceso por área, marca lectura o escritura. Solo puedes dar los accesos que tú tienes; Órdenes y Webhooks piden el permiso «Ver y asignar todos los documentos».
7. Si quieres, pon un Límite diario de páginas (vacío = sin límite; máximo 5000).
8. Pulsa Crear clave, cópiala con Copiar y pulsa Ya la guardé. La clave completa solo se muestra esa vez.

Puedes tener hasta 20 claves activas. Revocar apaga una clave al instante y no se puede deshacer. Trátala como una contraseña.

Staging y Producción: adónde apunta cada clave

Las dos se crean aquí, en www.ezdocu.ai, desde Ajustes › Claves de API. No necesitas otra cuenta.

Cada clave funciona solo en su URL. Empieza con Staging; cuando funcione, cambia URL y clave: las rutas son las mismas.

Dónde está la documentación

En el menú lateral, Documentación del API. Tiene el Inicio rápido, las guías Traducir un documento, Layout sin traducir y Revisión humana, Webhooks y verificación de firma y la referencia de cada ruta con ejemplos.

• En Ambientes eliges Staging o Producción: cambian la URL base, los ejemplos y las descargas (Descargar Postman y Descargar OpenAPI).
• Probar en Swagger llama al servidor del sitio donde estás: en www es Producción y crear una orden cobra créditos. Para la clave de Staging, usa Postman o tu código.

El flujo básico

Cada petición lleva la cabecera Authorization: Bearer <tu clave>. Todo POST, PATCH, PUT y DELETE lleva además Idempotency-Key: si repites la petición con la misma, nunca se crean dos órdenes ni se cobra dos veces.

1. Sube el archivo con POST /uploads (te da una URL de subida), envíalo a esa URL y confírmalo con POST /uploads/{id}/complete. Si ya está en una URL https:// pública, mándala en file_url al crear la orden.
2. Crea la orden con POST /orders. En mode va translate (traducir) o layout (maquetar en el mismo idioma). Al traducir, indica target_language, por ejemplo en-US. El idioma del documento se detecta solo.
3. Espera el resultado: con el webhook order.completed (recomendado) o consultando GET /orders/{id} cada 15 a 30 segundos.
4. Descarga: con la orden en completed, el detalle trae un enlace por archivo, válido 1 hora.

Qué archivos recibes

PDF, DOCX y HTML (un HTML por hoja y uno con todas), en la combinación que pidas, más el certificado y el original. El contenido del documento nunca viene en el JSON de la respuesta: solo los enlaces y los datos de la orden. Al traducir, el certificado y la firma digital del PDF van por defecto; puedes quitarlos en la petición.

Webhooks

Se crean por la API (POST /webhooks), no en Ajustes. EZDocu manda un POST firmado a tu URL https:// con cada evento:

El secreto de la firma (whsec_…) se muestra una sola vez. Tu servidor debe responder 2xx en menos de 10 segundos; si no, EZDocu reintenta durante algo más de un día y medio.

Revisión humana

Con review_required: true la orden se detiene en in_review y espera, sin límite de tiempo, a tu equipo. Quien la revisa la abre en Órdenes, pulsa Continuar Orden, la revisa y pulsa Finalizar Orden. Entonces llega order.completed. Quien finaliza elige el formato, el certificado y el Sello Human Verified: una orden sin revisión nunca lleva ese sello. La aprobación se hace en la web, no por la API.

Créditos y límites

• Mismo saldo que la web: 1 crédito por hoja, cobrado al crear la orden.
• Sin saldo, POST /orders responde 402 INSUFFICIENT_CREDITS y no se crea ni se cobra nada.
• Si una orden cobrada falla o la cancelas, los créditos no se devuelven solos: escribe a soporte con el número de la orden.
• Pedir DOCX, HTML, certificado o revisión no cobra más.
• 100 peticiones por minuto por clave (por defecto). Archivos de hasta 50 MB y 2000 hojas, en PDF, JPG, PNG, TIFF, WebP, HEIC, DOCX u ODT.

Errores frecuentes

Panel de uso

En el menú lateral, API abre Uso de la API: peticiones, órdenes, hojas, errores, webhooks y límites de tu cuenta, por periodo, por clave y por miembro. Lo ven quienes tienen el permiso Claves de API.

Preguntas frecuentes

¿Necesito un plan especial para usar la API? No. Hace falta el permiso Claves de API, que tienen el propietario y los gerentes.

Mi programador recibe 401 o 403 con la clave de Staging, ¿qué pasa? Casi siempre es la URL: la clave de Staging (ezk_test_) solo funciona en https://staging.ezdocu.ai/api/v1, y la de Producción (ezk_live_), en https://www.ezdocu.ai/api/v1. Si la clave de Staging es nueva, espera un minuto antes de usarla.

¿Las pruebas con la clave de Staging gastan créditos? No: las órdenes son simuladas. Solo cobra la clave de Producción.

¿Puedo recibir la traducción como texto en JSON? No. La API entrega archivos: PDF, DOCX o HTML.