API v1 · REST + FHIR

Referência da API HelloSaude

Integre agendamentos, pacientes e prontuários diretamente nos seus sistemas. Todos os endpoints retornam JSON com autenticação via Bearer token.

Solicitar acesso à API Explorar documentação

https://app.hellosaude.comBase URL

application/jsonContent-Type

Bearer <token>Authorization

Introdução

A API HelloSaude é REST com respostas em JSON. Três superfícies disponíveis:

/api/v1

API da Plataforma

Server-to-server via API Key. Requer feature partner_platform_api.

/api/fhir

API FHIR R4

Exportação HL7 FHIR R4 via API Key. Auditoria PHI.

/api/mobile

API Mobile

Para apps móveis de pacientes. WorkOS OAuth PKCE.

URL Base

https://app.hellosaude.com

curl -H "Authorization: Bearer sk_live_..." "https://app.hellosaude.com/api/v1/appointments"

Autenticação

API Key (Platform + FHIR)

Gerada em Configurações → API Keys. Passada no header Authorization.

Authorization: Bearer sk_live_xxxx...

Nunca exponha em código client-side.

Session Token (v1)

Para endpoints me/organizations/agenda. Obtenha via POST /api/v1/auth/session com access token WorkOS.

Mobile Token (OAuth PKCE)

Fluxo WorkOS PKCE. Troque o code em POST /api/mobile/v1/auth/token.

Authorization: Bearer <mobile_token>
X-Organization-Id: <org_uuid>

Erros

HTTP	Código	Descrição
401	—	Token ausente ou inválido
401	authentication_failed	Falha no fluxo WorkOS
403	staff_role_required	Usuário não é staff
403	patient_role_required	Usuário não é paciente
403	professional_role_required	Usuário não é profissional
403	organization_required	Organização não encontrada
403	—	Feature partner_platform_api não habilitada
404	—	Recurso não encontrado
422	participant_not_found	Participante não encontrado

Sessão

POST/api/v1/auth/sessionSem autenticação

Cria sessão a partir de access token WorkOS.

workos_access_token*	string	Access token WorkOS
device_name	string	Nome do dispositivo

{ "token": "eyJ...", "expires_at": "2026-07-29T00:00:00Z" }

DELETE/api/v1/auth/sessionBearer token

Invalida sessão. Retorna 204.

Perfil do Usuário

GET/api/v1/meBearer token (sessão)

Perfil do usuário, organização ativa e organizações em que é staff.

{ "user": { "id": "uuid", "name": "...", "email": "..." }, "organization": {...}, "organizations": [...] }

Organizações

GET/api/v1/organizationsBearer token (sessão)

Lista organizações em que o usuário é staff.

POST/api/v1/organizations/:id/switchBearer token (sessão)

Altera organização ativa. Requer ser staff na organização.

403 staff_role_required se não for staff.

Agendamentos

Requer feature: partner_platform_api

GET/api/v1/appointmentsAPI Key

Lista 50 agendamentos mais recentes.

[ { "id": "uuid", "title": "Consulta", "start_at": "2026-07-01T09:00:00Z", "end_at": "2026-07-01T10:00:00Z", "status": "confirmed" } ]

Pacientes

Dados PHI. Acesso registrado em auditoria. Requer partner_platform_api.

GET/api/v1/patientsPHI · AuditadoAPI Key

Lista 50 primeiros pacientes.

[ { "id": "uuid", "name": "Ana Souza", "user_id": "uuid | null" } ]

Faturas

GET/api/v1/invoicesAPI Key

Lista 50 faturas mais recentes. Requer partner_platform_api.

[ { "id": "uuid", "invoice_number": "INV-001", "amount_cents": 25000, "payment_status": "paid", "paid_at": "2026-06-15T14:30:00Z" } ]

Agenda do Profissional

Requer papel de profissional. Retorna 403 professional_role_required caso contrário.

GET/api/v1/me/agendaBearer token · Profissional

Agenda consolidada do profissional: disponibilidade e configurações de calendário.

GET/api/v1/me/appointmentsBearer token · Profissional

Agendamentos do profissional. Padrão: futuros. Use scope=past para passados.

GET/api/v1/platformAPI Key

Resumo OpenAPI da plataforma.

{ "version": "v1", "base_path": "/api/v1", "resources": ["appointments", "patients", "invoices"], "authentication": "Bearer API key" }

FHIR R4

HL7 FHIR R4. Acessos registrados em auditoria PHI. Autenticado via API Key.

GET/api/fhir/patients/:idPHI · AuditadoAPI Key

Paciente no formato FHIR R4 Bundle.

{ "resourceType": "Bundle", "type": "collection", "entry": [{ "resourceType": "Patient" }] }

GET/api/fhir/appointments/:idPHI · AuditadoAPI Key

Agendamento no formato FHIR R4 Appointment resource.

Autenticação Mobile

POST/api/mobile/v1/auth/tokenSem autenticação

Emite token mobile via código OAuth PKCE WorkOS.

code*	string	Código WorkOS PKCE
code_verifier*	string	Verificador PKCE
device_name	string	Nome do dispositivo

{ "token": "mt_...", "expires_at": "...", "user": {...}, "organizations": [...], "current_organization_id": "uuid" }

DELETE/api/mobile/v1/auth/tokenBearer token (mobile)

Logout mobile. Retorna 204.

Dashboard Mobile

Endpoints mobile requerem papel de paciente. Use X-Organization-Id para selecionar a organização.

GET/api/mobile/v1/dashboardBearer token · Paciente

Dashboard do paciente: próximos agendamentos, faturas pendentes e resumo da organização.

Agendamentos Mobile

GET/api/mobile/v1/appointmentsBearer token · Paciente

Agendamentos do paciente. Padrão: futuros. Use scope=past para passados.

GET/api/mobile/v1/appointments/:idBearer token · Paciente

Detalhes de um agendamento específico.

POST/api/mobile/v1/appointments/:id/confirmBearer token · Paciente

Confirma presença. Paciente deve ser participante com role patient.

422 participant_not_found se não for participante.

POST/api/mobile/v1/appointments/:id/declineBearer token · Paciente

Recusa o agendamento.

Faturas Mobile

GET/api/mobile/v1/invoicesBearer token · Paciente

Faturas do paciente na organização.

GET/api/mobile/v1/invoices/:idBearer token · Paciente

Detalhe de fatura. 404 se não pertencer ao paciente.

Organizações Mobile

GET/api/mobile/v1/organizationsBearer token (mobile)

Todas as organizações ativas do usuário.

POST/api/mobile/v1/organizations/:id/switchBearer token (mobile)

Altera organização ativa. Retorna dados da nova org e dashboard.

Webhooks — Google Calendar

Endpoint interno — chamado pelo Google. Não é necessário implementá-lo.

POST/google/webhooksGoogle Push Notification

Notificações push do Google Calendar para sincronização incremental.

organization_id	UUID	ID da organização
calendar_id	UUID	ID do GoogleCalendar

X-Goog-Channel-ID: <channel_id>
X-Goog-Resource-State: sync | exists | not_exists

Pronto para integrar?

Entre em contato para obter acesso à API, API Key e suporte técnico.

Solicitar acesso à API