NAV
http python node csharp

Introdução

Bem vindo a Minds API! Você pode utilizar a nossa API para obter acesso via REST aos endpoints dos produtos Biometria de Voz e Prevenção à Fraude.

Você pode visualizar alguns exemplos de como conectar em nossa API do lado direito, para ambos os cenários

Conceitos Importantes

Enrollment

São as operações que registram a voz informada em nosso banco de vozes para comparações futuras

Verification

São as operações que comparam a voz informada às vozes armazenadas em nosso banco de voz

Biometria

Representa a voz reconhecida de uma pessoa como sendo dela mesmo. São essas vozes que são utilizadas na comparação com outras vozes quando uma ligação/verificação é feita

Blocklist

São registros armazenados em uma lista restritiva, a partir do momento que são considerados como potenciais fraudadores.

Autenticação das API's

Veja um exemplo de como se autenticar em qualquer endpoint de nossa API:

curl "api_endpoint_here"
  -H "Authorization: Bearer jwt_token"

Para ambas API's, utilizamos JWT para permitir e validar o acesso às funcionalidades. Você pode obter seu token JWT entrando em contato com o nosso time informando qual o produto foi contratado pela sua empresa. Basta informar o seu token JWT no cabeçalho 'Authorization' de cada requisição:

Authorization: Bearer jwt_token

Biometria de Voz

Entendendo a aplicação e o contexto

Nossa solução de biometria de voz consegue autenticar em tempo real arquivos de áudio contendo a voz de uma pessoa, fazendo uma comparação com outros registros de vozes existentes em nossa base de dados para certificar de que a pessoa é realmente quem ela diz que é.

Os arquivos de áudio devem ser enviados nos formatos .wav ou .mp3, com rates de 8000hz ou 16000hz (para outros formatos, valide com nossa equipe técnica). Se as características técnicas dos áudios que sua empresa possui são diferentes dos listados anteriormente, entre em contato para realizarmos uma análise do seu cenário específico, pois isso influencia os resultados gerados pela nossa solução.

Para que a solução funcione corretamente, o seguinte fluxo de chamadas deve ser feito, com os parâmetros correspondentes sendo informados quando necessário. Para mais detalhes sobre todas as especificações de endpoints e parâmetros, consulte a seção de documentação

Fluxograma de negócio

Fluxograma do Negócio - Como funciona

Fluxograma de chamadas na API

Mais detalhes na seção sequência de chamadas

Fluxograma de chamadas à API

Prevenção à Fraude

Entendendo a aplicação e o contexto

Nossa solução de prevenção à fraude atua em dois momentos: ela consegue autenticar em tempo real arquivos de áudio contendo a voz de uma pessoa, fazendo uma comparação com outros registros de vozes existentes em nossa base de dados para certificar de que a pessoa é realmente quem ela diz que é, e também cruza informações recebidas da integração com seu CRM e/ou Call Center, para identificar comportamentos suspeitos. Sempre que não há uma correspôndencia entre a voz recebida com uma voz armazenada, ou um comportamento suspeito é identificado (como chamadas de números diferentes, ações repetidas ou vozes similares), uma flag é levantada e uma notificação é enviada para o CRM, para que as devidas atitudes sejam tomadas.

Os arquivos de áudio devem ser enviados nos formatos .wav ou .mp3, com rates de 8000hz ou 16000hz. Se as características técnicas dos áudios que sua empresa possui são diferentes dos listados anteriormente, entre em contato para realizarmos uma análise do seu cenário específico, pois isso influencia os resultados gerados pela nossa solução.

Para que a solução funcione corretamente, o seguinte fluxo de chamadas deve ser feito, com os parâmetros correspondentes sendo informados quando necessário. Para mais detalhes sobre todas as especificações de endpoints e parâmetros, consulte a seção de documentação

Fluxograma de negócio

Fluxograma do Negócio - Como funciona

Fluxograma de chamadas na API

Mais detalhes na seção sequência de chamadas

Fluxograma de Chamadas na API

Como testar

Sequência de chamadas

Para explicar de uma maneira mais didática, esse é o passo-a-passo necessário para executar corretamente o processo de autenticação e biometria

Passo 1

Deve-se configurar os cabeçalhos de autenticação para as chamadas na API

Passo 2

Para todo áudio enviado, é necessário realizar um verify-enrollment para validar se já existe cadastrada uma voz em nossa base de áudios para aquele CPF informado (chave primária usada para identificar um usuário).

Passo 3

Se já existir, uma verification deve ser feita em sequência para que a comparação de vozes seja feita pelo nosso modelo.

Passo 4

Se não existir, o endpoint de enrollment deve ser chamado para registrar a voz em nossa base de dados.

Passo 5

No entanto, o verification só vai funcionar se a voz estiver biometria cadastrada, pois é a garantia que nossa solução tem de que aquela voz é realmente do cliente em questão.

Exemplo de código para realizar sequência de chamadas

import os
import base64
import requests
from requests.structures import CaseInsensitiveDict
import json

API_URL = "https://speaker-api.minds.digital/v1.0/speaker"
KEY = "YOUR_JWT_TOKEN"
headers = CaseInsensitiveDict()
headers["Accept"] = "application/json"
headers["Authorization"] = f"Bearer {KEY}"
headers["Content-Type"] = "application/json"

CPF = "12345678909"

response = requests.post(f"{API_URL}/verify-enrollment",
   headers = headers,
   data = json.dumps({cpf: f"{CPF}"}}))

payload = {
   audio: "audio_base64",
   cpf: CPF,
   external_id: "your_external_id",
   phone_number: "your_phone_number";
   audio_extension: "wav",
   rate: "8k"
}

if request["enrolled"] == True
  verification = requests.post(f"{API_URL}/verification",
   headers = headers,
   data = json.dumps(payload)
  )

if request["enrolled"] == False
  verification = requests.post(f"{API_URL}/enrollment",
   headers = headers,
   data = json.dumps(payload)
  )

  request.post(f"{API_URL}/whitelist)",
   headers = headers,
   data = json.dumps({ cpf: CPF, external_type: "1" })
  )

Documentação da API

Voice Match

Este endpoint permite criar ou validar o processo de biometria de voz. Se não existir nenhuma voz cadastrada para o CPF informado, automaticamente faz o enrollment. Se já houver a voz cadastrada, realiza um verification. A validação ocorre de maneira síncrona, não sendo necessário configurar uma URL de callback

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/voice-match

Body Parameters

Parâmetro Obrigatório Tipo Descrição
cpf Sim string CPF do cliente.
external_id Não string ID externo para posterior identificação do áudio.
external_customer_id Não string ID externo para identificação do cliente que está enviando o áudio.
phone_number Não string Número de telefone do cliente. (Formato: (xx) xxxxx-xxxx)
enroll Não bool Realiza o cadastro do cliente caso não exista registro de voz associado.

Há quatro formas de passar parâmetros de áudio para esse endpoint

curl "https://speaker-api.minds.digital/v1.0/speaker/voice-match"
  -H "Authorization: Bearer jwt_token"
  -d "{ 
        'audio': [
            {
               'content': 'https://storage.googleapis.com/minds-public/audios/ogg/vitor.ogg'
            },
            {
               'content': 'https://storage.googleapis.com/minds-public/audios/ogg/vitor.ogg'
            }
         ],
        'cpf': '06298744679',
        'external_id': '123',
        'external_customer_id': '123',
        'phone_number': '(21) 98156-4763',
        'enroll': true
      }"

Forma 1: array de audios com URL de onde estão hospedados

Parâmetro Obrigatório Tipo Descrição
audio Sim array Array contendo URL's de onde os áudios estão hospedados
audio.content Sim string URL onde o áudio está hospedado
curl "https://speaker-api.minds.digital/v1.0/speaker/voice-match"
  -H "Authorization: Bearer jwt_token"
  -d "{ 
        'audio': 'https://storage.googleapis.com/minds-public/audios/ogg/vitor.ogg',
        'cpf': '06298744679',
        'external_id': '123',
        'external_customer_id': '123',
        'phone_number': '(21) 98156-4763',
        'enroll': true
      }"

Forma 2: URL única de onde arquivo de áudio está hospedado

Parâmetro Obrigatório Tipo Descrição
audio Sim string URL onde o áudio está hospedado
curl "https://speaker-api.minds.digital/v1.0/speaker/voice-match"
  -H "Authorization: Bearer jwt_token"
  -d "{ 
        'audio': [
            {
               'content': '4AAQSkZJRgABAQEAy...',
               'extension': 'ogg'
            },
            {
               'content': '4AAQSkZJRgABAQEAy...',
               'extension': 'ogg'
            }
         ],
        'cpf': '06298744679',
        'external_id': '123',
        'external_customer_id': '123',
        'phone_number': '(21) 98156-4763',
        'enroll': true
      }"

Forma 3: array de audios em base64

Parâmetro Obrigatório Tipo Descrição
audio Sim array Array contendo representações dos áudios em base64
audio.content Sim string String com a representação do áudio em base64
audio.extension Sim string Extensão do arquivo enviado. Ex: mp3, wav, ogg, m4a, etc
curl "https://speaker-api.minds.digital/v1.0/speaker/voice-match"
  -H "Authorization: Bearer jwt_token"
  -d "{ 
        'audio': '4AAQSkZJRgABAQEAy...',
        'audio_extension': 'ogg',
        'cpf': '06298744679',
        'external_id': '123',
        'external_customer_id': '123',
        'phone_number': '(21) 98156-4763',
        'enroll': true
      }"

Forma 4: audio em base64 simples

Parâmetro Obrigatório Tipo Descrição
audio Sim string String com a representação do áudio em base64
audio_extension Sim string Extensão do arquivo enviado. Ex: mp3, wav, ogg, m4a, etc

A API responderá com um JSON indicando que recebeu o áudio e colocou na fila de processamento com um ID específico.

{ 
   "success": true,
   "id": 1234
}

Em caso de erro na validação do arquivo/formato enviado, a API responderá de forma síncrona com os potenciais erros


{
    "external_id": "123",
    "status": "already_enrolled",
    "success": true
}

# ou

{
    "external_id": "123",
    "status": "invalid_length",
    "success": false
}

# ou

{
    "external_id": "123",
    "status": "invalid_format",
    "success": false
}

Nosso serviço vai processar a fila e realizar um postback na URL parametrizada pelo cliente, contendo a informação abaixo no body:

{ 
   "id": 1234,
   "action": "enrollment",
   "cpf": "00000000004",
   "external_id" : "123",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

# ou

{ 
   "id": 1234,
   "action": "verification",
   "cpf": "00000000004",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "match_prediction": "match",
   "confidence": "high",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

# ou

{ 
   "id": 1234, 
   "action": "verification",
   "cpf": "00000000004",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "match_prediction": "different",
   "confidence": "high",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

New Enrollment

curl "https://speaker-api.minds.digital/v1.0/speaker/enrollment"
  -H "Authorization: Bearer jwt_token"
  -d "{ 
        'audio': '4AAQSkZJRgABAQEAy...',
        'cpf': '06298744679',
        'external_id': '123',
        'external_customer_id': '123',
        'phone_number': '(21) 98156-4763'
      }"

Este endpoint permite criar uma nova biometria de voz.

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/enrollment

Body Parameters

Parâmetro Obrigatório Tipo Descrição
audio Sim string Representação do áudio de referência em base 64.
cpf Sim string CPF do cliente.
external_id Não string ID externo para posterior identificação do áudio.
external_customer_id Não string ID externo para identificação do cliente que está enviando o áudio.
phone_number Não string Número de telefone do cliente. (Formato: (xx) xxxxx-xxxx)
audio_extension Não string Extensão do arquivo de audio. (mp3 ou wav) - Default: mp3
rate Não string Audio sample rate. (8k ou 16k) - Default: 8k

A API responderá com um JSON indicando que recebeu o áudio e colocou na fila de processamento com um ID específico.

{ 
   "success": true,
   "id": 1234
}

Em caso de erro na validação do arquivo/formato enviado, a API responderá de forma síncrona com os potenciais erros


{
    "external_id": "123",
    "status": "already_enrolled",
    "success": true
}

# ou

{
    "external_id": "123",
    "status": "invalid_length",
    "success": false
}

# ou

{
    "external_id": "123",
    "status": "invalid_format",
    "success": false
}

Nosso serviço vai processar a fila e realizar um postback na URL parametrizada pelo cliente, contendo a informação abaixo no body:

{ 
   "id": 1234,
   "action": "enrollment",
   "cpf": "00000000004",
   "external_id" : "123",,
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

New Verification

curl "https://speaker-api.minds.digital/v1.0/speaker/verification"
  -H "Authorization: Bearer jwt_token"
  -d "{ 
        'audio': '4AAQSkZJRgABAQEAy...',
        'cpf': '06298744679',
        'external_id': '123',
        'external_customer_id': '123',
        'phone_number': '(21) 98156-4763'
      }"

Este endpoint permite verificar se a voz em um audio é a mesma voz cadastrada na biometria do cliente e, caso não seja, buscar clientes com vozes semelhantes.

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/verification

Body Parameters

Parâmetro Obrigatório Tipo Descrição
audio Sim string Representação do áudio de referência em base 64.
cpf Sim string CPF do cliente.
external_id Não string ID externo para posterior identificação do áudio.
external_customer_id Não string ID externo para identificação do cliente que está enviando o áudio.
phone_number Não string Número de telefone do cliente. (Formato: (xx) xxxxx-xxxx)
audio_extension Não string Extensão do arquivo de audio. (mp3 ou wav) - Default: mp3
rate Não string Audio sample rate. (8k ou 16k) - Default: 8k

A API responderá com um JSON indicando que recebeu o áudio e colocou na fila de processamento com um ID específico:

{ 
   "success": true,
   "id": 1234
}

Em caso de erro na validação do arquivo/formato enviado, a API responderá de forma síncrona com os potenciais erros


{
    "external_id": "123",
    "status": "invalid_length",
    "success": false
}

# ou

{
    "external_id": "123",
    "status": "invalid_format",
    "success": false
}

Nosso serviço vai processar a fila e realizar um postback na URL parametrizada pelo cliente, contendo a informação abaixo no body:


{ 
   "id": 1234,
   "action": "verification",
   "cpf": "00000000004",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "match_prediction": "match",
   "confidence": "high",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

# ou

{ 
   "id": 1234, 
   "action": "verification",
   "cpf": "00000000004",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "match_prediction": "different",
   "confidence": "high",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

New Authentication

curl "https://speaker-api.minds.digital/v1.0/speaker/authenticate"
  -H "Authorization: Bearer jwt_token"
  -d "{ 
        'audio': '4AAQSkZJRgABAQEAy...',
        'cpf': '06298744679',
        'external_id': '123',
        'external_customer_id': '123',
        'phone_number': '(21) 98156-4763'
      }"

Este endpoint permite criar ou validar o processo de biometria de voz. Se não existir nenhuma voz cadastrada para o CPF informado, automaticamente faz o enrollment. Se já houver a voz cadastrada, realiza um verification. O processamento ocorre de maneira assíncrona. Para receber o retorno, é necessário configurar uma URL de callback em nosso portal web.

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/authenticate

Body Parameters

Parâmetro Obrigatório Tipo Descrição
audio Sim string Representação do áudio de referência em base 64.
cpf Sim string CPF do cliente.
external_id Não string ID externo para posterior identificação do áudio.
external_customer_id Não string ID externo para identificação do cliente que está enviando o áudio.
phone_number Não string Número de telefone do cliente. (Formato: (xx) xxxxx-xxxx)
audio_extension Não string Extensão do arquivo de audio. (mp3 ou wav) - Default: mp3
rate Não string Audio sample rate. (8k ou 16k) - Default: 8k

A API responderá com um JSON indicando que recebeu o áudio e colocou na fila de processamento com um ID específico.

{ 
   "success": true,
   "id": 1234
}

Em caso de erro na validação do arquivo/formato enviado, a API responderá de forma síncrona com os potenciais erros


{
    "external_id": "123",
    "status": "already_enrolled",
    "success": true
}

# ou

{
    "external_id": "123",
    "status": "invalid_length",
    "success": false
}

# ou

{
    "external_id": "123",
    "status": "invalid_format",
    "success": false
}

Nosso serviço vai processar a fila e realizar um postback na URL parametrizada pelo cliente, contendo a informação abaixo no body:

{ 
   "id": 1234,
   "action": "enrollment",
   "cpf": "00000000004",
   "external_id" : "123",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

# ou

{ 
   "id": 1234,
   "action": "verification",
   "cpf": "00000000004",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "match_prediction": "match",
   "confidence": "high",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

# ou

{ 
   "id": 1234, 
   "action": "verification",
   "cpf": "00000000004",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "match_prediction": "different",
   "confidence": "high",
   "created_at": "2010-01-01",
   "status": "ok",
   "success": true,
   "whitelisted": true,
   "fraud_risk": "low"
}

Verify enrollment

curl "https://speaker-api.minds.digital/v1.0/speaker/verify-enrollment"
  -H "Authorization: Bearer jwt_token"

Este endpoint permite verificar se um cliente já possui biometria de voz.

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/verify-enrollment

Body Parameters

Parâmetro Obrigatório Tipo Descrição
cpf Sim string CPF do cliente.

A API responderá com um JSON semelhante a esse:

{
   "success": true,
   "enrolled": true,
   "external_id": "000",
   "external_type": "4",
   "whitelisted": true
}

# ou

{
   "success": true,
   "enrolled": false
}

Get a verification

curl "https://speaker-api.minds.digital/v1.0/speaker/verification/1234"
  -H "Authorization: Bearer jwt_token"

Este endpoint permite buscar as informações de uma verificação através do ID.

HTTP Request

GET https://speaker-api.minds.digital/v1.0/speaker/verification/<ID>

Query Parameters

Parâmetro Obrigatório Tipo Descrição
ID Sim int ID da verificação.

A API responderá com um JSON semelhante a esse:


{
   "id": 1234,
   "external_id": "123",
   "status": "invalid_length",
   "success": false
}

# ou

{ 
   "id": 1234,
   "action": "enrollment",
   "cpf": "00000000004",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "created_at": "2020/01/01",
   "whitelisted": true,
   "status": "ok",
   "match_prediction": "match",
   "fraud_risk": "low",
   "success": true,
   "confidence": "high",
   "threshold": 0.60
}

# ou

{ 
   "id": 1234,
   "action": "verification",
   "confidence": "high",
   "cpf": "00000000004",
   "result": "match",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "created_at": "2020/01/01",
   "whitelisted": true,
   "status": "ok",
   "match_prediction": "match",
   "fraud_risk": "low",
   "success": true,
   "confidence": "high",
   "threshold": 0.60
}

# ou

{ 
   "id": 1234, 
   "action": "verification",
   "confidence": "high",
   "cpf": "00000000004",
   "result": "different",
   "external_id" : "123",
   "enrollment_external_id" : "001",
   "created_at": "2020/01/01",
   "whitelisted": true,
   "status": "ok",
   "match_prediction": "match",
   "fraud_risk": "low",
   "success": true,
   "confidence": "high",
   "threshold": 0.60
}

Whitelist

curl "https://speaker-api.minds.digital/v1.0/speaker/whitelist"
  -H "Authorization: Bearer jwt_token"

Este endpoint permite adicionar um cliente na lista de clientes confiáveis.

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/whitelist

Body Parameters

Parâmetro Obrigatório Tipo Descrição
cpf Sim string CPF do cliente.
external_type Não string Tipo de autenticação. Default: null
created_by Não int ID do usuário que adicionou o registro na lista. Default: null

A API responderá com um JSON semelhante a esse:

{
   "success": true
}

# ou

{
   "success": false, "message": "Parameter cpf is required."
}

# ou

{
   "success": false, 
   "message": "Customer not found.", 
   "status": "invalid_customer"
}

# ou

{
   "success": false, 
   "message": "Customer already in whitelist.", 
   "status": "already_whitelisted"
}

# ou

{
   "success": false, 
   "message": "Customer already removed from whitelist.", 
   "status": "already_removed"
}


Unwhitelist

curl "https://speaker-api.minds.digital/v1.0/speaker/unwhitelist"
  -H "Authorization: Bearer jwt_token"

Este endpoint permite remover um cliente da lista de clientes confiáveis.

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/unwhitelist

Body Parameters

Parâmetro Obrigatório Tipo Descrição
cpf Sim string CPF do cliente.
removed_by Não int ID do usuário que removeu o usuário. Default: null

A API responderá com um JSON semelhante a esse:

{
   "success": true
}

# ou

{
   "success": false, "message": "Parameter cpf is required."
}

# ou

{
   "success": false, 
   "message": "Customer not found.", 
   "status": "invalid_customer"
}

# ou

{
   "success": false, 
   "message": "Customer not in whitelist", 
   "status": "not_whitelisted"
}

Encode audio

curl "https://speaker-api.minds.digital/v1.0/speaker/encode_audio"
  -H "Authorization: Bearer jwt_token"

Este endpoint converte um áudio enviado em array de bytes para base64, utilizando um algoritmo já validado para a aplicação

HTTP Request

POST https://speaker-api.minds.digital/v1.0/speaker/encode_audio

Body Parameters

Parâmetro Obrigatório Tipo Descrição
file Sim multipart/form-data Arquivo de áudio. Somente são permitidos arquivos nas extensões .WAV e .MP3

A API responderá com um JSON semelhante a esse:

{
   "success": true,
   "status": "valid",
   "encoded_audio": "<base64-audio>"
}

# ou

{
   "success": false,
   "status": "invalid",
   "message": "Invalid content type. Please, provide an audio file."
}

# ou

{
   "success": false,
   "status": "invalid",
   "message": "Invalid audio format. Please, provide following formats: 'wav', 'mp3'."
}

# ou

{
   "success": false, 
   "message": "Customer not in whitelist", 
   "status": "not_whitelisted"
}

Errors

Code Meaning
400 Bad Request -- Requisição inválida.
401 Unauthorized -- O jwt_token não foi enviado ou não é válido.
404 Not Found -- O endpoint solicitado não existe.
500 Internal Server Error -- Erro interno do servidor. Quando isso acontece nosso time é alertado automaticamente e já inicia as investigações para corrigir o problema.