receitapdf

Biblioteca Rust, CLI e extensão Python que recebem uma prescrição estruturada e devolvem os bytes do PDF. Os oito modelos usam os layouts ajustados e aprovados em examples/: A, B, B2, A/B veterinários, retinoides, talidomida e Receita de Controle Especial (RCE). A RCE também tem a variação receita_controle_especial_veterinaria, para prescrever medicamento humano a animais, com paciente/proprietário no padrão do NRA veterinário.

Também gera receita simples, pedidos de exame e documentos (atestado, declaração, termo, encaminhamento) em layouts nativos; veja Documentos nos layouts nativos.

Layouts usados na geração

A CLI e as APIs Rust/Python usam o mesmo renderizador Rust. Os cabeçalhos aprovados estão incorporados em assets/modelos/; os boxes, rótulos, dados, rodapé e QR são desenhados na geração. Não é necessário instalar PyMuPDF, executar scripts Python ou acessar a rede para gerar uma receita.

Os PDFs originais continuam como referência. Os layouts ajustados são derivados desses arquivos; não são os arquivos oficiais intactos. A consulta feita durante os ajustes está em endereço e modelo oficial.

Padrões compartilhados:

• Página de 595,5 × 842,25 pt; espaçamento de 10 pt entre os boxes.
• Caixa de numeração com as mesmas dimensões nos modelos e na variação veterinária da RCE.
• Rótulos de 7,5 pt acima dos valores de 10 pt; entrelinha de 14 pt.
• Nomes com até duas linhas; endereços de emitente/paciente com até três.
• Emitente e paciente com a mesma altura, calculada pelos dados.
• Prescrição com quebra automática e limite definido pelo espaço disponível.
• Rodapé alinhado pela base, com entrelinha de 20 pt. Plataforma e assinatura aceitam até duas linhas cada, sem reservar uma linha vazia.
• Últimas três instruções em itálico, URLs em negrito itálico ao lado dos rótulos.
• Token e código acima do QR, alinhados ao seu lado esquerdo; base visível do QR alinhada à última linha do rodapé.
• Na talidomida, nome/CPF/telefone do responsável ficam lado a lado, com endereço abaixo e espaço para duas linhas. Dose e tempo de tratamento ficam lado a lado.

A prescrição utiliza o espaço restante acima do rodapé: textos adicionais no rodapé reduzem sua altura quando necessário. Conteúdo que excede a capacidade retorna erro; não é truncado nem sobreposto.

CLI

Rust está declarado em mise.toml:

mise install
mise exec rust -- cargo run --release -- examples/notificacao-a.json saida.pdf

O executável recebe <entrada.json> <saida.pdf> [--preview <pasta>]. JSON com modelo gera uma receita Anvisa; JSON com layout gera um documento nativo. Com --preview, grava também a prévia de cada página em <pasta>/pagina-N.webp. Para entrada padrão:

cat examples/notificacao-a.json | mise exec rust -- cargo run --release -- - saida.pdf

API Rust

use receitapdf::{gerar_pdf, Receita};

fn gerar(receita: &Receita) -> Result<Vec<u8>, receitapdf::Erro> {
    gerar_pdf(receita)
}

gerar_pdf valida os campos obrigatórios, número, telefones e capacidade do layout. Retorna os bytes do PDF ou Erro. A assinatura criptográfica, a obtenção do número SNCR e as decisões clínicas são responsabilidades da integração chamadora.

API Python

CPython 3.13 ou superior. A extensão usa PyO3 com ABI estável abi3; Rust/Cargo são necessários para compilar a partir do código-fonte:

python3.13 -m pip install .

import json
from pathlib import Path
from receitapdf import gerar_pdf, url_qr

receita = json.loads(Path("examples/notificacao-a.json").read_text(encoding="utf-8"))
Path("saida.pdf").write_bytes(gerar_pdf(receita))
print(url_qr(receita))

gerar_pdf retorna bytes. Entrada ausente, inválida ou que exceda o espaço disponível gera ValueError; falhas internas de geração geram RuntimeError. Para construir o wheel: maturin build --release.

JSON: campos e formatos

CLI e APIs aceitam a mesma estrutura. Todos os exemplos declaram todos os campos da API; opcionais não usados recebem null. Os arquivos dados-curtos.json e dados-longos.json em cada pasta de modelo também são entradas válidas da CLI. Dados são totalmente fictícios.

Campos da receita

Campos obrigatórios não aceitam texto em branco. Os limites de linhas são medidos pela fonte e largura efetivas do PDF; uma palavra que não caiba na largura é rejeitada. \n cria uma quebra explícita. Datas, CPF/passaporte, CID e valores clínicos são textos fornecidos pela integração; o componente não valida sua semântica.

Emitente (prescritor)

Paciente / proprietário (paciente)

Campos específicos de um modelo são impressos somente nele. Telefones preenchidos são validados mesmo quando o campo não é impresso.

Prescrição (medicamento)

Na talidomida, o box usa quantidade, dose, tempo de tratamento, posologia e outras orientações. Nome, concentração e forma farmacêutica continuam obrigatórios na entrada estruturada, embora não sejam impressos nesse modelo.

Dados específicos e responsável

Sem responsável, o box permanece vazio. O endereço dele reserva duas linhas conforme o layout aprovado.

Telefones e endereços

Telefones devem usar E.164 sem espaços ou pontuação: +5571930000000. Outros formatos, como (71) 93000-0000, são rejeitados. No PDF, números brasileiros aparecem como (71) 93000-0000 ou (71) 3000-0000; telefones de outros países mantêm E.164.

Endereços são strings completas. Padrão usado nos exemplos: logradouro, número, complemento, bairro, cidade/UF, CEP 00000-000. A ordem é uma convenção dos exemplos, não uma validação normativa implementada. Veja a consulta sobre endereço.

Modelos, exemplos e QR

Nas Notificações, o QR usa a consulta SNCR:

https://sncr.anvisa.gov.br/receita/consultar?numero={numero}

Nas duas RCEs, o QR usa exatamente link_verificacao, conforme o layout aprovado neste projeto. O número da RCE segue o mesmo padrão textual do A, mas seu QR é da plataforma. url_qr retorna a URL correspondente nos modelos e na variação veterinária da RCE.

Documentos nos layouts nativos

Os layouts simples_carimbo e simples_digital geram receita simples, fórmula manipulada, pedidos de exame, atestados, declarações, termos e encaminhamentos. Diferem só no bloco de assinatura: espaço para carimbo ou caixa de assinatura digital. A geometria é fixa, como nos modelos Anvisa: texto que excede o limite do campo gera erro. Cabeçalho, paciente e título se repetem em todas as páginas; assinatura e "Emitido em" ficam só na última.

mise exec rust -- cargo run --release -- examples/documentos/receita-simples.json receita.pdf

use receitapdf::{gerar_documento, Documento, Imagens};

fn gerar(documento: &Documento, logo_png: &[u8]) -> Result<Vec<u8>, receitapdf::Erro> {
    let imagens = Imagens { logo: Some(logo_png), ..Imagens::default() };
    Ok(gerar_documento(documento, imagens)?.pdf)
}

import json
from pathlib import Path
from receitapdf import gerar_documento

pasta = Path("examples/documentos")
documento = json.loads((pasta / "receita-simples.json").read_text(encoding="utf-8"))
gerado = gerar_documento(
    documento,
    logo=(pasta / "logo-exemplo.png").read_bytes(),
    marca_dagua=(pasta / "marca-dagua-exemplo.png").read_bytes(),
)
Path("documento.pdf").write_bytes(gerado.pdf)
print(gerado.areas_assinatura)  # [], ou as áreas com assinatura.coordenadas

A biblioteca Rust recebe as imagens em bytes (Imagens) e não lê arquivos nem acessa a rede. clinica.logo (cabeçalho) e marca_dagua (rodapé, a 10% de opacidade) aceitam PNG de até 2 MB; imagens do corpo também são fornecidas em Imagens.corpo, associadas ao texto de origem. Todos são opcionais, e sem marca d'água o rodapé fica sem marca:

• CLI: caminho relativo ao JSON (ou ao diretório atual, com stdin) ou endereço https://, baixado com tempo limite de 10 s, sem redirecionamento para HTTP. O download depende da feature rede, padrão na CLI e ausente na extensão Python. Blocos de imagem no corpo usam caminhos de PNG locais.
• Python: só endereços https:// são baixados automaticamente; para arquivos locais, passe os bytes em logo= e marca_dagua=.

Campos do documento

• medicamento: nome (até duas linhas), quantidade, detalhe (apresentação, até duas linhas) e observacao (posologia, até quatro linhas).
• exame: nome (até duas linhas), codigos (lista de rotulo/valor, até duas linhas) e instrucao (até três linhas).

Medicamentos e exames são numerados em sequências próprias e nunca se dividem entre páginas; parágrafos quebram por linha. CID-10 e orientações aparecem depois do corpo, abaixo de um tracejado, com o rótulo sempre junto da primeira linha.

Conteúdo rico (TipTap 3, contrato v1)

Os layouts documento_carimbo e documento_digital removem toda a faixa do paciente e seu espaço. Clínica, emissor, título, assinatura (inclusive signatarios_extras), data e verificação continuam em Documento. O corpo do editor entra em conteudo_rico:

{
  "conteudo_rico": {
    "schema": 1,
    "doc": {
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "attrs": {"alignment": "justify"},
        "content": [
          {"type": "text", "text": "Atesto o comparecimento de "},
          {"type": "structuredField", "attrs": {"field": "paciente.nome"}, "marks": [{"type": "bold"}]}
        ]
      }]
    },
    "fields": {"paciente.nome": "Maria Helena Duarte"},
    "images": {}
  }
}

O exemplo acima é o trecho a acrescentar ao objeto Documento, não um documento completo. Rust, CLI e Python interpretam o mesmo envelope, sem acesso a arquivos ou rede para resolver campos e imagens ricos.

• Nós: paragraph, heading (nível 3), text, hardBreak, listas bulletList/orderedList com listItem aninhados, structuredField e clinicalImage. Listas numeradas sempre começam em 1 (start/type ignorados).
• Marcas: bold, italic e underline, combináveis. Itálico usa inclinação tipográfica da mesma fonte Quicksand. Títulos internos usam negrito de 14 pt; texto usa 12 pt. Parágrafos vazios e quebras explícitas preservam linhas vazias.
• Alinhamento: attrs.alignment ausente/null = esquerda; center, right ou justify. A última linha do parágrafo e linhas com quebra explícita não são justificadas. Espaços não separáveis (NBSP) não criam quebras de palavra.
• Campos: o valor vem exclusivamente de fields[attrs.field], preservando marcas e \n; label nunca é impresso como valor. Campo ausente gera erro.
• Imagem: {"type":"clinicalImage","attrs":{"image":"id","width":"50","float":"left"}}. Larguras: "25", "50" (padrão), "100", em percentual da largura útil da página. float ausente/null centraliza; left/right fazem as linhas seguintes contornarem a imagem até sua base. Largura 100 não flutua. images[id] contém content_type, width/height em pixels e data_base64. São aceitos PNG, JPEG, GIF e WebP (primeiro quadro nos formatos animados). Dimensões declaradas são conferidas com os bytes, sem EXIF/reorientação.
• Margens de imagens: 12 pt acima/abaixo em bloco; floats têm 4 pt acima, 20 pt entre imagem/texto e 12 pt abaixo. Cantos de 4 pt. Como nos layouts existentes, 1 px de geometria do editor corresponde a 1 pt no PDF.
• Imagens não se dividem entre páginas; float e linhas ao lado permanecem juntos. Floats adjacentes compartilham a linha quando há espaço; imagens em bloco começam depois dos floats ativos. Conteúdo que não cabe inteiro em sua área gera erro, nunca truncamento. Os limites de segurança por imagem são 16 MiB de bytes, 40 milhões de pixels e 16000 px por dimensão.
• Versão diferente de 1, atributos inválidos, campo/imagem faltante ou bytes inválidos retornam erro (ValueError em Python). Nós desconhecidos preservam o texto dos filhos; marcas desconhecidas são ignoradas. Profundidade máxima: 64.

Os 21 JSONs de referência estão em tests/fixtures/tiptap-v1.json. Exemplo completo com imagens incorporadas e formatação: examples/documentos/documento-tiptap.json.

Imagens legadas de blocos corpo[].imagem continuam em Imagens.corpo (Rust) ou imagens_corpo={"origem": bytes_png} (Python). Isso não é necessário para conteudo_rico.images, que já transporta os bytes em base64.

Assinatura

• simples_carimbo e documento_carimbo: reservam espaço acima da linha do emissor para carimbo e assinatura manual ou carimbo visual do serviço de assinatura. O rodapé só afirma a assinatura ICP-Brasil com campo_sig ou coordenadas.
• simples_digital e documento_digital: caixa com QR e texto de assinatura ICP-Brasil. O QR usa assinatura.url_qr (por exemplo, o validador da assinatura) ou, sem ele, verificacao.url_qr.
• campo_sig: cria campos de assinatura vazios (/FT /Sig) na última página, onde serviços PAdES assinam pelo nome: assinatura_emissor e, num termo em simples_digital, assinatura_paciente. Em simples_digital o campo do emissor é invisível.
• coordenadas: retorna areas_assinatura, uma lista com campo, pagina, x, y, largura, altura, largura_pagina e altura_pagina, em pontos com origem no canto inferior esquerdo (o mesmo espaço do /Rect do PDF). A CLI imprime a lista em JSON. Em simples_carimbo a área é o espaço do carimbo do emissor; em simples_digital o emissor não tem área (a caixa já mostra a assinatura) e, num termo, o paciente tem a área acima da linha dele, ao lado da caixa.

Os demais exemplos, inclusive documentos de várias páginas, estão em examples/documentos, com prévias e contato visual.

Prévia em WebP

gerar_preview rasteriza todas as páginas de um PDF gerado (receita Anvisa ou documento nativo) e devolve uma imagem WebP sem perdas por página, com a marca d'água diagonal "PRÉVIA — SEM VALIDADE" em cinza translúcido. O PDF não muda: a marca existe só nas imagens.

let paginas: Vec<Vec<u8>> = receitapdf::gerar_preview(&pdf, 144.0)?;

from receitapdf import gerar_preview

for numero, webp in enumerate(gerar_preview(gerado.pdf, dpi=144), start=1):
    Path(f"pagina-{numero}.webp").write_bytes(webp)

• dpi vai de 36 a 300 (144 dpi gera A4 com 1190 × 1684 px). Fora da faixa, ou com PDF ilegível, gera Erro::PreviaInvalida (ValueError em Python).
• Usa o hayro, rasterizador em Rust puro, sem PyMuPDF nem bibliotecas nativas. Fica na feature preview, padrão na CLI e incluída na wheel, onde acrescenta cerca de 2,5 MB. No Python, a função libera o GIL.
• Exemplo de uma receita de três páginas.

Gerar todos os exemplos

python -m pip install pymupdf pillow
python examples/gerar_exemplos.py

O script compila a CLI Rust e gera:

• Os oito PDFs principais e a variação veterinária da RCE em examples/.
• Dezoito PDFs e PNGs, com dados curtos e longos, em modelos-gerados.
• Prévias de 144 dpi e contato visual.
• Os quatro exemplos de rodapé com plataforma/assinatura em uma ou duas linhas, em examples/rodape-plataforma-*.pdf.
• Cada documento de examples/documentos/ nos layouts simples_carimbo e simples_digital, com PNGs de todas as páginas em examples/documentos/png/ e as prévias WebP da receita longa, geradas pela CLI, em examples/documentos/previa/.

PyMuPDF e Pillow são usados apenas nas prévias. Os PDFs são produzidos pela mesma CLI que o consumidor usa.

Os scripts examples/recriar_*.py mantêm as referências de ajuste visual e usam os mesmos JSONs da API. Após alterar os cabeçalhos nesses estudos, execute python examples/preparar_modelos.py para atualizar assets/modelos/ e recompile a biblioteca. As fontes Open Sans e os avisos vetoriais vêm dos originais; a composição Rust usa printpdf e lopdf. DejaVu Sans é incorporada nos dados e DejaVu Sans Bold Oblique nas URLs. Os layouts simples_* usam Quicksand (OFL).

Compilação e testes

mise exec rust -- cargo check --locked --all-targets --features python
mise exec rust -- cargo test --locked
mise exec rust -- cargo test --locked --features python
maturin build --release

O código é MIT (LICENSE); fontes e modelos de origem mantêm seus próprios termos.

Publicar no PyPI

O workflow publish-pypi.yml cria o sdist e o wheel Linux x86_64, executa os testes e publica via Trusted Publishing. Para habilitar a publicação, cadastre um publisher pendente nas configurações do PyPI com estes valores:

• Projeto PyPI: receitapdf
• Owner do GitHub: ramon
• Repositório: receitapdf
• Workflow: .github/workflows/publish-pypi.yml
• Environment do GitHub: pypi

Depois desse cadastro, a publicação pode ser iniciada manualmente em master ou ao publicar uma release do GitHub com tag vX.Y.Z igual à versão em pyproject.toml. O job usa OIDC; não é necessário guardar token do PyPI como secret.