API Pública
API Pública da Blueputto para acesso CRUD autenticado aos registros do workspace, com endpoints versionados, chaves de API, paginação, filtros e ações de fluxo de trabalho.
Grzegorz
A API Pública é a camada de integração autenticada da Blueputto. Ela expõe os mesmos registros principais com os quais a aplicação trabalha todos os dias, o que permite que sistemas externos criem, leiam, atualizem e removam dados operacionais sem introduzir um segundo modelo de conteúdo ao lado da UI.
Esta API fica em /v1 e foi projetada para funcionar com API Keys em nível de organização. Isso a torna o recurso usado pelas equipes quando os dados da Blueputto precisam ser enviados para um site, automação, script de importação, dashboard interno ou outro sistema de produto.
Uma API versionada para os principais recursos do workspace
O ponto de entrada em /v1 retorna uma carga de descoberta compacta com a versão da API, o formato de autenticação, a URL do documento OpenAPI e a lista de recursos atualmente expostos.
Na implementação atual, a superfície pública cobre:
documents,
items,
collections,
folders,
categories,
statuses,
labels,
e document templates.
A maioria desses recursos oferece suporte ao fluxo operacional padrão de listar, obter, criar, atualizar e excluir. A API também expõe ações específicas de fluxo de trabalho onde a UI precisa delas, como:
restaurar e exclusão permanente para documents e items,
duplicar para documents,
reordenar para categories, statuses e labels,
e filtragem apenas de ativos para document templates.
É isso que torna a API Pública mais do que uma camada de exportação somente leitura. Ela corresponde de perto ao ciclo de vida real dos registros já visível na própria Blueputto.
A autenticação e o formato de resposta permanecem previsíveis
A API Pública aceita a credencial da organização em uma de duas formas padrão:
x-api-key,
ou Authorization: Bearer <key>.
Isso dá às equipes flexibilidade ao conectar a Blueputto a diferentes runtimes, gateways e estilos de SDK. A própria chave é criada dentro da aplicação na página de configurações de API Keys.
O formato de resposta também é intencionalmente consistente. Respostas de recurso único são retornadas dentro de um envelope data. Endpoints de lista retornam data junto com meta, que inclui detalhes de paginação como page, limit, total items, total pages e o estado da próxima ou da página anterior.
Em todo o conjunto atual de recursos, a API também expõe filtros práticos que refletem fluxos de trabalho reais da UI, incluindo search, deletedOnly, folderId, withoutFolder e activeOnly.
Construída com base nas mesmas regras operacionais do aplicativo
A parte útil da API Pública da Blueputto não é apenas que os registros podem ser acessados externamente. É que a superfície de integração segue as mesmas regras que o produto já aplica na UI.
Por exemplo, a exclusão de documents e items é modelada como um fluxo de lixeira primeiro, em vez de destruição imediata. Algumas operações de documents podem retornar uma resposta de estado bloqueado quando o registro não está editável no momento. A limitação de taxa é aplicada por chave de API, com o limite padrão do backend atualmente definido como 5 req/s por chave.
Isso mantém a API alinhada ao comportamento real da aplicação. As integrações externas trabalham com o modelo real de recursos da Blueputto, não com um canal lateral simplificado que se comporta de forma diferente do produto.
