ForHosting KIT · PDF e documentos

Adicione um marcador ao PDF e valide a página

Em um PDF de 32 páginas em que Cover, Methods e Appendix apontam para as páginas 1, 8 e 27, um marcador Results para a página 18 fica em terceiro. Informe páginas, marcadores atuais, título e página e receba o sumário atualizado. Grátis no seu navegador.

Grátis
Funciona no seu navegador
Sem cadastro
Seus dados não saem do seu aparelho

Executar grátis Ver a API

Use pelo WebAPIE-mailTelegramApp em breve

Exemplo resolvido

Se você digitar

Quantidade de páginas: 32
Título: Results
Página: 18

Você obtém

Quantidade: 4
Índice inserido: 2

Adicione uma entrada de navegação confiável ao sumário de um PDF sem precisar adivinhar se o destino existe ou onde ele deve ficar. Informe o total de páginas do documento, os marcadores atuais de nível superior, um título e uma página de destino numerada a partir de um. A capacidade valida o novo destino em relação ao intervalo real, verifica o sumário existente e insere o marcador em ordem de página. Ela retorna um novo sumário estruturado e o índice de inserção, facilitando a serialização em uma etapa posterior de gravação do PDF ou a verificação em um fluxo documental automatizado.

Descreva o PDF e o marcador que você deseja adicionar

Comece pelo número total de páginas do PDF, pois esse valor define todos os destinos válidos. Depois, forneça o sumário atual de nível superior como uma lista de registros com título e página, na ordem usada pelo documento. A numeração começa em um: a página 1 representa a primeira página visível do PDF, e não um deslocamento interno igual a zero.

Por fim, informe o título e a página de destino do marcador que você deseja adicionar. Os espaços nas extremidades dos títulos são removidos, evitando que espaços inseridos por engano em um formulário ou uma planilha apareçam no rótulo visível. A capacidade trabalha com a representação do sumário, sem decodificar ou regravar os bytes binários do PDF.

Essa separação torna a operação adequada depois que um analisador lê o arquivo ou antes que uma biblioteca grave o sumário atualizado. Um sumário vazio é aceito, portanto o mesmo formato de solicitação cria o primeiro marcador ou amplia um índice já existente.

Valide os limites e preserve uma ordem previsível

Um marcador só é útil quando seu destino pode existir. Página zero, números negativos, frações e valores além da última página retornam um erro de entrada inválida com o intervalo aceito. Os marcadores existentes passam pela mesma verificação, impedindo que uma edição aparentemente bem-sucedida preserve destinos quebrados.

Os títulos também precisam conter texto visível. O sumário recebido deve estar em ordem crescente de página; aceitar uma lista desordenada tornaria ambígua a posição correta e poderia reorganizar silenciosamente a navegação pretendida pelo autor. Depois da validação, o algoritmo percorre os registros até encontrar o primeiro marcador de uma página posterior e faz a inserção nesse ponto.

Se vários marcadores já apontarem para a página solicitada, a nova entrada será colocada depois deles, mantendo a ordem relativa. A lista de entrada e seus registros não são alterados.

Aplique o sumário retornado ao fluxo do documento

Os dados retornados não dependem de uma biblioteca específica: um aplicativo pode associar cada título e página numerada a partir de um aos objetos de destino exigidos pelo gravador escolhido. Esta capacidade não altera os bytes do PDF, não deduz títulos do texto das páginas, não cria filhos aninhados nem corrige um sumário desordenado. Essas tarefas exigem análise, decisões de hierarquia ou serialização fora desta operação.

Separar a inserção facilita o diagnóstico: erros de intervalo param aqui, antes que um documento com navegação inválida seja produzido. Mantenha o total de páginas vindo da mesma versão que será gravada.

Casos de uso

Adicionar um capítulo recém-escrito

Insira o rótulo de um capítulo na página inicial verificada antes que o editor grave o PDF revisado.

Automatizar a navegação de relatórios

Adicione um marcador para um apêndice ou resumo gerado e rejeite modelos que calculem um destino impossível.

Revisar alterações no sumário

Mostre o índice de inserção e o sumário atualizado em uma interface de aprovação antes de mudar o arquivo original.

Perguntas frequentes

Esta capacidade modifica o próprio arquivo PDF?

Não. Ela retorna uma representação atualizada do sumário para um gravador de PDF ou fluxo documental aplicar.

Onde o marcador é colocado se outro usar a mesma página?

Ele é inserido depois de todos os marcadores existentes nessa página, preservando a ordem fornecida.

É possível adicionar marcadores aninhados?

Não. Esta operação específica adiciona um marcador de nível superior a um sumário ordenado por página.

Posso adicionar o primeiro marcador a um PDF que não tem nenhum?

Sim. Um sumário vazio é válido, então a mesma operação serve para criar o primeiro marcador ou para ampliar um índice longo, sem trocar de modo.

E se meus marcadores atuais não estiverem em ordem de página?

Eles são recusados. Os marcadores existentes precisam seguir da menor para a maior página; aceitar uma lista fora de ordem deixaria a posição certa ambígua e poderia reorganizar sem aviso a navegação feita pelo autor.

Ferramentas relacionadas

Para desenvolvedores — acesso via API

Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.

Endpoint

POSThttps://api.kit.forhosting.com/pdf/bookmarks-add

Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.

Chame do seu código

curl -X POST https://api.kit.forhosting.com/pdf/bookmarks-add \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_count":24,"outline":[{"title":"Introduction","page":1},{"title":"Results","page":12}],"title":"Methods","page":7}'

const res = await fetch("https://api.kit.forhosting.com/pdf/bookmarks-add", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "page_count": 24,
    "outline": [
      {
        "title": "Introduction",
        "page": 1
      },
      {
        "title": "Results",
        "page": 12
      }
    ],
    "title": "Methods",
    "page": 7
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/pdf/bookmarks-add",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "page_count": 24,
    "outline": [
        {
            "title": "Introduction",
            "page": 1
        },
        {
            "title": "Results",
            "page": 12
        }
    ],
    "title": "Methods",
    "page": 7
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/pdf/bookmarks-add", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"page_count":24,"outline":[{"title":"Introduction","page":1},{"title":"Results","page":12}],"title":"Methods","page":7}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"page_count":24,"outline":[{"title":"Introduction","page":1},{"title":"Results","page":12}],"title":"Methods","page":7}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/pdf/bookmarks-add", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Exemplo de requisição

{
  "page_count": 24,
  "outline": [
    {
      "title": "Introduction",
      "page": 1
    },
    {
      "title": "Results",
      "page": 12
    }
  ],
  "title": "Methods",
  "page": 7
}

Exemplo de resposta

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "pdf.bookmarks_add",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.

Preço

por chamadaUS$ 0,002

Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.

Limites

`max_mb`	25
`max_pages`	200

Erros

HTTP	Código	O que significa
`401`	`unauthorized`	Token ausente ou inválido. Confira o header Authorization.
`402`	`insufficient_balance`	Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo.
`404`	`unknown_type`	Esse tipo de tarefa não existe. Confira o campo type no catálogo.
`429`	`rate_limited`	Muitas requisições em pouco tempo. Espere um instante e tente de novo.

Notas técnicas

Valide os limites e preserve uma ordem previsível

Por isso, a página solicitada deve ser um número inteiro entre 1 e page_count, inclusive. Sem rede, horários, identificadores aleatórios ou comparações dependentes de localidade, a mesma entrada JSON sempre gera a mesma saída.

Aplique o sumário retornado ao fluxo do documento

A resposta inclui page_count, a contagem final de marcadores, um inserted_index baseado em zero e o sumário atualizado completo. Use inserted_index quando uma interface de revisão precisar destacar a linha recém-criada, ou ignore-o e encaminhe o sumário diretamente para a próxima etapa. A ferramenta no navegador ajuda um editor a conferir rapidamente um destino antes da publicação, enquanto uma chamada de API por US$ 0,002 atende a fluxos repetíveis, como avisos legais, apêndices, notas de versão e capítulos gerados.

Perguntas técnicas

Como as páginas são numeradas?

A numeração começa em um: 1 é a primeira página e page_count é o último destino válido.

O que acontece se a página de destino estiver fora do intervalo?

A solicitação falha com invalid_input e uma mensagem que informa o intervalo válido.

Quanto custa uma solicitação de API?

Uma solicitação de API bem-sucedida custa US$ 0,002; a mesma operação determinística é grátis no navegador.

Ver a documentação completa do KIT →

Executar grátis

Exemplo resolvido

Descreva o PDF e o marcador que você deseja adicionar

Valide os limites e preserve uma ordem previsível

Aplique o sumário retornado ao fluxo do documento

Casos de uso

Adicionar um capítulo recém-escrito

Automatizar a navegação de relatórios

Revisar alterações no sumário

Perguntas frequentes

Ferramentas relacionadas

Para desenvolvedores — acesso via API

Endpoint

Chame do seu código

Exemplo de requisição

Exemplo de resposta

Preço

Limites

Erros

Notas técnicas

Valide os limites e preserve uma ordem previsível

Aplique o sumário retornado ao fluxo do documento

Perguntas técnicas

obrigado