Logo PDFHQ

Documentos

DocumentaçãoPrimeiros passos

Idempotência e segurança de retry

Tente novamente com segurança a criação de tarefas de documento em tempos limite de rede usando cabeçalhos Idempotency-Key com escopo de projeto, e distinga-os do processo pago e despacho de provedor.

Chaves de API do lado do servidor Uploads de armazenamento assinado

Criação de tarefa segura para reprodução#

POST /v1/tasks aceita um opcional Idempotency-Key (8–128 letras ASCII, dígitos, pontos, sublinhados, dois-pontos ou hífens; começa com uma letra ou dígito). Repetir uma chave para a mesma conta HQTools e projeto de API retorna a tarefa existente. Reutilizar a mesma chave para uma ferramenta diferente retorna 409 IDEMPOTENCY_KEY_REUSED.

Crie tarefa com chave de repetição
curl -q --fail-with-body -X POST 'https://api.pdfhq.io/v1/tasks' \
  -H 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
  -H 'Idempotency-Key: job-20261025-00001' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"compress"}'

O ID da tarefa retornado é estável entre tentativas. As chaves têm escopo de conta e projeto de API e permanecem associadas à tarefa até que o registro subjacente seja removido. Crie uma nova chave para uma nova tarefa.

Regras de repetição diferentes para recursos diferentes#

Criação de tarefa: repetir usando a mesma Idempotency-Key após uma interrupção de rede. Processamento de tarefas: o ID de tarefa fixa já fornece idempotência de job/crédito de backend para opções idênticas; inspecione seu estado antes de tentar novamente. Trabalhos de IA: utilize uma citação aprovada pelo utilizador e uma Idempotency-Key estável conforme suportado pelo endpoint de IA. Envio de assinatura eletrônica: uma resposta incerta do provedor requer reconciliação de envelope; não reenvie cegamente uma solicitação de assinatura.

Uploads S3 assinados usam políticas de formulário POST de curta duração. Não envie x-api-key ou Idempotency-Key para S3. Uploads de armazenamento e estimativa de cotação não cobram créditos por si só; o processamento é que cobra.

Logo PDFHQ

Ferramentas PDF e inteligência de documentos. Prepare, compreenda e trabalhe com seus documentos.

© 2026 PDFHQ. Todos os direitos reservados.