Siga a estrutura de pergunta recomendada pelo Dev Bot antes de enviar suas dúvidas de integração.
Post the facial recognition photo of a member, prospect, employee or personal trainer.
POST
https://evo-integracao-api.w12app.com.br/api/v2/accessControl/facial-photo
Controle de Acesso - Cadastrar Foto Facial
Descrição
A foto é validada pelo serviço de reconhecimento facial, e o resultado da validação é devolvido na resposta. Quando aceito, o cadastro é gravado com a origem "API" e dispara o webhook
FacialPhotoRegistered.OBS. Disponível para uso com chave de acesso de filial, de ADM Geral e de central. Veja as regras de escopo abaixo.
🚧 Atenção! O reconhecimento facial precisa estar ativado para a unidade. Caso contrário, a API responde 400. O tamanho máximo da requisição é de 5 MB. Acima disso, a API devolve 413 (Payload Too Large).
📨 Parâmetros da Requisição (Request Body)
| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| personType | int32 | Sim | Tipo da pessoa: 1 = Cliente, 2 = Prospect, 3 = Funcionário, 4 = Personal. Qualquer outro valor é recusado. |
| idPerson | int32 | Sim | Identificador da pessoa. Deve ser maior que zero. A pessoa pode ser de outra filial da base; não há validação de pertencimento à filial. |
| photo | string | Sim | Foto em base64, nos formatos PNG ou JPEG. Os prefixos data:image/png;base64, e data:image/jpeg;base64, são aceitos e removidos antes do envio. Outros formatos, como HEIC e HEIF, não são aceitos. |
| idBranch | int32 | Condicional | Identificador da filial onde o cadastro será registrado. Obrigatório para chave de ADM Geral e de central; ignorado para chave de filial. |
| idRegisteringEmployee | int32 | Não | Identificador do funcionário que realizou o cadastro. Se informado, deve existir e não estar excluído. |
🔑 Escopo pela Chave de Acesso
| Tipo de chave | Comportamento do idBranch |
|---|---|
| Filial | Usa a filial do próprio token. O idBranch é ignorado. |
| ADM Geral | Obrigatório, e apenas para filiais da mesma empresa. |
| Central | Obrigatório, e apenas para filiais às quais a chave tem acesso. |
idBranch é aceito, o cadastro é registrado na unidade informada, e não na da chave.📤 Estrutura da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| success | boolean | Indica se a foto foi aceita na validação. |
| message | string | Resultado da validação (ex.: rosto não detectado). |
⚠️ Erros
| Código | Situação | Mensagem |
|---|---|---|
| 400 | idBranch não informado em chave de ADM Geral ou de central | Orienta a informar o idBranch. |
| 400 | idBranch de outra empresa (ADM Geral) ou sem acesso (central) | Sem permissão para a filial. |
| 400 | Filial inexistente | "Filial não encontrada" |
| 400 | Filial sem integração facial | "Filial sem integração facial" |
| 400 | Reconhecimento facial não ativado para a unidade | "O reconhecimento facial não está ativado para esta unidade. Procure o suporte para ativar o facial." |
| 400 | personType fora de 1 a 4, ou idPerson menor ou igual a zero | Mensagem da regra violada. |
| 400 | Foto vazia, base64 inválido ou prefixo diferente de png ou jpeg | "Formato da imagem inválido" |
| 400 | idRegisteringEmployee inexistente ou de funcionário excluído | Mensagem da regra violada. |
| 413 | Requisição acima de 5 MB | Payload Too Large |
📝 Exemplo de Requisição
{
"personType": 1,
"idPerson": 1025,
"photo": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"idBranch": 1,
"idRegisteringEmployee": 2001
}📝 Exemplo de Resposta
{
"success": true,
"message": "..."
}Requisição
Exemplos de Requisição
Respostas
Modificado em 2026-10-20 18:03:35