{"openapi":"3.0.0","info":{"title":"ArgosCloud — Developer REST API & Webhooks","version":"1.0.0","description":"\n**ArgosCloud API** — Plataforma Corporativa de Distribuição Segura e Upload de Arquivos.\n\nEsta documentação interativa permite testar todos os endpoints diretamente pelo navegador (**Try It Out**).\nPara autenticar requisições de teste:\n1. Clique no botão verde **Authorize** acima.\n2. Insira sua **Chave de API** gerada no painel administrativo (Ex: `argos_live_...`).\n        ","contact":{"name":"Suporte Técnico ArgosCloud","url":"http://cloud.argosgrupo.com","email":"suporte@argoscloud.com"}},"servers":[{"url":"http://cloud.argosgrupo.com","description":"Servidor Atual (Ambiente Ativo)"}],"tags":[{"name":"Developer API (Envios & Pedidos)","description":"Endpoints principais para ERPs, bots, automações gráficas e integrações externas."},{"name":"Chunk Uploads (Arquivos Gigantes em Fatias)","description":"Protocolo de envio particionado (resumable chunks) para arquivos de múltiplos gigabytes."},{"name":"Webhooks & Notificações em Tempo Real","description":"Recepção e teste de eventos de link aberto, upload criado e expiração."},{"name":"Links Públicos & Visualização","description":"Acesso e download de pacotes por token criptográfico ou número de pedido."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Chave de API gerada no painel administrativo do ArgosCloud."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT retornado no login do painel administrativo."}},"schemas":{"ApiResponseSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Operação realizada com sucesso."},"data":{"type":"object"}}},"ApiResponseError":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Chave de API inválida ou revogada."}}},"UploadResult":{"type":"object","properties":{"upload_id":{"type":"string","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"order_number":{"type":"string","example":"PED-2026-9901"},"public_token":{"type":"string","example":"API-20260824-A1B2C3D4"},"public_url":{"type":"string","example":"http://cloud.argosgrupo.com/f/API-20260824-A1B2C3D4"},"order_url":{"type":"string","example":"http://cloud.argosgrupo.com/p/PED-2026-9901"},"total_files":{"type":"integer","example":1},"total_size_bytes":{"type":"integer","example":2048500},"total_size_formatted":{"type":"string","example":"1.95 MB"},"retention_days":{"type":"integer","nullable":true,"example":0,"description":"0 ou null = permanente (nunca expira)"},"files":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","example":"f8b3c9e1-..."},"original_name":{"type":"string","example":"arte_banner_impressao.pdf"},"extension":{"type":"string","example":"pdf"},"size_bytes":{"type":"integer","example":2048500},"stream_url":{"type":"string","example":"http://cloud.argosgrupo.com/api/v1/files/f8b3c9e1-.../stream"},"download_url":{"type":"string","example":"http://cloud.argosgrupo.com/api/v1/files/f8b3c9e1-.../download"}}}}}},"OrderDetails":{"type":"object","properties":{"order_number":{"type":"string","example":"PED-2026-9901"},"created_at":{"type":"string","format":"date-time"},"friendly_url":{"type":"string","example":"http://cloud.argosgrupo.com/p/PED-2026-9901"},"total_uploads":{"type":"integer","example":1},"total_files":{"type":"integer","example":3},"total_size_bytes":{"type":"integer","example":5242880},"uploads":{"type":"array","items":{"$ref":"#/components/schemas/UploadResult"}}}}}},"paths":{"/api/v1/api/ping":{"get":{"tags":["Developer API (Envios & Pedidos)"],"summary":"1. Teste de Conectividade e Status da API","description":"Valida se o servidor está online e retorna a identidade do cliente autenticado via chave de API.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"API operacional e chave de API válida.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"service":{"type":"string","example":"ArgosCloud External Developer API"},"version":{"type":"string","example":"1.0.0"},"status":{"type":"string","example":"operational"},"authenticated_as":{"type":"object","properties":{"key_id":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000"},"key_name":{"type":"string","example":"ERP Tiny / Bling Produção"},"type":{"type":"string","example":"API_KEY"}}},"timestamp":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Chave de API inválida, ausente ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseError"}}}}}}},"/api/v1/api/upload":{"post":{"tags":["Developer API (Envios & Pedidos)"],"summary":"2. Envio de Arquivos do Pedido (Multipart / FormData)","description":"\nRecebe um ou múltiplos arquivos para um número de pedido.\n- Gera automaticamente os links amigáveis (`/p/{orderNumber}`) e link direto por token (`/f/{token}`).\n- Se `retention_days` for omitido ou `0`, o arquivo fica **permanente para sempre** (não expira).\n- Roda antivírus, inspeção de cabeçalhos, sanitização e extração de texto (OCR) em segundo plano.\n            ","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["order_number","files"],"properties":{"order_number":{"type":"string","description":"Número ou código identificador do pedido no seu ERP / CRM.","example":"PED-2026-9901"},"source":{"type":"string","description":"Identificador do sistema de origem (Ex: ERP Tiny, Bot WhatsApp, etc.).","example":"API - Sistema Gráfico"},"retention_days":{"type":"integer","description":"Tempo de retenção em dias. 0 ou vazio = PERMANENTE PARA SEMPRE.","example":0},"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Um ou mais arquivos a serem anexados ao pedido."}}}},"application/json":{"schema":{"type":"object","required":["order_number","files"],"properties":{"order_number":{"type":"string","example":"PED-2026-9901"},"source":{"type":"string","example":"API - JSON Base64"},"retention_days":{"type":"integer","example":0},"files":{"type":"array","items":{"type":"object","required":["name","content_base64"],"properties":{"name":{"type":"string","example":"arte_banner.pdf"},"content_base64":{"type":"string","example":"JVBERi0xLjQKJcTl8uXrp..."},"mime_type":{"type":"string","example":"application/pdf"}}}}}}}}},"responses":{"200":{"description":"Arquivos enviados e links gerados com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Upload processado com sucesso."},"data":{"$ref":"#/components/schemas/UploadResult"}}}}}},"400":{"description":"Parâmetros inválidos ou nenhum arquivo fornecido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseError"}}}},"401":{"description":"Não autorizado. Chave de API ausente ou inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseError"}}}}}}},"/api/v1/api/uploads/{idOrToken}":{"get":{"tags":["Developer API (Envios & Pedidos)"],"summary":"3. Consultar Detalhes e Arquivos de um Envio","description":"Consulta os metadados, lista de arquivos e links de download utilizando o ID ou o Token público do envio.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"idOrToken","in":"path","required":true,"description":"UUID do envio ou token público (Ex: `API-20260824-...`).","schema":{"type":"string","example":"API-20260824-A1B2C3D4"}}],"responses":{"200":{"description":"Detalhes do envio encontrados.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"upload":{"$ref":"#/components/schemas/UploadResult"}}}}}}}},"404":{"description":"Envio não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseError"}}}}}}},"/api/v1/api/orders/{orderNumber}":{"get":{"tags":["Developer API (Envios & Pedidos)"],"summary":"4. Consultar Todos os Arquivos por Número de Pedido","description":"Retorna todos os envios e arquivos associados a um determinado número de pedido (ex: `PED-2026-9901`).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"orderNumber","in":"path","required":true,"description":"Número do pedido.","schema":{"type":"string","example":"PED-2026-9901"}}],"responses":{"200":{"description":"Histórico do pedido localizado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/OrderDetails"}}}}}},"404":{"description":"Nenhum arquivo encontrado para este pedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseError"}}}}}}},"/api/v1/uploads/chunk/init":{"post":{"tags":["Chunk Uploads (Arquivos Gigantes em Fatias)"],"summary":"1. Iniciar Sessão de Upload em Chunks (Resumable)","description":"Inicia uma sessão de upload particionado para arquivos pesados (centenas de MBs ou GBs).","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_number","file_name","file_size","chunk_size","total_chunks"],"properties":{"order_number":{"type":"string","example":"PED-GIGANTE-990"},"file_name":{"type":"string","example":"video_institucional_4k.mp4"},"file_size":{"type":"integer","example":4294967296,"description":"Tamanho total em bytes"},"chunk_size":{"type":"integer","example":10485760,"description":"Tamanho de cada fatia (Ex: 10MB)"},"total_chunks":{"type":"integer","example":410},"retention_days":{"type":"integer","example":0}}}}}},"responses":{"200":{"description":"Sessão de chunk inicializada com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"sessionId":{"type":"string","example":"c56a4180-65aa-42ec-a945-5fd21dec0538"},"uploaded_chunks":{"type":"integer","example":0}}}}}}}}}}},"/api/v1/uploads/chunk/upload":{"post":{"tags":["Chunk Uploads (Arquivos Gigantes em Fatias)"],"summary":"2. Enviar Fatia de Arquivo (Chunk)","description":"Recebe um pedaço binário específico do arquivo referenciado pelo sessionId e chunk_index.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["sessionId","chunk_index","chunk"],"properties":{"sessionId":{"type":"string","example":"c56a4180-65aa-42ec-a945-5fd21dec0538"},"chunk_index":{"type":"integer","example":0},"chunk":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Chunk gravado com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"sessionId":{"type":"string","example":"c56a4180-65aa-42ec-a945-5fd21dec0538"},"chunk_index":{"type":"integer","example":0},"uploaded_chunks":{"type":"integer","example":1},"total_chunks":{"type":"integer","example":410}}}}}}}}}}},"/api/v1/uploads/chunk/finalize":{"post":{"tags":["Chunk Uploads (Arquivos Gigantes em Fatias)"],"summary":"3. Finalizar e Montar Arquivo Completo","description":"Após enviar todos os chunks, chama este endpoint para unificar as partes, gravar no Storage e gerar os links do pedido.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string","example":"c56a4180-65aa-42ec-a945-5fd21dec0538"}}}}}},"responses":{"200":{"description":"Arquivo finalizado com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/UploadResult"}}}}}}}}},"/api/v1/webhooks":{"get":{"tags":["Webhooks & Notificações em Tempo Real"],"summary":"1. Listar Webhooks Cadastrados","description":"Lista todos os webhooks ativos na conta com estatísticas de entrega.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Lista de webhooks."}}},"post":{"tags":["Webhooks & Notificações em Tempo Real"],"summary":"2. Cadastrar Novo Webhook","description":"Registra um endpoint HTTP para receber notificações em tempo real com assinatura HMAC SHA-256 no cabeçalho `X-Argos-Signature`.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","example":"Receptor de Notificações ERP"},"url":{"type":"string","example":"https://meu-erp.com.br/api/webhook/argos"},"secret":{"type":"string","example":"whsec_minha_chave_secreta_99"},"events":{"type":"array","items":{"type":"string","enum":["upload.created","link.opened","link.expired"]},"example":["upload.created","link.opened"]}}}}}},"responses":{"200":{"description":"Webhook registrado com sucesso."}}}},"/p/{orderNumber}":{"get":{"tags":["Links Públicos & Visualização"],"summary":"Link Público Amigável por Pedido","description":"Página amigável de visualização e download dos arquivos de um pedido específico para clientes finais.","parameters":[{"name":"orderNumber","in":"path","required":true,"schema":{"type":"string","example":"PED-2026-9901"}}],"responses":{"200":{"description":"Página HTML renderizada do pedido."},"404":{"description":"Pedido não encontrado ou expirado."}}}},"/f/{token}":{"get":{"tags":["Links Públicos & Visualização"],"summary":"Link Criptográfico Direto por Token","description":"Acesso seguro por token criptográfico único (`/f/...`), com suporte a senha de acesso e contagem de downloads.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","example":"API-20260824-A1B2C3D4"}}],"responses":{"200":{"description":"Download ou visualização do pacote de arquivos."}}}},"/api/v1/api/remove-bg":{"post":{"tags":["Inteligência Artificial & Remoção de Fundo"],"summary":"Remoção de Fundo com IA — Gera e Salva 3 URLs (Original, Branco e PNG Transparente)","description":"Processa o recorte de fundo de imagens e persiste 3 versões no storage: (1) Normal/Original sem alterar, (2) Fundo Branco sólido (#FFFFFF) e (3) PNG Transparente sem fundo.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Arquivo de imagem a ser recortado (JPG, PNG, WEBP)."},"size":{"type":"string","enum":["preview","auto","regular","full","medium","hd","4k"],"default":"preview","description":"Resolução de saída (preview utiliza saldo gratuito de 50 chamadas/mês por token)."},"type":{"type":"string","enum":["auto","person","product","car"],"default":"auto"}}}},"application/json":{"schema":{"type":"object","properties":{"image_base64":{"type":"string","example":"data:image/jpeg;base64,..."},"image_url":{"type":"string","example":"https://exemplo.com/foto_produto.jpg"},"filename":{"type":"string","example":"foto_produto.jpg"},"size":{"type":"string","enum":["preview","auto","regular","full","medium","hd","4k"],"default":"preview"}}}}}},"responses":{"200":{"description":"Sucesso! Retorna as 3 URLs salvas no storage do sistema.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"3 versões geradas com sucesso (Original, Fundo Branco e PNG Transparente)!"},"data":{"type":"object","properties":{"urls":{"type":"object","properties":{"original":{"type":"string","example":"http://cloud.argosgrupo.com/api/v1/storage/file?key=remove-bg/2026/08/24/..._original_foto.jpg"},"white_bg":{"type":"string","example":"http://cloud.argosgrupo.com/api/v1/storage/file?key=remove-bg/2026/08/24/..._white_bg_foto.png"},"transparent_bg":{"type":"string","example":"http://cloud.argosgrupo.com/api/v1/storage/file?key=remove-bg/2026/08/24/..._nobg_foto.png"}}},"original_url":{"type":"string"},"white_bg_url":{"type":"string"},"transparent_url":{"type":"string"},"result_url":{"type":"string"},"token_used":{"type":"string","example":"w9ab...8f3c"}}}}}}}}}}}}}