Criar Assinatura

O processo de assinatura inicia pela criação da consulta dentro do ScoreHub.

POST /api/signatures

Ambiente	URL
Homologação	`https://api.assinatura.dev.scorehub.com.br/api/signatures`
Produção	`https://api.assinatura.scorehub.com.br/api/signatures`

Importante

Atualmente aceitamos apenas 1 item nos arrays documents e signaturePeople por assinatura. Os campos já estão em formato de lista prevendo futuras expansões, mas no cenário atual não utilize múltiplos itens. Caso precise trabalhar com múltiplas assinaturas ou documentos, entre em contato conosco.

Idempotência

Opcional. Envie o header Idempotency-Key com um valor único por criação para evitar assinaturas duplicadas em caso de retry:

POST /api/signatures
Authorization: Bearer <secret>
Idempotency-Key: <uuid-gerado-por-voce>

Primeira chamada → 201 Created.
Repetição com a mesma chave (dentro de 24h) → 200 OK com o mesmo corpo da criação original, sem criar nova assinatura.
Sem o header, há uma proteção automática por hash do payload com janela curta (30s).

Payload de envio

Payload padrão utilizando a captura de documentos da ScoreHub (SCOREHUB_SDK):

{
  "deadLine": "2026-05-25",
  "notificationSchedule": 1,
  "fraudIfInconclusive": false,
  "cancelIfFraud": true,
  "numberOfRetriesIfFraud": 1,
  "purpose": "FGTS",
  "callbackUrl": "https://app.dev.scorehub.com.br",
  "documentConfig": {
    "documentFaceMatch": true,
    "documentIaCheck": true,
    "documentBackIaCheck": true,
    "documentFraudAfterRetries": false,
    "documentDigitalForcedAfterRetries": true,
    "documentFraudAfterAll": "REJECT",
    "documentCaptureMethod": "SCOREHUB_SDK"
  },
  "signaturePeople": [
    {
      "email": "assinatura@scorehub.com.br",
      "phone": "41996438555",
      "notificationType": "NO_NOTIFICATION",
      "cpf": "12345678909",
      "name": "Cliente Fake YES",
      "birth": "1991-09-25",
      "reuseDocument": false,
      "attachDocument": false,
      "canSendDigitalDocument": true,
      "canSendAttachDocument": true,
      "digitalDocumentFaceMatch": true
    }
  ],
  "documents": [
    {
      "fileName": "NOME_DO_DOCUMENTO",
      "file": "BASE_64"
    }
  ]
}

Configurações gerais

Campos da raiz do payload:

Campo	Tipo	Obrigatório	Resumo
`deadLine`	date	Sim	Data limite da assinatura (`AAAA-MM-DD`)
`notificationSchedule`	int	Não	Periodicidade dos lembretes (0 a 3)
`fraudIfInconclusive`	boolean	Sim	Comportamento em resultado inconclusivo — usar `false`
`cancelIfFraud`	boolean	Sim	Cancela o contrato inteiro em caso de fraude
`numberOfRetriesIfFraud`	int	Sim	Novas tentativas de biometria (0 a 2)
`purpose`	enum	Sim	Propósito: `FGTS` · `CONSIGNADO` · `CARTAO`
`callbackUrl`	string	Não	URL de redirecionamento pós-assinatura
`documentConfig`	objeto	Sim*	Configuração de captura de documentos — detalhe
`signaturePeople`	lista	Sim	Signatários — detalhe
`documents`	lista	Sim	Documentos a assinar — detalhe

* documentConfig deve sempre ser enviado com documentCaptureMethod: "SCOREHUB_SDK".

`deadLine`

Data limite para conclusão da assinatura. Se expirar sem finalizar, o contrato será automaticamente cancelado.

`notificationSchedule`

Opcional. Periodicidade dos lembretes de assinatura:

Valor	Frequência de notificação
`0`	Envia apenas a primeira solicitação
`1`	1 lembrete por dia
`2`	1 lembrete a cada 2 dias
`3`	1 lembrete a cada 3 dias

cuidado

Cada lembrete enviado será cobrado conforme o contrato vigente.

`fraudIfInconclusive`

Use sempre false. Enviar true somente quando a empresa não possuir capacidade de SCORE de risco.

Com o SCORE ativo e retorno inconclusivo, o processo entra na fila da Mesa de Análise, que poderá aprovar, solicitar nova tentativa ou marcar como fraude (cancelando). Em caso de dúvida, nos consulte antes de usar.

`cancelIfFraud`

Valor	Comportamento em caso de fraude
`true`	Cancela todo o contrato automaticamente — mesmo se houver mais pessoas para assinar ou assinaturas já concluídas
`false`	Nunca cancela automaticamente por fraude

`numberOfRetriesIfFraud`

Quantas novas tentativas são permitidas quando o SCORE indica NOVA TENTATIVA:

Valor	Comportamento
`0`	Não faz nenhuma nova tentativa
`1`	Permite 1 nova tentativa automática
`2`	Permite 2 novas tentativas automáticas

Precedência

Este campo tem precedência sobre cancelIfFraud. Mesmo com cancelIfFraud = true, se houver tentativas disponíveis o fluxo não será cancelado até que elas se esgotem. Detalhes em Fluxo e status.

`purpose`

Propósito do compartilhamento do documento. Valores aceitos:

Valor	Uso
`FGTS`	Operações de FGTS
`CONSIGNADO`	Crédito consignado
`CARTAO`	Cartão

`callbackUrl`

URL para onde o assinante será redirecionado ao concluir. Não obrigatório — pode ser enviado vazio.

documentConfig

Configuração da captura e validação de documentos pela SDK da ScoreHub:

Campo	Tipo	Resumo
`documentCaptureMethod`	enum	Sempre `SCOREHUB_SDK`
`documentFaceMatch`	boolean	FaceMatch entre selfie e documento (R$ 0,20)
`documentIaCheck`	boolean	Validação por IA da frente do documento (R$ 0,60)
`documentBackIaCheck`	boolean	Validação por IA do verso (o valor engloba frente e verso)
`documentFraudAfterRetries`	boolean	`true` = marca fraude direto após 3 tentativas de captura
`documentDigitalForcedAfterRetries`	boolean	`true` = após as tentativas, exige o Documento Digital (R$ 0,20). Tem precedência sobre `documentFraudAfterRetries`
`documentFraudAfterAll`	enum	Ação quando todas as validações de documento falham — ver abaixo

`documentFraudAfterAll`

Valor	Comportamento
`REJECT`	Recomendado. Marca fraude documental — nenhum documento passou nas validações
`PENDING`	Encaminha a decisão para a Mesa de Análise
`APPROVE`	Usa o "menos pior" disponível (sem garantia de qualidade); se nenhum tiver o mínimo de uso, rejeita mesmo assim

Recomendação

Use REJECT: se o documento não passou em nenhuma etapa de validação, não garantimos que exista um documento bom para uso.

signaturePeople

Lista de pessoas que assinarão o documento. Atualmente restrito a 1 pessoa por assinatura.

Campo	Tipo	Resumo
`email`	string	E-mail do signatário
`phone`	string	Telefone com DDD
`notificationType`	enum	`WHATSAPP` ou `NO_NOTIFICATION`
`cpf`	string	CPF do signatário
`name`	string	Nome completo
`birth`	date	Data de nascimento (`AAAA-MM-DD`)
`reuseDocument`	boolean	Enviar sempre `false`
`attachDocument`	boolean	Enviar sempre `false`
`canSendDigitalDocument`	boolean	Permite ao signatário enviar Documento Digital oficial (GOV/CNH)
`canSendAttachDocument`	boolean	Permite anexo de documento no fluxo da SDK
`digitalDocumentFaceMatch`	boolean	Realiza FaceMatch também no Documento Digital

`notificationType`

Valor	Comportamento
`WHATSAPP`	ScoreHub envia o link de assinatura por WhatsApp
`NO_NOTIFICATION`	Nenhuma notificação — o parceiro entrega o link ao cliente

documents

Lista de documentos a serem assinados. Atualmente apenas 1 documento por assinatura.

Campo	Tipo	Resumo
`fileName`	string	Nome do documento
`file`	string	Arquivo em Base64 — somente PDF

Retorno da criação

{
  "signatureUUID": "d855108d-4de5-49cb-a4ef-3f77b19fb0e9",
  "signatureStatus": "GENERATING_SIGNATURE",
  "callbackUrl": "https://app.dev.scorehub.com.br",
  "sendWebhookNotifications": true,
  "signaturePerson": [
    {
      "signaturePersonUUID": "086526c8-11fc-4a28-9863-df5652b79642",
      "signatureStatus": "PENDING_GENERATING_SIGNATURE",
      "parameters": [
        {
          "parameterName": "UNICO_BIOMETRIC",
          "statusBiometric": "",
          "scoreBiometric": ""
        },
        {
          "parameterName": "UNICO_DOCUMENT",
          "statusDocument": ""
        }
      ]
    }
  ],
  "signatureDocuments": [
    {
      "documentUUID": "815a5364-e287-45f4-b881-b65a34aa1896"
    }
  ],
  "documentConfig": {
    "documentFaceMatch": true,
    "documentIaCheck": true,
    "documentBackIaCheck": true,
    "documentFraudAfterRetries": false,
    "documentDigitalForcedAfterRetries": true,
    "documentFraudAfterAll": "REJECT",
    "documentCaptureMethod": "SCOREHUB_SDK"
  }
}

Campo	Descrição
`signatureUUID`	UUID da assinatura geral — guarde para correlacionar com o webhook
`signaturePerson[].signaturePersonUUID`	UUID da assinatura daquela pessoa
`signaturePerson[].signatureStatus`	Status da pessoa — nesta resposta o campo chama-se `signatureStatus`
`signatureDocuments[].documentUUID`	UUID do documento enviado
`documentConfig`	Eco da configuração, já com defaults aplicados

O link de assinatura NÃO vem nesta resposta

A resposta da criação não traz signatureUrl nem URLs de documento — o processamento é assíncrono. O link de assinatura (signatureUrl) e as URLs dos documentos chegam pelo webhook. Campos sem valor são omitidos do JSON.

Grafias diferentes entre criação e webhook

Na criação: signatureUUID, lista signaturePerson (singular) e o status da pessoa em signatureStatus. No webhook: signatureUuid, lista signaturePersons (plural) e o status da pessoa em signaturePersonStatus. Atenção ao mapear os dois contratos.

Os valores possíveis de status estão em Fluxo e status. Veja também Reenviar Notificações e Reenviar Webhook.

Erros

Token inválido
IP não autorizado
Payload inválido

{
  "title": "error.token.invalid",
  "status": "UNAUTHORIZED"
}

HTTP 401. O header Authorization está ausente, ou o token enviado não está cadastrado.

{
  "title": "error.invalid.ip.address",
  "status": "UNAUTHORIZED"
}

HTTP 401. O IP que realizou a requisição não está cadastrado para a empresa. Veja IP Autorizado.

{
  "title": "error.validation",
  "status": 400,
  "fieldErrors": [
    { "objectName": "createSignatureVM", "field": "deadLine", "message": "must not be null" }
  ]
}

HTTP 400. Um ou mais campos obrigatórios ausentes ou inválidos — a lista fieldErrors detalha cada um.

Idempotência​

Payload de envio​

Configurações gerais​

deadLine​

notificationSchedule​

fraudIfInconclusive​

cancelIfFraud​

numberOfRetriesIfFraud​

purpose​

callbackUrl​

documentConfig​

documentFraudAfterAll​

signaturePeople​

notificationType​

documents​

Retorno da criação​

Erros​