Assinar em Lote

Assina vários documentos de uma vez em nome do usuário autenticado, quando ele é signatário desses documentos. Útil quando a mesma pessoa tem vários documentos pendentes para assinar.

Endpoint

POST /v1/envelopes/batch-sign

Headers

Header	Valor
Authorization	Bearer {token}
Content-Type	application/json

Como funciona

O usuário autenticado (dono da chave de API ou do JWT) assina como signatário. Cada item identifica um signatário pelo accessToken, e o e-mail desse signatário precisa ser o mesmo e-mail do usuário autenticado. A mesma imagem, o mesmo tipo e a mesma posição de assinatura valem para todos os itens.

Como obter os itens

GET /v1/envelopes/my-signatures lista os documentos em que o usuário autenticado é signatário e devolve, para cada um, o accessToken e o documentHash usados aqui. Aceita o filtro status (status do signatário, por exemplo NOTIFIED ou VIEWED) e paginação com page e size.

Body

Campo	Tipo	Obrigatório	Descrição
items	object[]	Sim	Documentos a assinar, de 1 a 50
items[].accessToken	string	Sim	accessToken do signatário no envelope
items[].documentHash	string	Sim	Hash SHA-256, em hexadecimal, do PDF original. Se não conferir com o documento, o item falha
signatureImage	string	Não	Imagem da assinatura em Base64 (sem o prefixo data:), gravada como PNG
signatureType	string	Não	Tipo da assinatura: DRAWN, TYPED ou UPLOADED. Um valor fora dessa lista faz todos os itens falharem
geolocation	string	Não	Geolocalização do signatário, registrada junto com a assinatura
signaturePage	integer	Não	Página onde a assinatura é aplicada
signaturePosX, signaturePosY	number	Não	Posição da assinatura na página
signatureWidth, signatureHeight	number	Não	Largura e altura da assinatura
refPageWidth, refPageHeight	number	Não	Largura e altura da página usada como referência para a posição

Validação antes de assinar

Antes de assinar qualquer item, a API confere todos os tokens:

• se algum accessToken não existe, a requisição inteira falha com 404;
• se algum pertence a um signatário com e-mail diferente do usuário autenticado, a requisição inteira falha com 403.

Nesses dois casos nada é assinado. Passada essa etapa, cada item é assinado de forma independente: a falha de um item não interrompe os outros e aparece em results. Um item falha, por exemplo, quando o envelope expirou, quando o signatário não está NOTIFIED ou VIEWED, quando falta validar o código de verificação, quando o hash não confere, quando a imagem Base64 é inválida ou quando a cota mensal de assinaturas do dono do envelope acabou.

Exemplo de Requisição

curl -X POST https://api.tapsign.com.br/v1/envelopes/batch-sign \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "accessToken": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b8a1c0e77",
        "documentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
      },
      {
        "accessToken": "b7d1e4f0-2c3a-4e5b-8f6d-1a2b3c4d5e6f",
        "documentHash": "60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752"
      },
      {
        "accessToken": "c9a2b3d4-5e6f-4a7b-9c8d-0e1f2a3b4c5d",
        "documentHash": "fd61a03af4f77d870fc21e05e7e80678095c92d808cfb3b5c279ee04c74aca13"
      }
    ],
    "signatureImage": "iVBORw0KGgoAAAANSUhEUgAA...",
    "signatureType": "DRAWN"
  }'

Resposta de Sucesso

Status: 200 OK

{
  "results": [
    {
      "accessToken": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b8a1c0e77",
      "success": true,
      "error": null
    },
    {
      "accessToken": "b7d1e4f0-2c3a-4e5b-8f6d-1a2b3c4d5e6f",
      "success": true,
      "error": null
    },
    {
      "accessToken": "c9a2b3d4-5e6f-4a7b-9c8d-0e1f2a3b4c5d",
      "success": false,
      "error": "O hash do documento não confere. O documento pode ter sido alterado."
    }
  ],
  "totalSuccess": 2,
  "totalFailed": 1
}

Campos da Resposta

Campo	Tipo	Descrição
results	array	Um resultado por item, na ordem enviada
results[].accessToken	string	Token do item processado
results[].success	boolean	true se o item foi assinado
results[].error	string ou null	Motivo da falha, quando success é false
totalSuccess	integer	Quantidade de itens assinados
totalFailed	integer	Quantidade de itens com falha

Erros

Código	Quando acontece
400	items vazio ou com mais de 50 itens
401	Chave de API ou token ausente ou inválido
403	Algum accessToken pertence a um signatário com e-mail diferente do usuário autenticado
404	Algum accessToken não existe

O formato do corpo de erro está em Status de Erros.

Item já assinado

Repetir um item que já foi assinado não gera erro: ele volta com success: true e a assinatura não é registrada de novo.

Limite por requisição

O máximo é de 50 documentos por requisição. Para volumes maiores, divida em várias chamadas.