Validações de identidade

Combinações e estratégias por signatário

Ao gerar um processo de assinatura, é essencial entender as diferentes combinações possíveis de validações de identidade, bem como as estratégias que permitem aplicá-las de forma global ou individual por signatário.

Para estruturar essas validações, existem regras que você deve considerar para garantir que o processo funcione corretamente.

1. Tipos de validações disponíveis

As validações de identidade que você pode combinar em um processo incluem:

Validação	Tipo	Obrigatório	Descrição
camera	Boolean	Opcional	Solicita uma foto do rosto do signatário.
otpCode	Boolean	Opcional	Solicita um código de verificação.
options.camera	String	Condicional	Se você quiser comparar a foto do rosto com o documento de identidade do signatário, deve enviar 'identification' neste campo; se quiser apenas a foto do participante, envie 'photo'.
options.otpCode	String	Condicional	Este campo aceita os valores 'phone' e 'email' para indicar por qual meio o signatário receberá o código, caso otpCode esteja definido como true nos dados base.
options.whatsapp	Boolean	Condicional	Envie este campo como true somente se quiser que o fluxo de assinatura deste signatário seja realizado pelo WhatsApp; por padrão, é false.
options.both	Boolean	Condicional	Envie este campo como true somente se quiser que o fluxo de assinatura deste signatário seja realizado por WhatsApp e e-mail; por padrão, é false.
options.identificationCardBack	Boolean	Condicional	Envie este campo como true somente se quiser que a validação de identidade solicite adicionalmente o verso do documento, disponível apenas para WhatsApp.

info

Aqui você pode ver a lista de países e documentos de identidade aceitos

both não existe como campo independente

both não é um parâmetro de nível superior: ele não existe na raiz da requisição nem como signProfile[x].both. Ele só existe aninhado como options.both (ou signProfile[x].options.both para validações individuais).

2. Validações globais e individuais

Você pode aplicar as validações de duas maneiras:

• Global: na raiz da requisição. São aplicadas automaticamente a todos os signatários.
• Individual: no objeto signProfile[x], para validar cada signatário de forma personalizada.

info

As validações individuais têm precedência sobre as globais quando ambas são declaradas.

Os pacotes só aceitam validações globais

A criação de pacotes (POST /document/many) não aceita validações individuais por signatário: as validações são lidas apenas da raiz da requisição e se aplicam a todos os participantes do pacote. O que esta seção descreve sobre validações individuais não se aplica a esse endpoint.

A precedência individual é total, não uma mesclagem

Se um signProfile[x] definir qualquer um destes campos: camera, otpCode ou options, esse signatário deixa de herdar completamente as validações globais — mesmo para os campos que não incluiu. Qualquer campo ausente nesse signProfile[x] assume o valor false (para camera/otpCode) ou um objeto vazio (para options), independentemente do que as validações globais indiquem.

Exemplo: se você enviar "camera": true na raiz, mas um signatário individual definir apenas "options": { "otpCode": "email" } (sem incluir "camera": true nesse mesmo signProfile[x]), esse signatário ficará com camera: false, mesmo que a validação global esteja definida como true.

Se você quiser que um signatário mantenha uma validação global e personalize apenas outra, deve repetir explicitamente cada campo relevante (camera, otpCode) dentro desse mesmo signProfile[x].

3. Regras principais

1. options.camera = 'identification' ativa a comparação biométrica, mas só funcionará se o signatário tiver identification, country e identificationType definidos.
2. options.both = true indica que o signatário deve receber notificações por e-mail e WhatsApp simultaneamente; para que isso seja efetivo: options.whatsapp = true.
3. options.camera e options.otpCode só são válidos se, no mesmo nível (raiz ou dentro do mesmo signProfile[x]), existir camera: true ou otpCode: true, respectivamente. Por exemplo, signProfile[x].options.camera exige signProfile[x].camera: true para esse mesmo signatário; não basta que camera seja true globalmente. Se você declarar options.camera ou options.otpCode sem seu equivalente booleano nesse mesmo nível, o processo não será válido.
4. As validações individuais substituem completamente as globais para esse signatário: se um signProfile[x] declarar camera, otpCode ou options, qualquer campo não incluído nesse mesmo signProfile[x] assume false (ou {} para options), sem herdar o valor global. Veja o aviso na seção 2.

4. Exemplos:

Validações globais:

{
  ...,
  "camera": true,
  "otpCode": true,
  "options": {
    "camera": "identification",
    "otpCode": "email",
  }
  "signProfile": [
    {
      "name": "Firmante 1",
      "email": "example@auco.ai",
      "phone": "+573000000000",
      "identification": "123456789",
      "identificationType": "CC",
      "country": "CO"
    },
    {
      "name": "Firmante 2",
      "email": "example2@auco.ai",
      "phone": "+573000000000",
      "identification": "123456789",
      "identificationType": "CC",
      "country": "CO"
    }
  ],
  ...
}

Validações individuais:

{
  ...,
  "signProfile": [
    {
      "name": "Firmante 1",
      "email": "example@auco.ai",
      "phone": "+573000000000",
      "camera": true,
      "otpCode": true,
      "identification": "123456789",
      "identificationType": "CC",
      "country": "CO"
      "options": {
        "camera": "identification",
        "whatsapp": true,
        "otpCode": "email"
      }
    }
  ],
  ...
}