Documentação para Desenvolvedores | API & Guia de Integração - Implementação padrão

Exemplos de implementação

A Go.cam fornece dois exemplos padrão de implementação, disponíveis em PHP e JavaScript.

Verificação através da biblioteca de redirecionamento

Esta implementação gera uma URL de verificação Go.cam com base nas suas chaves de acesso.

Pode ser utilizada em modo autónomo se a verificação de idade tiver de ser executada numa nova janela do navegador ou através de um redirecionamento.

Este método foi concebido para ser simples e fácil de seguir. Abaixo encontra-se um guia passo a passo.

Dica: Uma implementação de exemplo pode ser descarregada a partir da sua conta Go.cam.

Passo 1: Incluir o SDK PHP


require_once 'avsPhpSdkV1.php';

Passo 2: Inicializar o SDK

Obtenha as credenciais necessárias a partir da sua conta Go.cam e edite o ficheiro config.php.


$config['partnerId'] = 0;
$config['cipherKey'] = '';
$config['hmacKey']   = '';

Inicialize a classe SDK no ficheiro index.php.


$avsInstance = new AvsPhpSdkV1(
	$config['partnerId'],
	$config['cipherKey'],
	$config['hmacKey']
);

Passo 3: (Opcional) Definir o idioma

Por predefinição, a página de teste é apresentada em inglês. Idiomas suportados:

Inglês, francês, alemão, neerlandês, italiano, português, espanhol


$avsInstance->setLanguage(AvsPhpSdkV1::LANGUAGE_EN);

Passo 4: Definir o payload do pedido

A Go.cam utiliza encriptação AES-256-CBC para uma comunicação segura.

Para cada sessão, deve definir o payload, que pode incluir parâmetros obrigatórios e opcionais.

Exemplo:


$avsInstance->fillRequest([
        'userData' => [
        // obrigatório: id interno do utilizador do parceiro, utilizado para acompanhar o utilizador
        'userId' => $userId,
        // opcional: alguns dados personalizados que o parceiro pretende incluir nesta sessão de verificação
        'someCustomData' => true,
        // opcional: cores personalizadas para a interface do processo de verificação Go.cam
        'colorConfig' => [
			'body' => [
				'background' => $colorConfigBodyBackground,
				'foreground' => $colorConfigBodyForeground,
				'button' => [
					'background' => $colorConfigButtonBackground,
					'foreground' => $colorConfigButtonForeground,
					'foregroundCallToAction' => $colorConfigButtonForegroundCTA,
					'backgroundFailure' => $colorConfigButtonBackgroundFailureInput,
					'foregroundFailure' => $colorConfigButtonForegroundFailureInput,
					'foregroundCallToActionFailure' => $colorConfigButtonForegroundCTAFailureInput,
				]
			],
		] // opcional
    ],
    'http' => [
        'userAgent' => $userAgent,
        'websiteHostname' => $websiteHostname,
        'paramList' => [
			// opcional: uma forma de controlar se o número da idade detetada é mostrado no ecrã durante o processo de verificação de idade por selfie
			'showDetectedAgeNumber' => $showDetectedAgeNumber,
			// opcional: o tipo de verificação que pretende mostrar ao utilizador
			// se não for especificado como parâmetro ou estiver vazio todos os tipos ficarão visíveis
			'verificationTypeList' => array('creditCard', 'selfie', 'scanId', 'email'),
			// opcional: o tipo de verificação que pretende selecionar por predefinição
			'verificationTypeDefault' => 'selfie',
			// opcional: utilizar a verificação por email como fallback caso a primeira verificação escolhida falhe
			'useEmailAsFallbackVerification' => true,
			// opcional: uma forma de controlar se a deteção por selfie utilizará liveness avançado (usa várias verificações para detetar se a pessoa na webcam é real)
			'advancedLiveness' => $advancedLiveness,
        ]
    ],
	// opcional: a versão de verificação Go.cam
	'verificationVersion' => AvsPhpSdkV1::VERIFICATION_VERSION_STANDARD_V1,
	// obrigatório: a URL para regressar ao site do parceiro após uma verificação
	'linkBack' => $linkBack,
	// opcional: ip do utilizador
	'ipStr' => $userIp,
	// opcional: código ISO do país do utilizador
	'countryCode' => $countryCode,
	// opcional: código ISO do estado do utilizador (usado principalmente para os EUA)
	'stateCode'  => $stateCode,
]);

Passo 5: Gerar a URL de verificação


$verificationUrl = $avsInstance->toUrl();

Passo 6: Adicionar um link no seu website


"$verificationUrl; ?>" target="_blank">Iniciar verificação de idade

A URL de postback deve apontar para o seu backend, onde irá tratar os dados de callback enviados pela Go.cam. Consulte a Referência de Dados de Callback do Backend para mais detalhes.

Verificação utilizando a biblioteca iframe

A biblioteca iframe baseia-se na biblioteca de redirecionamento, mas permite que a Go.cam seja executada como um iframe em overlay. Também fornece controlo do ciclo de vida e tratamento de eventos para o processo de verificação.

Dica: Uma implementação de exemplo pode ser descarregada a partir da sua conta Go.cam.

Passo 1: Gerar a URL do iframe

Em vez de toUrl(), chame:


$verificationUrl = $avsInstance->toIframeUrl();

Passo 2: Incluir o SDK Frontend

Passo 3: Adicionar um botão de ativação

Passo 4: Inicializar o SDK Frontend


var openVerificationIframeButton = document.querySelector('#openVerificationIframeButton');
var iframeUrl = ''; // gerado a partir do PHP acima

AvsJsSdk.V1.Config.create({ iframeLocationUrl: iframeUrl });

var avsInstance = new AvsJsSdk.V1.Core();
avsInstance.init();

Passo 5: Tratar os eventos do SDK

O SDK dispara eventos durante o processo de verificação. Pode escutá-los e reagir a eles:


avsInstance.onMessage = function (eventMessage) {
	switch (eventMessage.name) {

		// fase de verificação: o iframe foi carregado
		case AvsJsSdk.V1.Config.EVENT_ON_CHECK_IFRAME_LOADED:

			// envia um evento para o iframe para iniciar a fase de verificação do processo
			avsInstance.emit(AvsJsSdk.V1.Config.EVENT_STATUS_REQUEST);

			break;

		// fase de verificação: a verificação de idade foi bem-sucedida num processo anterior, o utilizador já está verificado
		case AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_SUCCESS:

			// o payload de verificação é válido
			if (eventMessage.data.isPayloadValid) {
				// desativa o botão "iniciar verificação"
				openVerificationIframeButton.disabled = true;
				return;
			}

			// o payload de verificação não é válido, continuar com o processo de verificação
			avsInstance.emit(AvsJsSdk.V1.Config.EVENT_RESOURCE_PRELOAD);

			break;

		// fase de verificação: a verificação de idade não foi bem-sucedida num processo anterior ou não foi executada
		case AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_NOT_FOUND:

			// a fase de verificação falhou, prosseguir para a fase de verificação, enviar um evento para iniciar o pré-carregamento dos recursos
			avsInstance.emit(AvsJsSdk.V1.Config.EVENT_RESOURCE_PRELOAD);

			break;

		// fase de verificação: os recursos do iframe foram carregados
		case AvsJsSdk.V1.Config.EVENT_ON_RESOURCES_LOADED:

			// ativa o botão "iniciar verificação"
			openVerificationIframeButton.disabled = false;

			// adiciona um evento de clique ao botão "iniciar verificação"
			openVerificationIframeButton.addEventListener('click', function () {
				// mostra o iframe de verificação como overlay
				avsInstance.iframeInstance.expand();
			});

			break;

		// fase de verificação: foi clicado o botão de fechar do overlay iframe
		case AvsJsSdk.V1.Config.EVENT_ON_CLOSE_IFRAME:

			// oculta o overlay do iframe de verificação (continua em execução em segundo plano)
			avsInstance.iframeInstance.collapse();

			break;

		// fase de verificação: o processo de verificação foi bem-sucedido
		case AvsJsSdk.V1.Config.EVENT_ON_VERIFICATION_SUCCESS:

			// desativa o botão "iniciar verificação"
			openVerificationIframeButton.disabled = true;

			break;

		}

	}

Referência de Eventos do SDK Frontend

Ao utilizar a biblioteca iframe, o SDK pode disparar os seguintes eventos:

EVENT_ON_CHECK_IFRAME_LOADED – Documento iframe pronto.
EVENT_STATUS_REQUEST – Solicitar o estado atual da verificação.
EVENT_ON_INITIAL_VERIFICATION_SUCCESS – Verificação anterior encontrada (cookie presente).
EVENT_ON_INITIAL_VERIFICATION_NOT_FOUND – Nenhuma verificação encontrada.
EVENT_RESOURCE_PRELOAD – Iniciar o carregamento dos recursos de verificação.
EVENT_ON_INITIAL_VERIFICATION_FATAL_ERROR – Chaves inválidas ou falha no carregamento de recursos.
EVENT_ON_START_PAGE_LOADED – Página de verificação carregada (os recursos ainda estão a carregar).
EVENT_ON_RESOURCES_LOADED – Recursos de verificação totalmente carregados.
EVENT_ON_CLOSE_IFRAME – Overlay iframe fechado.
EVENT_ON_VERIFICATION_SUCCESS – Verificação bem-sucedida.
EVENT_ON_VERIFICATION_ERROR – Falha na verificação.

Dados da URL de Callback do Backend

Após cada tentativa de verificação (sucesso ou falha), a Go.cam envia um postback servidor-a-servidor para notificar o seu backend do resultado.

O postback é entregue como um array com campos que descrevem a sessão de verificação e o seu resultado.

Exemplo de Payload


[
    'userData' => [
        'userId' => 123,
        'colorConfig' => [
            'body' => [
                'background' => '#900',
                'foreground' => '#fff',
                'button' => [
                    'background' => '#fb0',
                    'foreground' => '#333',
                    'foregroundCallToAction' => '#700',
                    'backgroundFailure' => '#fb0',
                    'foregroundFailure' => '#333',
                    'foregroundCallToActionFailure' => '#700',
                ]
            ]
        ]
    ],
    'state' => 'Success',
    'stateInt' => 2,
    'sessionId' => 12345,
    'errorCode' => 0,
    'deviceType' => 1,
    'stepId' => 2,
    'websiteHostname' => 'your-site-name.cam',
    'ip' => '127.0.0.1',
]

Referência dos Campos

state

Indica se a verificação foi bem-sucedida.

Valor possível	Significado
Success	a verificação foi bem-sucedida
Fail	a verificação falhou

stateInt

Representação numérica do estado da verificação.

Valor possível	Significado
0	desconhecido
1	Teste não iniciado ou abortado
2	Sucesso
3	Falhou
4	Link expirado
5	Link já utilizado

sessionId

Identificador único da sessão de verificação.

Exemplo: 12345

errorCode

Código de erro caso a verificação tenha falhado.

Valor possível	Significado
0	Sem erro
25001	O dispositivo não é suportado
25032	Falha no pré-carregamento dos recursos de verificação (recursos face api)
25033	Falha no pré-carregamento dos recursos de verificação (recursos tesseract)
25034	Não foi possível obter a lista de câmaras do seu dispositivo (etapa de seleção de câmara da deteção selfie)
25055	Não foi possível detetar rostos suficientes no vídeo do dispositivo (idade detetada é 0)
25056	Falha na verificação de similaridade facial (comparação de todos os rostos selfie)
25057	Não foi possível detetar rostos suficientes no vídeo do dispositivo (0 rostos detetados)
25070	Nenhum rosto detetado
25061	Não foi possível detetar rostos suficientes no vídeo do dispositivo (falha na verificação de expressão)
25062	Falha na verificação de similaridade facial (comparação de rostos de expressão)
25047	Erro de inicialização da webcam (etapa de deteção selfie)
25035	Falha ao inicializar as bibliotecas de deteção (etapa de deteção selfie -> detector face api)
25036	Falha ao inicializar as bibliotecas de deteção (etapa de deteção selfie -> modelo de idade face api)
25037	Falha ao inicializar as bibliotecas de deteção (etapa de deteção selfie -> modelo de reconhecimento face api)
25038	Falha ao inicializar as bibliotecas de deteção (etapa de deteção selfie -> modelo de landmarks face api)
25058	Falha ao inicializar as bibliotecas de deteção (etapa de deteção selfie -> modelo de expressão face api)
25067	Falha na verificação de correspondência facial de liveness
25069	Falha na verificação de correspondência facial de liveness
25085	Falha na verificação de correspondência facial de liveness
25086	Falha na verificação de correspondência facial de liveness
25068	Falha na verificação de liveness
25039	Não foi possível obter a lista de câmaras do seu dispositivo (etapa de seleção de câmara da deteção de documento)
25040	Falha ao inicializar as bibliotecas de deteção (etapa de deteção de documento -> worker tesseract)
25041	Falha ao inicializar as bibliotecas de deteção (etapa de deteção de documento -> modelo de idioma tesseract)
25042	Falha ao inicializar as bibliotecas de deteção (etapa de deteção de documento -> inicialização de idioma tesseract)
25043	Falha ao inicializar as bibliotecas de deteção (etapa de deteção de documento -> configuração do worker tesseract)
25044	Falha ao inicializar as bibliotecas de deteção (etapa de deteção de documento -> detector face api)
25045	Falha ao inicializar as bibliotecas de deteção (etapa de deteção de documento -> modelo de reconhecimento face api)
25091	Falha ao inicializar as bibliotecas de deteção (etapa de deteção de documento -> modelo yolo)
25051	Falha ao extrair um rosto do seu cartão de identidade
25052	O rosto selfie não corresponde ao encontrado no cartão de identidade
25053	A idade detetada é inferior a 18 anos (etapa de deteção de documento)
25075	A idade detetada é inferior a 18 anos (etapa de deteção selfie)
25054	Falha ao extrair a sua idade do cartão de identidade atual
25090	Falha ao extrair a sua idade do cartão de identidade atual (etapa yolo)
25046	Erro de inicialização da webcam (etapa de deteção de documento)
20056	Dados submetidos inválidos para verificação de idade por email
20051	Resposta captcha inválida
20052	Falha na verificação captcha
20053	O email não é elegível
20058	Erro na resposta de elegibilidade do email
20054	Falha ao enviar o código de verificação de idade por email
20057	Dados submetidos inválidos do código de verificação
20055	Falha na verificação do código de verificação
20061	Endereço de email inválido
20002	Tempo máximo permitido do teste expirado (callback de sucesso do teste)
20004	Id de etapa inválido (callback de sucesso do teste)
20000	Token inválido (callback de sucesso do teste)
20034	Resposta curl xcore api inválida (callback de sucesso do teste)
20003	Tempo máximo permitido do teste expirado (callback de falha do teste)
20005	Id de etapa inválido (callback de falha do teste)
20001	Token inválido (callback de falha do teste)
20035	Resposta curl xcore api inválida (callback de falha do teste)
20036	A idade detetada é inferior a 18 anos
18001	Erro interno na verificação do cartão de crédito
18002	Erro MaxMind na verificação do cartão de crédito

deviceType

Tipo de dispositivo utilizado.

Valor possível	Significado
0	desconhecido
1	móvel
2	desktop

stepId

Etapa do processo de verificação.

Valor possível	Significado
0	desconhecido
1	Teste não iniciado ou abortado
2	Sucesso
3	Falhou
4	Link expirado
5	Link já utilizado

idCountry

Código ISO do país do documento de identidade fornecido.

Exemplo: FR

idState

Código ISO do estado do documento de identidade fornecido (utilizado principalmente para os EUA).

Exemplo: TX

idType

Tipo de documento de identidade.

Valor possível	Significado
1	Cartão de identidade
2	Passaporte
3	Carta de condução

websiteHostname

Hostname do website onde a verificação foi iniciada.

Exemplo: your-site-name.cam

ip

Endereço IP do dispositivo do utilizador.

Exemplo: 127.0.0.1

Proteja a sua empresa, os seus utilizadores e a sua reputação

Escolha GO.cam — a solução simples e certificada de verificação de idade confiável pelos operadores de sites atuais.
Comece hoje!