Envio em Massa

Permite preencher um modelo várias vezes de uma só vez a partir de uma planilha XLSX. O fluxo tem 3 etapas:

1. Baixar a planilha base gerada pelo TapSign
2. Preencher a planilha com uma linha por documento
3. Fazer upload da planilha preenchida

O que a rota de upload faz

Para cada linha, a API registra um preenchimento do modelo com os valores da planilha travados e soma a quantidade ao documentsCount do modelo. Essa rota não cria envelope nem envia e-mail para o endereço da coluna email.

Para gerar e enviar documentos para uma lista de pessoas pela API, chame Criar Documento via Modelo uma vez por linha, usando externalId para evitar duplicidade.

---

Etapa 1: Baixar a planilha base

Endpoint

GET /v1/models/{id}/bulk-template

Headers

Header	Valor
Authorization	Bearer {token}

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	ID do modelo

Exemplo de Requisição

curl -X GET https://api.tapsign.com.br/v1/models/3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10/bulk-template \
  -H "Authorization: Bearer {token}" \
  -o planilha-base.xlsx

Resposta de Sucesso

Status: 200 OK

O retorno é o próprio arquivo XLSX (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, nome planilha-base.xlsx).

Estrutura da planilha base

• Uma aba chamada Dados.
• Primeira linha com os cabeçalhos: uma coluna para cada item de fields do modelo (usando fields[].name), na ordem do modelo.
• Última coluna: email.

---

Etapa 2: Preencher a planilha

Preencha uma linha para cada documento.

Exemplo de planilha preenchida:

nome_completo	cpf	valor_contrato	email
João da Silva	123.456.789-00	R$ 5.000,00	[email protected]
Maria Souza	987.654.321-00	R$ 3.500,00	[email protected]

Atenção

• Não altere os cabeçalhos: os valores são associados às variáveis pelo nome da coluna.
• Linhas totalmente vazias são ignoradas.
• Células vazias ficam sem valor.
• O limite é de 50 linhas com dados por envio.

---

Etapa 3: Upload da planilha

Endpoint

POST /v1/models/{id}/bulk-send

Headers

Header	Valor
Authorization	Bearer {token}
Content-Type	multipart/form-data

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	ID do modelo. O modelo precisa estar ACTIVE

Body (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
file	file	Sim	Planilha .xlsx preenchida. A API lê a primeira aba. Arquivos .xls e .csv são recusados

Exemplo de Requisição

curl -X POST https://api.tapsign.com.br/v1/models/3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10/bulk-send \
  -H "Authorization: Bearer {token}" \
  -F "[email protected]"

Resposta de Sucesso

Status: 201 Created

O processamento é síncrono: a resposta sai quando todas as linhas foram registradas.

{
  "documentsCreated": 2,
  "rowsProcessed": 2
}

Campos da Resposta

Campo	Tipo	Descrição
documentsCreated	number	Quantidade de preenchimentos registrados
rowsProcessed	number	Quantidade de linhas com dados lidas da planilha

Erros

Código	Quando acontece
400	Modelo inativo, planilha vazia, mais de 50 linhas, arquivo que não é XLSX válido ou id que não é UUID
401	Token ausente ou inválido
404	Modelo não encontrado ou de outro usuário
413	Arquivo acima de 10 MB, recusado antes de chegar à API

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

Fluxo completo resumido

1. GET  /v1/models/{id}/bulk-template   -> baixa a planilha base (XLSX)
2. Preencha a planilha                  -> uma linha por documento, até 50
3. POST /v1/models/{id}/bulk-send       -> registra um preenchimento por linha