Leve o prontuário da clínica para o seu sistema.
A API do Prontuário permite que um sistema parceiro, como um app do paciente, consulte com segurança os dados que a clínica liberou: cadastro, ficha clínica, medicamentos, exames, agenda e mais. É uma API REST, somente leitura, que responde em JSON.
https://app2.supermarcia.com.br/api/parceiro/v1Somente leitura
O parceiro consulta; nunca cria, altera ou apaga nada no prontuário.
Uma chave por parceiro
A clínica gera a chave, escolhe os dados liberados e pode revogar a qualquer momento.
Paciente pelo CPF
Você encontra o paciente pelo CPF ou e-mail. A partir daí, ele fica vinculado à sua chave.
Sincronização incremental
Um endpoint diz quais pacientes e quais blocos mudaram desde a última consulta.
O que dá para consultar
Cada bloco é liberado pela clínica, um a um, na hora de gerar a chave. Se um bloco não estiver liberado, o endpoint responde 403 escopo_nao_liberado.
| Bloco (escopo) | O que traz | Endpoints |
|---|---|---|
cadastro | Nome, CPF, e-mail, telefone, nascimento, sexo, gênero, endereço, foto, contato de emergência | /pacientes · /pacientes/{id} |
ficha | Tipo sanguíneo, alergias, doenças (CID), cirurgias, vacinas, peso e altura atuais | /pacientes/{id}/ficha |
medicamentos | Medicamentos em uso e histórico | /pacientes/{id}/medicamentos |
medidas | Sinais vitais e antropometria | /pacientes/{id}/medidas |
exames | Exames laboratoriais e de imagem (arquivos) | /pacientes/{id}/exames |
documentos | Atestados, declarações, planos em PDF, orientações | /pacientes/{id}/documentos |
receitas | Receitas (arquivos e Memed) | /pacientes/{id}/receitas |
agenda | Consultas, status, profissional, local, link de teleconsulta | /pacientes/{id}/agendamentos |
atendimentos | Resumo de atendimentos finalizados: conduta, orientações, exames pedidos, retorno | /pacientes/{id}/atendimentos |
planos | Planos de tratamento com itens e periodicidade (sem valores) | /pacientes/{id}/planos |
Começo rápido
Do zero à primeira ficha clínica em quatro chamadas.
Receba a chave da clínica
A clínica gera a chave em Integrações › Márcia Health › API do Prontuário e envia para você por um canal seguro. Chaves de teste começam com smk_test_; de produção, com smk_live_. Guarde a chave como segredo do servidor, nunca dentro do app.
Teste a conexão
O /status confirma a chave e mostra o que ela pode ver.
curl https://app2.supermarcia.com.br/api/parceiro/v1/status \ -H "Authorization: Bearer $SMK_CHAVE"
const BASE = "https://app2.supermarcia.com.br/api/parceiro/v1"; const res = await fetch(`${BASE}/status`, { headers: { Authorization: `Bearer ${process.env.SMK_CHAVE}` }, }); const { dados } = await res.json(); console.log(dados.conta, dados.escopos);
$base = 'https://app2.supermarcia.com.br/api/parceiro/v1'; $ch = curl_init("$base/status"); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('SMK_CHAVE')], CURLOPT_RETURNTRANSFER => true, ]); $r = json_decode(curl_exec($ch), true); echo $r['dados']['conta'];
import os, requests BASE = "https://app2.supermarcia.com.br/api/parceiro/v1" H = {"Authorization": f"Bearer {os.environ['SMK_CHAVE']}"} dados = requests.get(f"{BASE}/status", headers=H, timeout=20).json()["dados"] print(dados["conta"], dados["escopos"])
Encontre o paciente pelo CPF
Quando o paciente se cadastra no seu app, busque-o pelo CPF (ou e-mail). Guarde o id retornado: é a chave dele em todas as outras chamadas. Esta busca também vincula o paciente à sua chave.
curl "https://app2.supermarcia.com.br/api/parceiro/v1/pacientes?cpf=12345678909" \ -H "Authorization: Bearer $SMK_CHAVE"
Puxe os dados do paciente
Com o id, consulte cada bloco liberado. Exemplo: ficha clínica.
curl https://app2.supermarcia.com.br/api/parceiro/v1/pacientes/9167/ficha \ -H "Authorization: Bearer $SMK_CHAVE"
Autenticação
Toda chamada leva a chave no cabeçalho Authorization, no padrão Bearer.
Authorization: Bearer smk_live_3f9a…
Teste × produção
smk_test_… é para homologação (vale até 90 dias, geralmente 30). smk_live_… é para pacientes reais (12 meses ou sem vencimento, conforme a clínica) e só funciona a partir do IP do seu servidor, informado à clínica.
Sempre HTTPS
Chamadas sem HTTPS são recusadas. A chave nunca deve ir na URL, em logs ou no código do app instalado no celular do paciente: as chamadas saem do seu servidor.
Uma conta por chave
Cada chave pertence a uma clínica. Todas as respostas são só daquela clínica, e só dos blocos que ela liberou.
Revogação e troca
A clínica pode revogar a chave a qualquer momento (resposta passa a ser 401 token_invalido). Na troca, ela gera uma nova com o mesmo nome e os pacientes vinculados passam para a nova.
Vínculo do paciente
Sua chave não lista a base da clínica. Um paciente entra no alcance dela de duas formas: quando a clínica o agenda (se a opção "novos pacientes automaticamente" estiver ligada na chave) ou quando você o encontra pelo CPF ou e-mail.
A clínica agendou → paciente novo
O /alteracoes traz o paciente com o bloco novo_paciente. Busque o cadastro em /pacientes/{id}, crie a conta no seu app e envie o convite para ele definir a senha.
O paciente se cadastrou no app → busca por CPF
Para quem foi atendido antes da chave existir: busque /pacientes?cpf= no cadastro do app. Encontrou, o paciente fica vinculado.
Só pacientes aparecem: quem tem agendamento ou atendimento na clínica. Contatos do CRM (leads) nunca são retornados, nem pela busca por CPF. Por que assim? São dados de saúde. A busca por CPF garante que você só acessa quem de fato é seu usuário, e impede a varredura da base da clínica por número. Se o CPF estiver em mais de um cadastro na clínica, a busca devolve todos e vincula todos.
Sincronização
Em vez de baixar tudo de novo, pergunte o que mudou.
Receita recomendada
// 1) primeira carga (quando o paciente é vinculado) paciente = GET /pacientes?cpf={cpf} // guarda paciente.id para cada bloco liberado: GET /pacientes/{id}/{bloco} // salva no seu banco // 2) a cada 10–15 minutos r = GET /alteracoes?desde={ultimo_gerado_em - 1 minuto} para cada item em r.dados.alterados: se "novo_paciente" em item.blocos: p = GET /pacientes/{item.paciente_id} // nome, CPF, e-mail, telefone crie a conta no app (ou vincule pelo CPF) e envie o convite puxe todos os blocos liberados desse paciente para cada bloco em item.blocos: dados = GET /pacientes/{item.paciente_id}/{bloco} // todas as páginas substitua o bloco inteiro do paciente no seu banco ultimo_gerado_em = r.meta.gerado_em
Substitua o bloco, não some. Cada endpoint de bloco devolve o estado atual completo daquele paciente. Ao receber, troque tudo o que você tinha daquele bloco: assim, um registro removido na clínica também some do seu lado. Use 1 minuto de sobreposição no desde para não perder nada na virada.
Arquivos
Exames, documentos e receitas em PDF ou imagem vêm com um link temporário.
Link assinado
O campo arquivo_url já traz a assinatura. Não precisa de cabeçalho: é só baixar com GET.
Expira em 10 minutos
Baixe logo e guarde no seu armazenamento. Não salve o link: depois de expirado ele responde 410 link_expirado.
Mesmas regras da chave
O download respeita a chave que gerou o link: se ela for revogada ou o IP não for o seu, o arquivo é recusado.
Datas, paginação e formato
Resposta de sucesso
Sempre {"dados": …}. Listas trazem também {"meta": {"pagina", "limite", "tem_mais"}}.
Resposta de erro
Sempre {"erro": {"codigo", "mensagem"}}, com o status HTTP correspondente. Use o codigo na sua lógica, não a mensagem.
Datas
Formato AAAA-MM-DDTHH:MM:SS, no horário local da clínica (Brasília). Parâmetros de data aceitam também só AAAA-MM-DD. Campos sem valor vêm como null.
Paginação
?limite= de 1 a 200 (padrão 100) e ?pagina= a partir de 1. Continue enquanto meta.tem_mais for true.
Só o que mudou
Os endpoints de bloco aceitam ?atualizado_desde= para trazer só registros criados ou alterados depois da data.
Codificação
JSON UTF-8. CPF e telefone vêm só com números. IDs são inteiros e estáveis.
Referência de endpoints
Todos são GET, exigem a chave e respondem JSON. Os exemplos usam dados fictícios.
Confirma que a chave funciona e mostra a conta, os blocos liberados, o limite por minuto e a validade. Use para testar a integração e para alertar o seu time quando a chave estiver perto de expirar.
{
"dados": {
"conta": "Clínica Exemplo",
"token": "DrMycon",
"ambiente": "producao",
"escopos": ["cadastro", "ficha", "exames"],
"somente_autorizados": false,
"novos_pacientes_automaticos": true,
"novos_pacientes_desde": "2026-11-14T10:00:00",
"limite_por_minuto": 60,
"expira_em": "2027-11-14T10:00:00"
}
}Encontra o paciente pelo CPF ou e-mail e vincula à sua chave. Devolve uma lista (normalmente com 1 item). Não existe listagem da base inteira.
| Parâmetro | Descrição |
|---|---|
cpf | 11 dígitos, com ou sem pontuação. |
email alternativa | E-mail exato do cadastro. |
Lista vazia: o CPF não está cadastrado nesta clínica.
{
"dados": [{
"id": 9167,
"nome": "Maria Exemplo",
"cpf": "12345678909",
"email": "maria@exemplo.com",
"telefone": "85999990000",
"data_nascimento": "1988-03-21",
"sexo": "F",
"endereco": "Rua das Flores, 100 – Fortaleza/CE",
"foto_url": null,
"genero": "Mulher cisgênero",
"contato_emergencia": {
"nome": "João Exemplo",
"parentesco": "Cônjuge",
"telefone": "85988887777"
},
"atualizado_em": "2026-11-10T14:02:11"
}]
}Lista os pacientes vinculados à sua chave que tiveram algo criado ou alterado desde a data, e em quais blocos. Só aparecem blocos que a sua chave pode ver.
| Parâmetro | Descrição |
|---|---|
desde | Obrigatório. Use o meta.gerado_em da chamada anterior. |
Valores de blocos: novo_paciente (acabou de ser agendado: crie a conta no app), cadastro, ficha, medicamentos, medidas, exames, documentos, receitas, agendamentos, atendimentos, planos.
{
"dados": {
"alterados": [
{ "paciente_id": 9167, "blocos": ["exames", "agendamentos"] },
{ "paciente_id": 10422, "blocos": ["ficha"] }
],
"removidos": []
},
"meta": {
"desde": "2026-11-14T13:00:00",
"gerado_em": "2026-11-14T13:15:02"
}
}Cadastro atual do paciente vinculado, com gênero e contato de emergência (null quando não informados). Mesmo formato de um item da busca por CPF. Use para atualizar nome, contato e endereço quando /alteracoes indicar o bloco cadastro.
Paciente não vinculado à sua chave responde 404 paciente_nao_encontrado.
curl https://app2.supermarcia.com.br/api/parceiro/v1/pacientes/9167 \ -H "Authorization: Bearer $SMK_CHAVE"
Perfil de saúde: tipo sanguíneo, peso e altura mais recentes, alergias (com gravidade e reação), doenças com CID, cirurgias e vacinas.
| Campo | Observação |
|---|---|
alergias[].ativa | false = alergia descartada pelo profissional. |
doencas[].status | Situação informada pela clínica (ex.: ativa, controlada, resolvida). |
vacinas[].proximo_reforco | Útil para lembretes no app. |
{
"dados": {
"perfil": { "tipo_sanguineo": "O+", "peso_kg": 68.4, "altura": 1.65, "registrado_em": "2026-11-03T09:40:00" },
"alergias": [{ "id": 31, "nome": "Dipirona", "categoria": "medicamento",
"gravidade": "moderada", "reacao": "urticária", "ativa": true, … }],
"doencas": [{ "id": 88, "descricao": "Hipertensão arterial", "cid": "I10",
"data_diagnostico": "2021-05-10", "status": "ativa", … }],
"cirurgias": [{ "id": 4, "procedimento": "Apendicectomia", "data": "2015-02-01", … }],
"vacinas": [{ "id": 12, "nome": "Influenza", "dose": "anual",
"data_aplicacao": "2026-04-12", "proximo_reforco": "2027-04-12", … }]
}
}Medicamentos do paciente, em uso primeiro. em_uso: false = histórico.
| Parâmetro | Descrição |
|---|---|
ativos=1 opcional | Só os medicamentos em uso. |
atualizado_desde opcional | Só os alterados depois da data. |
limite, pagina | Paginação. |
Frequência é texto (ex.: "8/8h", "1x ao dia"), como o profissional registrou. Para lembretes, confirme os horários com o paciente no app.
{
"dados": [{
"id": 512,
"nome": "Losartana",
"principio_ativo": "losartana potássica",
"dose": "50 mg",
"via": "oral",
"frequencia": "1x ao dia",
"inicio": "2024-01-15",
"termino": null,
"motivo": "Hipertensão",
"prescritor_externo": null,
"em_uso": true,
"observacao": null,
"atualizado_em": "2026-10-02T10:11:00"
}],
"meta": { "pagina": 1, "limite": 100, "tem_mais": false }
}Duas séries, da mais recente para a mais antiga: sinais vitais (pressão, frequências, temperatura, saturação, glicemia, dor, peso, altura, IMC) e antropometria (composição corporal e circunferências). Campos não medidos vêm null.
{
"dados": {
"sinais_vitais": [{
"id": 77, "registrado_em": "2026-11-03T09:40:00",
"pressao_sistolica": 128.0, "pressao_diastolica": 82.0,
"frequencia_cardiaca": 74.0, "temperatura": 36.5,
"saturacao_o2": 98.0, "glicemia": 96.0,
"peso_kg": 68.4, "altura": 1.65, "imc": 25.1, …
}],
"antropometria": [{
"id": 20, "registrado_em": "2026-11-03T09:45:00",
"circunferencia_abdominal": 84.0, "gordura_percentual": 27.3,
"perimetro_cefalico": null, …
}]
},
"meta": { "pagina": 1, "limite": 100 }
}Exames laboratoriais e de imagem anexados ao prontuário. tipo: exame_laboratorial ou exame_imagem. Baixe o arquivo pelo arquivo_url em até 10 minutos (veja Arquivos).
{
"dados": [{
"origem": "arquivo",
"id": 20311,
"tipo": "exame_laboratorial",
"nome": "Hemograma completo",
"nome_arquivo": "hemograma_nov.pdf",
"data": "2026-11-05T16:20:00",
"profissional": "Dra. Ana Lima",
"especialidade": "Clínica médica",
"mime": "application/pdf",
"tamanho_bytes": 184220,
"arquivo_url": "https://…/arquivos/20311?tk=…&exp=…&sig=…"
}],
"meta": { "pagina": 1, "limite": 100, "links_expiram_em_segundos": 600 }
}Dois tipos de item, pelo campo origem:
| origem | Conteúdo |
|---|---|
arquivo | Atestados e planos em PDF, com arquivo_url. |
documento | Documentos e materiais gerados no atendimento, com o texto em conteudo_html (sem arquivo). |
Ao exibir conteudo_html, sanitize o HTML antes de renderizar.
{
"dados": [
{ "origem": "documento", "id": 88, "tipo": "material",
"nome": "Orientações pós-consulta", "data": "2026-11-03T10:05:00",
"conteudo_html": "<p>Beber 2 L de água…</p>", "arquivo_url": null, … },
{ "origem": "arquivo", "id": 20102, "tipo": "atestado",
"nome": "Atestado", "arquivo_url": "https://…", … }
]
}Receitas anexadas (origem: "arquivo", com link temporário) e receitas digitais Memed (origem: "memed", com o link da própria Memed quando disponível).
{
"dados": [
{ "origem": "memed", "id": 74, "tipo": "receita", "nome": "Receita",
"data": "2026-11-03T10:02:00", "profissional": "Dra. Ana Lima",
"status": "enviada", "arquivo_url": "https://memed.com.br/…" }
]
}Consultas do paciente, da mais recente para a mais antiga.
| Parâmetro | Descrição |
|---|---|
de, ate opcional | Filtra pela data da consulta. Ex.: próximas consultas = ?de=hoje. |
atualizado_desde opcional | Só as criadas ou alteradas depois da data. |
status: agendado, confirmado, em_atendimento, compareceu, nao_compareceu, desmarcado, remarcado.
{
"dados": [{
"id": 135220,
"inicio": "2026-11-20T14:00:00",
"fim": "2026-11-20T14:30:00",
"status": "confirmado",
"profissional": "Dra. Ana Lima",
"especialidade": "Clínica médica",
"servicos": "Consulta de retorno",
"local": { "nome": "Unidade Aldeota", "endereco": "Av. Santos Dumont, 2000",
"cidade": "Fortaleza", "uf": "CE" },
"teleconsulta_url": null,
"atualizado_em": "2026-11-14T08:12:40"
}],
"meta": { "pagina": 1, "limite": 100, "tem_mais": false }
}Resumo dos atendimentos finalizados ou assinados (atendimentos em andamento nunca aparecem): conduta, orientações, exames solicitados, encaminhamentos e retorno recomendado.
Se a clínica liberar também a nota médica completa (clinico_completo), cada item ganha o objeto clinico com queixa, histórias, exame físico, hipóteses, CIDs e evolução.
{
"dados": [{
"id": 70011,
"data": "2026-11-03T10:00:00",
"status": "finalizado",
"profissional": "Dra. Ana Lima",
"especialidade": "Clínica médica",
"conduta": "Manter losartana 50 mg.",
"orientacoes": "Reduzir sal, caminhar 30 min/dia.",
"exames_solicitados": "Hemograma, perfil lipídico",
"encaminhamentos": null,
"retorno_recomendado_em": "2026-12-03",
"retorno_observacao": "Trazer exames",
"atualizado_em": "2026-11-03T10:31:00"
}],
"meta": { "pagina": 1, "limite": 100, "tem_mais": false }
}Planos de tratamento aprovados, em andamento ou concluídos (rascunhos e orçamentos não aparecem), com os itens e a periodicidade. Sem valores financeiros. Bom para a "meta terapêutica" e lembretes estruturados.
{
"dados": [{
"id": 635, "titulo": "Controle da pressão", "status": "em_andamento",
"inicio": "2026-11-03", "fim_previsto": "2027-02-03",
"profissional": "Dra. Ana Lima",
"itens": [{
"id": 2350, "tipo": "medicamento", "nome": "Losartana",
"dose": "50 mg", "via": "oral", "frequencia": "1x ao dia",
"periodicidade": { "tipo": "diaria", "valor": "1", "observacao": null },
"quantidade_planejada": 90.0, "status": "ativo", …
}]
}]
}Erros
Formato único: {"erro": {"codigo": "…", "mensagem": "…"}}.
| HTTP | codigo | O que fazer |
|---|---|---|
| 400 | parametro_invalido · parametro_obrigatorio | Corrija o parâmetro (CPF com 11 dígitos, data no formato certo, desde informado). |
| 401 | token_ausente · token_invalido | Envie o cabeçalho Authorization. Se já envia, a chave foi revogada ou expirou: peça uma nova à clínica. |
| 403 | escopo_nao_liberado | A clínica não liberou esse bloco para a sua chave. |
| 403 | ip_nao_autorizado | A chamada saiu de um IP que não está cadastrado na chave. |
| 403 | modulo_inativo · https_obrigatorio · link_invalido | Prontuário inativo na clínica, chamada sem HTTPS ou link de arquivo alterado. |
| 404 | paciente_nao_encontrado | Paciente inexistente ou ainda não vinculado. Busque antes por CPF. |
| 404 | rota_inexistente · arquivo_nao_encontrado · arquivo_indisponivel | Confira o endereço. Para arquivos, consulte o bloco de novo. |
| 405 | metodo_nao_permitido | A API é somente leitura: use GET. |
| 410 | link_expirado | O link do arquivo passou de 10 minutos. Consulte o bloco de novo para receber outro. |
| 429 | limite_excedido | Espere o tempo do cabeçalho Retry-After (60 s) e tente de novo. |
| 503 | indisponivel | Instabilidade temporária. Tente de novo com espera crescente. |
Limites e boas práticas
Limite por minuto
Padrão de 60 requisições por minuto por chave (a clínica pode ajustar). Acima disso, 429 com Retry-After: 60.
Sincronize pelo /alteracoes
Consulte a cada 10–15 minutos e busque só os blocos indicados. Evite varrer todos os pacientes em todo ciclo.
Tente de novo com calma
Em 429 e 5xx, espere e tente de novo com intervalo crescente (1 s, 2 s, 4 s…). Não repita 4xx sem corrigir a causa.
Guarde os arquivos
Baixe assim que receber o link e armazene do seu lado. Não exponha o link ao app do paciente.
Chave só no servidor
Use variável de ambiente ou cofre de segredos. Se a chave vazar, avise a clínica para revogar e gerar outra.
Monitore a validade
Use /status para ver expira_em e peça a renovação à clínica com antecedência.
Segurança e LGPD
Dados de saúde são dados pessoais sensíveis. A integração foi desenhada para que a clínica mantenha o controle.
Controle da clínica
A clínica decide quais blocos libera, de qual IP, por quanto tempo, e pode revogar a qualquer momento.
Tudo registrado
Cada consulta fica no histórico da clínica: quando, de qual IP, qual bloco e de qual paciente.
Mínimo necessário
Sem dados financeiros, sem rascunhos, sem atendimentos em andamento. Nota médica completa só com liberação explícita.
Antes da produção: a clínica (controladora) e o parceiro (operador/controlador do app) devem formalizar um acordo de tratamento de dados. O parceiro é responsável pela guarda segura do que recebe e por mostrar a cada paciente apenas os próprios dados.