Área do desenvolvedor

API Clínica nas Nuvens

Aqui você encontra informações sobre o fluxo de autenticação para aplicativos do market place e exemplos de requisição para a API.

Caso esteja buscando desenvolver integrações diretamente para sua clínica, acesse a área do usuário.

Documentação técnica: https://api.clinicanasnuvens.com.br/swagger-ui.html

Introdução

A autenticação para integração com as APIs do Clínica nas Nuvens utiliza o fluxo de OAuth para conceder autorização de acesso.

Neste fluxo, seu aplicativo possui duas credenciais - um client_id e um client_secret - utilizados para gerar tokens de acesso. Uma vez que um token de acesso tenha sido gerado, este será utilizado nas requisições para as API's.

Caso você não possua as credenciais, você deve solicitá-las através do endereço developers@camtwo.com.br. Serão solicitados alguns dados sobre seu aplicativo e, caso aprovado pela nossa equipe, suas credenciais serão criadas.

Para criar seu aplicativo, você precisa ter uma conta do Clínica nas Nuvens e uma url de callback, exemplo: https://yourapp.com.br/auth/callback.


O que é uma URL de callback?

Dentro do fluxo de autenticação de nossas APIs, seu aplicativo está solicitando autorização para ter acesso a uma conta dentro da estrutura do Clínica nas Nuvens, por isso precisamos de uma URL de callback para devolver o code pertinente ao seu aplicativo para dar prosseguimento ao processo de autenticação.

Basicamente, a URL de callback é o endereço em seu aplicativo para onde retornaremos o código de autenticação caso nosso cliente autorize a conexão de sua ferramenta com o Clínica nas Nuvens.

Juntamente com o code, será devolvido o x-tenant, que deve ser armazenado e enviado via Header junto da requisição para a API. O valor de x-tenant identifica a clínica a qual o usuário autorizou o acesso pelo seu aplicativo.

Caso você possua as credenciais, já poderá iniciar o processo de autorização.


Iniciando o processo de autorização

Primeiramente, seu aplicativo deverá direcionar o usuário para a URL de autorização abaixo, substituindo os parâmetros por suas credenciais:

GET https://auth.clinicanasnuvens.com.br/oauth/authorize?response_type=code&client_id={client_id}
Parâmetros do request
client_id client_id fornecido pelo Clínica nas Nuvens.

O usuário, após efetuar login, verá a caixa de confirmação da autorização, selecionará a clínica a qual deseja conectar, e clicará no botão para confirmar o acesso.

Após isso, o Clínica nas Nuvens devolverá o controle para o seu aplicativo, redirecionando para a redirect_uri cadastrada para seu aplicativo, juntamente com o parâmetro code e x-tenant, como por exemplo em https://yourapp.com/auth/callback?x-tenant=1234&code={code}.

É necessário fazer este processo uma vez por clínica. Por exemplo, se o cliente possuir várias filiais no Clínica nas Nuvens e deseja utilizar seu aplicativo em todas, deverá autorizar filial por filial.

Este processo poderá se repetir caso deseje gerar um novo code ou o usuário seja desconectado.

Observação: Se a url de callback possuir query string, o valor deve ser passado em formato encoded. Exemplo:

  • Url de callback: http://example.com/callback/index?name=auth
  • Url encoded: http%3A%2F%2Fexample.com%2Fcallback%2Findex%3Fname%3Dauth


Obtendo o token de acesso

Uma vez que seu aplicativo receba o parâmetro code, este deverá confirmar a identidade fazendo uma requisição para obter um token de acesso:

POST https://auth.clinicanasnuvens.com.br/oauth/token?grant_type=authorization_code&code={code}
Parâmetros do request
code code recebido pelo processo anterior de autorização.
Autenticação
Basic {client_id}:{client_secret}

Sua requisição receberá uma resposta contendo o seguinte conteúdo em JSON:


{
	"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTI5NjA3NzEsInVzZXJfbmFtZSI6InZpdG9yemFjaGlAZ21haWwuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6ImQ1MmJmMTBiLTNhN2YtNDNlOS1hZjNkLTIzOTEyYjkyMzZhNiIsImNsaWVudF9pZCI8Im5pbmEiLCJzY29wZSI6WyJhcGljbm2iXX0.ishLp0rcD_7P7kDXqY_B-ryBJ48uFMsfEZNQfXTkpOg",
	"token_type": "bearer",
	"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJ2aXRvcnphY1hpQGdtYWlsLmNvbSIsImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiJdLCJqdGkiOiIyYWMyMzhkNi1lM2RmLTQ0ZWQtOTczZS0xMWJhNjYzNTRkZDIiLCJjbGllbnRfaWQiOiJuaW5hIiwic7NvcGUiOlsiYXBpY25uIl0sImF0aSI6ImQ1MmJmMTBiLTNhN2YtNDNlOS7hZjNkLTIzOTEyYjkyMzZhNiJ8.j5FxApv2vOKuy9UqK1Jwf8mZpHe9tUuv0VvwaehDphs",
	"expires_in": 36000,
	"scope": "apicnn",
	"userEmail": "user@clinicanasnuvens.com.br",
	"userId": 21127
}
					

Com o access_token gerado, este deverá ser enviado no cabeçalho de cada requisição para a API Pública do Clínica nas Nuvens, juntamente com o X-tenant.


Atualizando o token de acesso

Uma vez que seu aplicativo receba o token de acesso, receberá também o tempo de validade em segundos(expires_in) e o refresh_token para solicitar novo access_token.

POST https://auth.clinicanasnuvens.com.br/oauth/token?grant_type=refresh_token&client_id={client_id}&refresh_token={refresh_token}
Parâmetros do request
client_id client_id do seu aplicativo.
refresh_token o último refresh_token recebido para o tenant.
Autenticação
Basic {client_id}:{client_secret}

Sua requisição receberá uma resposta contendo o seguinte conteúdo em JSON:


{
	"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTI5NjA3NzEsInVzZXJfbmFtZSI6InZpdG9yemFjaGlAZ21haWwuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6ImQ1MmJmMTBiLTNhN2YtNDNlOS1hZjNkLTIzOTEyYjkyMzZhNiIsImNsaWVudF9pZCI8Im5pbmEiLCJzY29wZSI6WyJhcGljbm2iXX0.ishLp0rcD_7P7kDXqY_B-ryBJ48uFMsfEZNQfXTkpOg",
	"token_type": "bearer",
	"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJ2aXRvcnphY1hpQGdtYWlsLmNvbSIsImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiJdLCJqdGkiOiIyYWMyMzhkNi1lM2RmLTQ0ZWQtOTczZS0xMWJhNjYzNTRkZDIiLCJjbGllbnRfaWQiOiJuaW5hIiwic7NvcGUiOlsiYXBpY25uIl0sImF0aSI6ImQ1MmJmMTBiLTNhN2YtNDNlOS7hZjNkLTIzOTEyYjkyMzZhNiJ8.j5FxApv2vOKuy9UqK1Jwf8mZpHe9tUuv0VvwaehDphs",
	"expires_in": 36000,
	"scope": "apicnn",
	"userEmail": "user@clinicanasnuvens.com.br",
	"userId": 21127
}
					

Com o novo access_token recebido, este deverá ser enviado no cabeçalho de cada requisição para a API Pública do Clínica nas Nuvens, juntamente com o X-tenant. Utilize o novo refresh_token para atualizar o access_token quando expirar.


Exemplo de requisição

Após efetuar os passos de autenticação para obtenção do access_token, pode-se efetuar requisições para a API pública do Clínica nas Nuvens, conforme o exemplo:

GET https://api.clinicanasnuvens.com.br/especialidade/lista
Headers
Authentication Bearer {access_token}
X-tenant x-tenant recebido após autorização efetuada neste passo.