Personalizar la constancia de una emisión con overwriteRecord

Cuando emites una credencial con POST /credential/issue, la constancia (el registro/PDF) usa por defecto el diseño, los textos y las imágenes definidos en la plantilla (credentialTemplateId). El objeto overwriteRecord te permite sobrescribir esos tres aspectos solo para esa emisión puntual, sin tocar la plantilla ni afectar ninguna otra emisión.

1. Qué sobrescribe cada sub-clave

overwriteRecord es opcional y admite tres sub-claves independientes — puedes enviar una, dos o las tres; no es obligatorio incluir todas:

Sub-clave	Qué sobrescribe
`recordDesign`	El diseño de la constancia definido en la plantilla.
`texts`	Cualquier texto definido en el diseño de constancia.
`images`	Cualquiera de las imágenes (logos, firmas, fondos, etc.) que haya en el diseño de constancia.

🔎 Fíjate en: overwriteRecord es un mecanismo de excepción puntual. La plantilla sigue siendo la fuente de verdad para todas las demás emisiones; este objeto solo afecta el registro generado para ese acreditado en específico.

El detalle exacto de los campos internos de recordDesign, texts e images (tipos y valores permitidos) está en el contrato OpenAPI de Swagger: https://public-api.acreditta.com/swagger/#/. Esta guía te explica cómo usar el objeto, no reemplaza esa referencia.

2. Ejemplo de payload

{
  "credentialTemplateId": "string",
  "firstName": "Ana",
  "lastName": "Gómez",
  "email": "ana.gomez@example.com",
  "awardedAt": "2026-09-07",
  "sendNotification": true,
  "overwriteRecord": {
    "recordDesign": "",
    "texts": [
      { "name": "my_textbox_1", "str": "new string to replace" },
      { "name": "my_textbox_2", "str": "some generic text" }
    ],
    "images": [
      { "name": "logo", "url": "https://example.com/logo.png" }
    ]
  }
}

Cada sub-clave es independiente: si solo necesitas cambiar un texto para este acreditado en particular, envía únicamente texts.

3. Errores y validaciones a considerar

Si el cuerpo no pasa la validación del esquema (por ejemplo, una estructura inválida dentro de overwriteRecord), la API responde 406. Verifica el cuerpo contra el esquema exacto en Swagger antes de integrar en producción.
overwriteRecord no tiene efecto si en la misma petición envías updateCredential: true junto con credentialUUID — esa es la ruta de actualización de una credencial ya emitida, no la de una emisión nueva (ver Endpoints de la API).
El campo name debe coincidir con algún elemento de texto o de imagen del diseño; si no coincide con ninguno, se ignora. Si varios elementos comparten el mismo name, el reemplazo se aplica en el primero que se encuentre. Asegúrate de que ese nombre sea único: haz clic derecho sobre el elemento de texto o de imagen que quieres reemplazar, clic en Propiedades y ahí personaliza el nombre del contenedor.
En las imágenes, el reemplazo se hace por URL, y esa URL debe apuntar directamente a un archivo de imagen público (JPG o PNG, no una página HTML). Por eso no sirven los enlaces de proveedores de almacenamiento, como Google Drive o Microsoft, que no entregan una ruta directa a la imagen.

4. Usarlo en una emisión masiva

Si emites por lotes desde la plataforma (no por API) y necesitas que la constancia de una fila puntual del archivo se vea distinta a la del resto, puedes agregar una columna llamada overwrite_record al archivo de carga y pegar ahí el mismo objeto — ver Envío masivo.

Referencias

Endpoints de la API — catálogo completo de rutas, incluida POST /credential/issue.
Envío masivo — cómo usar overwrite_record al emitir por lotes desde la plataforma.
Swagger: https://public-api.acreditta.com/swagger/#/ — contrato exacto de recordDesign, texts e images.