---
# System prepended metadata

title: Integração Kovi <> 55PBX

---

# Integração Kovi <> 55PBX

## __Dicionário JSON__
| Nome                  | Tipo              | Descrição           
| --------------------- | ----------------- | -------------
| valid_national_id     | Boolean           | CPF Válido?
| groups_pool           | { [Int]: String } | Grupo a ser direcionado caso para cada dígito apertado
| message_tts           | String            | Mensagem para ser lida
| callback_endpoint     | String            | Url a ser acionada quando usuário interage 
## __Autenticação__

Autenticação via header
`Authorizarion: Bearer {token}`

Onde o token será passado diretamente para o responsável técnico.
Todos os endpoints nessa documentação utilizam o mesmo formato de autenticação assim como o mesmo token fornecido.

Ex.: token = `SECRET_TOKEN`
`Authorizarion: Bearer SECRET_TOKEN`

# Endpoint consulta de CPF

### Mensagem padrão
__IMPORTANTE:__ Caso o retorno da API não seja 200 ou não apresente o campo `message_tts` a mensagem abaixo deverá ser enviada para o usuário.

__Para dúvidas sobre o aluguel com a Kóvi, por favor acesse ajuda ponto kóvi ponto com ponto br. Obrigado por ligar para a Kóvi.__

### Request
url: `https://api.kovi.us/utils/ura`
method: __POST__
body:
```JSON
{
  "CPF": "12345678900"
}
```
### Responses:

#### 401
Request sem Authorization header
Body:
```JSON
{ "errors": ["You must pass Authorization header"] }
```

Request com Authorization header inválido
Body:
```JSON
{ "errors": ["Invalid token"] }
```

---

#### 500
Request inesperada pelo servidor ou erro interno
Body: 
```JSON
{"message": "Internal server error"}
```
---
#### 200
body:
```JSON
{
  "valid_national_id": true,
  "message_tts": "Olá bom dia...",
  "groups_pool": {
    "1": "GROUP_1",
    "2": "GROUP_2",
  },
  "callback_endpoint": "http://sampleurl.com"
}
```




# Possíveis fluxos
## __FLUXO 1: Usuário insere um CPF inválido__
### __Evidência__
1. valid_national_id = false
### __Ação__
__55PBX__:
1. Lê mensagem
2. Retorna para inserção de CPF
### __Retorno__
```JSON
{
    "national_id": "12345678900",
    "valid_national_id": false,
    "message_tts": "CPF Inválido, por favor, digite novamente."
}
```

## __FLUXO 2: Usuário recebe uma mensagem que não necessita de interação__
### __Evidência__
1. `valid_national_id = true`
2. `has_booking = false`
### __Ação__
__55PBX__:
1. Lê mensagem
2. Encerra ligação


### __Retorno__
```JSON
{
    "national_id": "12345678900",
    "valid_national_id": true,
    "message_tts": "Para dúvidas sobre o aluguel com a Kovi, por favor acesse ajuda ponto kovi ponto com ponto br. Obrigado por ligar para a Kovi."
}
```

## __FLUXO 3: Usuário recebe uma mensagem que não necessita de interação__
### __Evidência__
1. `valid_national_id = true`
2. `groups_pool` != null
3. `callback_endpoint` != null
### __Ação__
__55PBX__
1. Lê mensagem
2. Aguarda input do usuário
   1. Caso usuário não aperte nenhuma opção voltar para o passo 1
   2. Caso usuário aperte uma opção ir para passo 3
3. Direciona o número selecionado para o pool correto baseado no campo `groups_pool`
4. Envia para endpoint `callback_endpoint` a opção selecionada pelo usuário (ler especificações do endereço de callback)

### __Retorno__
```JSON
{
    "valid_national_id": true,
    "message_tts": "Identificamos que você possui 5 débitos com a Kóvi, acabamos de enviar para você o link para você acessar e regularizar a sua situação. Para emergência, pressione 1. Para pagamentos, pressione 2. Para sinistros, pressione 3. Para manutenção, pressione 4.",
    "groups_pool": {
        "1": "EMERGENCY",
        "2": "MY_PLAN",
        "3": "ACCIDENT",
        "4": "MAINTENANCE",
    },
    "callback_endpoint": "http://sampleurl.com"
}
````

# Endpoint callback

### Request

O valor enviado no `pool` é o nome do pool corresponte ao número selecionado pelo usuário.

url: `https://api.kovi.us/utils/ura/callback`
method: __POST__
body:
```JSON
{
  "CPF": "12345678900",
  "pool": "EMERGENCY"
}
```

### Response
body:
```JSON
{
  "success": true
}
```

### Interações

```JSON
{
  "INVALID_NATIONAL_ID": "CPF desconhecido, por favor, digite novamente.",
  "DEFAULT_MESSAGE": "Para dúvidas sobre o aluguel com a Kovi, por favor acesse ajuda ponto kovi ponto com ponto br. Obrigado por ligar para a Kovi.",
  "SIGNUP": {
    "DOCS_PENDING": "O seu cadastro está em andamento, mas estamos aguardando o envio do seu comprovante de residência. Obrigado por ligar para a Kovi.",
    "DOCS_CHECKING": "Neste momento estamos verificando os seus documentos, aguarde o nosso contato por email e WhatsApp. Obrigado por ligar para a Kovi.",
    "PAYMENT_PENDING": "O seu cadastro está em andamento, mas estamos aguardando você fazer a seleção do seu plano com a Kovi, para mais informações sobre planos acesse ajuda ponto kovi ponto com ponto br. Obrigado por ligar para a Kovi.",
    "PAYMENT_PENDING_PAYMENT": "Estamos aguardando o pagamento dos valores relacionados ao seu aluguel. Obrigado por ligar para a Kovi",
    "DELIVERY_PENDING": "Nosso time está verificando a disponibilidade de veículos para fazer o agendamento. Entraremos em contato em breve. Obrigado por ligar para a Kovi",
    "DELIVERY_SCHEDULED": "Seu agendamento já foi realizado e será no dia {day} de {month} as {hour} horas. Verifique seu email para mais informações. Obrigado por ligar para a Kovi."
  },
  "BOOKING_WITH_DEBITS": "Identificamos que você possui {debit_count} débitos com a Kóvi. Acabamos de enviar para você o link para acessar, e regularizar a sua situação. Para emergência, pressione 1. Para desbloqueio de veículos, pressione 2. Para pagamentos, pressione 3. Para sinistros, pressione 4. Para manutenção, pressione 5.",
  "BOOKING_NO_DEBITS": "Para emergência, pressione 1. Para pagamentos, pressione 2. Para sinistros, pressione 3. Para manutenção, pressione 4."
}
```