> ## 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.

# Plugin KYC WordPress: Verificação de idade no WooCommerce

> Plugin da Didit para WordPress e WooCommerce: verificação de identidade e idade, sem código. Desde $0.33 por KYC completo; $10 grátis/mês.

Adicione verificação de identidade da Didit e controlo de idade a qualquer site WordPress ou loja WooCommerce. O plugin funciona como um proxy de backend seguro: a sua chave de API permanece no servidor. Disponibiliza shortcodes, uma barreira de finalização da compra no WooCommerce e hooks para programadores, para que possa integrar a verificação sem escrever JavaScript.

## Pré-requisitos

* WordPress 6.0 ou superior
* PHP 7.4 ou superior
* Uma conta na [Didit Console](https://business.didit.me)

## Passo 1: Obtenha as suas credenciais da Didit

1. Registe-se ou inicie sessão em **[business.didit.me](https://business.didit.me)**
2. Aceda a **API e Webhooks** e copie a sua **Chave de API**
3. Aceda a **Fluxos**, crie ou selecione um fluxo e copie o **ID do fluxo**

> [!NOTE]
>
> Pode usar um **URL UniLink** para pré-visualizar o fluxo de verificação sem chaves de API.
> Use o modo **API Session** com uma Chave de API e um ID do fluxo para barreiras de conteúdo e requisitos de verificação do WooCommerce.
> A conclusão de um UniLink, por si só, não desbloqueia conteúdo protegido nem aprova uma encomenda.

## Passo 2: Instale o plugin

1. Transfira `didit-verify-0.3.4.zip` a partir da **[versão 0.3.4](https://github.com/didit-protocol/plugin-wordpress/releases/tag/v0.3.4)**
2. No painel de administração do WordPress, aceda a **Plugins → Adicionar novo → Carregar plugin**
3. Escolha o ficheiro ZIP transferido e clique em **Instalar agora**
4. Clique em **Ativar**

> [!NOTE]
>
> O Didit Verify também está listado no [WordPress.org](https://wordpress.org/plugins/didit-verify/).
> Verifique a versão antes de instalar: use a 0.3.4 ou posterior para o comportamento de verificação confirmado pelo servidor descrito aqui.
> A partir da versão 0.3.4, o acesso a conteúdo protegido é revogado quando uma verificação aprovada é posteriormente recusada, expira ou volta à análise.
> Se o diretório tiver uma versão mais antiga, instale o ZIP da versão indicada acima.

> [!WARNING]
>
> Após a atualização a partir de uma versão anterior à 0.3.2, os utilizadores cuja aprovação anterior não tenha sido confirmada pelo servidor devem verificar-se novamente antes de acederem a conteúdo protegido ou concluírem uma finalização de compra que exija verificação.

## Passo 3: Configure o plugin

Aceda a **Definições → Didit Verify**.

### Escolha o seu modo

| Modo | Ideal para | O que é necessário |
| - | - | - |
| **UniLink** | Testes rápidos | Apenas o URL UniLink do seu fluxo |
| **API Session** (recomendado) | Utilização em produção | ID do fluxo + Chave de API |

**Para UniLink:** Defina o Modo como "UniLink", cole o seu URL e guarde.

**Para API Session:** Defina o Modo como "API Session", introduza o seu ID do fluxo e a Chave de API, e guarde.

> [!NOTE]
>
> A chave de API é guardada de forma segura no seu servidor e nunca é exposta aos visitantes.

### Configure as opções de sessão (apenas no modo API)

Estas são definições opcionais que lhe dão mais controlo:

* **Dados do fornecedor**: associa cada verificação a um utilizador específico no seu painel da Didit, para que possa acompanhar quem se verificou. A predefinição é o ID de utilizador do WordPress (por exemplo, `wp-42`). Também pode escolher o e-mail do utilizador, um prefixo personalizado ou desativar esta opção.
* **URL de retorno**: uma página do seu site para onde os utilizadores são redirecionados após a verificação. A Didit acrescenta `verificationSessionId` e `status` como parâmetros de consulta.
* **Método de retorno**: indica qual o dispositivo que trata do redirecionamento: `initiator` (o dispositivo que iniciou), `completer` (o dispositivo que concluiu) ou `both`.
* **Idioma**: escolha entre 54 idiomas ou deixe a deteção automática pelo navegador.

### Configure as opções de apresentação

* **Modo de apresentação**: Modal (sobreposição em pop-up) ou Incorporado (em linha na página)
* **Botão de fechar**: mostrar ou ocultar o botão X no modal
* **Confirmação de saída**: mostrar uma caixa de diálogo "Tem a certeza?" ao fechar
* **Fecho automático**: fechar automaticamente o modal quando a verificação for concluída
* **Registo de depuração**: registar os eventos do SDK na consola do navegador (para resolução de problemas)

### Personalize o botão

Em **Aspeto do botão**, pode alterar:

* Texto do botão e texto de sucesso
* Cor de fundo e cor do texto
* Raio do canto, espaçamento interno e tamanho da fonte

Uma pré-visualização em tempo real é atualizada à medida que altera os valores.

## Passo 4: Adicione a verificação ao seu site

### Para lojas WooCommerce

1. Em **Definições → Didit Verify → WooCommerce**, marque **Exigir verificação de identidade na finalização da compra**
2. Escolha onde aparece a secção de verificação:
   * No topo da página de finalização da compra
   * Após os dados de faturação
   * Após as notas da encomenda
   * Antes de "Finalizar encomenda" (recomendado)
3. Opcionalmente, escolha um **Âmbito de produtos**: todos os produtos (predefinição), apenas os produtos selecionados ou todos os produtos exceto os selecionados.
   Marque os produtos com a caixa **Verificação da Didit** em **Dados do produto → Avançado** no editor de produtos.
   Um carrinho com pelo menos um produto que exija verificação obriga à verificação.
   O âmbito aplica-se tanto à finalização da compra como aos modos pós-compra.
4. Opcionalmente, edite o **Título da Secção**, a **Mensagem de finalização da compra** e a **Mensagem pós-compra** em **Definições → Didit Verify → WooCommerce**. Os campos vazios usam o texto predefinido.
5. Opcionalmente, ative **Enviar dados de faturação** para enviar automaticamente à Didit o nome, o e-mail, o telefone e a morada do cliente, para pré-preenchimento e validação cruzada.

> [!NOTE]
>
> Os códigos de país são convertidos automaticamente do formato alpha-2 do WooCommerce para o formato alpha-3 exigido pela Didit.

Os clientes devem receber uma decisão **Aprovada** confirmada pelo servidor antes de poderem efetuar uma encomenda.
Isto aplica-se tanto à finalização da compra clássica como à finalização da compra em blocos.
O plugin verifica que a sessão pertence ao comprador atual e que ainda não foi utilizada para outra encomenda.
O ID da sessão é guardado na encomenda para referência.

Se escolher **Após a compra**, a encomenda fica em espera até o servidor confirmar a aprovação. Os clientes convidados podem verificar-se a partir da página da encomenda, usando a sua chave de encomenda válida.
Configure o URL do webhook e o segredo apresentados em **Definições → Didit Verify** para que as atualizações de estado assinadas possam libertar as encomendas aprovadas.

### Para qualquer página do WordPress

Adicione este shortcode a qualquer página ou publicação:

```
[didit_verify]
```

Aparecerá um botão de verificação, com o estilo definido em **Aspeto do botão**.

Pode substituir o texto em cada página:

```
[didit_verify text="Verify Now" success_text="Done!"]
```

Ou forçar o modo incorporado numa página específica:

```
[didit_verify mode="embedded"]
```

## Passo 5: Restringir conteúdo a utilizadores verificados (opcional)

Mostrar ou ocultar conteúdo com base no estado da verificação:

Os bloqueios de conteúdo exigem um utilizador com sessão iniciada e uma aprovação confirmada através do modo API Session.
Callbacks do navegador e parâmetros de consulta no redirecionamento não concedem acesso.

```
[didit_gate]
This content is only visible to verified users.
[/didit_gate]
```

Os utilizadores não verificados veem uma mensagem e um botão de verificação. Pode personalizar a mensagem:

```
[didit_gate message="Please verify to continue."]Secret content here.[/didit_gate]
```

Mostrar o estado de verificação do utilizador em qualquer local:

```
[didit_status]
```

Apresenta "Identity Verified" ou "Not Verified" para o utilizador com sessão iniciada.

## Verificar o estado da verificação

| Onde | Como |
| - | - |
| **Painel de administração** | **Users → All Users**: uma coluna "Didit" mostra ✓ junto dos utilizadores verificados |
| **Encomendas do WooCommerce** | O ID da sessão Didit aparece nos detalhes da encomenda |
| **Shortcode** | `[didit_status]` apresenta o estado em qualquer página |

## Resolução de problemas

| Problema | Solução |
| - | - |
| "Creating session..." fica bloqueado | Verifique se o seu Workflow ID e a sua chave de API estão corretos em **Settings → Didit Verify** |
| A janela modal não abre | Confirme que a página contém `[didit_verify]` ou que a verificação no checkout do WooCommerce está ativada |
| Interface de verificação no idioma errado | Altere a definição **Language** em **Session Options** |
| Precisa de depurar | Ative **Debug Logging** em Display Options e, depois, abra a consola do navegador (F12) para ver os eventos do SDK |

## Segurança

O plugin atua como um proxy de backend seguro. A sua chave de API nunca chega ao navegador. Cada pedido de sessão está protegido por:

1. **Nonce CSRF**: os pedidos têm de ter origem no seu site WordPress
2. **Requisito de início de sessão**: apenas utilizadores registados podem criar sessões (configurável)
3. **Limitação de pedidos**: 10 sessões por hora por utilizador, 3 por hora por IP para visitantes
4. **Sanitização de dados de entrada**: todos os campos estão incluídos numa lista de permissões e são sanitizados no servidor

A criação de sessões associa a verificação ao comprador ou à encomenda atual.
O plugin confirma as decisões com a API da Didit ou com um webhook verificado antes de marcar um utilizador ou uma encomenda como aprovados.
O checkout de visitantes pode criar uma sessão quando a verificação é exigida, mesmo que o requisito geral de início de sessão esteja ativado.
A verificação após a compra exige também uma chave de encomenda válida.

***

## Para programadores

### Hooks PHP

O plugin dispara ações do WordPress às quais outros plugins ou temas se podem ligar:

```php theme={null}
// When a user completes verification
add_action('didit_verification_completed', function ($user_id, $session_id, $status) {
    // Update CRM, send email, grant access, etc.
}, 10, 3);

// When a user cancels verification
add_action('didit_verification_cancelled', function ($user_id, $session_id) {
    // Log cancellation
}, 10, 2);

// When a session is created server-side
add_action('didit_session_created', function ($url, $user_id, $vendor_data) {
    // Log, notify, etc.
}, 10, 3);
```

### Evento JavaScript

É disparado um evento DOM quando a verificação termina:

```javascript theme={null}
document.addEventListener('didit:complete', function (e) {
    console.log('Result:', e.detail); // { type, session }
});
```

### Verificar o estado da verificação em PHP

```php theme={null}
$is_verified = Didit_Verify::init()->is_user_verified($user_id);
```

Use este auxiliar para incluir a verificação da confirmação pelo servidor.
Não conceda acesso com base apenas em metadados de utilizador antigos ou no evento `didit:complete` do navegador.

## Recursos

* [Código-fonte do plugin (GitHub)](https://github.com/didit-protocol/plugin-wordpress)
* [Documentação da API da Didit](https://docs.didit.me/pt.md)
* [Didit Console](https://business.didit.me)
* [Referência da API Create Session](https://docs.didit.me/pt/sessions-api/create-session.md)


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