Criar um envelope a partir de um modelo

Um modelo (template) é um envelope pré-configurado: os documentos e as vagas de
participante já existem, só faltam os dados de quem vai assinar desta vez.
Este guia mostra como descobrir as vagas de um modelo e criar um envelope a
partir dele numa única chamada.

1. Liste os modelos da conta

A resposta traz id, title, status e meta de paginação. Anote o id do
modelo que você quer usar.

2. Consulte o modelo e encontre o `templateParticipantId` de cada vaga

A resposta traz documents, participants (as vagas — cada uma com id,
roleName, type e order) e fields (os campos posicionados de cada
documento, com templateParticipantId dizendo de qual vaga é cada campo).

O id de cada item em participants é o templateParticipantId que você vai
usar no próximo passo. Guarde-o pelo roleName (por exemplo, "Contratante",
"Testemunha") — casar vaga por posição no array não é seguro, porque a ordem
pode mudar se o modelo for editado depois.

3. Crie o envelope preenchendo cada vaga

A resposta segue o mesmo formato de GET /v4/api/envelopes/{envelopeId}. Com
send: false (o padrão) o envelope fica em rascunho e o preenchimento pode
ser parcial — vaga sem nome nem contato fica do jeito que estava no
modelo, e quem usa a tela (ou uma chamada seguinte) completa depois, com
POST /v4/api/envelopes/{envelopeId}/send. Com send: true a chamada já sai
enviando, pelo mesmo caminho e com os mesmos limites do plano (cota do ciclo,
documentos por envelope, volume por hora) — e por isso send: true exige que
toda vaga que precisa de uma pessoa (signatário, aprovador, observador —
tudo, exceto vaga de grupo) esteja preenchida, seja pelo modelo (nome e e-mail
já cadastrados nele) ou pelo pedido. Faltando alguma, a chamada recusa com
422 UNPROCESSABLE_ENTITY (código TEMPLATE_ENVELOPE_MISSING_PARTICIPANTS)
antes de criar qualquer coisa — nada fica em rascunho para você limpar:

{
  "error": {
    "code": "TEMPLATE_ENVELOPE_MISSING_PARTICIPANTS",
    "message": "1 vaga(s) do modelo exigem nome e contato para enviar e nao vieram preenchidas: Testemunha.",
    "details": {
      "missingSlots": [
        { "templateParticipantId": "vaga_da_testemunha", "roleName": "Testemunha" }
      ]
    }
  }
}

A chamada é tudo ou nada: se qualquer passo DEPOIS da criação for recusado
(vaga desconhecida, contato inválido, pasta sem acesso, limite do envio), o
rascunho criado é apagado e o erro volta. Repetir a chamada, com ou sem
Idempotency-Key, não deixa rascunhos sobrando.

O que este atalho não faz

CPF do participante. O corpo não aceita o CPF de quem vai assinar. O
documento é conferido no momento da assinatura, pelo próprio signatário.

Valor inicial de campo. Os campos posicionados vêm do modelo; nenhum
deles pode ser pré-preenchido por esta operação.

Essas duas exigem outro fluxo de produto e não têm caminho equivalente na
tela hoje — se a sua integração precisa de qualquer uma delas, fale com o
time da SuperSign antes de desenhar em cima do que não existe.

Escopo da chave

POST /v4/api/templates/{templateId}/envelopes exige o escopo
envelopes:send, mesmo quando send é false. Uma chave que deve só ler
modelos e montar rascunhos, sem nunca poder enviar, usa o fluxo em várias
chamadas: POST /v4/api/envelopes, PUT .../participants,
POST .../documents — ver Primeiro envelope em 5
minutos.

1. Liste os modelos da conta#

2. Consulte o modelo e encontre o templateParticipantId de cada vaga#

3. Crie o envelope preenchendo cada vaga#

O que este atalho não faz#

Escopo da chave#

1. Liste os modelos da conta

2. Consulte o modelo e encontre o `templateParticipantId` de cada vaga

3. Crie o envelope preenchendo cada vaga

O que este atalho não faz

Escopo da chave