Assets Handler V2

Navegação rápida

Encontrar por URL: Find by URL
Verificar saúde de link: Health Check
Criar asset: Create
Testar funcionalidades: Test Endpoints
Erros comuns: Errors
Arquitetura & Fluxo: Architecture & Flow
Casos de uso: Use Cases

Geral

Esta área do código é dedicada a cuidar de mídias, links e outros assets que circulam na plataforma. Toda vez que um link de qualquer tipo de mídia for transitar pela plataforma, precisamos levar ele para um “local” controlado, onde exista uma transcrição acessível, controle de deleção e link encurtado. O encurtamento de link é especialmente importante porque isso ajuda a reduzir o tamanho do payload da mensagem, o que é importante para otimizar o uso de tokens.

API Endpoints Disponíveis

POST /api/externalAPIs/public/assets/findByUrl

Busca um asset pela URL na base de dados de assets. Aceita qualquer uma das variantes: file_url, bucket_url, short_original ou short_minio. A URL é sanitizada antes da busca e o resultado pode usar cache.

Autenticação: Bearer Token (API Key)

Exemplo cURL (findByUrl)

curl -X POST https://api.tolky.to/api/externalAPIs/public/assets/findByUrl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/file.pdf",
    "useCache": true,
    "includeDeleted": false
  }'

Payload:

{
  "url": "https://example.com/file.pdf",
  "useCache": true,
  "includeDeleted": false,
  "checkUrl": false
}

Observações:

url pode ser a URL original, a URL do MinIO, ou uma das URLs encurtadas (original/minio)
Busca pode incluir registros deletados quando includeDeleted=true

Parâmetros:

url (string, obrigatório): URL a ser verificada
useCache (boolean, opcional): Se deve usar cache. Padrão: true
includeDeleted (boolean, opcional): Se deve incluir assets deletados. Padrão: false
checkUrl (boolean, opcional): Se deve verificar saúde do link (disponibilidade e tipo). Padrão: false

Resposta (200)

Campos de data quando o asset é encontrado:

id (uuid), created_at (date-time), updated_at (date-time|null)
bucket_url (string|null), file_url (string|null)
user_id (uuid|null), host_id (uuid|null), avatar_id (uuid|null)
type (string|null), date (date-time|null)
short_description (string|null)
drive_id (uuid|null)
last_sync_at (date-time|null), synchronized (boolean|null)
dataset_id (uuid|null)
deleted (boolean)
mime_type (string|null)
short_original (string|null), short_minio (string|null)
healthCheck (object|null) quando checkUrl=true

Exemplos:

// found
{
  "exists": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "bucket_url": "https://minio.tolky.to/assets/file.pdf",
    "file_url": "https://example.com/file.pdf",
    "host_id": "660e8400-e29b-41d4-a716-446655440000",
    "type": "document",
    "mime_type": "application/pdf",
    "short_original": "https://short.tolky.to/abc123",
    "short_minio": "https://short.tolky.to/xyz789",
    "deleted": false
  }
}

// notFound
{
  "exists": false,
  "data": null
}

// foundWithHealthCheck
{
  "exists": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "bucket_url": "https://minio.tolky.to/assets/file.pdf",
    "file_url": "https://example.com/file.pdf",
    "host_id": "660e8400-e29b-41d4-a716-446655440000",
    "type": "document",
    "mime_type": "application/pdf",
    "short_original": "https://short.tolky.to/abc123",
    "short_minio": "https://short.tolky.to/xyz789",
    "deleted": false,
    "healthCheck": {
      "url": "https://example.com/file.pdf",
      "ok": true,
      "status": 200,
      "mimeType": "application/pdf",
      "type": "document"
    }
  }
}

HealthCheck Response:

url: URL que foi verificada (prioriza: short_minio > short_original > bucket_url > file_url)
ok: true se o link está acessível (status 2xx/3xx) e válido, false caso contrário
status: Código HTTP retornado (ex: 200, 404, 403) ou null se falhou
mimeType: Tipo MIME detectado (via sniffing de bytes ou header Content-Type)
type: Tipo categorizado: 'img', 'video', 'audio', 'document' ou 'unknown'

⚠️ Importante: A verificação de saúde do link (checkUrl: true) faz uma requisição HTTP real ao link para verificar se está acessível. Use com moderação para evitar sobrecarga. O resultado é cacheado por 5 minutos.

Ver mais exemplos em: docs/EXAMPLES.md

POST /api/externalAPIs/public/assets/create

Documentação completa desta funcionalidade foi movida para uma página dedicada.

Consulte: Asset Creation Endpoint

Exemplo cURL (create)

curl -X POST https://api.tolky.to/api/externalAPIs/public/assets/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/documents/contract.pdf",
    "hostId": "660e8400-e29b-41d4-a716-446655440001",
    "type": "document"
  }'

Códigos de Erro

400 Requisição inválida (ex.: URL ausente ou inválida)
401 Token de autenticação inválido
500 Erro interno do servidor

Exemplos:

// 400
{ "error": "URL é obrigatória" }

// 401
{ "error": "Token de autenticação inválido" }

// 500
{ "error": "Erro ao verificar existência da URL" }

Recursos

Para esta aplicação vamos usar alguns recursos.

public.assets.
encryptJson() e decryptJson() do secOps/crypto.js.
minIO service.
tolky kutt service.
media link checker MediaLinkHealthChecker().

Fluxo

O usuário envia um link de mídia.
O link é validado pelo media link checker.
Se o link for válido, ele é processado pelo mediaAnalysisV3.js.
Se o link não for válido, ele é retornado ao usuário.
O link é processado pelo mediaAnalysisV3.js.
O link é salvo no public.assets.
O link é salvo no minIO service.
O link é encurtado pelo tolky kutt service.
O link é retornado ao usuário.

Funcionalidades / benefícios

Evitar baixar links que já foram baixados.
Redução de custo com tokens por causa do encurtamento de link.
Evitar links quebrados/expirados.
Evitar links que não são de mídia.
Evitar compartilhar links quebrados/expirados.
Verificação periódica de saúde dos links.
Possibilidade de manter o link partilhado e modificar o local onde ele está armazenada a mídia.

Verificação de Saúde de Links (Health Check)

A funcionalidade de health check permite verificar se os links armazenados ainda estão acessíveis e válidos, evitando compartilhar links quebrados ou expirados com os usuários.

Como funciona

Verificação sob demanda: Ative passando checkUrl: true nas opções
Priorização inteligente: Verifica URLs na ordem:
- short_minio (mais rápido e confiável)
- short_original (encurtador Kutt)
- bucket_url (MinIO direto)
- file_url (URL original)
Cache automático: Resultados são cacheados por 5 minutos para reduzir chamadas HTTP
Detecção de tipo: Identifica o tipo real do arquivo (imagem, vídeo, áudio, documento)
Não invasivo: Usa HEAD request + byte-range fetch (não baixa o arquivo completo)

Quando usar

✅ USE quando:

Antes de compartilhar links em conversas
Em processos de validação/limpeza de assets
Ao listar assets para o usuário
Em pipelines de monitoramento/alerta

❌ NÃO USE quando:

Em operações em lote muito grandes (cuidado com rate limiting)
Quando performance é crítica (adiciona latência de rede)
Para assets recém-criados (provavelmente estão OK)

Assets V2 - Test Endpoints

Endpoints para testar funcionalidades do Assets Handler V2 via API.

Base URL: /api/externalAPIs/public/assets/test

Autenticação: Bearer Token (API Key) obrigatório em todos os endpoints

📋 GET /api/externalAPIs/public/assets/test

Executa uma suite completa de testes do Assets Handler.

Headers

Authorization: Bearer YOUR_API_KEY

Resposta de Sucesso (200)

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "tests": {
    "sanitizeUrl": {
      "success": true,
      "input": "  https://example.com/file.pdf  \n\t",
      "output": "https://example.com/file.pdf"
    },
    "sanitizeInvalidUrl": {
      "success": true,
      "input": "not-a-valid-url",
      "output": null
    },
    "healthChecker": {
      "success": true,
      "url": "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png",
      "result": {
        "ok": true,
        "status": 200,
        "mimeType": "image/png",
        "type": "img"
      }
    },
    "healthCheckerBroken": {
      "success": true,
      "url": "https://example.com/this-file-does-not-exist-404.pdf",
      "result": {
        "ok": false,
        "status": 404,
        "mimeType": "",
        "type": "unknown"
      }
    },
    "checkUrlExistsBasic": {
      "success": true,
      "url": "https://example.com/test-file.pdf",
      "found": false,
      "hasHealthCheck": false
    },
    "checkUrlExistsWithHealthCheck": {
      "success": true,
      "url": "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png",
      "found": false,
      "healthCheck": {
        "ok": true,
        "status": 200,
        "mimeType": "image/png",
        "type": "img"
      }
    },
    "cache": {
      "success": true,
      "note": "Cache testado. Verifique logs para confirmar cache HIT/MISS"
    }
  },
  "summary": {
    "total": 7,
    "success": 7,
    "failed": 0,
    "allPassed": true,
    "passRate": "100.00%"
  }
}

Exemplo cURL

curl -X GET https://api.tolky.to/api/externalAPIs/public/assets/test \
  -H "Authorization: Bearer YOUR_API_KEY"

🔍 POST /api/externalAPIs/public/assets/test/health-check

Testa o health check de uma URL específica.

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

{
  "url": "https://example.com/file.pdf"
}

Resposta de Sucesso (200)

{
  "url": "https://example.com/file.pdf",
  "healthCheck": {
    "ok": true,
    "status": 200,
    "mimeType": "application/pdf",
    "type": "document"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Exemplo cURL

curl -X POST https://api.tolky.to/api/externalAPIs/public/assets/test/health-check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/file.pdf"}'

📊 POST /api/externalAPIs/public/assets/test/check-multiple

Testa o health check de múltiplas URLs em batch (máximo 20 URLs).

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

{
  "urls": [
    "https://example.com/file1.pdf",
    "https://example.com/file2.jpg",
    "https://example.com/file3.mp4"
  ]
}

Resposta de Sucesso (200)

{
  "count": 3,
  "duration": "1250ms",
  "avgPerUrl": "416.67ms",
  "results": [
    {
      "url": "https://example.com/file1.pdf",
      "ok": true,
      "status": 200,
      "mimeType": "application/pdf",
      "type": "document"
    },
    {
      "url": "https://example.com/file2.jpg",
      "ok": false,
      "status": 404,
      "mimeType": "",
      "type": "unknown"
    },
    {
      "url": "https://example.com/file3.mp4",
      "ok": true,
      "status": 200,
      "mimeType": "video/mp4",
      "type": "video"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Exemplo cURL

curl -X POST https://api.tolky.to/api/externalAPIs/public/assets/test/check-multiple \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/file1.pdf",
      "https://example.com/file2.jpg",
      "https://example.com/file3.mp4"
    ]
  }'

🧹 POST /api/externalAPIs/public/assets/test/sanitize

Testa a sanitização de uma URL.

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

{
  "url": "  https://example.com/file.pdf  \n\t"
}

Resposta de Sucesso (200)

{
  "original": "  https://example.com/file.pdf  \n\t",
  "sanitized": "https://example.com/file.pdf",
  "valid": true,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Exemplo URL Inválida

{
  "original": "not-a-valid-url",
  "sanitized": null,
  "valid": false,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Exemplo cURL

curl -X POST https://api.tolky.to/api/externalAPIs/public/assets/test/sanitize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "  https://example.com/file.pdf  \n\t"}'

🗑️ DELETE /api/externalAPIs/public/assets/test/cache

Limpa o cache de uma URL específica ou todo o cache de assets.

Headers

Authorization: Bearer YOUR_API_KEY

Query Parameters

url (opcional): URL específica para limpar do cache. Se não fornecida, limpa todo o cache.

Resposta - Cache Específico (200)

{
  "cleared": "specific",
  "url": "https://example.com/file.pdf",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Resposta - Todo o Cache (200)

{
  "cleared": "all",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Exemplos cURL

Limpar cache de URL específica:

curl -X DELETE "https://api.tolky.to/api/externalAPIs/public/assets/test/cache?url=https://example.com/file.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY"

Limpar todo o cache:

curl -X DELETE https://api.tolky.to/api/externalAPIs/public/assets/test/cache \
  -H "Authorization: Bearer YOUR_API_KEY"

🚨 Respostas de Erro

400 - Bad Request

{
  "error": "URL é obrigatória"
}

401 - Unauthorized

{
  "error": "Token de autenticação inválido"
}

500 - Internal Server Error

{
  "error": "Erro interno do servidor"
}

💡 Casos de Uso

1. Validação de URLs antes de processar

# Testa se uma URL está acessível antes de fazer upload para MinIO
curl -X POST https://api.tolky.to/api/externalAPIs/public/assets/test/health-check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://client-site.com/document.pdf"}'

2. Verificação em batch de múltiplos arquivos

# Valida lista de URLs de uma vez
curl -X POST https://api.tolky.to/api/externalAPIs/public/assets/test/check-multiple \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://site1.com/file1.pdf",
      "https://site2.com/file2.jpg",
      "https://site3.com/file3.mp4"
    ]
  }'

3. Debug de problemas de cache

# Limpa cache e testa novamente
curl -X DELETE https://api.tolky.to/api/externalAPIs/public/assets/test/cache \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET https://api.tolky.to/api/externalAPIs/public/assets/test \
  -H "Authorization: Bearer YOUR_API_KEY"

4. Monitoramento de saúde dos links

# Script de monitoramento periódico
#!/bin/bash
URLS=(
  "https://example.com/important-file1.pdf"
  "https://example.com/important-file2.jpg"
)

for url in "${URLS[@]}"; do
  response=$(curl -s -X POST https://api.tolky.to/api/externalAPIs/public/assets/test/health-check \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"url\": \"$url\"}")
  
  echo "$response" | jq '.'
done

⚠️ Notas Importantes

Rate Limiting: Endpoints de teste respeitam os mesmos limites de rate limiting da API.
Cache: O health check é cacheado por 5 minutos. Use o endpoint DELETE para forçar nova verificação.
Timeout: Verificações de health check têm timeout de 10 segundos por URL.
Batch Limit: Máximo de 20 URLs por requisição no endpoint check-multiple.
Logs: Todos os testes geram logs detalhados. Verifique os logs do servidor para debug.

🔗 Endpoints Relacionados

POST /api/externalAPIs/public/assets/checkUrlExists - Verifica se URL existe no banco
GET /api/minio/test - Testes do MinIO Handler

API Pública de Followup Buscar por URL

Assets Handler V2
Navegação rápida
Geral
API Endpoints Disponíveis
POST /api/externalAPIs/public/assets/findByUrl
Exemplo cURL (findByUrl)
Resposta (200)
POST /api/externalAPIs/public/assets/create
Exemplo cURL (create)
Códigos de Erro
Recursos
Fluxo
Funcionalidades / benefícios
Verificação de Saúde de Links (Health Check)
Como funciona
Quando usar
Assets V2 - Test Endpoints
📋 GET /api/externalAPIs/public/assets/test
Headers
Resposta de Sucesso (200)
Exemplo cURL
🔍 POST /api/externalAPIs/public/assets/test/health-check
Headers
Body
Resposta de Sucesso (200)
Exemplo cURL
📊 POST /api/externalAPIs/public/assets/test/check-multiple
Headers
Body
Resposta de Sucesso (200)
Exemplo cURL
🧹 POST /api/externalAPIs/public/assets/test/sanitize
Headers
Body
Resposta de Sucesso (200)
Exemplo URL Inválida
Exemplo cURL
🗑️ DELETE /api/externalAPIs/public/assets/test/cache
Headers
Query Parameters
Resposta - Cache Específico (200)
Resposta - Todo o Cache (200)
Exemplos cURL
🚨 Respostas de Erro
400 - Bad Request
401 - Unauthorized
500 - Internal Server Error
💡 Casos de Uso
1. Validação de URLs antes de processar
2. Verificação em batch de múltiplos arquivos
3. Debug de problemas de cache
4. Monitoramento de saúde dos links
⚠️ Notas Importantes
🔗 Endpoints Relacionados

Conhecendo o tolky

Gerenciando Avatar

Integrações

Configurar WhatsApp

Desenvolvedor

Novidades no tolky

Essenciais

​Assets Handler V2

​Navegação rápida

​Geral

​API Endpoints Disponíveis

​POST /api/externalAPIs/public/assets/findByUrl

​Exemplo cURL (findByUrl)

​Resposta (200)

​POST /api/externalAPIs/public/assets/create

​Exemplo cURL (create)

​Códigos de Erro

​Recursos

​Fluxo

​Funcionalidades / benefícios

​Verificação de Saúde de Links (Health Check)

​Como funciona

​Quando usar

​Assets V2 - Test Endpoints

​📋 GET /api/externalAPIs/public/assets/test

​Headers

​Resposta de Sucesso (200)

​Exemplo cURL

​🔍 POST /api/externalAPIs/public/assets/test/health-check

​Headers

​Body

​Resposta de Sucesso (200)

​Exemplo cURL

​📊 POST /api/externalAPIs/public/assets/test/check-multiple

​Headers

​Body

​Resposta de Sucesso (200)

​Exemplo cURL

​🧹 POST /api/externalAPIs/public/assets/test/sanitize

​Headers

​Body

​Resposta de Sucesso (200)

​Exemplo URL Inválida

​Exemplo cURL

​🗑️ DELETE /api/externalAPIs/public/assets/test/cache

​Headers

​Query Parameters

​Resposta - Cache Específico (200)

​Resposta - Todo o Cache (200)

​Exemplos cURL

​🚨 Respostas de Erro

​400 - Bad Request

​401 - Unauthorized

​500 - Internal Server Error

​💡 Casos de Uso

​1. Validação de URLs antes de processar

​2. Verificação em batch de múltiplos arquivos

​3. Debug de problemas de cache

​4. Monitoramento de saúde dos links

​⚠️ Notas Importantes

​🔗 Endpoints Relacionados

Assets Handler V2

Navegação rápida

Geral

API Endpoints Disponíveis

POST /api/externalAPIs/public/assets/findByUrl

Exemplo cURL (findByUrl)

Resposta (200)

POST /api/externalAPIs/public/assets/create

Exemplo cURL (create)

Códigos de Erro

Recursos

Fluxo

Funcionalidades / benefícios

Verificação de Saúde de Links (Health Check)

Como funciona

Quando usar

Assets V2 - Test Endpoints

📋 GET /api/externalAPIs/public/assets/test

Headers

Resposta de Sucesso (200)

Exemplo cURL

🔍 POST /api/externalAPIs/public/assets/test/health-check

Headers

Body

Resposta de Sucesso (200)

Exemplo cURL

📊 POST /api/externalAPIs/public/assets/test/check-multiple

Headers

Body

Resposta de Sucesso (200)

Exemplo cURL

🧹 POST /api/externalAPIs/public/assets/test/sanitize

Headers

Body

Resposta de Sucesso (200)

Exemplo URL Inválida

Exemplo cURL

🗑️ DELETE /api/externalAPIs/public/assets/test/cache

Headers

Query Parameters

Resposta - Cache Específico (200)

Resposta - Todo o Cache (200)

Exemplos cURL

🚨 Respostas de Erro

400 - Bad Request

401 - Unauthorized

500 - Internal Server Error

💡 Casos de Uso

1. Validação de URLs antes de processar

2. Verificação em batch de múltiplos arquivos

3. Debug de problemas de cache

4. Monitoramento de saúde dos links

⚠️ Notas Importantes

🔗 Endpoints Relacionados