Integrando com o Prescreve

1. ContatoNo cadastro do Prescreve (/register), a opção "Quer integrar o Prescreve ao seu sistema via API?" abre um formulário que chega direto pro time comercial.
2. Conta de IntegraçãoA equipe Softmente cria uma conta do tipo Integração, associada ao plano correspondente.
3. Geração da chaveUm admin da plataforma gera a API Key pelo painel administrativo e a compartilha com você por um canal seguro combinado.

GET /v1/patients HTTP/1.1
Host: api.prescreve.app
X-API-Key: rcp_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

O formato da chave é rcp_ seguido de 32 caracteres hexadecimais. Uma chave inválida ou revogada retorna 401; uma conta suspensa (trial expirado, pagamento em atraso) retorna 403 com code: "ACCOUNT_SUSPENDED" — vale tratar esse código especificamente no seu lado, já que ele indica um problema de conta, não de requisição.

URL base

Todas as rotas ficam sob o prefixo /v1. Combine o domínio exato com o time Softmente no momento do provisionamento.

Isso também significa que uma chave nunca representa um médico ou assistente específico — todas as ações feitas com ela aparecem como sendo da clínica/conta como um todo, não de uma pessoa. Se seu sistema precisa saber "quem fez o quê" de forma auditável por usuário individual, isso precisa ser controlado no seu lado, não no Prescreve.

Respostas de sucesso

{ "success": true, "data": { "id": "...", "name": "..." } }

Listas paginadas

Paginação é opcional — omita page/limit pra receber a lista inteira. Informando os dois, a resposta ganha um bloco meta:

GET /v1/patients?page=1&limit=20

{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 143, "page": 1, "limit": 20, "totalPages": 8 }
}

limit é sempre limitado a 100, mesmo se um valor maior for enviado.

Erros

{ "error": "Paciente não encontrado." }

Não há um limite maior liberado especificamente pra chaves de integração hoje. Se sua integração faz sincronização em lote (ex: importar um histórico grande de pacientes), espace as chamadas ou entre em contato pra combinar uma janela de importação. Ao exceder o limite, a resposta é 429 com uma mensagem indicando pra tentar novamente em breve — não há cabeçalho Retry-After hoje, então um backoff exponencial simples do seu lado é a abordagem mais segura.

Acessível com API Key

Só com login interativo (JWT) — não aceita API Key

Essas áreas são login-only por natureza — o portal do paciente e o de farmácia são experiências de outra pessoa (paciente/farmacêutico) logando com a própria conta, e cobrança/configurações da conta são ações que fazem mais sentido vindas de um humano autenticado interativamente do que de uma integração automatizada.

Público, sem autenticação

Verificação de documentos (/v1/verify/*) e o formulário de contato são públicos por design — não precisam de chave nenhuma.

Na prática, isso divide o fluxo em duas partes:

1. Sua integração cria o rascunhoVia API Key: paciente, receita/documento com os medicamentos ou conteúdo, tudo como rascunho — sem validade jurídica ainda.
2. O médico assina no PrescreveO médico precisa logar normalmente (navegador) e assinar o rascunho pelo painel — seja abrindo o Prescreve diretamente, seja através de um link que sua integração gere apontando pra tela de edição do documento.

Em receitas especificamente, isso também aparece no Swagger: as rotas de listar/criar/consultar receitas aceitam API Key, mas PATCH /v1/prescriptions/:id (editar) e POST /v1/prescriptions/:id/sign (assinar) exigem sessão JWT do médico — API Key não é aceita nessas duas.

Não existe hoje um mecanismo de notificação push (webhook) pra avisar sua integração quando, por exemplo, um médico termina de assinar um documento criado por você. O padrão recomendado é fazer polling do recurso específico:

GET /v1/prescriptions/{id}
→ verifique o campo "status": "DRAFT" | "SIGNED" | "CANCELLED"

Pra evitar polling excessivo, filtre por status ao listar (ex: GET /v1/prescriptions?status=SIGNED) e use um intervalo razoável (30–60s) em vez de consultar em loop apertado — lembre do limite de 200 req/min por IP.

Cria o paciente (ou reaproveita um já existente, se o corpo incluir um externalId que já foi usado antes — o Prescreve trata isso como upsert pelo seu identificador).

{
  "externalId": "pac_38210",
  "name": "Maria da Silva",
  "cpf": "000.000.000-00",
  "birthDate": "1990-04-12",
  "phone": "11999998888"
}

→ 201 { "success": true, "data": { "id": "b7e1...", "name": "Maria da Silva", ... } }

Cria a receita como rascunho, vinculada ao médico e ao paciente.

{
  "prescriberId": "d92a...",
  "patientId": "b7e1...",
  "prescriptionType": "SIMPLES",
  "medications": [
    { "name": "Amoxicilina 500mg", "dosage": "1 cápsula", "frequency": "de 8 em 8h por 7 dias" }
  ]
}

→ 201 { "success": true, "data": { "id": "f0c3...", "status": "DRAFT", ... } }

Faça polling deste endpoint (ou liste com filtro de status) até status virar "SIGNED". A resposta assinada já traz o link de verificação e o PDF:

→ 200 {
  "success": true,
  "data": {
    "id": "f0c3...",
    "status": "SIGNED",
    "verifyToken": "8f2c1a9b",
    "pdfUrl": "https://.../v1/verify/8f2c1a9b/pdf"
  }
}

Endpoint público de verificação — o mesmo que o QR code do PDF aponta. Não precisa de chave, e é seguro compartilhar esse link com o paciente.

Lista/busca pacientes. Filtros comuns: search (nome/CPF), externalId, mais page/limit pra paginar.

name

Nome completo. obrigatório

cpf

CPF do paciente.

externalId

Identificador do paciente no seu sistema — usado como chave de upsert em chamadas futuras.

birthDate, phone, email, address...

Demais campos cadastrais, todos opcionais.

Filtros úteis: status (DRAFT / SIGNED / CANCELLED), patientId, prescriberId.

prescriberId

Médico que vai assinar. obrigatório

patientId

Paciente. obrigatório

medications[]

Lista de medicamentos (nome, dosagem, frequência...). obrigatório

prescriptionType

Simples, Controle Especial, Notificação A/B/B2, Retinoide, Talidomida. Tipos de controle especial exigem um talonário com numeração disponível.

validUntil, notes

Opcionais.

Cada um segue o padrão POST / (criar rascunho), GET / e GET /:id (consultar), PATCH /:id (editar rascunho), POST /:id/sign (assinar — requer o médico logado), POST /:id/cancel.

Consultas por profissional e período — útil pra sincronizar disponibilidade com um sistema de agendamento externo.

Anotações de prontuário por paciente.

Confirma que o token é válido e devolve um resumo do documento.

Com o CPF do paciente no corpo, devolve os dados completos e o pdfUrl.

Bytes do PDF diretamente — é o link que o QR code do documento impresso abre.