Portal para desenvolvedores

A API do Clínica nas Nuvens permite integrar sistemas externos aos cadastros e às operações utilizadas na rotina clínica, por meio de requisições HTTP e dados no formato JSON.

Entre os recursos disponíveis estão agenda, pacientes, convênios, orçamentos, planos de tratamento, lista de espera e cadastros de clínica escola.

Como navegar pela documentação

O portal está organizado em duas áreas complementares:

• Guias: apresentam os fluxos de integração de ponta a ponta, com a sequência de operações necessária para executar cada tarefa.
• Referência da API: descreve o contrato de cada endpoint, incluindo métodos HTTP, parâmetros, campos, exemplos e a possibilidade de testar chamadas diretamente pela interface.

Primeira chamada

Para validar a configuração da integração, obtenha as credenciais de acesso, configure os cabeçalhos de autenticação e execute uma requisição GET /info, conforme o exemplo da seção Autenticação.

Credenciais de acesso

As credenciais de acesso à API do Clínica nas Nuvens são disponibilizadas diretamente no sistema após a contratação do módulo de API.

Para consultá-las, acesse Configurações → Integrações → API. Nessa tela, estão disponíveis as três informações necessárias para a integração:

Credencial	Finalidade
client_id	Identifica a integração na autenticação HTTP Basic.
client_secret	Compõe as credenciais da autenticação HTTP Basic.
clinicaNasNuvens-cid	Token enviado em um cabeçalho para identificar a clínica cujos dados serão acessados.

Cada clínica possui seu próprio token. Utilize as credenciais correspondentes à clínica que será acessada pela integração.

Geração de um novo token

A opção Alterar token, disponível na mesma tela, gera um novo clinicaNasNuvens-cid e invalida o anterior imediatamente. As integrações que utilizam o token anterior deixam de ser autorizadas até serem atualizadas com o novo valor.

Autenticação

Todas as requisições devem incluir os dois cabeçalhos de autenticação:

Cabeçalho	Valor
Authorization	Basic seguido da codificação Base64 de client_id:client_secret.
clinicaNasNuvens-cid	Token da clínica que será acessada.

Os cabeçalhos têm funções distintas: Authorization fornece as credenciais da integração, enquanto clinicaNasNuvens-cid identifica a clínica no contexto da requisição.

Exemplo de requisição GET

curl -X GET "https://api.clinicanasnuvens.com.br/info" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>"

Exemplo de requisição POST

As requisições com corpo, como POST e PUT, também enviam o cabeçalho Content-Type: application/json:

curl -X POST "https://api.clinicanasnuvens.com.br/origem/novo" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  -H "Content-Type: application/json" \
  -d '{ "nome": "Instagram" }'

Substitua os valores entre os sinais de menor e maior pelos valores correspondentes. Para o cabeçalho Authorization, utilize a codificação Base64 da sequência client_id:client_secret, incluindo os dois-pontos entre as credenciais.

Se a resposta do GET /info for 200 OK, a chamada foi processada com sucesso. Utilize esse resultado como verificação inicial do acesso e prossiga para os guias de integração.

URL base

A API disponibiliza o seguinte ambiente:

Ambiente	URL base
Produção	https://api.clinicanasnuvens.com.br

Os exemplos deste portal utilizam a URL de produção.

Formatos de dados

Os corpos das requisições devem conter JSON válido e respeitar os formatos definidos para cada campo.

Tipo	Formato	Exemplo
Data	yyyy-MM-dd	2026-10-05
Hora	HH:mm:ss	08:00:00

Os campos do tipo hora devem incluir horas, minutos e segundos. Por exemplo, 08:00:00 segue o formato documentado, enquanto 08:00 não o atende.

Índices e paginação

A API utiliza índices iniciados em zero. Na paginação, a primeira página corresponde ao valor 0. Em arrays, o primeiro elemento também ocupa o índice 0.

Respostas de listagem

As operações de listagem retornam os registros em um objeto que contém a lista de resultados e informações sobre a paginação.

{
  "lista": [],
  "pagina": 0,
  "totalPaginas": 3
}

Por padrão, cada página contém até 50 registros. O limite máximo é de 100 registros por página. Valores de tamanho de página superiores a 100 são ajustados para 100, e a requisição é processada com esse limite.

Respostas de erro

As respostas de erro seguem um formato único:

{
  "mensagem": "Paciente não encontrado nesta clínica.",
  "identificador": null,
  "errors": []
}

Nos erros de validação, a lista errors contém um item por campo, com o nome do campo em atributo e a descrição do problema em erro.

Limite de requisições

O limite informado é de 120 requisições por minuto por token de clínica. As respostas incluem o cabeçalho X-request-count, que informa o consumo atual.

Quando o limite é excedido, a API retorna 429 Too Many Requests. Nesse caso, controle o ritmo das chamadas e retome as requisições conforme a janela de limitação aplicável.

Próximos passos

A criação de um agendamento é o fluxo de integração mais comum e utiliza dados de vários recursos: o paciente, o convênio do paciente e os cadastros da agenda (locais, tipos de consulta e executores). O guia da Agenda descreve esse fluxo.

Para explorar os endpoints antes de iniciar a integração, importe a especificação em uma ferramenta de coleções, como o Postman ou o Insomnia.