Saiba quem é o seu cliente, sem guardar o documento dele

1. Obtenha um cliente

Registramos o seu cliente — um client id e um secret, exibido uma única vez —, um plano (nível, dados e a finalidade que a pessoa vai ler) e as suas redirect URIs: uma página https, o esquema do seu próprio app (yourapp://verify) ou ambos. Todo cliente recebe um ambiente de testes dedicado antes de entrar em produção.

2. Envie a solicitação a partir do seu backend

Nunca de um navegador ou de um app: o secret fica no seu servidor. Você recebe um link de uso único, válido por dez minutos; depois de aberto, a pessoa tem uma hora para concluir.

POST https://api.ism.ec/verify/v1/par
{
  "client_id":     "cl_…",
  "client_secret": "…",
  "plan_id":       "bn_…",
  "redirect_uri":  "yourapp://verify",
  "state":         "<aleatório, guardado na sua sessão>"
}

→ { "req": "…", "verify_url": "https://id.ism.ec/go?req=…", "expires_at": "…" }

3. A pessoa se verifica

Abra o link no celular dela, mostre-o como QR code em um computador ou envie-o pelo canal que você já usa para falar com o seu cliente. O link leva apenas uma referência opaca — sem cliente, sem escopo, sem dados pessoais.

4. De volta para você

Quando a pessoa termina, o ID Protekt abre a sua redirect_uri com ?code=…&state=…. Confira se o state é o mesmo que você guardou.

5. Recolha a resposta

Troque o code imediatamente: ele é de uso único, vale 120 segundos e só o cliente para o qual foi emitido pode resgatá-lo. As credenciais vão no corpo ou como HTTP Basic.

POST https://api.ism.ec/verify/v1/token
{ "client_id": "cl_…", "client_secret": "…", "code": "<do redirect>" }

→ {
    "claims":             { "subject_is": true },
    "assurance":          "L4",
    "verified_by":        "device",
    "device_attestation": "…",
    "verified_at":        "…",
    "consent_receipt_id": "…",
    "state":              "…"
  }

A pessoa não voltou? A resposta chega mesmo assim

Registre um webhook e o seu backend fica sabendo de cada resultado — concluído, recusado ou com falha —, mesmo quando a pessoa termina no app ID Protekt e nunca volta, ou começou em um computador. Cada evento é assinado com o seu próprio secret whsec_ (ISM-Signature, HMAC-SHA256), leva a referência da solicitação e nenhum dado pessoal, e é reenviado por cerca de um dia. Depois, busque o resultado pela referência, em até 24 horas:

POST https://api.ism.ec/verify/v1/token
{
  "client_id":     "cl_…",
  "client_secret": "…",
  "grant_type":    "request",
  "req":           "<do webhook>"
}

A resposta é liberada uma única vez, pelo code ou pela referência, o que vier primeiro.

Leia o dado, não o status. Uma verificação concluída não é uma aprovação: subject_is: false é uma recusa, e um dado ausente não foi provado. Mantenha aberta a sessão da pessoa, para que, se ela não voltar, possa simplesmente tentar de novo.