Docs / Enviar Documentos

Enviar Documentos

Documentos são o núcleo do aqoon. Envie arquivos, cole texto ou forneça URLs — o aqoon extrai o conteúdo, divide em trechos pesquisáveis e indexa tudo para recuperação rápida.

Formatos Suportados

Tipo de origem Formatos aceitos Tamanho máximo
PDF .pdf 50 MB
Documento Word .docx, .doc 50 MB
Imagem .png, .jpg, .jpeg 50 MB
Markdown .md 50 MB
Arquivo de Texto .txt 50 MB
Planilha .csv, .xlsx, .xls 50 MB
URL da Web Qualquer URL acessível publicamente —
Texto Simples Cole texto diretamente —

Como Enviar

  1. Abra uma coleção e clique em Enviar
  2. Digite um título para o documento
  3. Selecione um arquivo — o tipo de origem é detectado automaticamente pela extensão do arquivo (PDF, Documento Word, Imagem, Markdown, Texto, Planilha) ou selecione manualmente para colar Texto Simples ou URL da Web
  4. Dependendo do tipo:
    • Envio de arquivos — Arraste e solte ou clique para navegar
    • URL — Cole o endereço web
    • Texto Simples — Digite ou cole seu conteúdo
  5. Opcionalmente adicione tags (separadas por vírgula) para ajudar a organizar e filtrar depois
  6. Clique em Enviar

Enviando Múltiplos Arquivos

Você pode enviar múltiplos arquivos de uma vez. Selecione vários arquivos no seletor ou arraste e solte juntos.

  • O tipo de origem de cada arquivo é detectado automaticamente pela extensão
  • Títulos são gerados automaticamente a partir dos nomes dos arquivos (para arquivos Markdown, o primeiro cabeçalho # é usado)
  • Tags são aplicadas a todos os arquivos do lote
  • Arquivos não suportados ou muito grandes são ignorados com um aviso

O Que Acontece Após o Envio

Após enviar um documento, o aqoon o processa automaticamente:

  1. Pendente — Documento na fila para processamento
  2. Processando — Texto sendo extraído (OCR para imagens, parsing para PDFs/DOCX, busca para URLs)
  3. Indexado — Conteúdo foi dividido em trechos, vetorizado e adicionado ao índice de busca

Se algo der errado, o status mostra Falhou com uma mensagem de erro. Causas comuns incluem arquivos corrompidos ou URLs inacessíveis.

O processamento normalmente leva alguns segundos para texto e arquivos pequenos. PDFs grandes ou documentos com muitas imagens podem demorar mais.

Visualizando um Documento

Clique em qualquer título de documento para ver sua página de detalhes, que mostra:

  • Metadados completos (título, tipo de origem, tamanho do arquivo, data de envio)
  • Tags como selos
  • O conteúdo de texto extraído
  • Uma lista de todos os trechos criados durante o processamento, com seu índice e uma prévia do conteúdo

Baixando Arquivos

Você pode baixar o arquivo original de qualquer documento enviado como arquivo (PDF, DOCX, imagem, etc.). Documentos somente texto e URL não possuem arquivo armazenado e não podem ser baixados.

Interface Web

Na página de detalhes do documento, clique no botão Baixar. O botão fica oculto para documentos somente texto ou URL.

API

GET /api/v1/documents/{uuid}/download/
curl -L -H "Authorization: Bearer aqn_..." \
  https://aqoon.ai/api/v1/documents/<document-uuid>/download/ \
  -o file.pdf

SDK Python

url = client.get_download_url("document-uuid")

SDK JavaScript

const url = await client.getDownloadUrl(uuid);

O endpoint retorna um redirecionamento 302 para uma URL assinada do Azure Blob Storage. Use -L no curl para seguir o redirecionamento. A URL é válida por 1 hora. Retorna 404 para documentos sem arquivo armazenado.

Excluindo um Documento

Na página de detalhes do documento, clique em Excluir para remover o documento e todos os seus trechos do índice de busca. Esta ação não pode ser desfeita.

Enviando via API

Você pode enviar documentos programaticamente usando a API REST. Qualquer chave de API com permissão de escrita pode enviar para a coleção para a qual foi emitida.

Endpoint

POST /api/v1/collections/{uuid}/documents/

Autenticação

Authorization: Bearer aqn_...

A chave de API deve ter permissão de escrita na coleção de destino.

Envio de arquivo único (curl)

curl -X POST https://aqoon.io/api/v1/collections/<collection-uuid>/documents/ \
  -H "Authorization: Bearer aqn_..." \
  -F "files=@report.pdf"

Envio em lote — múltiplos arquivos em uma requisição (curl)

curl -X POST https://aqoon.io/api/v1/collections/<collection-uuid>/documents/ \
  -H "Authorization: Bearer aqn_..." \
  -F "files=@report.pdf" \
  -F "files=@notes.docx" \
  -F "files=@data.csv"

SDK Python

client.upload_document(collection_uuid, "path/to/file.pdf")

SDK JavaScript

await client.uploadDocument(collectionUuid, file);

Tipos de arquivo suportados

PDF (.pdf), documentos Word (.docx, .doc), imagens (.png, .jpg, .jpeg), planilhas (.csv, .xlsx, .xls), Markdown (.md) e texto simples (.txt).

Processamento assíncrono

Documentos enviados começam com status de pendente e são processados em segundo plano. Consulte o status do documento usando:

GET /api/v1/documents/{uuid}/

O campo de status progride por pendente → processando → indexado. Um status de falhou significa que o processamento encontrou um erro.

Dica: Em vez de polling, você pode configurar um webhook para receber uma notificação quando o processamento for concluído. Configure uma URL de webhook via POST /api/v1/webhooks/ e o aqoon enviará um payload assinado para sua URL nos eventos document.indexed e document.failed.

Exclusão em Massa

Na página de detalhes da coleção, proprietários podem excluir múltiplos documentos de uma vez usando caixas de seleção.

  • Cada linha de documento tem uma caixa de seleção à esquerda — visível apenas para proprietários da coleção
  • A caixa de seleção Selecionar Todos no cabeçalho da tabela seleciona ou desmarca todos os documentos na página atual
  • Quando um ou mais documentos são selecionados, um botão Excluir Selecionados aparece mostrando a contagem de documentos selecionados
  • Clicar em Excluir Selecionados abre uma caixa de confirmação antes de qualquer exclusão
  • Exclusões confirmadas são exclusões suaves — documentos são removidos da lista da coleção e suas entradas no índice de busca são removidas imediatamente

A exclusão em massa está disponível apenas para proprietários da coleção. Inscritos veem a lista de documentos sem caixas de seleção.

Substituindo um Documento

Quando o conteúdo de um documento muda, você pode substituir o arquivo sem perder o UUID original ou quebrar integrações que o referenciam. As entradas antigas do índice de busca são removidas e o novo arquivo é processado do zero.

Interface Web

Na página de detalhes do documento, clique em Substituir. O formulário preenche automaticamente o título e as tags existentes. Selecione o novo arquivo e clique em Enviar. O documento retorna ao status pendente enquanto é reprocessado.

API

POST /api/v1/documents/{uuid}/replace/
curl -X POST https://aqoon.io/api/v1/documents/<document-uuid>/replace/ \
  -H "Authorization: Bearer aqn_..." \
  -F "file=@updated-report.pdf" \
  -F "title=Annual Report 2026"

SDK Python

doc = client.replace_document("document-uuid", "path/to/new_file.pdf")

SDK JavaScript

const doc = await client.replaceDocument(uuid, file);

Comportamentos principais:

  • O UUID é preservado — referências existentes permanecem válidas
  • Trechos antigos e entradas do índice de busca são removidos antes do reprocessamento
  • Título e tags são mantidos a menos que sejam explicitamente substituídos na requisição
  • O novo arquivo é processado assincronamente: pendente → processando → indexado
  • Requer permissão de escrita na coleção (mesma do envio)