Envio em Massa
Permite criar dezenas ou centenas de documentos a partir de um modelo usando uma planilha Excel (XLSX). Ideal para envio de contratos em larga escala, como matriculas, renovacoes e onboarding de clientes.
O fluxo de envio em massa funciona em 3 etapas:
- Baixar o template XLSX gerado pelo TapSign
- Preencher a planilha com os dados de cada documento
- Fazer upload da planilha preenchida
Etapa 1: Baixar Template XLSX
Endpoint
GET /v1/models/{id}/bulk-template
Headers
| Header | Valor |
|---|---|
| Authorization | Bearer {token} |
Parametros de URL
| Parametro | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
id | string (UUID) | Sim | ID do modelo |
Exemplo de Requisicao
curl -X GET https://api.tapsign.com.br/v1/models/m1o2d3e4-l5o6-7890-abcd-ef1234567890/bulk-template \
-H "Authorization: Bearer {token}" \
-o template-envio-massa.xlsx
Resposta de Sucesso
Status: 200 OK
O retorno e o arquivo XLSX diretamente (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).
O template XLSX gerado contem as seguintes colunas:
- Colunas de variaveis -- Uma coluna para cada variavel
{{...}}do modelo (ex:nome_completo,cpf,valor_contrato) - signer_name -- Nome do signatario (obrigatorio)
- signer_email -- Email do signatario (obrigatorio)
- signer_phone -- Telefone do signatario (opcional)
A primeira linha contem os cabecalhos. Cada linha subsequente representa um documento a ser criado.
Etapa 2: Preencher a Planilha
Abra o arquivo XLSX baixado no Excel, Google Sheets ou qualquer editor de planilhas. Preencha uma linha para cada documento que deseja criar.
Exemplo de planilha preenchida:
| nome_completo | cpf | data_inicio | valor_contrato | signer_name | signer_email | signer_phone |
|---|---|---|---|---|---|---|
| Joao da Silva | 123.456.789-00 | 01/04/2026 | R$ 5.000,00 | Joao da Silva | joao@email.com | +5511999999999 |
| Maria Souza | 987.654.321-00 | 01/04/2026 | R$ 3.500,00 | Maria Souza | maria@email.com | +5511888888888 |
| Pedro Santos | 456.789.123-00 | 15/04/2026 | R$ 7.200,00 | Pedro Santos | pedro@email.com |
- Nao altere os cabecalhos da primeira linha
- Nao adicione ou remova colunas
- Deixe campos opcionais em branco (nao preencha com "N/A" ou "-")
- O limite maximo e de 500 linhas 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 |
Parametros de URL
| Parametro | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
id | string (UUID) | Sim | ID do modelo |
Body (multipart/form-data)
| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
file | file | Sim | Arquivo XLSX preenchido |
autoSend | boolean | Nao | Se true, envia todos os envelopes automaticamente. Padrao: false |
Exemplo de Requisicao
curl -X POST https://api.tapsign.com.br/v1/models/m1o2d3e4-l5o6-7890-abcd-ef1234567890/bulk-send \
-H "Authorization: Bearer {token}" \
-F "file=@template-envio-massa-preenchido.xlsx" \
-F "autoSend=true"
Resposta de Sucesso
Status: 202 Accepted
{
"batchId": "b1a2t3c4-h5i6-7890-abcd-ef1234567890",
"status": "PROCESSING",
"totalRows": 3,
"message": "Envio em massa iniciado. Use o batchId para acompanhar o progresso.",
"createdAt": "2026-03-29T14:30:00Z"
}
O envio em massa e processado em segundo plano. A resposta 202 Accepted indica que o TapSign recebeu a planilha e comecou o processamento. Use o webhook batch.completed ou consulte o status via API para acompanhar.
Campos da Resposta
| Campo | Tipo | Descricao |
|---|---|---|
batchId | string (UUID) | ID unico do lote para acompanhamento |
status | string | Status inicial: PROCESSING |
totalRows | number | Total de linhas (documentos) detectadas na planilha |
message | string | Mensagem informativa |
createdAt | string (ISO 8601) | Data de inicio do processamento |
Erros
| Codigo | Descricao |
|---|---|
400 | Arquivo nao e um XLSX valido ou cabecalhos incorretos |
404 | Modelo nao encontrado |
413 | Arquivo excede o limite de tamanho (5 MB) |
422 | Linhas com dados obrigatorios ausentes (resposta inclui detalhes por linha) |
429 | Limite de envios em massa excedido |
1. GET /v1/models/{id}/bulk-template -> Baixa o XLSX template
2. Preencha a planilha com os dados -> Uma linha = um documento
3. POST /v1/models/{id}/bulk-send -> Faz upload e inicia o processamento
4. Webhook batch.completed -> Notificacao quando finalizar
O envio em massa e limitado a 500 documentos por requisicao e 3 envios em massa por hora por conta. Para volumes maiores, entre em contato com o suporte para liberacao de limites especiais.