goVendas Platform API

Esta API foi construída para que seja possível agregar à solução dos parceiros o acesso aos serviços de segmentação inteligentes, gerados pelos algoritmos de IA da plataforma goVendas. Desta forma, softwares de CRM, Força de vendas, E-commerce, ERP, dentre outros, poderão carregar as agendas inteligentes sugeridas pelo goVendas, registrar feedbacks de atendimento e cadenciar o contato com o cliente certo, na hora certa.

Primeiros Passos

A integração com o sistema goVendas é facilitada por meio de uma API Rest seguindo o protocolo HTTP, com formato de comunicação em JSON. Apesar da aparente complexidade das siglas, o processo é bastante simplificado. Seu software pode interagir com nossos servidores usando requisições HTTP, semelhante à interação de um navegador web.

O protocolo HTTP é amplamente utilizado pelos navegadores para comunicar-se com servidores web, empregando métodos como GET, POST e PUT. Você utilizará esses mesmos métodos para realizar leituras, cadastros e atualizações de registros em nossa API.

No ambiente de produção e outros ambientes, utilizamos o protocolo HTTPS para garantir a segurança das comunicações.

A integração pode ser desenvolvida em qualquer linguagem de programação. Os únicos requisitos são:

• Uma biblioteca para realizar conexões HTTP.

• Uma biblioteca para leitura/escrita de dados no formato JSON. Nesta lista temos algumas opções disponíveis.

A maioria das linguagens de programação oferece bibliotecas nativas ou de terceiros (que podem ser baixadas e instaladas) para facilitar esse tipo de operação.

Para realizar testes na API consedere utilizar os ambientes de intereção disponibilizados pela Plataforma goVendas para consumir a API Rest:

• Swagger-UI

• Scalar

Habilitar integração do cliente goVendas com o parceiro

Para habilitar a integração e permitir o uso desta API é necessário a criação de um usuário do tipo Supervisor em uma conta goVendas.

Essa etapa deve ser executada pelo usuário Gestor de um conta do goVendas.

A partir desse usuário será possivel ao parceiro realizar o consumo da API. É necessário saber a credêncial deste usuário (login e senha).

Utilizando a API

Para fazer uso da API podemos definir dois momentos principais:

• Fazer a autenticação com o usuário credenciado.
• Fazer uso dos endpoints após a autenticação.

Abaixo segue um listagem rápidas dos recursos disponíveis na plataforma:

• Endpoint de autenticação dentro dos padrões OpenID connect;

• Endpoint para recuperar as segmentações (agendas) dos vendedores;

• Endpoint para recuperar a lista de clientes de uma segmentação ou carteira de um vendedor;

• Endpoint para recuperar a lista de tipos de atendimento;

• Endpoint para registro de atendimento.

URL Base

Os endpoints são acessados a partir da seguinte url:

https://api.govendas.com/v1

Estratégia de Versionamento

Essa seção tem como objetivo fornecer informações claras e abrangentes sobre o esquema de versionamento utilizado pela API e como os clientes devem especificar a versão desejada ao fazer uso da API.

Para o nosso sistema de versionamento, optamos por utilizar o esquema SemVer (Semantic Versioning). O SemVer consiste em três números separados por pontos: MAJOR.MINOR.PATCH.

As atualizações de versão serão realizadas de acordo com a seguinte política:

SemVer	Atualizações	Descrição
[MAJOR]	Principais	Introduzem mudanças incompatíveis com as versões anteriores e requerem uma análise cuidadosa para atualizar as integrações existentes.
[MINOR]	Menores	Adicionam novas funcionalidades de forma compatível e não afetam a integração existente.
[PATCH]	Correções	Corrigem bugs e problemas de segurança, sem introduzir novas funcionalidades ou alterações incompatíveis.

Fazendo uso da API especificando a versão

As atualizações que gerarão novos releases da plataforma serão apenas alterações MAJOR, visando reduzir assim o impacto da quantidade de atualizações e dando longevidade a cada versão.

A especificação da versão da API é feita através da URI, onde a versão da API é adicionada na URL, incluindo um segmento que a identifique. Por exemplo, a versão na URI abaixo é especificada por v1:

https://api.govendas.com/v1/<endpoint>

Histórico de Lançamentos

Para manter um registro claro das versões e alterações da API, manteremos um histórico de lançamentos. Após cada lançamento da API, a documentação da página de Release Notes será atualizada para refletir as alterações introduzidas na nova versão. Isso incluirá informações sobre as alterações significativas, melhorias implementadas, correções de bugs e qualquer outra modificação relevante para os clientes.

Manutenção de Versões Paralelas

Para garantir uma transição suave entre as versões, iremos procurar sempre manter a base da API em funcionamento dando o máximo de atenção possível a retrocompatibilidade. Sobre as versões da API, manteremos no máximo 2 versões da API executando em paralelo e no máximo por um período de 6 meses. Durante esse período, os clientes serão notificados e poderão se manter atualizados através da página de Release Notes regularmente sobre as alterações e prazos para atualização, permitindo que se preparem para migrações futuras.

---

AuthByHeader

A API utiliza um mecanismo de autenticação baseado em tokens para garantir a segurança dos endpoints. Para realizar o uso dos endpoints, é necessario que seu usuário esteja autenticado e as requisições sejam realizadas com um token de acesso válido.

Solicitação do token

Para obter o token de acesso, o usuário deve realizar uma requisição POST ao endpoint /auth/login informando suas credenciais de acesso (usuário e senha) no corpo da requisição. O endpoint retornará um token de acesso, válido por 30 dias.

Portanto, solicite o token pelo endpoint:

/auth/login

Uso do token de acesso

Em cada chamada, esse token deve ser utilizado como um Bearer Token, garantindo permissão de acesso à API. Ele deve ser passado no header Authorization no formato Bearer <token>, onde <token> é substituído pelo valor real do token adquirido.

Exemplo de requisição autenticada utilizando o comando curl:

curl --request GET \
 --url http://https://api.govendas.com/v1/platform/segmentation/search \
 --header 'Authorization: Bearer <token>'

Para revalidar o token antes da expiração uma requisição POST deve ser feita ao endpoint /auth/refresh para obter um novo token. Caso uma chamada seja feita após um token expirar, a chamada retornará Acesso Negado.

Uso do token dentro da interface de documentação

Utilizando o swagger-ui:

Acrescente no campo Value : Bearer <token>

Utilizando o scalar-ui:

Acrescente no campo Header API Key : Bearer <token>