Inicio rápido de la API

Esta página le lleva de una cuenta vacía a un documento terminado creado por su propio código: una cuenta, una plantilla, una clave y una solicitud HTTP. Cada campo, respuesta y error se describe en la referencia de la API de documentos.

Planes

La API de documentos funciona en todos los planes, incluido el Gratuito. Cada documento que crea es un documento automatizado: con Pro no hay límite; si no, se descuenta de los documentos automatizados de sus puestos Business (20 000 al año por puesto), después de la cuota mensual gratuita y después de sus paquetes de documentos. Un documento se cuenta cuando se completa, así que uno fallido no cuesta nada. En el plan Gratuito, los documentos llevan la línea de pie de página “Generated with AutomaDoc”, salvo que su empresa tenga un paquete comprado. Consulte Planes, puestos y paquetes.

1. Una cuenta

Cualquier cuenta de AutomaDoc puede llamar a la API: una organización de Microsoft 365, un dominio de Google Workspace, un espacio de trabajo de Lark o una cuenta de correo electrónico. Si solo necesita la API, regístrese con una dirección de correo electrónico: consulte Cuentas solo API.

Los pasos 2 y 3 se hacen en el Portal de empresa, en company.automadoc.cc, y requieren un administrador de su cuenta (en un espacio de trabajo de Lark, un administrador de la app de Lark).

2. Una plantilla y su ID

Una plantilla es un archivo de Word, Excel o PowerPoint con marcadores donde van sus datos. Para esta página, tome una factura de Word con:

• {Invoice_No} y {Customer} en el texto,
• una fila de tabla cuya primera celda empieza por {#Items}{Product}, después {Qty}, y cuya última celda termina en {Price}{/Items}: la fila se repite una vez por elemento,
• {Total | currency:"USD"} bajo la tabla.

La sintaxis completa está en Sintaxis de plantillas.

Para añadirla en el Portal de empresa:

1. Abra Plantillas y haga clic en Nueva plantilla de API.
2. Escriba un nombre y haga clic en Crear plantilla de API.
3. Abra el menú al final de la fila de la plantilla y elija Subir archivo. El archivo se comprueba al subirlo; si tiene algún problema, la página lo indica y usted sube uno corregido.
4. En el mismo menú, elija Copiar ID de la plantilla.

La API rellena cualquier plantilla de su empresa, no solo las plantillas de API: una creada en el complemento de Excel, desde una hoja de Google o en la extensión de Lark Base funciona igual, y su fila en Plantillas tiene el mismo Copiar ID de la plantilla. Si inicia sesión en el portal con Lark, cree las plantillas en la extensión de Base; su tarjeta API de documentos, en la pestaña Plantilla, también muestra el endpoint con el ID incluido.

3. Una clave de API de la empresa

1. En el Portal de empresa, abra Empresa → Claves de API y haga clic en Nueva clave de API.
2. Rellene Nombre de la clave con el sistema que la usará, por ejemplo ERP, y haga clic en Crear clave.
3. Copie la clave. Empieza por amk_ y se muestra una sola vez.

Una clave de la empresa abre todas las plantillas de su empresa. Guárdela como una contraseña. Revocar, en la misma página, la detiene al instante.

Una plantilla de Lark Base también tiene una clave propia, en su tarjeta API de documentos, que solo abre esa plantilla.

4. Enviar su primera solicitud

Envíe los datos de la plantilla en JSON a POST /api/v1/templates/{templateId}/documents, con la clave en el encabezado X-Webhook-API-Key:

curl -X POST 'https://api.automadoc.cc/api/v1/templates/TEMPLATE_ID/documents?wait=20' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Invoice_No": "INV-2026-001",
      "Customer": "Acme Corp",
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Total": 1540
    },
    "format": "pdf"
  }'

• data es el registro. Cada clave rellena el marcador con el mismo nombre. Los espacios, los puntos y otros símbolos de una clave se convierten en _, así que "Invoice No." rellena {Invoice_No_}; se distinguen mayúsculas y minúsculas.
• format es opcional: "pdf", "png" (la primera página como imagen) o "native" (el tipo de archivo propio de la plantilla). Si se omite, decide el ajuste de la plantilla.
• ?wait=20 retiene la respuesta hasta 20 segundos (25 como máximo) mientras se crea el documento, así que a menudo basta con una solicitud.

filename, recordId y mode también son opcionales; consulte Crear documentos.

5. Leer la respuesta y obtener el archivo

Cuando el documento se termina dentro de la espera, la respuesta es 200 OK:

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "templateId": "9b1c…",
  "status": "completed",
  "statusUrl": "https://api.automadoc.cc/api/v1/documents/5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "createdAt": 1791878400000,
  "filename": "Invoice-INV-2026-001.pdf",
  "downloadUrl": "https://api.automadoc.cc/api/generations/…/download?expires=…&signature=…",
  "downloadUrlExpiresAt": 1792137600000
}

Cuando todavía se está creando, la respuesta es 202 Accepted con "status": "processing" y aún sin enlace. Lea statusUrl con la misma clave cada pocos segundos (como máximo 60 lecturas por minuto por documento) hasta que status sea completed o failed:

curl 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

• completed: downloadUrl abre el archivo sin clave. Funciona mientras su empresa conserve los documentos generados, y cada lectura del estado da uno nuevo.
• failed: error indica por qué, por ejemplo un bucle que nunca se cierra.
• warnings, cuando aparece, enumera lo que se omitió, como una imagen cuya URL no se pudo obtener o marcadores para los que sus datos no tenían valor.

Para obtener el propio archivo con la clave en lugar de un enlace:

curl -o invoice.pdf 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID/file' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

Cuando se rechaza la solicitud

Cada rechazo tiene un code y un error en inglés. Los primeros que encontrará:

Estado	code	Qué hacer
401	API_KEY_MISSING	Añada el encabezado X-Webhook-API-Key
403	API_KEY_INVALID	Compruebe la clave y el ID de la plantilla: un ID incorrecto también recibe esta respuesta
409	TEMPLATE_FILE_MISSING	Suba el archivo de la plantilla
400	TEMPLATE_VALIDATION_ERRORS	Corrija el archivo de la plantilla; validationErrors enumera los problemas
403	QUOTA_EXCEEDED	No quedan documentos este mes; compre un paquete o un puesto
429	RATE_LIMITED	Más de 60 solicitudes por minuto para una plantilla, o 600 documentos por minuto para su empresa; espere y vuelva a intentarlo

La lista completa está en Errores.

Lo mismo en Node.js

Node.js 18 o posterior incluye fetch. Guarde esto como quickstart.mjs y ejecútelo con AUTOMADOC_KEY=amk_… node quickstart.mjs:

import { writeFile } from 'node:fs/promises'

const API = 'https://api.automadoc.cc'
const KEY = process.env.AUTOMADOC_KEY
const TEMPLATE_ID = 'TEMPLATE_ID'

async function makeDocument(templateId, data) {
  const res = await fetch(`${API}/api/v1/templates/${templateId}/documents?wait=20`, {
    method: 'POST',
    headers: { 'X-Webhook-API-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ data, format: 'pdf' }),
  })
  let doc = await res.json()
  if (!res.ok) throw new Error(`${doc.code}: ${doc.error}`)

  // Not finished within the wait: read the status until it is.
  while (doc.status === 'processing') {
    await new Promise((resolve) => setTimeout(resolve, 3000))
    const poll = await fetch(doc.statusUrl, { headers: { 'X-Webhook-API-Key': KEY } })
    doc = await poll.json()
    if (!poll.ok) throw new Error(`${doc.code}: ${doc.error}`)
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc
}

const doc = await makeDocument(TEMPLATE_ID, {
  Invoice_No: 'INV-2026-001',
  Customer: 'Acme Corp',
  Items: [
    { Product: 'Consulting', Qty: 10, Price: 120 },
    { Product: 'Travel', Qty: 1, Price: 340 },
  ],
  Total: 1540,
})

const file = await fetch(doc.downloadUrl)
await writeFile(doc.filename, Buffer.from(await file.arrayBuffer()))
console.log(`Saved ${doc.filename}`, doc.warnings ?? '')

Siguientes pasos

• Bucles. Una lista de objetos rellena un bucle {#Items}…{/Items}, una fila o un bloque por objeto; el bucle puede filtrar, ordenar y limitar sus filas. Consulte Bucles.
• Imágenes. Dé a una imagen de la plantilla el texto alternativo {Logo} y envíe "Logo": "https://…". La URL debe ser una dirección http(s) pública; en cualquier otro lugar de la plantilla, una URL es solo texto. Consulte Imágenes dinámicas y Cómo rellenan sus datos la plantilla.
• PDF, imagen o archivo de Office. "format" elige la salida en cada solicitud; si lo omite, se aplica el ajuste propio de la plantilla.
• Muchos documentos en una solicitud. Envíe data como una lista de hasta 50 objetos para obtener un documento por elemento. Consulte Varios documentos a la vez.
• Un documento a partir de muchos registros. Una plantilla configurada para crear una lista, una página por registro o etiquetas convierte una lista de hasta 500 elementos en un solo documento, que cuenta como uno. Consulte Un documento a partir de muchos registros y Un documento con todos los elementos.
• Firma electrónica. En una plantilla de Lark Base con campos de firma, un bloque sign envía el documento a firmar en cuanto se crea. Consulte Enviar el documento para firmar.
• Sin nada de código. En Microsoft 365, el conector de Power Automate hace la misma solicitud desde un flujo.