Personalizar o registro de uma emissão com overwriteRecord

Quando você emite uma credencial com POST /credential/issue, o registro (o PDF) usa por padrão o design, os textos e as imagens definidos no template (credentialTemplateId). O objeto overwriteRecord permite sobrescrever esses três aspectos somente para aquela emissão pontual, sem alterar o template nem afetar nenhuma outra emissão.

1. O que cada sub-chave sobrescreve

overwriteRecord é opcional e aceita três sub-chaves independentes — você pode enviar uma, duas ou as três; não é obrigatório incluir todas:

Sub-chave	O que sobrescreve
`recordDesign`	O design do registro definido no template.
`texts`	Qualquer texto definido no design do registro.
`images`	Qualquer uma das imagens (logos, assinaturas, fundos etc.) presentes no design do registro.

🔎 Observação: overwriteRecord é um mecanismo de exceção pontual. O template continua sendo a fonte de verdade para todas as demais emissões; este objeto afeta apenas o registro gerado para aquele acreditado específico.

O detalhe exato dos campos internos de recordDesign, texts e images (tipos e valores permitidos) está no contrato OpenAPI do Swagger: https://public-api.acreditta.com/swagger/#/. Este guia explica como usar o objeto, não substitui essa referência.

2. Exemplo 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-chave é independente: se você só precisa alterar um texto para este acreditado em particular, envie apenas texts.

3. Erros e validações a considerar

Se o corpo não passar na validação do esquema (por exemplo, uma estrutura inválida dentro de overwriteRecord), a API responde 406. Verifique o corpo contra o esquema exato no Swagger antes de integrar em produção.
overwriteRecord não tem efeito se, na mesma requisição, você enviar updateCredential: true junto com credentialUUID — esse é o caminho de atualização de uma credencial já emitida, não o de uma nova emissão (veja Endpoints da API).
O campo name deve corresponder a um elemento de texto ou de imagem do design; se não corresponder a nenhum, é ignorado. Se vários elementos compartilharem o mesmo name, a substituição é aplicada ao primeiro encontrado. Certifique-se de que esse nome seja único: clique com o botão direito no elemento de texto ou de imagem que deseja substituir, clique em Propriedades e ali personalize o nome do contêiner.
Nas imagens, a substituição é feita por URL, e essa URL deve apontar diretamente para um arquivo de imagem público (JPG ou PNG, não uma página HTML). Por isso, links de provedores de armazenamento, como Google Drive ou Microsoft, que não fornecem um caminho direto para a imagem, não funcionam.

4. Usar em uma emissão em lote

Se você emite em lote pela plataforma (não pela API) e precisa que o registro de uma linha específica do arquivo seja diferente do restante, você pode adicionar uma coluna chamada overwrite_record ao arquivo de carregamento e colar ali o mesmo objeto — veja Envio em lote.

Referências

Endpoints da API — catálogo completo de rotas, incluindo POST /credential/issue.
Envio em lote — como usar overwrite_record ao emitir em lote pela plataforma.
Swagger: https://public-api.acreditta.com/swagger/#/ — contrato exato de recordDesign, texts e images.