Verificação biométrica
curl --request POST \
--url http://api.gu1.ai/api/kyc/biometric \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_image": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
'import requests
url = "http://api.gu1.ai/api/kyc/biometric"
payload = {
"user_image": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_image: {},
entityId: '<string>',
entityExternalId: '<string>',
externalEntityId: '<string>',
entityTaxId: '<string>'
})
};
fetch('http://api.gu1.ai/api/kyc/biometric', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_image' => [
],
'entityId' => '<string>',
'entityExternalId' => '<string>',
'externalEntityId' => '<string>',
'entityTaxId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/biometric"
payload := strings.NewReader("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/biometric")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/biometric")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyBiométrico
Verificação biométrica
Valide uma imagem de rosto contra sessões KYC previamente aprovadas usando a API KYC da gu1 para reautenticação e verificação de identidade.
POST
/
api
/
kyc
/
biometric
Verificação biométrica
curl --request POST \
--url http://api.gu1.ai/api/kyc/biometric \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_image": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
'import requests
url = "http://api.gu1.ai/api/kyc/biometric"
payload = {
"user_image": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_image: {},
entityId: '<string>',
entityExternalId: '<string>',
externalEntityId: '<string>',
entityTaxId: '<string>'
})
};
fetch('http://api.gu1.ai/api/kyc/biometric', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_image' => [
],
'entityId' => '<string>',
'entityExternalId' => '<string>',
'externalEntityId' => '<string>',
'entityTaxId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/biometric"
payload := strings.NewReader("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/biometric")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/biometric")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyResumo
O serviço Biométrico da Gu1 verifica se uma imagem de rosto corresponde a uma pessoa que já concluiu uma validação KYC aprovada na sua organização. Você envia uma única imagem do rosto e a entidade a verificar (porentityId, entityExternalId ou entityTaxId). A API compara esse rosto com os dados biométricos armazenados em sessões de validação por sessão já aprovadas para essa entidade. Se o rosto coincidir com alguma dessas sessões aprovadas, a resposta indica match e retorna os IDs das validações KYC associadas.
Como funcionaO serviço consulta as sessões KYC aprovadas (criadas via validação por sessão) para a entidade informada. Compara o rosto que você envia com as informações biométricas já armazenadas nessas sessões aprovadas. Nenhuma nova sessão hospedada é iniciada—é uma verificação pontual contra dados existentes.
Pré-requisitos
Para este endpoint funcionar, sua organização precisa ter a validação KYC por sessão configurada:- Integração de validação por sessão ativada: A integração usada para validação por sessão (ex.: “Gu1 KYC” / validação por sessão) deve estar ativada para sua organização (ex.: no Marketplace / Integrações).
- Credenciais configuradas: A API key (e o webhook secret) dessa integração de validação por sessão deve estar configurada nas configurações KYC da organização. O endpoint Biométrico usa as mesmas credenciais da validação por sessão para realizar a verificação.
NOT_ENABLED ou NOT_CONFIGURED).
O serviço Biométrico é um serviço da Gu1. Toda a verificação é executada em nossa infraestrutura; nenhum nome de provedor externo é exposto nas respostas ou nos erros.
Solicitação
Endpoint
POST https://api.gu1.ai/api/kyc/biometric
Content-Type
Aceitamultipart/form-data ou application/json.
Multipart — envie a imagem do rosto de uma destas formas (igual ao Face Match / ID Verification):
- Como arquivo: campo
userImageouuser_image(recomendado). - Como string base64: mesmos nomes de campo com a imagem em base64 (com ou sem prefixo
data:image/...;base64,).
user_image ou userImage como base64, data URL ou URL http(s) para o servidor buscar a imagem. Identificadores de entidade: entityId, entityExternalId e/ou entityTaxId.
É obrigatório enviar pelo menos um de entityId, entityExternalId ou entityTaxId para a API saber contra qual entidade verificar.
Headers
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
Authorization: Bearer SUA_API_KEY
Content-Type: multipart/form-data; boundary=----...
X-Organization-Id.
Parâmetros do body
file | string
required
Imagem do rosto. Multipart: campo
userImage ou user_image como arquivo ou string base64 (com ou sem prefixo data:image/...;base64,). JSON: user_image ou userImage como base64, data URL ou URL http(s). Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.string
UUID da entidade pessoa na Gu1. É obrigatório enviar pelo menos um de
entityId, entityExternalId ou entityTaxId.string
Seu próprio identificador da entidade (ID externo). Se você não enviar
entityId, a API resolve a entidade por organização + externalId. É obrigatório enviar pelo menos um identificador de entidade.string
Alias obsoleto de
entityExternalId. Ainda aceito em POST /api/kyc/biometric por compatibilidade. Prefira entityExternalId em novas integrações.string
Identificação fiscal da entidade (CUIT, CPF, RFC, etc.). Se você não enviar
entityId nem entityExternalId, a API resolve a entidade por organização + tax_id normalizado (ignora hífens, pontos e outros caracteres de formatação). É obrigatório enviar pelo menos um identificador de entidade.Resposta
Sucesso (200 OK)
| Campo | Tipo | Descrição |
|---|---|---|
match | boolean | true se o rosto coincide com pelo menos uma validação KYC approved desta entidade na Gu1. |
matchedSessionIds | string[] | Session IDs das validações approved que deram match. |
matchedKycValidationIds | string[] | IDs dessas validações KYC na Gu1. |
faceSearch | object | Resumo: totalMatches, requestId (para suporte). |
{
"match": true,
"matchedSessionIds": ["session-abc-123"],
"matchedKycValidationIds": ["550e8400-e29b-41d4-a716-446655440000"],
"faceSearch": {
"totalMatches": 1,
"requestId": "req_xyz"
}
}
Exemplo de solicitação
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
user_image: 'data:image/jpeg;base64,/9j/4AAQ...',
entityTaxId: '20-41873887-2',
}),
});
const result = await response.json();
console.log('Match:', result.match, 'KYC validations:', result.matchedKycValidationIds);
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: {
'Authorization': 'Bearer SUA_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
user_image: 'data:image/jpeg;base64,/9j/4AAQ...',
entityId: '550e8400-e29b-41d4-a716-446655440000',
}),
});
const result = await response.json();
console.log('Match:', result.match, 'Validações KYC:', result.matchedKycValidationIds);
const form = new FormData();
form.append('userImage', imageFile);
form.append('entityId', '550e8400-e29b-41d4-a716-446655440000');
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: { 'Authorization': 'Bearer SUA_API_KEY' },
body: form,
});
const result = await response.json();
curl -X POST https://api.gu1.ai/api/kyc/biometric \
-H "Authorization: Bearer SUA_API_KEY" \
-F "userImage=@selfie.jpg" \
-F "entityId=550e8400-e29b-41d4-a716-446655440000"
Respostas de erro
| Código | HTTP | Significado |
|---|---|---|
NOT_CONFIGURED | 403 | Credenciais de validação KYC por sessão não configuradas na organização. |
NOT_ENABLED | 403 | Integração de validação KYC por sessão não está ativada para esta organização. |
INVALID_REQUEST | 400 | Body ausente ou inválido (ex.: falta user_image ou nenhum de entityId, entityExternalId, entityTaxId foi enviado). |
NOT_FOUND | 404 | Nenhuma entidade encontrada para o entityId, entityExternalId ou entityTaxId informado nesta organização. |
UNAUTHORIZED | 401 | Autenticação inválida ou ausente. |
VERIFICATION_FAILED | 500 | Verificação não pôde ser concluída; tentar novamente ou contatar o suporte. |
Relação com o KYC por sessão
- Validação por sessão (
POST /api/kyc/validations): Cria uma sessão KYC, fornece uma URL hospedada ao usuário e armazena o resultado (incluindo dados biométricos) ao concluir o fluxo. Essas sessões são as que o endpoint Biométrico usa para comparar. - Biométrico (
POST /api/kyc/biometric): Você envia uma imagem de rosto e a API verifica se coincide com alguma sessão já aprovada para essa entidade. Use quando precisar re-verificar a mesma pessoa (ex.: no login ou em uma nova ação) sem iniciar uma nova sessão.
Próximos passos
Criar validação KYC
Iniciar uma verificação por sessão
Face Match (Documento + Selfie)
Comparar duas imagens em uma chamada
Was this page helpful?