Publiva API

v1.0.6

Geração de criativos a partir de um briefing: content plan, DesignSpec, render e assets persistidos por organização. Os endpoints da engine respondem sem token; os de persistência usam o access token do Supabase.

Catálogo em JSON: GET /api · status em GET /api/health

Chaves e procedência

Qualidade e origem de cada variável. Valores nunca aparecem aqui. Atualize esta lista quando colar uma chave nova no .env.

Ainda falta (obrigatório)

META_APP_ID / META_APP_SECRET — Instagram + Facebook Pages. Login OAuth, token de 60 dias e Page token. Sem isso Conectar devolve 503. Produção para clientes: App Review (política de privacidade + vídeo do fluxo).

SUPABASE_URL / VITE_SUPABASE_URL
pública
obrigatória
presente
Origem: Supabase → Project Settings → API Keys. URL https://<ref>.supabase.co
HTTP Auth + Postgres (cliente JS). Não é connection string Direct/ORM.
SUPABASE_PUBLISHABLE_KEY / VITE_SUPABASE_PUBLISHABLE_KEY
pública
obrigatória
presente
Origem: Supabase → API Keys → Publishable (`sb_publishable_…`)
Login no browser. Pode ir no front. Não bypassa RLS.
SUPABASE_SECRET_KEY / SUPABASE_SERVICE_ROLE_KEY
secreta
obrigatória
presente
Origem: Supabase → API Keys → Secret (`sb_secret_…`). O app aceita os dois nomes.
Só no Lambda. Bypass RLS. Nunca no front.
SUPABASE_JWKS_URL
pública
opcional
presente
Origem: `/auth/v1/.well-known/jwks.json` no mesmo host do projeto
Reservado. Auth hoje usa as chaves HTTP, não JWKS.
OPENAI_API_KEY
produção
obrigatória
presente
Origem: https://platform.openai.com/api-keys (`sk-proj-…` ou `sk-…`)
Arte gpt-image. Sem ela a geração de imagem falha.
OPENAI_IMAGE_MODEL / OPENAI_IMAGE_QUALITY
interna
opcional
presente
Origem: Nossa config. Qualidade atual: `low` (mais barato, pior nitidez).
Modelo `gpt-image-1`. Subir para `medium`/`high` aumenta custo.
ANTHROPIC_API_KEY
interna
opcional
falta
Origem: https://console.anthropic.com/settings/keys (`sk-ant-…`) — não usar.
Módulo Claude na engine/agente. Não está em uso. Copy fica offline.
STRIPE_SECRET_KEY
teste
opcional
parcial
Origem: https://dashboard.stripe.com/test/apikeys — hoje é `rk_test_…` (restricted). `sk_test_…` ou `sk_live_…` também servem.
Checkout. Restricted precisa de Customers + Checkout Sessions. `rk_live_`/`sk_live_` = dinheiro real.
STRIPE_WEBHOOK_SECRET
teste
opcional
presente
Origem: Stripe → Developers → Webhooks → signing secret (`whsec_…`)
Assina POST /api/stripe/webhook. Sem isso o pagamento não ativa o plano.
META_APP_ID / META_APP_SECRET
produção
obrigatória
falta
Origem: https://developers.facebook.com/apps → app → Settings → Basic. Redirect: `{origem}/api/social-accounts/oauth/callback`
Instagram + Facebook Pages. Login OAuth, token de 60 dias e Page token. Sem isso Conectar devolve 503. Produção para clientes: App Review (política de privacidade + vídeo do fluxo).
PUBLIVA_OAUTH_STATE_SECRET
secreta
opcional
falta
Origem: String aleatória nossa. Se vazio, usa META_APP_SECRET ou a secret do Supabase.
HMAC do state OAuth. Melhor ter um valor dedicado.
LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET
produção
opcional
falta
Origem: https://www.linkedin.com/developers/apps
Publicar no LinkedIn. Sem isso a rede fica pendente.
PINTEREST_APP_ID / PINTEREST_APP_SECRET
produção
opcional
falta
Origem: https://developers.pinterest.com/apps/
Publicar no Pinterest. Sem isso a rede fica pendente.
EVOLUTION_API_URL / EVOLUTION_API_KEY / EVOLUTION_INSTANCE
secreta
opcional
falta
Origem: https://evoapicloud.com → Project + → instância. Copiar Base URL, token (`apikey`) e Instance ID/nome. Docs: https://docs.evoapicloud.com/instances/token
WhatsApp. Sem isso o cron prepara o post e anota pendência.
PUBLIVA_CRON_SECRET
interna
obrigatória
presente
Origem: Gerada por nós. Header `Authorization: Bearer …` nos crons EventBridge.
Autentica /api/public/cron/gerar e /publish. Não é chave de terceiro.
PUBLIVA_S3_BUCKET / AWS_REGION
interna
obrigatória
presente
Origem: Bucket `publiva-assets-ssmalkk`, região us-east-1. Lambda usa a role IAM, não access key no env.
Arquivos. Access keys de IAM user não vão para a função.
UNSPLASH_ACCESS_KEY / PEXELS_API_KEY
pública
opcional
falta
Origem: Unsplash Developers / Pexels API. Só se não houver OpenAI para foto.
Fallback de stock. Com OPENAI_API_KEY não são necessárias.
Google OAuth (painel, sem env)
produção
opcional
falta
Origem: Google Cloud → Credenciais OAuth (Web). Client ID/Secret no Supabase Authentication → Providers → Google. Callback fixo: `https://mklzrrzvvhiygejbyldz.supabase.co/auth/v1/callback`. Redirects: Site URL + `http://localhost:8080/**`.
Botão Entrar com Google. Sem isso o login é só e-mail/senha.
META_BUSINESS_PARTNER_ID / META_SYSTEM_USER_TOKEN
produção
opcional
falta
Origem: Meta Business Suite → configurações da BM. O ID é público (cliente cola como parceiro). O token é de System User com páginas atribuídas.
Facebook Pages sem OAuth. GET Graph client_pages/owned_pages/me/accounts; POST /{page-id}/feed.
Schema SQL (migrations)
interna
obrigatória
presente
Origem: `npx supabase db push` no projeto `mklzrrzvvhiygejbyldz`. A base está em `20260825170000_schema_base.sql`.
Sem tabelas (`plans`, `organizations`…) o health fica `database: down` mesmo com as chaves HTTP certas.
PUBLIVA_MODO_TESTE
interna
opcional
presente
Origem: Nossa flag. Local = `1` (IA que falha vira mock). Lambda deve ficar `0`.
Não é chave de terceiro. Em produção com `1` o usuário vê peça rosa [MOCK].

Token de acesso

Entre para obter um bearer token. A organização é criada no primeiro acesso autenticado.

Engine

Sem persistência e sem token. Compatível com o briefing original.

GET/api/health
Templates, formatos, provedor de foto, driver de render, storage, banco e se o Cloud remoto está configurado.
GET/api/custo
Tokens e custo já gastos nesta sessão.
GET|POST/api/custo/estimativa
Quanto sairia um plano deste tamanho, antes de gastar (?posts=4&imagens=4).
GET/api/formats
Formatos nativos das redes, com área de segurança de cada uma.
GET/api/templates
Catálogo de templates com os campos de conteúdo de cada um.
GET/api/templates/:id
Detalhe de um template.
GET/api/brands/presets
Paletas e tipografias prontas, mais o BrandKit padrão.
POST/api/spec
template + conteúdo + marca => DesignSpec, sem renderizar.
POST/api/render
template + conteúdo => imagem (?format=png|jpeg|webp&scale=&supersample=).
POST/api/render/spec
DesignSpec editado => imagem.
POST/api/variants
N variações de layout do mesmo conteúdo, já renderizadas.
POST/api/plan
Briefing => plano de conteúdo escrito pela IA (offline sem chave).
POST/api/plan/render
Briefing => posts prontos: imagem, legenda e hashtags, sem persistir.
POST/api/carousel
Carrossel completo: capa + slides + página final.
POST/api/campaign
Um conteúdo em vários formatos de uma vez (feed, story, ...).

Persistência

Exigem Authorization: Bearer <access_token>. Escopados pela organização do usuário.

POST/api/campaigns/run
token
Fluxo completo persistido: briefing → plano → posts → DesignSpecs → render → assets → generations.
GET|POST/api/brands
token
Lista e cria brands da organização.
GET|PATCH|DELETE/api/brands/:id
token
Lê, atualiza e remove uma brand.
GET|POST/api/projects
token
Lista e cria projects da organização.
GET|PATCH|DELETE/api/projects/:id
token
Lê, atualiza e remove um project.
GET|POST/api/campaigns
token
Lista (?projectId=) e cria campanhas.
GET|PATCH|DELETE/api/campaigns/:id
token
Campanha completa: posts, generations, DesignSpecs e assets.
GET/api/generations/:id
token
Generation com o DesignSpec e os assets assinados.
GET/api/assets/:id
token
Asset com URL assinada (?redirect=1 responde 302).
GET|POST/api/assets
token
Biblioteca: lista (?kind= ?brandId= ?productId=) e upload multipart (campo file).
GET/api/midia
token
Alias da biblioteca (mesmo conjunto de /api/assets).
GET|POST/api/social-accounts
token
Lista e cria contas sociais (status pending_configuration). Nunca devolve credentials.
PATCH|DELETE/api/social-accounts/:id
token
Atualiza handle/status ou remove uma conta social.
POST/api/social-accounts/:id/connect
token
Inicia OAuth Meta (Instagram/Facebook). Devolve { url }; nunca devolve tokens.
GET/api/social-accounts/oauth/callback
Callback do Facebook Login (state assinado; sem bearer).
GET|POST/api/social-accounts/:id/meta-pages
token
Lista Páginas/Instagram autorizados (sem tokens) e grava a Page escolhida.
GET|POST/api/social-accounts/meta-parceiro
token
Parceiro BM: ID público da nossa BM e gravação do token da Página.
POST/api/social-accounts/:id/credentials
token
Grava credentials Evolution (WhatsApp). Nunca ecoa secrets.
POST/api/social-accounts/:id/disconnect
token
Limpa credentials e marca a conta como disconnected.
GET|PATCH/api/config
token
Perfil da organização: nome comercial da empresa, fuso, negócio, tom.
POST/api/agente
token
Agente conversacional do workspace. Módulo Anthropic existe, não está em uso (sem chave = indisponível/mock). Foto de post usa OPENAI_API_KEY.
POST/api/public/cron/gerar
Worker: cria agendamentos a partir das campanhas e gera a peça na hora de publicar. Antecipação é a estrela no calendário. Schedule `*/5 * * * *` (EventBridge). Header Authorization: Bearer <PUBLIVA_CRON_SECRET>.
POST/api/public/cron/publish
Worker de publicação no dia. Schedule `*/5 * * * *` (EventBridge). Header Authorization: Bearer <PUBLIVA_CRON_SECRET>. WhatsApp via Evolution API quando configurada; sem rede, prepara o post e anota o impedimento sem derrubar o lote.
GET|POST/api/products
token
Lista e cria produtos da organização (?brandId= ?status= ?busca=).
GET|PATCH|DELETE/api/products/:id
token
Lê, atualiza e remove um produto.
GET|POST/api/modelos
token
Templates da organização: listar e criar (?busca=).
GET|PATCH|DELETE/api/modelos/:id
token
Lê, atualiza e remove um template da organização.
GET|PUT/api/campaigns/:id/products
token
Produtos vinculados à campanha. PUT substitui o conjunto.
POST/api/campaigns/:id/posts
token
Cria um post na campanha (content, template, format, caption, spec…).
GET|PATCH/api/posts/:id
token
Post com generations, DesignSpec e assets.
GET/api/tokens
token
Saldo de tokens, plano da organização e tabela de preços.
GET/api/tokens/extrato
token
Extrato paginado de token_transactions (?limite= ?antesDe=).
GET|POST/api/tokens/estimativa
token
Quanto custaria uma ação, sem gastar.
GET/api/calendario
token
Agenda agrupada por dia local (?de= ?ate= ?tz=).
PATCH/api/calendario/:id
token
Remarca um agendamento (runAt + timezone).
POST/api/calendario/:id/gerar
token
Gera o post agora (estrela no calendário).
GET/api/agenda
token
Publicações agendadas numa janela (?de= ?ate=).
POST/api/campaigns/agendar
token
Agenda os posts da campanha. Gerar antes da hora é a estrela no calendário.

Fluxo completo em uma chamada: POST /api/campaign com { "objective": "...", "postCount": 3 }.