Criar Documento via Modelo

Gera um documento a partir de um modelo (template), preenche as variáveis, grava o contato do signatário e envia para assinatura na mesma chamada. É a rota recomendada para integrações servidor a servidor.

Requisição

POST /v1/integration/documents/create-from-template

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	`string`	Sim	`Bearer {token}`, com a chave de API (`tsk_...`) ou um access token JWT
Content-Type	`string`	Sim	`application/json`

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`templateId`	`string` (UUID)	Sim	ID do modelo, obtido em Listar Modelos. O modelo precisa estar `ACTIVE` e pertencer ao usuário autenticado
`signerName`	`string`	Sim	Nome do signatário. Preenche o signatário dinâmico do modelo e compõe o título do documento
`signerEmail`	`string`	Não	E-mail do signatário. Sem ele, o convite não é enviado por e-mail
`signerPhoneCountry`	`string`	Não	DDI sem o `+` (ex.: `55`). Padrão: `55`
`signerPhoneNumber`	`string`	Não	Telefone só com dígitos, sem DDI. Com telefone, o TapSign também dispara a notificação por WhatsApp
`externalId`	`string`	Não	Seu identificador. Garante idempotência e volta no campo `external_id` dos webhooks
`templateVariables`	`object`	Não	Mapa com o nome da variável e o valor. As chaves são os `fields[].name` do modelo

Campos aceitos e ignorados

O schema também aceita sendAutomaticEmail e folderPath, mas esta rota não aplica esses campos.

Como o signatário é preenchido

O TapSign cria os signatários configurados no modelo e dá ao signatário dinâmico o nome de signerName. O e-mail e o telefone são gravados no signatário que tem esse nome (ou no primeiro signatário, se nenhum tiver). Se o modelo não tiver signatários configurados, é criado um com o nome informado.

Variáveis não enviadas

Variáveis do modelo que não estiverem em templateVariables continuam no PDF como texto, por exemplo {{cpf}}. Envie todas as chaves listadas em Detalhar Modelo.

Exemplo de requisição

curl -X POST \
  https://api.tapsign.com.br/v1/integration/documents/create-from-template \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10",
    "signerName": "Carlos Eduardo Mendes",
    "signerEmail": "[email protected]",
    "signerPhoneCountry": "55",
    "signerPhoneNumber": "11999998888",
    "externalId": "pedido-42",
    "templateVariables": {
      "nome_completo": "Carlos Eduardo Mendes",
      "cpf": "123.456.789-00",
      "valor_contrato": "R$ 5.000,00"
    }
  }'

Resposta

201 - Criado com sucesso

{
  "token": "6c2d8f4a-3b1e-4c7d-9a5f-0e8b2d4c6a13",
  "externalId": "pedido-42",
  "status": "SENT",
  "signers": [
    {
      "token": "d4a7c1e9-5f2b-4e8d-a3c6-9b1f7e2d5c80",
      "name": "Carlos Eduardo Mendes",
      "email": "[email protected]",
      "status": "NOTIFIED",
      "signUrl": "https://tapsign.com.br/signing/d4a7c1e9-5f2b-4e8d-a3c6-9b1f7e2d5c80"
    }
  ]
}

Campos da resposta

Campo	Tipo	Descrição
`token`	`string` (UUID)	Token do envelope. É o `token` que chega nos webhooks e o identificador para cancelar
`externalId`	`string`	Eco do `externalId` enviado (pode ser `null`)
`status`	`string`	Status do envelope, em maiúsculas. Na criação: `SENT`
`signers[].token`	`string` (UUID)	Token de acesso do signatário
`signers[].name`	`string`	Nome do signatário
`signers[].email`	`string`	E-mail do signatário
`signers[].status`	`string`	Status do signatário, em maiúsculas: `PENDING`, `NOTIFIED`, `VIEWED`, `SIGNED` ou `DECLINED`
`signers[].signUrl`	`string`	Link de assinatura do signatário: `https://tapsign.com.br/signing/{token do signatário}`

Maiúsculas e minúsculas

Nesta rota os status vêm em maiúsculas. Nos webhooks e na Compatibility API eles vêm em minúsculas.

Prazo de assinatura

O envelope é enviado na hora e expira 30 dias após o envio. Acompanhe o andamento pelos webhooks usando o token do envelope ou o seu externalId.

Idempotência com `externalId`

Se já existe um documento seu com o mesmo externalId em DRAFT, SENT ou IN_PROGRESS, a chamada devolve esse documento (mesmo token e mesmos signatários) em vez de criar outro. A resposta continua 201, e os dados enviados na repetição são ignorados.

Depois que o documento é cancelado, expira ou é concluído, o mesmo externalId cria um documento novo. Assim você pode repetir com segurança uma chamada que deu timeout.

Erros

Código	Quando acontece
`400`	`templateId` ou `signerName` ausentes, `templateId` que não é UUID, modelo inativo (`Este modelo esta inativo.`), falha ao processar o DOCX ou cota mensal de assinaturas do plano insuficiente para o envio
`401`	Token ausente, inválido ou chave desativada
`404`	Modelo não encontrado ou de outro usuário
`429`	Limite de requisições excedido. Veja Rate Limit

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

Pacote: vários documentos com um único link

Quando os mesmos signatários precisam assinar vários documentos de uma vez, crie um pacote. Cada signatário recebe um único link que percorre todos os documentos na ordem enviada.

POST /v1/integration/bundles/create-from-templates

Campo	Tipo	Obrigatório	Descrição
`templates`	`array`	Sim	De 1 a 20 modelos. A ordem é preservada na apresentação ao signatário
`templates[].templateId`	`string` (UUID)	Sim	ID do modelo
`templates[].variables`	`object`	Não	Variáveis deste modelo
`signers`	`array`	Sim	De 1 a 10 signatários. Cada um assina todos os documentos
`signers[].name`	`string`	Sim	Nome do signatário
`signers[].email`	`string`	Sim	E-mail do signatário. Sem e-mail, o pacote é recusado com erro `400`
`signers[].phoneCountry`	`string`	Não	DDI sem o `+`. Padrão: `55`
`signers[].phoneNumber`	`string`	Não	Telefone só com dígitos, sem DDI
`bundleTitle`	`string`	Não	Título do pacote. Padrão: `Pacote de N documentos`
`externalId`	`string`	Não	Repetir o mesmo valor devolve o pacote já criado com esse ID, em qualquer status
`sendImmediately`	`boolean`	Não	Padrão: `true`. Com `false`, o pacote fica em `DRAFT` para envio posterior

curl -X POST \
  https://api.tapsign.com.br/v1/integration/bundles/create-from-templates \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "bundleTitle": "Pacote de cadastro",
    "templates": [
      { "templateId": "3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10", "variables": { "valor_contrato": "R$ 1.200,00" } },
      { "templateId": "8a1d4c7e-2b5f-4e9a-b3c6-7d0e1f2a4b58", "variables": { "cidade": "São Paulo" } }
    ],
    "signers": [
      { "name": "Maria Silva", "email": "[email protected]", "phoneCountry": "55", "phoneNumber": "11987654321" }
    ],
    "externalId": "cadastro-42"
  }'

Resposta 201 Created:

{
  "bundleId": 88,
  "externalId": "cadastro-42",
  "status": "SENT",
  "envelopes": [
    { "envelopeId": 1543, "envelopeToken": "0b7e2d4c-6a13-4c7d-9a5f-6c2d8f4a3b1e", "sortOrder": 0 },
    { "envelopeId": 1544, "envelopeToken": "5f2b4e8d-a3c6-4b1f-8e2d-d4a7c1e95c80", "sortOrder": 1 }
  ],
  "signers": [
    {
      "token": "5b1e9c3a-7d2f-4a6e-8c0b-3f5d7a9e1c24",
      "name": "Maria Silva",
      "email": "[email protected]",
      "status": "NOTIFIED",
      "signUrl": "https://tapsign.com.br/signing/bundle/5b1e9c3a-7d2f-4a6e-8c0b-3f5d7a9e1c24"
    }
  ]
}

status do pacote, em maiúsculas: DRAFT, SENT, IN_PROGRESS, COMPLETED ou CANCELED.
signers[].status, em maiúsculas: PENDING, NOTIFIED, IN_PROGRESS ou COMPLETED.
Cada envelopeToken é o token que chega nos webhooks daquele documento.

Cancelar pela API de integração

Cancelar um documento

DELETE /v1/integration/documents/{token}

Use o token do envelope. A resposta é 200 OK com { "message": "Documento cancelado com sucesso" }, e o evento doc_canceled é enviado aos webhooks inscritos.

Código	Quando acontece
`400`	Documento já concluído, cancelado ou expirado
`404`	Token inexistente ou de outro usuário

Cancelar um pacote inteiro

DELETE /v1/integration/bundles/by-envelope/{token}

Use o token de qualquer envelope do pacote. Todos os envelopes do pacote são cancelados e a resposta é 200 OK com { "message": "Pacote cancelado com sucesso" }. Cancelar um pacote que já está cancelado também retorna 200.

Código	Quando acontece
`400`	O documento não pertence a um pacote, pertence a outro usuário, ou o pacote já foi concluído
`404`	Token inexistente

Compatibility API (migração)

Formato de compatibilidade para quem migra de outra plataforma de assinatura: campos em snake_case e variáveis no array data. Em integrações novas, prefira a rota nativa acima.

POST /api/v1/models/create-doc/
DELETE /api/v1/docs/{docToken}/

A barra final faz parte do caminho.

Campo	Tipo	Descrição
`template_id`	`string` (UUID)	ID do modelo (obrigatório)
`signer_name`	`string`	Nome do signatário (obrigatório)
`signer_email`	`string`	E-mail do signatário
`signer_phone_country`	`string`	DDI sem o `+`. Padrão: `55`
`signer_phone_number`	`string`	Telefone só com dígitos, sem DDI
`external_id`	`string`	Seu identificador, com a mesma regra de idempotência da rota nativa
`data`	`array`	Variáveis no formato `{ "de": "nome_variavel", "para": "valor" }`. O `de` pode vir com ou sem as chaves duplas
`owner_sign`	`boolean`	Se `true`, o dono da conta também assina o documento
`owner_email`	`string`	E-mail do dono que assina, usado com `owner_sign`

Os campos send_automatic_whatsapp, disable_signer_emails, lang, folder_path e created_by são aceitos, mas não alteram o comportamento.

curl -X POST https://api.tapsign.com.br/api/v1/models/create-doc/ \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10",
    "signer_name": "Maria Silva",
    "signer_email": "[email protected]",
    "external_id": "pedido-42",
    "data": [
      { "de": "nome_completo", "para": "Maria Silva" },
      { "de": "valor_contrato", "para": "R$ 1.200,00" }
    ]
  }'

Resposta 201 Created:

{
  "token": "6c2d8f4a-3b1e-4c7d-9a5f-0e8b2d4c6a13",
  "open_id": 1542,
  "name": "Contrato de Prestação de Serviços - Maria Silva",
  "status": "sent",
  "external_id": "pedido-42",
  "signers": [
    {
      "token": "d4a7c1e9-5f2b-4e8d-a3c6-9b1f7e2d5c80",
      "name": "Maria Silva",
      "email": "[email protected]",
      "status": "notified",
      "sign_url": "https://tapsign.com.br/signing/d4a7c1e9-5f2b-4e8d-a3c6-9b1f7e2d5c80"
    }
  ]
}

open_id é o ID numérico do envelope e name é o título do documento. O cancelamento DELETE /api/v1/docs/{docToken}/ segue as mesmas regras de Cancelar um documento.

Requisição​

Headers​

Body (JSON)​

Exemplo de requisição​

Resposta​

201 - Criado com sucesso​

Campos da resposta​

Idempotência com externalId​

Erros​

Pacote: vários documentos com um único link​

Cancelar pela API de integração​

Cancelar um documento​

Cancelar um pacote inteiro​

Compatibility API (migração)​