> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Carteiras de identidade digital: APIs de verificação

> Verifique a identidade por carteira de identidade digital na sua aplicação com as APIs da Didit, sem criar um fluxo de verificação.

Use um endpoint dedicado de carteira para verificar uma pessoa a partir da sua própria aplicação.
Você não precisa criar nem publicar um fluxo de verificação (workflow), nem informar um `workflow_id`.
O seu backend inicia a verificação e obtém o resultado; a sua interface conduz a pessoa pela autenticação exigida pela carteira.

> [!NOTE]
>
> Uma integração via API continua exigindo que a pessoa se autentique e aprove o compartilhamento da sua identidade.
> Não é possível verificar alguém enviando o identificador pessoal dessa pessoa sem essa interação.

## Como a verificação funciona

1. O seu backend consulta o [catálogo de carteiras](https://docs.didit.me/pt-br/standalone-apis/digital-id-wallet-catalog.md) e, em seguida, chama o endpoint de início de uma carteira disponível usando a chave de API da sua aplicação.
2. A Didit retorna uma referência da verificação e a ação que a pessoa precisa realizar.
3. A sua aplicação abre a página de autenticação ou exibe as instruções de aprovação da carteira.
4. A pessoa se autentica com a sua carteira.
5. O seu backend obtém o resultado da verificação e trata as notificações de conclusão.

A autenticação por carteira é assíncrona.
Uma requisição de início bem-sucedida significa que a autenticação começou; não significa que a identidade foi verificada.
Sempre confira o resultado final antes de tratar a pessoa como verificada.

## Integração no backend

Use [Listar carteiras de identidade digital](https://docs.didit.me/pt-br/standalone-apis/digital-id-wallet-catalog.md) para obter os endpoints atuais, os campos obrigatórios e a disponibilidade para a sua aplicação.

Mantenha a sua `x-api-key` no backend.
Não a coloque em um bundle de navegador nem em uma aplicação mobile.
Use uma `Idempotency-Key` distinta para cada nova tentativa de verificação e reutilize essa chave ao tentar novamente a mesma requisição de início.
Alterar a requisição reutilizando a chave dela é um conflito, não uma nova tentativa de verificação.

Cada carteira tem sua própria URL de início, como `/v3/id-verification/wallets/ftn/` para a Finnish Trust Network.
O `request_id` identifica a verificação independente nas operações seguintes.
Use `vendor_data` para a sua própria referência, com até 2.000 bytes UTF-8, e `metadata` para um objeto JSON opcional.
Ambos são retornados no resultado e no webhook de conclusão.

| Operação | Endpoint |
| - | - |
| Ler status e resultado | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Consultar uma aprovação por telefone | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Enviar a resposta de uma carteira de Credenciais Digitais | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Cancelar uma verificação pendente | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

Essas operações usam a chave de API da aplicação que iniciou a verificação.
A consulta periódica (polling) e a disponibilidade da autenticação dependem da carteira selecionada.

Um cancelamento recusa uma verificação pendente sem cobrar por ela e retorna uma verificação concluída sem alterações.
Para Smart-ID e Mobile-ID, um cancelamento que chega enquanto uma consulta está verificando a aprovação aguarda alguns segundos por essa consulta.
Em seguida, ele recusa a verificação ou a retorna como `verified` se a pessoa já tiver aprovado.
Uma verificação que a pessoa está concluindo naquele momento não pode ser cancelada: a resposta é `409` com `error: "verification_in_progress"` e um cabeçalho `Retry-After`.
Tente novamente depois desse número de segundos para ler o resultado concluído.

## Registre o seu destino de retorno

Carteiras com redirecionamento enviam a pessoa de volta à sua aplicação após a autenticação.
Registre o hostname exato antes de iniciar uma verificação:

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

Depois, envie uma `return_url` HTTPS, como `https://app.example.com/identity/complete`, na requisição de início.
Use apenas hostnames em `allowed_return_hosts`, sem esquema, caminho ou curinga.
Registre separadamente cada subdomínio que você usa, até 20 hostnames.
Atualizar `allowed_return_hosts` substitui a lista registrada, então inclua todos os hostnames que deseja manter.
`GET /v3/webhook/` retorna a lista atual; consulte [Configuração de webhook](https://docs.didit.me/pt-br/sessions-api/management-api.md#configuração-de-webhook).
Você não precisa de um fluxo nem de um domínio de marca própria para registrar um destino de retorno.
O destino é uma página de retorno no navegador; configure os webhooks de conclusão separadamente para o seu backend.

## Exemplo: Finnish Trust Network

Depois de registrar o seu hostname de retorno, inicie uma verificação pela Finnish Trust Network:

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

Salve o `request_id` retornado e envie o navegador da pessoa para `wallet_verification.next_action.url` quando o `type` da ação for `redirect`.
Depois que a pessoa retornar, obtenha o resultado a partir do seu backend:

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

Confira `wallet_verification.outcome`:

| Resultado | Significado |
| - | - |
| `pending` | A autenticação ainda está em andamento. |
| `verified` | A autenticação foi concluída e a identidade retornada está verificada. |
| `cancelled` | A pessoa ou a sua aplicação cancelou a tentativa. |
| `timeout` | A janela de autenticação expirou. |
| `failed` | A autenticação ou a validação da identidade falhou. |

Use a identidade somente quando o resultado for `verified` e `simulated` for `false`, no caso de uma verificação de identidade real.
Uma resposta pendente pode trazer uma próxima ação; respostas finais não têm próxima ação.

## Experiências de autenticação

**Carteiras com redirecionamento** retornam uma URL de autenticação.
Abra essa URL no navegador da pessoa, deixe que ela conclua o processo de autenticação da carteira e leve-a de volta ao destino que você registrou.
Leia o resultado pelo seu backend em vez de confiar em um parâmetro da URL de retorno como prova de identidade.

**Smart-ID e Mobile-ID** usam uma solicitação de aprovação no celular da pessoa.
Sua interface coleta o identificador pessoal exigido; o Mobile-ID também precisa do número de telefone associado.
Exiba o código de comparação e oriente a pessoa a aprovar somente quando ele corresponder ao código mostrado no celular dela.
O PIN dela deve ser digitado na carteira ou na solicitação do celular, nunca no seu formulário nem em uma requisição de API.
Faça polling pelo seu backend no intervalo `poll_interval_seconds` retornado para acompanhar a solicitação.
A Didit também verifica em segundo plano as aprovações pendentes no celular, então a conclusão pode chegar ao seu webhook depois que a pessoa fechar sua página.

O **Google Wallet** é solicitado pela sua própria página ou aplicativo por meio da Digital Credentials API, sem redirecionamento; consulte [Carteiras Digital Credentials (Google Wallet)](#carteiras-de-credenciais-digitais-google-wallet).

A interação disponível depende da carteira selecionada.
Não presuma que toda carteira oferece suporte a formulário incorporado, QR code ou autenticação sem navegador.

## Carteiras de credenciais digitais (Google Wallet)

O Google Wallet é acionado diretamente pela sua página web ou pelo seu aplicativo Android, usando a W3C Digital Credentials API.
Não há redirecionamento, nem página hospedada pela Didit, nem QR code da Didit.
Ele está como **Em breve** em produção: funciona com aplicações de sandbox e em staging, e o acesso em produção depende da aprovação do Google.
Consulte [Listar carteiras de identidade digital](https://docs.didit.me/pt-br/standalone-apis/digital-id-wallet-catalog.md) para ver o que sua aplicação já pode iniciar.

**1. Inicie com a sua origem**

Seu backend chama `POST /v3/id-verification/wallets/google-wallet/` com o `country` da pessoa (`USA`, `GBR`, `BRA`, `SGP` ou `TWN`) e o `origin` que vai acionar a carteira.
O `origin` é a origem HTTPS da sua página, como `https://app.example.com`, cujo host deve ser um dos seus [hostnames de retorno registrados](#registre-o-seu-destino-de-retorno) ou o seu domínio de marca própria.
Para um aplicativo Android, é `android:apk-key-hash:` seguido do SHA-256 em base64 do certificado de assinatura do seu aplicativo, sem padding.
A carteira recusa uma requisição feita a partir de qualquer outra origem.
Não há `return_url`.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**2. Acione a carteira em resposta a um gesto do usuário**

A resposta contém `wallet_verification.interaction = "digital_credentials"` e `next_action.type = "request_digital_credential"`.
Passe `next_action.digital_credentials.request` para o navegador ou para o Android Credential Manager, a partir de um toque ou clique no `origin` com que você iniciou.
No desktop, o navegador exibe o próprio QR code quando a carteira está em outro dispositivo.

**3. Envie o que a carteira retornou**

Envie o `{protocol, data}` retornado ao seu backend e, de lá, para `POST /v3/id-verification/wallets/verifications/{request_id}/response/` como `{"response": {...}}`.
A requisição pode ser enviada uma única vez; um segundo envio retorna a verificação já concluída.

**4. Leia o resultado**

A resposta do envio é a verificação concluída.
Você também pode lê-la com `GET /v3/id-verification/wallets/verifications/{request_id}/` ou recebê-la no webhook de conclusão.

No navegador, acione a carteira a partir de um handler de clique:

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

Ofereça o método somente onde o navegador oferecer suporte, por exemplo quando `"DigitalCredential" in window` for verdadeiro.
`navigator.credentials.get` deve ser executado em um gesto do usuário, então chame-o a partir do handler de clique, e não depois de uma etapa assíncrona.

No Android, use o Jetpack Credential Manager (`androidx.credentials` 1.5.0 ou posterior) com a mesma requisição:

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

Erros a tratar:

| Erro | Onde | Significado |
| - | - | - |
| `origin_invalid` | Início, `400` | `origin` não é uma origem HTTPS nem uma origem de aplicativo Android. |
| `origin_not_allowed` | Início, `400` | O host da origem não está registrado para a sua aplicação. Registre-o em `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Envio, `409` | Esta verificação não aceita uma resposta de carteira. |

Uma credencial que não passa na verificação gera uma verificação concluída com resultado `failed`, e não uma resposta de erro.
Somente os campos solicitados pela verificação saem da carteira, e o resultado contém os atributos de identidade que a carteira retornou.
Um passe de identidade do Google Wallet ou uma carteira de motorista digital de um estado dos EUA não retorna foto do rosto.

Em uma aplicação de sandbox, o fluxo é simulado com as mesmas etapas e retorna `simulated: true`.
Qualquer resposta enviada define o resultado da verificação de acordo com o `sandbox_scenario`, então você pode construir toda a jornada no navegador ou no aplicativo sem uma credencial real.

## Webhooks de conclusão

Configure um destino do webhook da aplicação para `status.updated` usando o [guia de integração de webhooks](https://docs.didit.me/pt-br/integration/webhooks.md).
Use `webhook_version: "v3"` para obter a estrutura de decisão descrita aqui.
Verifique a assinatura do webhook no seu backend antes de processá-lo.
O `session_id` do webhook corresponde ao `request_id` retornado pela API de carteira.
Uma identidade de carteira concluída aparece no array `decision.id_verifications` do webhook com `verification_method: "wallet"`.
Você também pode usar o identificador para obter o resultado da API dedicada de carteira.

Trate as notificações de aprovação e de recusa, incluindo verificações canceladas e expiradas.
Torne o handler do seu webhook idempotente, porque entregas com falha são reenviadas.
Um retorno pelo navegador não é um webhook de conclusão, e seus parâmetros de consulta não são prova de identidade.

## Identidade retornada

Use os campos de identidade normalizados para nomes e datas de nascimento quando esses campos forem retornados.
Os atributos específicos de cada carteira descrevem as informações de identidade compartilhadas pela carteira selecionada.
Os atributos disponíveis variam conforme a carteira e o país.
Uma identidade autenticada não significa que um retrato, o endereço ou qualquer outro atributo solicitado esteja disponível.

## Testar no sandbox

Uma aplicação no modo sandbox da Didit simula a verificação por carteira sem contatar um provedor de carteira e sem consumir créditos.
A resposta identifica essas requisições com `wallet_verification.simulated: true`.
Uma aprovação simulada são dados de exemplo, não uma identidade real verificada.

Para uma carteira com redirecionamento, acesse a URL retornada para testar o callback e voltar à sua aplicação.
Para Smart-ID ou Mobile-ID, use o endpoint de polling para concluir a aprovação simulada; nenhuma notificação é enviada a um telefone.
Para testar o tratamento de falhas, defina `sandbox_scenario` como `wallet_cancelled`, `wallet_timeout` ou `wallet_provider_error` ao iniciar uma requisição.
Aplicações em produção rejeitam `sandbox_scenario`.

A simulação no sandbox da Didit é diferente de testar no ambiente de testes do próprio provedor.
Uma simulação bem-sucedida não garante acesso ao provedor em produção nem disponibilidade em produção.

### Sandbox do provedor ConnectID

O sandbox do provedor ConnectID usa bancos de teste e é diferente da simulação no sandbox da Didit.
Quando o acesso ao sandbox do provedor estiver configurado para a sua integração, envie o `authorisation_server_id` do banco selecionado ao [endpoint de início do ConnectID](https://docs.didit.me/pt-br/api-reference/digital-id-wallets/connectid.md).
Use o ID retornado pelo seletor de bancos do ConnectID; não envie a URL de um banco nem um emissor arbitrário.
Se você omitir o campo, o banco de teste padrão será selecionado.
O campo é específico do ConnectID e não altera os atributos de identidade solicitados.

O pacote inicial solicita nome, sobrenome e data de nascimento.
Siga o `next_action` retornado para se autenticar e, em seguida, recupere o resultado da verificação ou consulte-o por polling.
Somente um resultado concluído com status aprovado confirma que a verificação foi bem-sucedida; o retorno à sua aplicação não confirma isso.
O ConnectID continua como **Coming soon** em produção enquanto o onboarding e a certificação são concluídos.

## Disponibilidade e preços

A cobertura de endpoints e a ativação das carteiras em produção são coisas distintas.
Uma carteira pode ter uma página de referência da API e continuar indisponível para autenticação em produção.
Verifique a cobertura de países e o status de produção da carteira antes de implementar uma jornada em produção.

Consulte os [preços das carteiras de identidade digital](https://docs.didit.me/pt-br/getting-started/pricing.md#preços-das-carteiras-de-identidade-digital) para ver as tarifas publicadas e a disponibilidade.
A verificação de carteira é faturada separadamente da captura de documentos.

## Como escolher uma integração

Use estas APIs quando quiser controlar a interface e a lógica da aplicação ao redor da verificação.
Use a [Sessions API](https://docs.didit.me/pt-br/sessions-api/create-session.md) quando quiser a jornada de verificação hospedada da Didit, as regras do fluxo de verificação (workflow) e as etapas alternativas configuradas.
Nas duas abordagens, o processo de autenticação e consentimento da carteira continua sendo obrigatório.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.