SignXP Docs Acessar minha conta

SignXP Docs

Validação por IA

Quando a sua licença coleta foto do documento ou selfie, o SignXP pode conferir cada imagem com inteligência artificial no momento em que o signatário a envia — antes de deixá-lo seguir para a assinatura.

A validação responde três perguntas:

Verificação O que confere
Documento (frente e verso) Se é mesmo um documento de identificação, se está legível e se o titular confere com o signatário convidado.
Selfie Se há um rosto humano visível e nítido o suficiente para reconhecimento.
Conferência facial Se a pessoa da selfie é a mesma da foto do documento.

Imagem reprovada não passa: o signatário recebe o motivo em português na própria tela e tira outra foto. Você não precisa fazer nada — nem tratar nada na sua integração — para que isso aconteça.

A validação por IA é um recurso contratado por licença e configurado pela equipe SignXP. Se a sua licença não o tem, nada nesta página muda o seu fluxo.

Conferindo a identidade do signatário

Envie tax_id (CPF ou CNPJ) em cada signatário e a IA passa a comparar o número e o nome com o que está impresso no documento fotografado:

{
  "key": "contratante",
  "name": "Maria Souza",
  "email": "maria@empresa.com.br",
  "tax_id": "529.982.247-25"
}

O campo é opcional e aceita máscara. Sem ele, a IA continua conferindo a qualidade e a legibilidade da imagem, mas não tem como saber se o documento é da pessoa certa — nesse caso o próprio signatário informa o número na página de assinatura, e o Termo de Evidências registra que ele foi autodeclarado.

Um tax_id com dígito verificador inválido recusa o envio com 422. É proposital: um número errado no cadastro reprovaria justamente o signatário certo.

Quando a IA não consegue decidir

Duas situações não têm resposta automática: o serviço de IA fica indisponível, ou o signatário esgota as tentativas permitidas para a mesma imagem.

Em ambas, o SignXP não trava o signatário — ele conclui a assinatura normalmente. O que acontece é do lado do documento:

  1. O documento assume o status awaiting_review.
  2. A selagem é retida: não há cópia certificada nem document.completed.
  3. O licenciado confere as imagens e aprova ou recusa — no portal ou pela API, sem sair do seu sistema (veja "Decidindo pela API", abaixo).
Decisão O que você recebe
Aprovada O documento segue para a selagem e você recebe document.completed, como em qualquer conclusão.
Recusada O documento é encerrado e você recebe document.rejected, com o motivo escrito pelo licenciado.

Ou seja: um documento em awaiting_review ainda pode virar qualquer um dos dois desfechos. Trate-o como pendente, nunca como concluído.

Decidindo pela API, sem sair do seu sistema

Se o seu software já é a tela que o cliente final usa, mandá-lo ao nosso portal para destravar um contrato é uma quebra no meio do fluxo. A conferência inteira cabe na API — achar, abrir, ver as fotos e decidir:

GET  /api/v1/reviews
GET  /api/v1/documents/{id}/signers/{signer_id}/review
GET  /api/v1/documents/{id}/signers/{signer_id}/review/images/{kind}
POST /api/v1/documents/{id}/signers/{signer_id}/review/approve
POST /api/v1/documents/{id}/signers/{signer_id}/review/reject

A fila traz o que está esperando na sua licença, mais antigo primeiro — é a ordem em que os contratos ficaram parados:

{
  "data": [
    {
      "document": { "id": 128, "external_id": "contrato-2026-0001", "title": "Contrato", "status": "awaiting_review" },
      "signer": { "id": 91, "key": "contratante", "name": "Maria Souza", "email": "maria@empresa.com.br", "tax_id": "529.982.247-25", "tax_id_self_declared": false, "signed_at": "2026-08-03T14:02:11-03:00" },
      "reasons": ["O serviço de validação não respondeu."],
      "ai_checks": { "document": { "status": "unverified" } },
      "images": {
        "document_front": "https://arquivos.signxp.com.br/...",
        "document_back": null,
        "selfie": "https://arquivos.signxp.com.br/..."
      },
      "images_expire_at": "2026-08-03T14:20:00-03:00",
      "images_purged_at": null,
      "waiting_since": "2026-08-03T14:05:00-03:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}

As imagens

Cada chave de images traz a URL da foto ou null quando ela não existe. São links assinados e temporários, servidos direto do nosso armazenamento: a imagem não passa pelo corpo da resposta, não vai para o seu log e o endereço morre em 15 minutos (images_expire_at).

Quando o link expirar antes de a pessoa decidir, peça outro — um de cada vez:

GET /api/v1/documents/128/signers/91/review/images/selfie

{ "url": "https://arquivos.signxp.com.br/...", "expires_at": "2026-08-03T14:35:00-03:00" }

Os valores de {kind} são document_front, document_back e selfie. Uma imagem que essa evidência não tem responde 404.

images_purged_at preenchido significa que não há mais o que olhar. As imagens de evidência têm prazo de retenção; passado ele, são descartadas e o pedido de imagem responde 410. A pendência continua decidível — só que sobre o resto da evidência, não sobre a foto.

A conferência e as imagens só respondem por assinaturas que passaram pela validação manual. Um signatário que nunca entrou na fila responde 404: esta é uma porta para destravar o que a IA não resolveu, não um jeito de baixar as imagens de qualquer assinatura da licença.

Abrindo uma pendência específica

Recebeu document.awaiting_review no callback? Vá direto nela, sem paginar a fila atrás do documento:

GET /api/v1/documents/128/signers/91/review

A resposta é a mesma linha da fila, mais o veredito — e ela continua respondendo depois de decidida, com quem decidiu, quando e o que escreveu:

{
  "review_status": "approved",
  "reviewed_at": "2026-08-03T14:31:07-03:00",
  "reviewed_by": "ana@meu-erp.com.br",
  "note": "Documento confere com o cadastro."
}

Decidindo

A decisão leva quem decidiu:

{ "reviewer": "ana@meu-erp.com.br", "note": "Documento confere com o cadastro." }
Campo Aprovar Recusar
reviewer obrigatório obrigatório
note opcional obrigatório — vira o motivo comunicado às partes

A resposta diz no que o documento parou:

{ "review_status": "approved", "document_status": "completed" }

Aprovar solta a selagem retida e o document.completed sai como em qualquer conclusão. Recusar encerra o documento, avisa todas as partes e dispara document.rejected.

reviewer vai para o Termo de Evidências. É o nome que constará como responsável pela conferência, ao lado da data e da observação. Mande quem de fato decidiu no seu sistema — uma aprovação sem responsável não é evidência de nada. Nós não temos como conferir esse nome: a responsabilidade por ele é sua.

Decidir duas vezes sobre a mesma assinatura devolve 422: só o que está realmente pendente pode ser decidido.

O que a sua integração precisa fazer

Se você já trata completed e rejected, o essencial continua funcionando. Duas recomendações:

  • Aceite o status awaiting_review na consulta de status sem tratá-lo como erro. Ele significa "assinado, aguardando conferência humana".
  • Escute o evento document.awaiting_review se você acompanha o documento por callback. Sem ele, um documento retido para conferência parece simplesmente parado — e a espera pode durar horas ou dias, porque depende de uma pessoa.
{
  "event": "document.awaiting_review",
  "id": 128,
  "external_id": "contrato-2026-0001",
  "status": "awaiting_review",
  "completed_at": null,
  "signers": [
    { "key": "contratante", "email": "maria@empresa.com.br", "status": "signed", "signed_at": "2026-07-28T13:58:02-03:00" }
  ]
}

O que fica registrado

O Termo de Evidências anexado ao PDF final traz o resultado de cada verificação — aprovada, reprovada ou não verificada —, o modelo usado e o número de tentativas. Quando houve conferência humana, ele registra também quem decidiu, quando e a observação escrita.

Uma imagem liberada por indisponibilidade do serviço nunca aparece como "aprovada": o Termo não afirma o que ninguém conferiu.