Adicionar assinante

Adiciona um assinante a uma operação em andamento. O novo membro aceita as mesmas opções de um assinante criado junto com a operação: posição na ordem de assinatura, canal de notificação, dupla autenticação, posicionamento visual da assinatura (coordenadas ou tags no PDF), anexos e antifraude.

Este endpoint adiciona apenas assinantes — observadores só podem ser definidos na criação da operação.

Quando usar

• Entrou uma testemunha, avalista ou aprovador depois da operação criada
• Substituir um assinante (adicione o novo e remova o antigo)
• Encaixar alguém numa posição específica da ordem de assinatura

Endpoint

curl -X POST "https://example.com/api/v2/operation/0/members" \  -H "Content-Type: application/json" \  -d '{}'

null

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

O {operationId} na URL é o ID da operação — o campo id retornado em Criar operação.

Body — exemplo mínimo

{
  "name": "Claudio Nogueira",
  "email": "[email protected]",
  "role": "Testemunha",
  "signatureType": "UserChoice",
  "notificationChannel": "Email",
  "signatures": [
    {
      "documentId": "114488ce-8fc6-42c2-9b13-d4233a3ce089",
      "printSignature": true,
      "positions": [
        { "page": 1, "coordenateX": "4.93%", "coordenateY": "26.46%" }
      ]
    }
  ]
}

Campos básicos

Notificação e autenticação

Posição na ordem de assinatura

Relevante quando a operação é sequencial (order=true na criação) — ou quando você quer converter uma operação paralela em sequencial:

Posicionamento da assinatura

Tag e coordenadas são mutuamente exclusivas para o mesmo elemento — enviar as duas juntas retorna 400.

Antifraude e anexos

Exemplo

curl -X POST "https://api.forsign.digital/api/v2/operation/4821/members" \
  -H "X-Api-Key: $FORSIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claudio Nogueira",
    "email": "[email protected]",
    "signatureType": "UserChoice",
    "notificationChannel": "Email",
    "signatures": [
      {
        "documentId": "114488ce-8fc6-42c2-9b13-d4233a3ce089",
        "printSignature": true,
        "positions": [{ "page": 1, "coordenateX": "4.93%", "coordenateY": "26.46%" }]
      }
    ]
  }'

await fetch(`https://api.forsign.digital/api/v2/operation/${operationId}/members`, {
  method: 'POST',
  headers: {
    'X-Api-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Claudio Nogueira',
    email: '[email protected]',
    signatureType: 'UserChoice',
    notificationChannel: 'Email',
    signatures: [
      {
        documentId: '114488ce-8fc6-42c2-9b13-d4233a3ce089',
        printSignature: true,
        positions: [{ page: 1, coordenateX: '4.93%', coordenateY: '26.46%' }],
      },
    ],
  }),
});

var resp = await http.PostAsJsonAsync(
    $"/api/v2/operation/{operationId}/members",
    new
    {
        name = "Claudio Nogueira",
        email = "[email protected]",
        signatureType = "UserChoice",
        notificationChannel = "Email",
        signatures = new[]
        {
            new
            {
                documentId = "114488ce-8fc6-42c2-9b13-d4233a3ce089",
                printSignature = true,
                positions = new[] { new { page = 1, coordenateX = "4.93%", coordenateY = "26.46%" } },
            },
        },
    });
resp.EnsureSuccessStatusCode();

Respostas de sucesso

201 Created — quando notificationChannel é Email, SMS ou WhatsApp. Corpo vazio; o membro foi criado e a notificação segue o fluxo da operação.

200 OK — quando notificationChannel é None. O corpo traz o link de assinatura para você distribuir:

{
  "data": {
    "accessUri": "https://fsign.app/aBc123"
  }
}

Comportamento e gotchas

• Duplicidade: já existir um membro com o mesmo email e nome na operação retorna 400 (a comparação ignora maiúsculas/minúsculas).
• Notificação respeita a ordem: em operação paralela, o novo membro é notificado imediatamente. Em operação sequencial, ele só é notificado quando chega a vez da posição dele (a menos que entre justamente na posição ativa).
• Colisão de posição: coordenadas (ou tag) sobre uma posição já ocupada por outra assinatura/rubrica no mesmo documento retornam 400.
• Tag precisa existir no PDF — tag não encontrada no documento retorna 400.
• Certificado digital tem regras próprias: exige cpf; não aceita rubricas nem formulário; no máximo 1 posição por documento; e sempre entra no fim da ordem (assina por último), independentemente do orderPosition enviado. Adicionar um membro de certificado a uma operação paralela converte a operação para sequencial automaticamente.
• Certificado assina por último — nos dois sentidos: depois que um membro de certificado já assinou, não dá mais para adicionar assinantes comuns (400). E um assinante comum não pode ficar em posição igual ou posterior à de um certificado — em particular, insertMode=Group numa posição ocupada por um certificado retorna 400 (use Shift, que desloca o certificado para frente).
• Antifraude consome crédito: Liveness, CpfSerpro e FacialCpfSerpro debitam crédito no momento da adição (SelfieSimples e Disabled não consomem). Sem crédito, a chamada retorna 400 e o membro não é criado. O override por membro (antifraudFeatures diferente da política da conta) precisa estar habilitado nas configurações de antifraude da conta — enviar a mesma feature da política padrão não conta como override e é sempre aceito.
• Página inexistente: positions[].page maior que o total de páginas do documento retorna 400.
• Auditoria: a adição fica registrada na trilha de auditoria da operação.

Erros comuns

Veja também