Documentação (pt-br)

Última atualização em 29/06/2025 às 15h07.

Bem-vindo à documentação oficial da The Bagui, o seu canivete suíço para acelerar o desenvolvimento. Nossa API foi projetada para ser simples, poderosa e dev-friendly.

Toda a autenticação é feita através do header x-api-key. A URL base para todas as requisições é: https://services.thebagui.net/api.

// Exemplo de como configurar um HttpClient em C#
var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "SUA_CHAVE_SECRETA");

Cache

Serviço de cache chave-valor ultra-rápido para otimizar suas aplicações.

Criar ou Atualizar Chave

Cria ou atualiza uma chave no cache com um valor associado.

POST /api/cache

Corpo da Requisição

{
  "key": "my_user_session:123",
  "value": { 
    "name": "João",
    "permissions": ["admin", "editor"]
  },
  "ttl": 3600
}

value (any): Pode ser uma string, um número ou um objeto JSON.
ttl (integer, opcional): Tempo de vida da chave em segundos. Se omitido ou nulo, a chave não expira.

Obter Valor pela Chave

Recupera o valor armazenado associado a uma chave.

GET /api/cache/:key

Remover Chave

Apaga permanentemente uma chave e seu valor do cache.

DELETE /api/cache/:key

Banco de Dados

Crie, gerencie e consulte bancos de dados SQLite isolados via API, sem configurar nada.

Criar Banco de Dados

POST /api/databases/create

Corpo da Requisição

{
  "dbName": "meu_projeto_db"
}

Executar Query SQL

Execute uma instrução SQL em um banco de dados específico.

POST /api/databases/:dbName/query

Corpo da Requisição

{
  "sql": "SELECT Name FROM Person WHERE Id = ?",
  "params": [1999]
}

params (array, opcional): Use para passar parâmetros de forma segura e evitar SQL Injection.

Acompanhar Tamanho do Banco

Verifica o espaço em disco (em MB) consumido por um banco de dados.

GET /api/databases/:dbName/size

Remover Banco de Dados

Apaga permanentemente um banco de dados e todos os seus dados.

DELETE /api/databases/:dbName

Operações com navegador

Serviços de automação web.

Gerar PDF a partir de HTML

Converte um conteúdo HTML para um arquivo PDF, que é retornado diretamente na resposta.

POST /api/browser/generate-pdf

Corpo da Requisição

{
  "html": "<h1>Meu Título</h1><p>Um parágrafo em <b>negrito</b>.</p>"
}

Tirar Screenshot de um Site

Captura a tela de um site a partir de uma URL.

POST /api/browser/screenshot-page

Corpo da Requisição

{
  "url": "https://www.google.com"
}

Capturar HTML de um Site (Scrape)

Extrai o conteúdo HTML completo de uma página após a renderização do JavaScript.

POST /api/browser/scrape-page

Corpo da Requisição

{
  "url": "https://www.google.com"
}

Manipulação de Arquivos

DOC e DOCX: Extrair Texto

Extrai todo o conteúdo textual de arquivos .doc e .docx. Requisição via multipart/form-data. Limite de 10MB.

POST /api/docx/extract-text

Corpo da Requisição (form-data)

Chave: document
Valor: O arquivo .doc ou .docx.

DOC e DOCX: Converter para HTML

Converte o conteúdo de um arquivo .doc ou .docx para HTML. Requisição via multipart/form-data. Limite de 10MB.

POST /api/docx/convert-to-html

Corpo da Requisição (form-data)

Chave: document
Valor: O arquivo .doc ou .docx.

OCR (Reconhecimento de Imagens)

Extrair Texto de Imagens

Extrai texto de imagens. Ideal para documentos. Extensões permitidas: PNG, JPEG, BMP, TIFF. Requisição via multipart/form-data. Limite de 10MB.

POST /api/ocr/extract-text

Corpo da Requisição (form-data)

Chave: image
Valor: O arquivo de imagem.

Utilitários de Texto e Dados

Análise de Sentimento

Analisa um texto e retorna sua polaridade (POSITIVO, NEGATIVO ou NEUTRO) com um score de confiança.

POST /api/sentiment/analyze

Corpo da Requisição

{
  "text": "Eu estou muito feliz por estar usando esta API!"
}

Markdown para HTML

Converte uma string em formato Markdown para HTML.

POST /api/markdown/markdown-to-html

Corpo da Requisição

{
  "markdown": "# Título\nIsso é um texto em **negrito**."
}

HTML para Markdown

Converte uma string HTML para Markdown.

POST /api/markdown/html-to-markdown

Corpo da Requisição

{
  "html": "<h1>Título</h1><p>Isso é um texto em <b>negrito</b>.</p>"
}

XML para JSON

Converte uma string XML para um objeto JSON.

POST /api/xml/convert-to-json

Corpo da Requisição

{
  "xml": "<root><pessoa nome='Ana' /></root>"
}

Validar E-mail

Verifica se um e-mail é válido e/ou descartável e previna bots nos seus sistemas/formulários de cadastro.

POST /api/email/validate/:email

QRCode

Gerar QRCode

Gere um QRCode a partir de um texto ou link.

POST /api/qrcode/generate

Corpo da Requisição

{
  "text": "https://thebagui.net",
  "outputImage": true
}

outputImage (boolean, opcional): Se true, a resposta será a imagem PNG diretamente. Se false ou omitido, a resposta será um JSON com a imagem em base64.

Webhooks

Crie endpoints dinâmicos e personalizáveis para receber requisições. Este serviço possui duas rotas base: /manage para gerenciar seus webhooks e /call para acioná-los.

Criar Webhook

POST /api/webhooks/manage

Corpo da Requisição

{
  "name": "meu-primeiro-webhook",
  "method": "POST",
  "responseContentType": "application/json",
  "responseContent": "{\"status\": \"ok\", \"message\": \"Webhook recebido!\"}"
}

name (string): Nome único para a rota (sem espaços ou caracteres especiais).
method (string): Método HTTP que o webhook irá aceitar (GET, POST, PUT, etc.).
responseContentType (string): O Content-Type da resposta (ex: application/json, text/html).
responseContent (string): O corpo da resposta que será retornado quando o webhook for acionado.

Listar Webhooks

Retorna uma lista de todos os webhooks que você criou.

GET /api/webhooks/manage

Acionar um Webhook

Faz uma chamada para um dos seus webhooks dinâmicos.

GET | POST | etc. /api/webhooks/call/:webhookName

A requisição para esta rota deve usar o método HTTP que foi definido na criação do webhook.
Todos os cabeçalhos, query params e o corpo da requisição são salvos no histórico para auditoria.

Exemplo de Chamada cURL

curl -X POST https://thebagui.net/api/webhooks/call/meu-primeiro-webhook \
 -H "x-api-key: SUA_CHAVE" \
 -H "Content-Type: application/json" \
 -d '{"event": "new_user_signup", "userId": 123}'

Obter Histórico de Requisições

Recupera os logs de todas as chamadas feitas para um webhook específico, com paginação.

GET /api/webhooks/manage/:name/history

Query Parameters

page (integer, opcional): O número da página. Padrão: 1.
limit (integer, opcional): O número de registros por página. Padrão: 25.

Remover Webhook

Apaga permanentemente uma definição de webhook e todo o seu histórico.

DELETE /api/webhooks/manage/:name

Manipulação de imagens

Manipular

Com esse recurso você pode cortar sua imagem, redimensionar, deixar preto e branco, alterar a qualidade (comprimir), alterar o contraste, virar horizontalmente ou verticalmente ou rotacionar. Extensões permitidas: PNG, JPEG, BMP, TIFF. Requisição via multipart/form-data. Limite de 10MB.

POST /api/image/manipulate

Corpo da Requisição (form-data)

Chave: image
Valor: O arquivo de imagem.

Além do arquivo passado, as seguintes opções são permitidas para os processo de manipulação (formato: chave-valor, como acima):

resizeWidth (valor inteiro), resizeHeight (valor inteiro), cropX (valor inteiro), cropY (valor inteiro), cropWidth (valor inteiro), cropHeight (valor inteiro), grayscale (true ou false), constrast (0.0 à 1.0), rotate (ângulo), flipHorizontal (true ou false), flipVertical (true ou false), quality (0 à 100).

A imagem manipulada será retornada na requisição com o Content-Type: image/webp.

Geração de planilhas

Geração a partir de um JSON

Gere uma planilha com seus dados.

POST /api/sheet/generate

Corpo da Requisição

{
  "fileName": "meu_arquivo",
  "sheetName": "Dados",
  "data": {
    columns: [
        { label: "Nome", value: "name" },
        { label: "Email", value: "email" }
    ],
    rows: [
        { name: "Joao", email: "[email protected]" },
        { name: "Luis", email: "[email protected]" },
    ]
  }
}

fileName (obrigatório)
sheetName (obrigatório): será o nome da sua página da planilha
data (obrigatório): precisa estar no formato de colunas e linhas. As colunas são presentes pelo label (termo que será visivel na planilha) e value é para linkar os valores presentes em rows com suas respectivas colunas.

Após realizar a requisição, seu arquivo de planilha será retornado no Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.