API da Bússola da Gestão#
Esta API foi criada para que aplicações parceiras possam consumir informações e serviços oferecidos pela Bússola da Gestão. Ela foi desenvolvida obedecendo os padrões REST.Esta documentação detalha os endpoints disponíveis na API da Bússola da Gestão e disponibiliza a opção de executar as requisições. Além disso, através desta documentação, é possível visualizar o código das requisições para diversas linguagens (PHP, Java, Ruby, Nodejs, entre outras). Para poder utilizá-las, é preciso possuir credenciais fornecidas pela equipe de tecnologia da empresa.Ambiente de teste#
Nossa API possui um ambiente de testes, que pode ser acessada através do endereço abaixo:As credenciais do ambiente de teste não são as mesmas do ambiente de produção. Portanto, assim todos os testes necessários forem realizados neste ambiente, é necessário solicitar novas credenciais para o ambiente de produção.Autenticação#
A autenticação é feita através do fornecimento de uma chave e uma senha. O Access Token gerado no processo de autenticação deve ser transmitido no Header de todas as requisições. Caso o token não seja informado ou ser inválido, uma resposta HTTP 401 será retornada.Atenção! Suas credenciais, como também seu Access Token carrega muitos privilégios. Portanto, certifique-se de mantê-los protegidos. Não informe ela em atendimentos e nem a exponha no front-end da sua aplicação. Havendo suspeita de vazamento destas informações, elas serão inutilizadas e perderão validade. Além disso, não é possível recuperá-la em caso de perda, sendo necessário a geração de uma nova.
Códigos HTTP das respostas#
A API da Bússola da Gestão utiliza respostas HTTP convencionais para indicar sucesso ou falha nas requisições. Respostas com status 2XX indicam sucesso, status 4xx indicam falhas decorrentes de erros nas informações enviadas, e status 5XX indicam erros internos no servidor.Eis alguns retornos comuns da API:200 OK - Sua requisição foi bem sucedida.201 Created - Retornada quando um cadastro ocorreu com sucesso.204 No Content - Retorna quando uma solicitação foi recebida e processada com sucesso, mas não necessita retornar nenhuma informação. Comum quando é solicitado uma exclusão de recurso.422 Unprocessable Entity - Algum parâmetro obrigatório não foi enviado ou é inválido. Nestes casos, analisar a resposta. A própria indicará qual é o problema.401 Unauthorized - Access Token não informado, inválido ou expirado.404 Not Found - O endpoint ou o objeto solicitado não existe.500 Internal Server Error - A requisição causou um erro interno no servidor. Nestes casos, a equipe de desenvolvimento é notificada quando este erro ocorre. Se o erro for persistente por muito tempo, entre em contato com o suporte.Todos os endpoints da API do Dental Gold recebem e respondem no formato JSON.Listas e paginação#
Todos os endpoints da API que retornam uma lista de itens são paginados. Informações sobre a paginação será enviado na resposta das requisições. Para navegar entre as páginas, utilize os parâmetros abaixo:| Parâmetro | Descrição | Padrão |
|---|
| offset | Posição do objeto a partir do qual a página deve ser carregada | 0 |
| limit | Quantidade de objetos por página. Valores aceitos: 5, 10, 20, 25 e 50. | 10 |
| orderby | Nome da coluna que o resultado será ordenado | * |
| q | Busca entre os registros da tabela | |
* Os valores padrões e opções disponíveis podem variar para cada tipo de objetoPor exemplo, utilizando offset=0 e limit=20 será retornado os primeiros 20 registros. Utilizando offset=20 e limit=20 trará 20 registros, começando pelo registro 21. O limit deve ser um valor entre as opções informadas na tabela acima. Se for informado um valor diferente dos valores válidos, o valor padrão será utilizado. Nenhum destes parâmetros é obrigatório. Se ausentes, o valor padrão será utilizado.Buscas e filtros#
Ainda nos endpoints que retornam uma lista de itens, em alguns será possível realizar buscas e filtrar os resultados. Por exemplo, para encontrar um cliente, será possível realizar buscas pelo seu código, nome, cpf ou data de nascimento. Na lista de mensalidades, será possível filtrá-las pela data de vencimento ou a sua situação.Observe a documentação para cada endpoint que estes recursos estarão disponíveis.Suporte#
Se mesmo após ler a documentação, ainda restarem dúvidas ou encontrar algum problema, envie um e-mail para suporte@bussoladagestao.com.br com a descrição do seu problema.