PMC / OA – Obtenção de PDF de Literatura
Pré-requisitos
Apenas para artigos de Acesso Aberto (OA) (CC BY / CC BY-NC / CC BY-NC-ND, etc.). Não use para contornar paywalls de artigos assinados – isso constitui violação de direitos autorais. Verifique o status OA: Unpaywall retorna is_oa: true ou EuropePMC isOpenAccess: Y.
Cenário de Assinatura Institucional (Complemento Importante)
Quando a universidade/instituição do usuário possui assinatura de banco de dados da editora, o download manual de artigos individuais é totalmente compatível dentro dos termos de licença, mas é necessário atentar para:
- Rede do campus / IP institucional: As editoras reconhecem o IP, não o usuário. O 5º nível da cadeia de fallback (link direto da editora) geralmente retorna 200 sem bloqueio do Cloudflare – nesse caso, o pipeline desta skill pode obter diretamente o conteúdo assinado, sem qualquer lógica de login.
- Acesso externo: Priorize o uso de VPN institucional (transparente para scripts, configurada uma vez); WebVPN (proxy baseado em reescrita de URL) não é suportado devido às regras variáveis entre instituições e à necessidade de cookies de sessão.
- Não implemente automação de login Shibboleth/OpenAthens: Requer armazenamento local de credenciais, representando risco de segurança; além disso, os fluxos IdP variam muito entre instituições, inviabilizando uma implementação genérica.
- Linha vermelha para download em massa: Quase todas as licenças institucionais de editoras diferenciam entre download manual individual e downloading sistemático/em massa. Mesmo com assinatura, a coleta automatizada em massa viola os termos, podendo levar ao bloqueio de todo o bloco de IPs da instituição. Para necessidades reais de mineração de texto completo em larga escala, solicite a API TDM (Text Mining) da editora (ex.: Elsevier TDM API, Springer Nature Meta API) pelos canais oficiais de cota, em vez de usar esta skill para loops em massa.
Cadeia de Fallback (Ordem Estrita)
| Prioridade | Via | Comando / Endpoint | Descrição |
|---|---|---|---|
| 1 | EuropePMC Texto Completo Estruturado | https://www.ebi.ac.uk/europepmc/webservices/rest/{PMCID}/fullTextXML | Mais estável. Extrai estrutura de texto completo com precisão de subtítulos. Retorna JATS XML |
| 2 | Unpaywall localiza localização OA | https://api.unpaywall.org/v2/{DOI}[email protected] | Lê oa_locations[].url_for_pdf, fornece link direto para PDF |
| 3 | Resolução PoW do PMC | scripts/pmc_pdf.py <PMCID> <out.pdf> | Veja abaixo. Solução principal para obter PDF do artigo |
| 4 | EuropePMC Materiais Suplementares | https://www.ebi.ac.uk/europepmc/webservices/rest/{PMCID}/supplementaryFiles | Retorna ZIP: imagens originais (gr1…=Figura 1…) + PDF de material suplementar (mmc1.pdf) |
| 5 | Link direto da editora | Cada editora .../article-pdf/... | Geralmente retorna 403 (Cloudflare). Tente por último |
Endpoints Confirmadamente Inválidos (Não Perca Tempo)
…/rest/{PMCID}/fullTextPDF→ 404 (obsoleto)…/rest/{PMCID}/fulltextRepo→ 403https://europepmc.org/articles/{PMCID}?pdf=render→ 403https://europepmc.org/backend/ptpmcrender.fcgi?accid=…&blobtype=pdf→ 403https://www.ncbi.nlm.nih.gov/pmc/utils/oa/oa.fcgi?id=…→ 404 (serviço OA migrado)- Páginas de artigo
ashpublications.orgficam presas no desafio Cloudflare "Aguarde…" em navegadores headless, não utilizável
★ Pré-requisito: Nome do arquivo PDF do PMC não é fixo, deve ser resolvido primeiro
O nome do arquivo em https://pmc.ncbi.nlm.nih.gov/articles/{PMCID}/pdf/<nome>.pdf varia conforme periódico e ano. Codificar main.pdf resultará em 404 na maioria dos casos.
| Periódico testado | Nome real do arquivo |
|---|---|
| Am J Hematol | main.pdf |
| Blood Advances | main.pdf |
| HemaSphere | HEM3-10-e70338.pdf |
| Am J Hematol | AJH-101-1790.pdf |
| Liver International | LIV-46-0.pdf |
| Haematologica | 111300.pdf (volume 111 + página inicial 300, abreviatura do periódico omitida) |
| Blood (manuscrito NIH) | nihms-2192199.pdf |
Método de resolução (por prioridade; múltiplos testes acertaram o 1º em todos os casos)
- Tag
<meta name="citation_pdf_url" content="https://pmc.ncbi.nlm.nih.gov/articles/{PMCID}/pdf/XXX.pdf">na página do artigo ← Mais confiável grep -oE 'href="[^"]*?/pdf/[^"]+?\.pdf"'pegue o primeiro resultado- Fallback
pdf/main.pdf
Padrões de nomenclatura (não confiáveis, apenas para referência): Periódicos Wiley OA frequentemente <abreviatura>-<volume impresso>-0.pdf (ex.: LIV-46-0.pdf); com número de artigo <abreviatura>-<volume>-<número_artigo>.pdf (ex.: HEM3-10-e70338.pdf); mesmo periódico <abreviatura>-<volume>-<página_inicial>.pdf (ex.: AJH-101-1790.pdf); também há variante "volume+página inicial, sem abreviatura" (ex.: 111300.pdf da Haematologica = volume 111 + página inicial 300).
Ao buscar a página do artigo, descarte cookies: Use uma requisição independente, sem manter cookies, para ler a página; a requisição do PDF ainda deve ser iniciada de uma sessão de cookies nova. Se levar
ncbi_sid/ncbi_pingergerados pela página do artigo para a requisição do PDF, será imediatamente elevado para reCAPTCHA (testado).scripts/pmc_pdf.pyjá implementa isso.
Solução Principal: Resolução Offline do Proof-of-Work do PMC
Princípio
https://pmc.ncbi.nlm.nih.gov/articles/{PMCID}/pdf/<nome>.pdf alterna entre dois tipos de página de desafio com base em estratégia de risco:
- Página PoW (1817 bytes, título
Preparing to download ...) → Resolvível offline, este é o canal que queremos. - Página reCAPTCHA (~20 KB, título contém
reCAPTCHA) → Não resolvível offline.
Chave para acionar PoW em vez de reCAPTCHA: Use User-Agent simplificado e não acesse a página do artigo antes de solicitar o PDF.
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
Contraexemplos (elevam para reCAPTCHA, testados):
- UA completo do Chrome (
…AppleWebKit/537.36 … Chrome/1xx.0.0.0 Safari/537.36) - Primeiro fazer
GETda página do artigo (carregandoncbi_sid/ncbi_pinger) e depois solicitar o PDF
Algoritmo PoW (reversamente engenheirado de pow-*.js, confirmado)
A página PoW contém quatro constantes embutidas: POW_CHALLENGE / POW_DIFFICULTY / POW_COOKIE_NAME / POW_COOKIE_PATH.
- Encontre o menor inteiro não negativo
noncetal quesha256(challenge + str(nonce)).hexdigest()comece com'0' * difficulty; - Defina o Cookie:
<POW_COOKIE_NAME> = challenge + "," + nonce(caminho =POW_COOKIE_PATH); - Com esse Cookie e
Referer: https://pmc.ncbi.nlm.nih.gov/articles/{PMCID}/, refaça a requisição ao link direto do PDF → Deve retornar200comContent-Type: application/pdf.
difficulty típico = 4 (cerca de 65536 hashes, concluído em submilissegundo localmente).
Script Único
# Recomendado: resolve automaticamente o nome real do PDF (via citation_pdf_url) e resolve o PoW offline
python3 scripts/pmc_pdf.py PMC13575452 ./out.pdf
# Se já resolveu o nome do arquivo, pode especificar diretamente, pulando a requisição à página do artigo
python3 scripts/pmc_pdf.py PMC13575452 ./out.pdf --pdf-name LIV-46-0.pdf
# Modo silencioso (apenas linha de resultado)
python3 scripts/pmc_pdf.py PMC13575452 ./out.pdf --quiet
Comportamento do script: Primeiro, com UA simplificado descartando cookies, solicita a página do artigo para resolver o link real do PDF → depois, com sessão de cookies nova, faz uma requisição fria a esse link → se obtiver diretamente o PDF, salva; caso contrário, resolve as constantes PoW, encontra o nonce, preenche o Cookie e tenta novamente. Se precisar forçar a reobtenção do desafio, basta reexecutar (o script não persiste cookies, cada execução é uma sessão nova).
★★ Duas regras rígidas que devem ser lembradas (lições amargas testadas)
1. O segundo parâmetro posicional é o caminho completo do arquivo de saída, não um diretório. Passar um diretório lançará
IsADirectoryError: [Errno 21] Is a directorydepois de já ter obtido o PDF, desperdiçando a resolução PoW e o PDF obtido. ❌pmc_pdf.py PMC13482240 --outdir /caminho/para/dir✅pmc_pdf.py PMC13482240 /caminho/para/dir/xxx.pdf2. O canal de PDF do PMC tem característica de "uma única oportunidade". A primeira requisição fria geralmente passa pelo PoW e obtém o PDF verdadeiro; requisitar o mesmo PDF novamente imediatamente após quase certamente será elevado para reCAPTCHA (não é um rate limit comum que "basta trocar o UA"). Portanto, acerte o caminho de saída na primeira vez, absolutamente não "teste antes". Testado: primeira rodada
status=200 type=application/pdf bytes=23970819, segundos depois a mesma URL retornatype=text/html bytes=21329(página de desafio reCAPTCHA). Uma vez perdida essa oportunidade, vá diretamente para a rota de fallback da editora na próxima seção, não fique repetindo no PMC.
Solução de Problemas
| Sintoma | Causa | Ação |
|---|---|---|
Retorna HTML com POW_CHALLENGE | Entrou no canal PoW (normal) | Deixe o script resolver |
Retorna HTML com recaptcha | Elevado para reCAPTCHA | Troque para UA simplificado, limpe cookies da sessão, espere e tente novamente; se ainda falhar, use vias 4/5 |
| 404 / "Article not found" | Nome do arquivo PDF errado | Volte à página do artigo e resolva citation_pdf_url, não codifique main.pdf |
nonce não converge | difficulty aumentado | Verifique difficulty; se >5, considere resolução assíncrona ou multiprocessamento |
| Resolução bem-sucedida mas PDF ainda é HTML | Cookie domain/path incorreto | Confirme cookie domain como pmc.ncbi.nlm.nih.gov e path como POW_COOKIE_PATH |
IsADirectoryError: Is a directory | Parâmetro de saída tratado como diretório | O segundo parâmetro é o caminho completo do arquivo de saída. Neste ponto, o PDF já foi obtido mas não salvo – não reexecute imediatamente (acionará reCAPTCHA), corrija o caminho e, se já elevado, vá para a rota da editora |
| Primeira vez bem-sucedida, segunda imediatamente reCAPTCHA | Rate limit de "uma oportunidade" do PMC para o mesmo caminho de PDF | Veja a regra rígida 2 acima; abandone o PMC, vá para a rota de fallback da editora |
citation_pdf_url retorna -mmc1.pdf | O PDF do artigo não está no repositório, resolveu para material suplementar | Comum em periódicos como Blood (texto completo JATS disponível mas PDF do artigo não). Abandone imediatamente a rota PMC, não use material suplementar como se fosse o artigo (testado) |
★ Existe rate limit a nível de IP (testado) Após solicitar repetidamente PDFs do PMC em curto período (ex.: baixar vários artigos consecutivos), mesmo com UA simplificado correto, será diretamente elevado para reCAPTCHA, e aguardar 45 segundos ainda não recupera. Padrão: "primeira bem-sucedida, todas subsequentes falham". Ação: ① Em downloads em lote, deixe intervalo suficiente entre requisições; ② Uma vez em estado reCAPTCHA, não tente repetidamente (só prolonga o bloqueio), mude para outras tarefas ou use a via 4 (
supplementaryFiles) e links diretos da editora; ③ Se houver necessidade real de múltiplos artigos, baixe sob demanda em vez de pré-aquecer em lote.
★★ Rota de Fallback: Quando o PMC está travado por reCAPTCHA, use o site da editora (testado e eficaz)
Quando o link direto do PMC for duas vezes elevado para reCAPTCHA (rate limit a nível de IP, não recupera após espera) e o periódico alvo for totalmente OA, usar o site da editora é mais confiável do que continuar tentando o PMC:
UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
# 1) Resolução de DOI → observe em qual página de artigo da editora cai
curl -s -o /dev/null -w "final: %{url_effective}\nHTTP: %{http_code}\n" -A "$UA" -L "https://doi.org/<DOI>"
# 2) Na página do artigo, resolva o link direto real do PDF
curl -s -A "$UA" "https://<publisher-article-page>" | grep -oiE '<meta name="citation_pdf_url"[^>]*>|href="[^"]*\.pdf[^"]*"' | sort -u | head
# 3) Baixe diretamente com Referer (editoras quase não validam Referer, mas é mais seguro)
curl -sL --retry 3 -A "$UA" -e "$ARTICLE_PAGE" -o "$OUT" "$PDF_URL"
★★ Quando a página da editora está completamente bloqueada pelo Cloudflare: Use o navegador "Imprimir como PDF" (testado e eficaz)
O ashpublications.org (periódicos ASH) nesta rodada apresentou bloqueio completo do Cloudflare,
com a experiência anterior de "esperar 10 s e abrir" não se repetindo. Caminho alternativo eficaz:
- Abra a página de texto completo do PMC (não o PDF), contornando o site da editora
- Use a ferramenta de impressão do navegador para salvar a página como PDF:
agent-browser pdf - Quando o reCAPTCHA aparecer pela primeira vez, execute
opennovamente para passar
Ponto de decisão: Se o periódico alvo pertence a ASH / ScienceDirect com forte proteção Cloudflare, não fique repetindo com curl – baixa taxa de sucesso e agrava o bloqueio. Vá diretamente para o canal do navegador.
- Testado e viável: Haematologica / Ferrata Storti –
doi.org/10.3324/haematol.2025.287698→haematologica.org/article/view/12187→haematologica.org/article/download/12187/78653→ 2.91 MB / 14 páginas. - Não viável: Editoras com bloqueio do tipo Cloudflare (ASH
ashpublications.org, Wileyonlinelibrary.wiley.com/doi/pdfdirect/..., De Gruyter, Thieme) – essas só podem ser acessadas pelo canal PMC ou sessão de navegador. - Julgamento prévio: Apenas periódicos totalmente OA / Gold OA valem a pena tentar essa rota (periódicos assinados encontrarão paywall, proibido contornar).
★ Verificação de Integridade: Downloads grandes interrompidos corrompem xref
Se o curl for interrompido por SIGTERM/timeout ao baixar PDF, o cabeçalho do arquivo ainda será %PDF-1.6 e o tamanho aparentará ok, mas o pdfinfo reportará Invalid XRef entry. Portanto, após o download, não confie apenas no cabeçalho e tamanho; todos os itens a seguir devem ser verificados:
head -c 8 "$OUT" # %PDF-…
tail -c 32 "$OUT" | od -c | tail -3 # Deve mostrar startxref … %%EOF
pdfinfo "$OUT" | grep -E "Pages|Page size" # Número de páginas deve ser consistente com o volume/edição
Somente com todos os três itens ok o download é considerado completo; caso contrário, baixe novamente (adicione --retry 3), não entregue um arquivo corrompido.
Materiais Suplementares e Imagens
Quando o PDF do artigo está inacessível, o endpoint supplementaryFiles geralmente ainda está disponível, e seu conteúdo costuma ser exatamente as imagens do artigo e métodos suplementares:
curl -sL -o sup.zip "https://www.ebi.ac.uk/europepmc/webservices/rest/PMC13049628/supplementaryFiles"
unzip -o sup.zip -d sup/
Convenção de nomenclatura (Wiley / ASH): *-gr1…*-grN correspondem às Figuras 1…N, *-ga1 é o resumo gráfico, *-mmc1.pdf é o material suplementar.
Ao Usar Ferramentas de Navegador
Use agent-browser apenas quando for necessário clicar, fazer login ou renderizar páginas JS. Em cenários puramente de download, não inicie o navegador – PoW pode ser resolvido offline, iniciar Chromium só adiciona centenas de MB de overhead e pontos de falha. Se realmente precisar do navegador:
- Certifique-se de que um node funcional está no PATH (senão o daemon pode exceder o tempo limite de inicialização);
- Ao finalizar a tarefa, sempre execute
agent-browser closepara evitar daemons zumbis.
Lista de Verificação
- Antes de baixar, confirme que o artigo alvo é OA (ou que está dentro do bloco de IPs da assinatura institucional – nesse caso, links diretos da editora estão disponíveis, mas ainda apenas para download manual individual, proibido em lote)
- Resolva o nome real do arquivo PDF a partir da tag
citation_pdf_urlda página do artigo (não codifiquemain.pdf) - Após salvar, verifique se o cabeçalho é
%PDF - Verifique o final por
startxref/%%EOF(arquivos grandes interrompidos deixam cabeçalho intacto mas xref corrompido;pdfinfodetecta) - Valide o número de páginas: use
re.findall(rb'/Count\s+(\\d+)', data)ou conte/Type /Page, não confie nofile out.pdf(no macOS frequentemente reporta erroneamente "1 pages"); também pode usarmdls -name kMDItemNumberOfPages - Extraia primeira e última página para verificar o conteúdo (
pdftotext -f 1 -l 1/-f N -l N), confirmando que não é material suplementar ou outro artigo - Registre o
PMCID/DOI/ caminho do arquivo salvo para verificação posterior - Em caso de falha, relate honestamente o motivo, não use material suplementar ou imagens como substituto do PDF do artigo