Bem-vindo à SnapID API v2.0

Armazenamento de arquivos: simples, rápido e seguro. A SnapID fornece uma API RESTful para upload, gerenciamento e entrega de arquivos (imagens, vídeos, áudios e documentos) com alta disponibilidade em Nuvem (HA) e suporte a envios de até 6 GB por arquivo.

🚀 Quickstart Guide

Comece a usar a API em menos de 2 minutos.

Passo 1: Obtenha sua API Key

Faça uma requisição de registro para gerar sua chave gratuitamente. Ela será exibida na resposta e enviada para seu e-mail.

import requests

response = requests.post(
    "https://snapid.com.br/api/register",
    json={"email": "dev@exemplo.com", "name": "Dev", "whatsapp": "11999999999"}
)
print(response.json())
const response = await fetch("https://snapid.com.br/api/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "dev@exemplo.com", 
    name: "Dev", 
    whatsapp: "11999999999"
  })
});
const data = await response.json();
console.log(data);
curl -X POST https://snapid.com.br/api/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@exemplo.com", "name": "Dev", "whatsapp": "11999999999"}'

Passo 2: Faça seu primeiro Upload

Use a api_key recebida no passo anterior para enviar um arquivo.

import requests

api_key = "sk_suachaveaqui"
with open("imagem.jpg", "rb") as file:
    response = requests.post(
        f"https://snapid.com.br/upload?key={api_key}",
        files={"file": file}
    )
print(response.json())
const apiKey = "sk_suachaveaqui";
const formData = new FormData();
// Supondo que 'fileInput' seja um elemento 
formData.append("file", fileInput.files[0]);

const response = await fetch(`https://snapid.com.br/upload?key=${apiKey}`, {
  method: "POST",
  body: formData
});
const result = await response.json();
console.log(result.data.url); // URL pública do arquivo
curl -X POST \
  -F "file=@/caminho/para/imagem.jpg" \
  "https://snapid.com.br/upload?key=sk_suachaveaqui"

Autenticação

O acesso às rotas protegidas requer uma API Key. Você pode passá-la via ?key=YOUR_KEY (query string), via Header X-API-Key: YOUR_KEY ou no Body JSON.

POST /api/recover Público

Recuperar API Key

Reenvia a chave de acesso para o e-mail cadastrado.

Body (JSON)

Campo Tipo Status
email string Required 
import requests
requests.post("https://snapid.com.br/api/recover", json={"email": "dev@exemplo.com"})
curl -X POST https://snapid.com.br/api/recover \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@exemplo.com"}'

Exemplo Prático: CRUD

Veja como integrar as 4 operações fundamentais (Create, Read, Update, Delete) em um único fluxo de aplicação com a SnapID API.

Ciclo de Vida de um Arquivo

Neste exemplo prático, fazemos o upload de um arquivo, consultamos os dados dele, atualizamos sua validade (ou metadados) e por fim o excluímos de forma sequencial.

import requests

BASE_URL = "https://snapid.com.br/api/files"
KEY = "sk_suachaveaqui"

# 1. CREATE (Upload)
with open("foto.jpg", "rb") as f:
    res = requests.post("https://snapid.com.br/upload", params={"key": KEY}, files={"file": f})
file_id = res.json()["data"]["id"]
print(f"Criado: {file_id}")

# 2. READ (Get Info)
info = requests.get(f"{BASE_URL}/{file_id}", params={"key": KEY})
print("Lido:", info.json()["data"]["url"])

# 3. UPDATE (Metadata)
update = requests.put(f"{BASE_URL}/{file_id}", params={"key": KEY}, json={"expiration": 3600})
print("Atualizado:", update.status_code)

# 4. DELETE
delete = requests.delete(f"{BASE_URL}/{file_id}", params={"key": KEY})
print("Deletado:", delete.status_code)
const BASE_URL = "https://snapid.com.br/api/files";
const KEY = "sk_suachaveaqui";

// 1. CREATE (Upload)
const formData = new FormData();
formData.append("file", fileInput.files[0]);
let res = await fetch(`https://snapid.com.br/upload?key=${KEY}`, { method: "POST", body: formData });
let data = await res.json();
const fileId = data.data.id;
console.log(`Criado: ${fileId}`);

// 2. READ (Get Info)
res = await fetch(`${BASE_URL}/${fileId}?key=${KEY}`);
data = await res.json();
console.log(`Lido: ${data.data.url}`);

// 3. UPDATE (Metadata)
res = await fetch(`${BASE_URL}/${fileId}?key=${KEY}`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ expiration: 3600 })
});
console.log(`Atualizado: ${res.status}`);

// 4. DELETE
res = await fetch(`${BASE_URL}/${fileId}?key=${KEY}`, { method: "DELETE" });
console.log(`Deletado: ${res.status}`);

Arquivos

GET /api/files 🔑 Auth

Listar Arquivos

Retorna uma lista paginada dos seus arquivos enviados.

Query Params

Nome Tipo Descrição
key string Required - Sua API Key
category string Optional - image, video, audio, document
limit number Optional - Padrão 50
offset number Optional - Padrão 0 
import requests
res = requests.get("https://snapid.com.br/api/files", params={"key": "sk_xyz", "category": "image", "limit": 10})
print(res.json())
const res = await fetch("https://snapid.com.br/api/files?key=sk_xyz&category=image&limit=10");
console.log(await res.json());
curl "https://snapid.com.br/api/files?key=sk_xyz&category=image&limit=10"
POST /api/upload/resumable/... 🔑 Auth

Resumable Uploads (Arquivos até 10GB)

Para o envio de arquivos muito grandes, recomendamos utilizar a nova API Direct-to-GCS. O fluxo contorna o servidor Node.js e consiste em três etapas para garantir estabilidade máxima e altíssima performance.

1. Inicialização (/api/upload/resumable/init)

Valida sua chave, checa sua cota de armazenamento e devolve uma URL assinada exclusiva do Storage.

// Request Body
{
  "filename": "video_gigante.mp4",
  "mime_type": "video/mp4",
  "file_size": 2147483648
}

2. Envio (Upload Direto - Navegador/App)

O cliente envia os bytes (fatiados ou não) via requisição PUT diretamente para a upload_url recebida no passo 1. O servidor Node.js nem sequer enxerga esse tráfego, evitando gargalos.

3. Finalização (/api/upload/resumable/finalize)

Confirma a conclusão, audita se os bytes realmente chegaram no GCS e consolida os dados finais no banco de dados.

// Request Body
{
  "uuid": "retornado_no_passo_1",
  "storage_path": "retornado_no_passo_1",
  "filename": "video_gigante.mp4",
  "mime_type": "video/mp4",
  "file_size": 2147483648
}
GET /file/:uuid.ext Público

Acessar / Visualizar

Rota pública de acesso direto ao arquivo. Pode ser usada em tags <img src="..."> ou <video src="...">. 

<img src="https://snapid.com.br/file/a1b2c3d4.jpg" alt="Foto" />
DELETE /api/files/:uuid 🔑 Auth

Excluir Arquivo

Exclui o arquivo permanentemente do storage. Só o proprietário pode realizar esta ação.

curl -X DELETE "https://snapid.com.br/api/files/a1b2c3d4?key=sk_xyz"
GET /api/files/download-all 🔑 Auth

Baixar Todos os Arquivos (ZIP)

Compacta todos os arquivos não excluídos do cliente em um único arquivo ZIP de download. O arquivo ZIP gerado organiza os itens internamente divididos em subpastas por categoria (images/, videos/, etc.).

Query Params

Nome Tipo Descrição
key string Required - Sua API Key 
curl -L "https://snapid.com.br/api/files/download-all?key=sk_xyz" -o meus-arquivos.zip
// Pode ser chamado abrindo diretamente a URL no navegador:
window.location.href = "https://snapid.com.br/api/files/download-all?key=sk_xyz";

Planos & Assinaturas

GET /api/plans Público

Listar Planos

Retorna os planos disponíveis, limites de armazenamento e preços.

curl https://snapid.com.br/api/plans
POST /api/subscribe 🔑 Auth

Assinar um Plano

Ativa a assinatura e retorna um link de checkout do Mercado Pago.

curl -X POST "https://snapid.com.br/api/subscribe?key=sk_xyz" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": 2, "billing_cycle": "monthly"}'

Uso & Limites

GET /api/usage 🔑 Auth

Consultar Armazenamento

Retorna dados analíticos sobre seu armazenamento e limite do plano.

curl "https://snapid.com.br/api/usage?key=sk_xyz"

🤖 Integração Avançada: n8n

O SnapID é ideal para servir como backend de armazenamento temporário ou permanente para automações low-code/no-code no n8n. Um uso comum é receber imagens de um usuário, hospedá-las na SnapID, e enviar as URLs públicas para um modelo de Inteligência Artificial (ex: fal.ai, Grok) para gerar vídeos.

Gerador de Vídeo com IA

O fluxo de automação abaixo demonstra o processo:

  1. Um formulário web envia múltiplas imagens para o Webhook do n8n via multipart/form-data.
  2. O nó "Upload to SnapID" itera sobre os binários e faz requisições POST /upload para o SnapID.
  3. O n8n coleta as URLs geradas (data.public_url) da resposta.
  4. Um nó HTTP request envia essas URLs para a API de geração de vídeo.
  5. Um loop aguarda a finalização e retorna o vídeo para o usuário.

Configuração do Nó HTTP Request (Upload para SnapID) no n8n:

⬇️ Baixar JSON Completo 
{
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://snapid.com.br/upload",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "key",
              "value": "SUA-KEY-AQUI"
            }
          ]
        },
        "sendBody": true,
        "contentType": "multipart-form-data",
        "bodyParameters": {
          "parameters": [
            {
              "name": "expiration",
              "value": "86400"
            },
            {
              "parameterType": "formBinaryData",
              "name": "file",
              "inputDataFieldName": "files"
            }
          ]
        },
        "options": {}
      },
      "name": "Upload to SnapID",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [
        -7744,
        -1216
      ],
      "id": "ac0850e2-4935-4776-8749-11e69f065fc6"
    }
  ],
  "connections": {
    "Upload to SnapID": {
      "main": [
        []
      ]
    }
  },
  "pinData": {},
  "meta": {
    "templateCredsSetupCompleted": true,
    "instanceId": "ea88013e5b7309b0c438c7b5879b0b0d92d2795380298c2786b7759d6ebb26dd"
  }
}

💻 Integração Web/Social

🖼️ Imagens Responsivas

<picture>
  <source srcset="https://snapid.com.br/file/UUID.webp" type="image/webp" />
  <img src="https://snapid.com.br/file/UUID.jpg" alt="Foto responsiva" style="max-width: 100%;" />
</picture>

🎬 Player de Vídeo

<video src="https://snapid.com.br/file/UUID.mp4" 
       controls poster="https://snapid.com.br/file/THUMB.jpg" 
       style="width: 100%; border-radius: 8px;">
</video>

🌐 Open Graph (Preview para Redes Sociais)

Adicione no <head> do seu site para preview no WhatsApp/Facebook/X.

<meta property="og:title" content="Meu Título" />
<meta property="og:description" content="Descrição" />
<meta property="og:image" content="https://snapid.com.br/file/UUID.jpg" />
<meta property="og:url" content="https://meusite.com" />
<meta name="twitter:card" content="summary_large_image" />

⚠️ Fluxo de Inadimplência

O SnapID possui um fluxo automatizado e transparente de cobrança, backup e exclusão de arquivos para clientes que deixaram de pagar a assinatura (status expired). O ciclo completo dura 30 dias e envia 5 comunicações no total:

Ciclo de Vida da Cobrança (30 dias)

Avisos Semanais (Avisos 1 a 4)

Toda quarta-feira às 09:00, o sistema envia um e-mail de alerta informando a falta de pagamento e que a ausência de renovação implicará no cancelamento do contrato e na exclusão permanente dos arquivos.

  • Aviso 1 (Semana 1): Alerta sobre a falta de pagamento. Prazo: 30 dias restantes.
  • Aviso 2 (Semana 2): Alerta sobre a falta de pagamento. Prazo: ~21 dias restantes.
  • Aviso 3 (Semana 3): Alerta sobre a falta de pagamento. Prazo: ~14 dias restantes.
  • Aviso 4 (Semana 4): Último alerta antes da remoção dos arquivos. Prazo: ~7 dias restantes.

Exclusão e Despedida (Aviso 5)

Após 30 dias completos de inadimplência:

  • Todos os arquivos armazenados do cliente são excluídos permanentemente do Google Cloud Storage e do banco de dados.
  • A conta do cliente é suspensa (status suspended) e as chaves de API param de funcionar.
  • O cliente recebe o 5º e-mail contendo um agradecimento pela utilização da plataforma e um convite para retornar a assinar quando bem desejar.

💡 Recuperação de Arquivos: Durante todo o período de 30 dias de inadimplência, o cliente tem acesso garantido para fazer o download completo de suas mídias compactadas em ZIP pelo Dashboard do cliente ou programaticamente pela rota /api/files/download-all.

Exemplo de Recuperação de Arquivos (Download ZIP)

Para realizar o download de todos os seus arquivos compactados, você pode utilizar a rota abaixo passando sua chave de API:

curl -L "https://snapid.com.br/api/files/download-all?key=SUA-KEY-AQUI" -o backup-snapid.zip
// No navegador, redirecione para iniciar o download:
window.location.href = "https://snapid.com.br/api/files/download-all?key=SUA-KEY-AQUI";

Códigos de Erro

HTTP Status Código JSON Descrição
400 BAD_REQUEST Parâmetros faltando ou inválidos.
401 API_KEY_MISSING API Key ausente.
401 API_KEY_INVALID API Key inválida.
403 QUOTA_EXCEEDED Limite de armazenamento atingido.
404 NOT_FOUND Arquivo ou recurso não encontrado.