Boas práticas de consumo

Limite de uso da API

O limite vale por IP, não por usuário. Por isso ele é resolvido na arquitetura, não em cada tela:

• Uma saída só. Todas as chamadas à API Rapidoc passam por um ponto do seu backend, com uma fila que respeita o teto de 30 por minuto. O navegador ou o app nunca chamam a API direto.
• Leia da sua base primeiro. Planos, especialidades, beneficiários e encaminhamentos PENDING ficam salvos do seu lado; a API só é chamada quando o dado não existe ou precisa mudar.
• Agrupe. Cadastre até 10 vidas por POST /beneficiaries e busque a disponibilidade do mês inteiro numa chamada, em vez de uma por dia.
• Espere antes de repetir. Chamada recusada com 403 por limite volta para a fila com espera crescente (backoff) — reenviar na hora só consome o limite de novo.

O que salvar na sua base

Dados de referência mudam pouco: salve uma vez e leia localmente. O mínimo é o uuid do beneficiário.

Sincronizar cadastro

Planos e beneficiários entram na sua base uma vez; o dia a dia lê dali.

Encaminhamentos PENDING: sua base primeiro

Uma sincronização periódica mantém os pendentes na sua base; a busca da vida na API é só o fallback.

Sincronização periódica

Na hora de agendar

Agendar consulta

Especialidade e encaminhamento saem da sua base; a API só é chamada para horários e para criar a consulta.

Especialista

Generalista

Câmera e microfone

A consulta em vídeo acontece na página aberta pela URL de atendimento. Se o seu app ou site não liberar câmera e microfone para essa página, o beneficiário entra na sala, mas o profissional não o vê nem o ouve.

São sempre duas etapas, seja qual for a plataforma:

1. Pedir a permissão no seu lado — ao navegador ou ao sistema do celular — antes de abrir a URL.
2. Repassar a permissão para a página da consulta, que roda dentro de um iframe (web) ou de um WebView (app).

Web (iframe)

Peça a permissão com getUserMedia assim que tiver a URL de atendimento e só então mostre o iframe. Com o acesso já concedido à sua página, o navegador repassa câmera e microfone para a consulta pelo atributo allow. Feche o stream logo depois: ele só serve para disparar o pedido de permissão.

Na Web, a sala de consulta também oferece compartilhamento de tela, usado pelo beneficiário para mostrar um exame, um documento ou qualquer outra imagem ao profissional durante o atendimento. Esse recurso é exclusivo do iframe (não existe no WebView do app) e depende da permissão display-capture: sem ela no allow do iframe (e sem restrição no Permissions-Policy da sua página), o navegador bloqueia o compartilhamento de tela dentro da consulta.

async function abrirConsulta(urlAtendimento: string) {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
    stream.getTracks().forEach((track) => track.stop());
    setUrlConsulta(urlAtendimento);
  } catch (erro) {
    if (erro instanceof DOMException && erro.name === 'NotAllowedError') {
      avisar('Libere a câmera e o microfone nas configurações do navegador para iniciar a consulta.');
    } else if (erro instanceof DOMException && erro.name === 'NotFoundError') {
      avisar('Nenhuma câmera ou microfone foi encontrado neste dispositivo.');
    } else {
      avisar('Não foi possível acessar a câmera e o microfone.');
    }
  }
}

<iframe
  src={urlConsulta}
  allow="camera; microphone; display-capture; fullscreen"
  style={{ width: '100%', height: '80vh', border: 0 }}
/>

Headers da sua página

A URL de atendimento não tem domínio fixo: ele pode variar de um atendimento para outro. Use sempre a URL recebida da API, sem montar nem validar o domínio no seu código.

• Permissions-Policy — se o seu site não declara camera, microphone e display-capture nesse header, não precisa fazer nada: o allow do iframe já delega o acesso para a origem da URL carregada. Se declara, restringir a (self) bloqueia a consulta.
• Content-Security-Policy — se o seu site restringe frame-src, a URL de atendimento precisa ser permitida. Como o domínio pode mudar, alinhe com a Rapidoc antes de fechar uma lista.

Permissions-Policy: camera=(self), microphone=(self), display-capture=(self)
Content-Security-Policy: frame-src 'self'

React Native (WebView)

O exemplo usa react-native-webview para abrir a consulta e react-native-permissions para pedir o acesso ao usuário. Declare as permissões no Android e no iOS, peça ao usuário e só então abra o WebView.

Android — AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.CAMERA" />
  <uses-permission android:name="android.permission.RECORD_AUDIO" />
  <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

  <uses-feature android:name="android.hardware.camera" android:required="false" />
  <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />
  <uses-feature android:name="android.hardware.microphone" android:required="false" />

  <application>
    <!-- ... -->
  </application>
</manifest>

android:required="false" mantém o app disponível na loja para aparelhos sem câmera ou autofoco.

iOS — Info.plist

<key>NSCameraUsageDescription</key>
<string>Usamos a câmera para que o profissional possa ver você durante a consulta.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Usamos o microfone para que o profissional possa ouvir você durante a consulta.</string>

Sem essas chaves, o iOS encerra o app no momento em que a câmera é pedida. O texto aparece para o usuário na janela de permissão — escreva o motivo com clareza.

No iOS, o react-native-permissions também precisa das permissões declaradas no Podfile:

setup_permissions([
  'Camera',
  'Microphone',
])

Pedir a permissão

import { Platform } from 'react-native';
import { PERMISSIONS, RESULTS, openSettings, requestMultiple } from 'react-native-permissions';

const PERMISSOES =
  Platform.OS === 'ios'
    ? [PERMISSIONS.IOS.CAMERA, PERMISSIONS.IOS.MICROPHONE]
    : [PERMISSIONS.ANDROID.CAMERA, PERMISSIONS.ANDROID.RECORD_AUDIO];

export async function liberarCameraMicrofone(): Promise<boolean> {
  const resultado = Object.values(await requestMultiple(PERMISSOES));

  if (resultado.every((status) => status === RESULTS.GRANTED)) {
    return true;
  }
  if (resultado.some((status) => status === RESULTS.BLOCKED)) {
    await openSettings();
  }
  return false;
}

BLOCKED significa que o usuário negou antes e o sistema não mostra mais a janela: a única saída é levá-lo às configurações do app.

WebView

import { WebView } from 'react-native-webview';

export function Consulta({ urlAtendimento }: { urlAtendimento: string }) {
  return (
    <WebView
      source={{ uri: urlAtendimento }}
      javaScriptEnabled
      allowsInlineMediaPlayback
      mediaPlaybackRequiresUserAction={false}
      mediaCapturePermissionGrantType="grantIfSameHostElsePrompt"
    />
  );
}

No Android, o react-native-webview repassa o pedido da página para as permissões do app — por isso CAMERA e RECORD_AUDIO precisam estar concedidas antes de abrir o WebView.

Revisão dos endpoints

Quando cada chamada vale a pena, e o que dela fica salvo do seu lado.

Custo em chamadas

O mesmo agendamento com especialista, com e sem os dados de referência salvos.

Faça e não faça