Conheça a nossa nova rota MEDICAL RECEIPT para validação automatizada de recibos do Receita Saúde!
| Categoria | Requisito Mínimo |
|---|---|
| Câmera | Câmera frontal obrigatória (deve ser colorida). |
| Taxa de atualização (display) | Mínimo de 60 Hz. |
| Tamanho da tela | Mínimo de 4 polegadas. |
| Segurança do SO | O dispositivo não deve estar jail-broken (iOS) ou rooted (Android). |
| Categoria | Requisito Mínimo |
|---|---|
| Resolução de gravação | Mínimo de 480x640px. |
| Taxa de quadros (frame rate) | Mínimo de 15 quadros por segundo (fps). |
| Tipo de câmera | Não são suportadas câmeras virtuais ou softwares de câmera simulados. |
| Uso em desktop | Para uso de webcam em desktops, a câmera deve ser montada na parte superior do mesmo monitor onde a checagem é iniciada. |
| Categoria | Requisito Mínimo |
|---|---|
| Largura de banda (bandwidth) | Mínimo de 100 kbps. |
| Navegadores suportados | As três últimas versões dos principais navegadores (Google Chrome, Mozilla Firefox, Apple Safari e Microsoft Edge). |
POST /liveness/streaming/async), é possível enviar o objeto settings com configurações adicionais que alteram o comportamento da prova de vida. Todos os parâmetros são opcionais e podem ser combinados na mesma requisição.| Parâmetro | Tipo | Finalidade |
|---|---|---|
setSystemClockOffset | Boolean | Compensa diferenças entre o relógio do dispositivo e o do servidor. |
frameAncestors | Array de strings | Define quais domínios podem incorporar a interface de prova de vida em um iframe. |
"settings": {
"setSystemClockOffset": false,
"frameAncestors": ["app.suaempresa.com.br"]
}setSystemClockOffset aumenta a resiliência da prova de vida em dispositivos cujo relógio esteja incorreto ou dessincronizado em relação aos servidores de verificação."settings": {
"setSystemClockOffset": true
}{
"result": {
"processId": "2de80502-f4fe-4e6b-93ee-53d9474f26ca",
"status": "ERROR",
"statusDescription": "Server and device clocks are out of sync",
"livenessScore": null,
"frontalImage": null
},
"requestId": "Y8XfDzvy5k2KoGLv67C79",
"elapsedMilliseconds": 677,
"status": {
"message": "Ok",
"code": "200",
"errors": null
}
}setSystemClockOffset, o sistema calcula automaticamente a diferença entre o relógio local e o do servidor no início da sessão, ajustando as requisições para que a variação de horário não cause a falha da prova de vida.| Valor | Comportamento |
|---|---|
false ou parâmetro não enviado | Comportamento padrão. O horário do dispositivo é comparado com o do servidor e, se houver divergência considerável, a prova de vida falhará. |
true | O sistema aplica uma compensação (offset) baseada no horário do servidor, permitindo que a análise ocorra normalmente mesmo em dispositivos com data e hora configuradas incorretamente. |
true apenas em cenários com taxa alta de erros técnicos do tipo "Server and device clocks are out of sync". Assim, você garante uma melhor experiência ao usuário e evita que ele seja barrado por uma configuração incorreta no próprio dispositivo.iframe dentro da sua aplicação. Por segurança, para prevenir ataques como o clickjacking, somente domínios previamente autorizados podem exibir a página de prova de vida em um iframe.frameAncestors define, por sessão, quais desses domínios autorizados podem incorporar a página."settings": {
"frameAncestors": ["app.suaempresa.com.br", "*.suaempresa.com.br"]
}⚠️ Importante: liberação prévia de domínios Para incorporar a interface em um iframe, os domínios da sua aplicação precisam estar cadastrados na lista de domínios aprovados da sua conta. Sem esse cadastro, a página não pode ser incorporada, mesmo que o parâmetro frameAncestorsnão seja enviado.Para solicitar a inclusão, entre em contato com o nosso suporte e envie a lista de domínios desejados.
| Valor enviado | Comportamento |
|---|---|
Parâmetro não enviado ou null | A página pode ser incorporada por todos os domínios cadastrados para a sua conta. Se a conta não tiver domínios cadastrados, a página não pode ser incorporada. |
Lista de domínios, ex.: ["app.suaempresa.com.br"] | A página só pode ser incorporada pelos domínios informados, que devem estar cadastrados para a sua conta. |
[] (lista vazia) | A página não pode ser incorporada em nenhum iframe. |
Valor que não é uma lista (ex.: "suaempresa.com.br") | Erro na criação da sessão (HTTP 400, código R101). |
| Lista com domínio não cadastrado | Erro na criação da sessão (HTTP 400, código R101). |
| Lista com mais de 20 hosts | Erro na criação da sessão (HTTP 400, código R101). |
| Formato | Exemplo |
|---|---|
| Domínio completo | app.suaempresa.com.br |
| Curinga para subdomínios | *.suaempresa.com.br |
["suaempresa.com.br"], e não "suaempresa.com.br".https:// é opcional e é removido automaticamente.* isolado, palavras-chave como 'self' ou 'none', esquemas (https:, data:), endereços com http://, portas, caminhos (ex.: /pagina), espaços ou ;.💡 Sobre curingas: o cadastro *.suaempresa.com.brlibera subdomínios comoportal.suaempresa.com.br, mas não libera o domínio raizsuaempresa.com.br. Se precisar dos dois, solicite o cadastro de ambos.
frameAncestors é inválido, a sessão não é criada e a API retorna HTTP 400 com o código R101. O campo errors indica o parâmetro com problema e o motivo da rejeição.Mensagem em errors | Causa | Como corrigir |
|---|---|---|
frameAncestors is not of an expected type | O valor enviado não é uma lista (ex.: "suaempresa.com.br"). | Envie os domínios em uma lista: ["suaempresa.com.br"]. |
The frameAncestors field contains hosts not allowed for this account | Um ou mais domínios da lista não estão cadastrados para a sua conta ou estão em formato não aceito. | Confira os domínios enviados e o formato aceito. Para incluir novos domínios, entre em contato com o suporte. |
{
"result": null,
"requestId": "ZnBcGfuGxA8ojRaQV4cxz",
"elapsedMilliseconds": 503,
"status": {
"message": "A specified parameter is wrong",
"code": "R101",
"errors": [
{
"field": "frameAncestors",
"message": "frameAncestors is not of an expected type"
}
]
}
}{
"result": null,
"requestId": "UopYShZ6OOsMaSOg7SNzf",
"elapsedMilliseconds": 2930,
"status": {
"message": "A specified parameter is wrong",
"code": "R101",
"errors": [
{
"field": "frameAncestors",
"message": "The frameAncestors field contains hosts not allowed for this account"
}
]
}
}<iframe> deve conceder essa permissão pelo atributo allow. Sem ele, o navegador bloqueia o acesso à câmera e a prova de vida termina com o erro "Camera access error".allow a origem do link da sessão de prova de vida, sempre com o prefixo https://:portal.suaempresa.com.br (página principal)
└── app-parceiro.com.br (aplicação em iframe)
└── liveness.mostqi.com (prova de vida em iframe)<iframe> da cadeia precisa liberar a câmera para todas as origens abaixo dele:portal.suaempresa.com.br):app-parceiro.com.br):allow, a permissão de câmera se perde nesse ponto da cadeia.frameAncestors. O navegador valida todos os níveis acima da página de prova de vida, e não apenas o iframe imediatamente superior. Portanto, tanto a página principal quanto a aplicação intermediária precisam estar cadastradas para a sua conta e, se o parâmetro for enviado, incluídas na lista:"settings": {
"frameAncestors": ["portal.suaempresa.com.br", "app-parceiro.com.br"]
}| Status | statusDescription | Detalhe |
|---|---|---|
| TODO | "Waiting for user interaction" | A prova de vida ainda não foi iniciada. A sessão está disponível para iniciar o processo. |
| DOING | "User interaction in progress" | A prova de vida foi iniciada e o processo está em execução. |
| DONE | "User interaction completed successfully" | A prova de vida foi concluída. Nesse caso, o resultado incluirá valores para os atributos frontalImage e livenessScore, se disponíveis, que devem ser avaliados para a definição do resultado final da prova de vida. |
| EXPIRED | "User did not interact within the time limit" | A sessão de prova de vida expirou. Isso ocorre quando o usuário não conclui a prova de vida dentro do prazo de 3 minutos após clicar em "Iniciar captura". |
| CANCELED | "Canceled after 1 hour of inactivity" | A sessão de prova de vida foi cancelada por não ser concluída dentro do tempo máximo de 1 hora. |
| ERROR | "Camera access error" | Não foi possível acessar a câmera do dispositivo. Verifique se a permissão de uso da câmera está habilitada no navegador ou nas configurações do aparelho. |
| ERROR | "Camera framerate error" | A câmera não está conseguindo capturar imagens com a taxa mínima necessária. |
| ERROR | "Default camera not found" | Nenhuma câmera foi encontrada no dispositivo. Verifique se o equipamento possui câmera disponível e se ela está funcionando corretamente. |
| ERROR | "Liveness session has expired. Please create a new session." | A sessão de verificação expirou. Por favor, inicie uma nova sessão para continuar o processo. |
| ERROR | "Face distance error" | O rosto está muito próximo ou muito distante da câmera. Ajuste a posição do dispositivo até que seu rosto fique bem enquadrado na tela. |
| ERROR | "The security token included in the request is invalid." | O token de segurança da requisição é inválido ou expirou. |
| ERROR | "Server and device clocks are out of sync" | O horário do dispositivo está diferente do horário do servidor. Verifique se a data e hora do aparelho estão configuradas corretamente. |
| ERROR | "Device orientation error" | A orientação do dispositivo está incorreta. Posicione o celular na orientação indicada na tela para continuar. |
| ERROR | "Multiple faces error" | Foram detectados vários rostos na câmera. Certifique-se de que apenas uma pessoa esteja visível no enquadramento. |
| ERROR | "Liveness session has results available. Please get results for the session." | Esta sessão de verificação já possui resultados disponíveis. Utilize a consulta de resultados para obter as informações da sessão. |
| ERROR | "Unexpected runtime error" | Ocorreu um erro inesperado durante a execução do processo. Tente novamente em alguns instantes. |
| ERROR | "Unexpected server error" | Ocorreu um erro inesperado no servidor. Tente novamente mais tarde. |
| ERROR | "Connection timed out" | O tempo de conexão foi excedido. Verifique sua conexão com a internet e tente novamente. |
TODO está disponível para iniciar o fluxo de prova de vida. Sessões nos demais status não podem ser reiniciadas utilizando o mesmo link.setSystemClockOffset.| Título exibido na interface | Detalhe exibido na interface | Quando pode ocorrer |
|---|---|---|
| Tempo de conexão esgotado | Ocorreu um erro de tempo de conexão durante a verificação de vivacidade. Por favor, solicite uma nova verificação. | Pode ocorrer quando a comunicação necessária para execução da prova de vida excede o tempo limite esperado. Para o usuário, o tratamento é o mesmo do cenário de Tempo de conexão esgotado : solicitar uma nova verificação. |
| Tempo de conexão esgotado | Ocorreu um erro de tempo de conexão durante a verificação de vivacidade. Por favor, solicite uma nova verificação. | Ocorre quando o processo excede o tempo limite definido para uma operação. A interface apresenta a mesma mensagem de Tempo de conexão esgotado . |
| Erro inesperado | Ocorreu um erro inesperado durante a verificação de vivacidade. Por favor, solicite uma nova verificação. | Pode ocorrer quando acontece uma falha inesperada durante a execução do processo que não se enquadra nos demais tipos de erro específicos. |
| Erro de taxa de quadros da câmera | Ocorreu um erro relacionado à taxa de quadros da câmera durante a verificação de vivacidade. Por favor, solicite uma nova verificação. | Pode ocorrer quando a câmera não consegue realizar a captura na taxa mínima necessária. A documentação técnica estabelece mínimo de 15 fps para a captura de vídeo.) |
| Erro de acesso à câmera | Ocorreu um erro relacionado ao acesso à câmera durante a verificação de vivacidade. Certifique-se de que a câmera está conectada e que o navegador tem permissão para acessá-la. Por favor, solicite uma nova verificação. | Pode ocorrer quando o navegador ou dispositivo não permite o acesso à câmera, por exemplo, quando a permissão não foi concedida ou foi bloqueada. A interface solicita essa permissão antes do início da captura. |
| Erro de distância do rosto | Ocorreu um erro relacionado à distância do rosto durante a verificação de vivacidade. Certifique-se de que seu rosto esteja centralizado e a uma distância adequada da câmera. Por favor, solicite uma nova verificação. | Ocorre quando o rosto está muito próximo ou muito distante da câmera, impedindo a captura adequada. |
| Erro de orientação do dispositivo | Ocorreu um erro relacionado à orientação do dispositivo durante a verificação de vivacidade. Por favor, mantenha seu dispositivo na orientação retrato durante a verificação. Por favor, solicite uma nova verificação. | Pode ocorrer quando o dispositivo móvel está sendo utilizado na orientação paisagem em vez da orientação retrato. |
| Erro de múltiplos rostos | Ocorreu um erro relacionado à detecção de múltiplos rostos durante a verificação de vivacidade. Certifique-se de que apenas uma pessoa esteja na frente da câmera durante a verificação. Por favor, solicite uma nova verificação. | Ocorre quando mais de um rosto é detectado no enquadramento da câmera. |
| Erro de câmera padrão não encontrada | Ocorreu um erro relacionado à câmera padrão durante a verificação de vivacidade. Certifique-se de que uma câmera esteja conectada e configurada como padrão no seu dispositivo. Por favor, solicite uma nova verificação. | Pode ocorrer quando o dispositivo não possui uma câmera disponível ou quando nenhuma câmera válida está configurada como padrão. |
| Erro do servidor | Ocorreu um erro no servidor durante a verificação de vivacidade. Por favor, tente novamente mais tarde. | Pode ocorrer quando acontece uma falha inesperada no processamento do serviço. |
| Assinatura inválida | A assinatura fornecida para esta verificação de vivacidade é inválida. Isso ocorre quando o horário do servidor e do dispositivo estão fora de sincronia. | Pode ocorrer quando existe uma diferença significativa entre o relógio do dispositivo do usuário e o relógio utilizado pelo servidor. A documentação recomenda considerar setSystemClockOffset para cenários com ocorrência elevada desse problema. |
TODO podem iniciar o fluxo normalmente. Os demais status indicam que a sessão já está em andamento, foi concluída, expirou ou foi encerrada.| Status | Título exibido na interface | Detalhe exibido na interface | Quando pode ocorrer |
|---|---|---|---|
DOING | Sessão em andamento | Esta sessão já está em andamento. Por favor, aguarde. | Ocorre quando o usuário acessa o link de uma sessão que já foi iniciada e ainda está em processamento. O status DOING representa uma sessão na qual o usuário já clicou em Iniciar captura. |
DONE | Sessão concluída | Esta sessão já foi concluída. Você pode fechar esta janela agora. | Ocorre quando a prova de vida já foi concluída e a sessão possui resultado disponível. Uma nova prova de vida não deve ser iniciada utilizando esse mesmo link. |
ERROR | Sessão inválida | Ocorreu um erro durante o processo de verificação de vivacidade. Por favor, solicite uma nova verificação. | Ocorre quando a sessão foi encerrada com erro. Por exemplo, a prova pode ter sido finalizada devido a um problema de câmera, timeout ou outro erro técnico. Ao tentar acessar novamente o mesmo link, a interface apresenta esta mensagem em vez de permitir uma nova tentativa. |
EXPIRED | Sessão expirada | Esta sessão expirou. Por favor, solicite uma nova verificação. | Ocorre quando o usuário não conclui a prova de vida dentro do prazo permitido para a sessão. Atualmente, a documentação informa o limite de 3 minutos após o início da captura. |
CANCELED | Sessão expirada | Esta sessão expirou. Por favor, solicite uma nova verificação. | Ocorre quando a sessão permanece sem conclusão até atingir o tempo máximo de 1 hora de inatividade. |
ERROR e a mensagem "Sessão inválida"ERROR após uma tentativa de prova de vida ser encerrada devido a um erro técnico.ERROR| Título exibido na interface | Detalhe exibido na interface | Quando ocorre |
|---|---|---|
| Sucesso! | Confirmamos com sucesso a vivacidade do usuário. Obrigado por concluir o processo! | Ocorre quando o resultado da análise confirma a vivacidade do usuário. |
| Quase lá! | Não foi possível confirmar a vivacidade do usuário. Por favor, solicite uma nova verificação. | Ocorre quando a análise não consegue confirmar a vivacidade do usuário. Nesse caso, deve ser solicitada uma nova verificação. |