---
title: "POST Sign file with certificate"
method: POST
path: "/api/files/sign/certificate"
---

# POST Sign file with certificate

`POST /api/files/sign/certificate`

## Request

- Base URL: `https://app.plugsign.com.br`
- URL: `https://app.plugsign.com.br/api/files/sign/certificate`
- Auth: API key in header `Authorization`

Assina um ou mais documentos via API com um certificado digital **.pfx** enviado na própria requisição ou, se nenhum for enviado, com o certificado cadastrado para o usuário do token (ou o certificado da plataforma, na falta dele).

**Como funciona:**

*   Cada item de `signatures[]` recebe o selo visual na página e posição informadas; com `rubric: true` o selo é aplicado em todas as páginas e `page` é dispensado.
*   Todas as document keys são validadas antes do processamento, mas um erro no meio do lote deixa os documentos anteriores assinados (não há reversão).
*   Cada documento é marcado como `Signed` e suas solicitações pendentes são canceladas. Documentos Word são convertidos para PDF antes de assinar. Diferente de `POST /api/files/sign`, este endpoint não dispara webhooks.
*   `stamp` personaliza os textos do selo e funciona em modo tudo ou nada: `name`, `reason`, `date_label` e `date_format` são obrigatórios em conjunto; `email` é opcional. Sem `stamp`, o selo padrão é usado.
*   O certificado enviado é usado apenas nesta requisição e descartado em seguida.

Envie como `multipart/form-data` (campos aninhados no formato `signatures[0][document_key]`, `signatures[0][page]`, `stamp[name]`...). Em caso de sucesso a resposta é `201 Created`.

## Request body `multipart/form-data`

- object
  - `signatures` object[], required: Lista de assinaturas (um item por documento/posição).
    - `document_key` string, required: Document Key do arquivo (precisa pertencer à sua empresa).
    - `page` integer: Página em que a assinatura será inserida. Obrigatória quando rubric não é true.
    - `xPos` number, required: Posição no eixo X onde a assinatura será inserida.
    - `yPos` number, required: Posição no eixo Y onde a assinatura será inserida.
    - `rubric` boolean: Quando true, todas as páginas do documento são assinadas na posição especificada, dispensando page.
  - `certificate` string, binary: Arquivo do certificado digital .pfx (PKCS12). Opcional: sem ele a API usa o certificado cadastrado para o usuário do token ou, na falta dele, o certificado da plataforma.
  - `certificate_password` string: Senha do certificado enviado. Obrigatória quando certificate é enviado.
  - `stamp` object: Textos personalizados do selo visual. Ao informar stamp, name, reason, date_label e date_format são obrigatórios (até 120 caracteres cada); email é opcional.
    - `name` string: Nome exibido no selo.
    - `reason` string: Texto da linha de motivo do selo (substitui o padrão "Signatário: ...").
    - `date_label` string: Rótulo exibido antes da data (padrão: "Data:").
    - `date_format` string: Formato da data no padrão do PHP (padrão: d.m.Y H:i:s). Ex.: d/m/Y H:i.
    - `email` string, email: E-mail exibido ao lado do nome (opcional).

## Response `201`

Assinaturas realizadas

- object
  - `message` string
  - `file_urls` string[]: URLs de download dos documentos assinados, na ordem de signatures[].

## Other responses

- `400`: Certificado que não é um .pfx (PKCS12) válido
- `401`: Token sem usuário ativo na empresa (apenas quando nenhum certificado é enviado)
- `403`: Certificado cadastrado para o usuário expirado
- `404`: Documento, usuário ou certificado não encontrado (index indica a posição no lote)
- `409`: Falha ao aplicar a assinatura (arquivo, senha ou validade do certificado)
- `422`: Erro de validação ou rubrica sem páginas detectadas
- `500`: Falha na conversão do Word

## Changes

- **2026-11-03** `3db1513040ea`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/plugsign/apis/endpoints-manuais/changes/api/files/sign/certificate/post.md)

---

[API](https://skmtc.dev/plugsign/apis/endpoints-manuais.md) - [All operations](https://skmtc.dev/plugsign/apis/endpoints-manuais/llms.txt) - [OpenAPI document](https://skmtc.dev/plugsign/apis/endpoints-manuais/revisions/3db1513040ea?raw)