Instale o FastRestful no seu computador

Uma primeira instalação completa para quem nunca executou uma aplicação Django ou Node. Siga as etapas em ordem. Cada etapa termina com uma verificação para você saber que funcionou antes de continuar.

Antes de começar

Você não precisa de Docker, Redis, armazenamento em nuvem nem de uma conta de pagamento para a demonstração local. SQLite e um cache em memória mantêm a primeira execução simples.

1. Verifique suas ferramentas

Execute estes comandos no terminal. Se algum estiver faltando, instale-o primeiro e reabra o terminal.

python3.11 --version
node --version
npm --version
git --version

Você deve ver Python 3.11, Node 22.13 ou mais recente e uma versão do npm. Se python3.11 não for encontrado, instale o Python 3.11 em python.org. Se o Node for anterior ao 22.13, instale a versão LTS atual em nodejs.org.

2. Baixe o código

git clone <your-fastrestful-repository> fastrestful
cd fastrestful
npm ci

npm ci instala as versões exatas das dependências do frontend a partir do arquivo de lock. Pode levar alguns minutos. Você deve terminar com uma pasta node_modules e nenhuma mensagem de erro.

3. Crie o ambiente do backend

Um ambiente virtual mantém os pacotes Python do FastRestful separados do restante do seu computador.

cd backend
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

No Windows PowerShell, ative com .venv\Scripts\Activate.ps1 em vez de source .venv/bin/activate. Quando o ambiente estiver ativo, seu prompt normalmente começa com (.venv).

4. Crie o arquivo de configuração do backend

Copie o arquivo de exemplo e depois gere dois segredos e cole-os em backend/.env.

cp .env.example .env
python3.11 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
python3.11 -c "import secrets; print(secrets.token_urlsafe(64))"

1. Abra backend/.env em qualquer editor de texto.
2. Cole a primeira saída em FIELD_ENCRYPTION_KEY=. Isso criptografa chaves de API e segredos de provedores.
3. Cole a segunda saída em DJANGO_SECRET_KEY=.
4. Deixe DJANGO_DEBUG=True, DATABASE_URL=sqlite:///db.sqlite3 e FRONTEND_URL=http://localhost:5055 para o desenvolvimento local.

5. Crie o banco de dados e os dados de demonstração

Certifique-se de que o ambiente virtual ainda está ativo e de que você está dentro de backend/.

python3.11 manage.py migrate
python3.11 manage.py seed_demo
python3.11 manage.py seed_apis
python3.11 manage.py seed_docs
python3.11 manage.py seed_engagement

migrate cria as tabelas do banco de dados. Os comandos de seed criam um marketplace de demonstração, produtos de API, conteúdo de documentação e perfis da comunidade. Isso cria um arquivo local backend/db.sqlite3.

6. Inicie o backend

# inside backend/, with the virtual environment active
python3.11 manage.py runserver 127.0.0.1:5056

Deixe este terminal aberto. O backend está pronto quando imprime Starting development server at http://127.0.0.1:5056/. Verifique em outro terminal com:

curl http://127.0.0.1:5056/api/health/live

7. Inicie o frontend

Abra o segundo terminal e volte para a raiz do repositório. O backend deve continuar em execução no terminal 1.

cd /path/to/fastrestful
npm run dev -- --port 5055 --host 127.0.0.1

O servidor de desenvolvimento do Vite faz proxy das rotas do Django (/api/v1, /api/health, /api/schema, /api/docs, /admin, /static, /media) para o backend na porta 5056. Páginas públicas de produtos, como /api/{slug}, continuam sendo servidas pelo frontend.

8. Abra o aplicativo e entre

Abra estes endereços no navegador:

Entre no plano de controle com admin / Admin12345!.

Lista de verificação da primeira execução

• O site público carrega e o catálogo do marketplace fica visível.
• O plano de controle abre e você consegue entrar como admin.
• Configurações do site, Planos da plataforma e a seção de conteúdo do site abrem sem erros.
• Uma conta de consumidor consegue criar um aplicativo e uma chave de API.
• Uma requisição pelo gateway aparece nos logs de requisição.

O que fazer agora

• Siga o Início rápido: sua primeira requisição pelo gateway para fazer uma chamada de API com medição.
• Leia Configuração para entender quais configurações importam primeiro.
• Conecte pagamentos com Gateways de pagamento, passo a passo quando estiver pronto para cobrar dinheiro real.
• Consulte Implantação antes de colocar o aplicativo em um servidor público.

Problemas comuns de instalação

Início rápido: sua primeira requisição pelo gateway

Passe de uma instalação local limpa a uma chamada de API com medição. Você assinará uma API de demonstração, criará uma chave, enviará uma requisição e verá o evento de uso e o log de requisição.

1. Entre e escolha um espaço de trabalho

Abra http://127.0.0.1:5055 e entre com admin / Admin12345!, ou registre uma nova conta. Um espaço de trabalho (organização) agrupa seus aplicativos, chaves, assinaturas e faturas.

O espaço de trabalho ativo é enviado no cabeçalho X-Organization nas chamadas de API. O console do navegador o define automaticamente. Quando você chama a API por conta própria, deve incluí-lo, a menos que a requisição use uma chave de API em vez de uma sessão de navegador.

2. Assine um produto

Abra o marketplace, escolha um produto com uma versão ativa e selecione um plano. O produto SignalStack incluído no seed tem uma versão 2.4.0 ativa e três planos.

Se o plano for gratuito, a ativação é imediata. Se o plano for pago, o FastRestful abre o provedor de pagamento configurado. Um redirecionamento do navegador nunca concede acesso por si só: a assinatura só é ativada depois que um webhook assinado do provedor liquida a primeira fatura.

3. Crie um aplicativo e uma chave

No console do consumidor, crie um aplicativo e depois emita uma chave de API. A chave bruta é exibida uma única vez, então copie-a imediatamente para um gerenciador de senhas ou para um arquivo .env local.

fr_live_<random-secret>

# Store it in a secret manager or local .env file.
# Never commit it to a repository or paste it into a public issue.

Os escopos são full, execute ou read. Escolha o escopo mais restrito que funcione. Se perder a chave, revogue-a e emita uma nova; a chave antiga deixa de funcionar imediatamente.

4. Envie uma requisição pelo gateway

Substitua fr_live_… pela chave que você acabou de criar. Este exemplo usa o produto SignalStack incluído no seed e seu alias de caminho.

curl --request GET \
  --url 'http://127.0.0.1:5055/api/v1/signal-stack/v2/deliveries?limit=10' \
  --header 'X-API-Key: fr_live_…' \
  --header 'Idempotency-Key: quickstart-001'

Com o roteamento por host do produto ativado, a mesma requisição usa https://{product-slug}.{FASTRESTFUL_API_HOST_SUFFIX}/.... Ambas as portas de entrada compartilham a mesma assinatura, cota, limite de taxa, idempotência, medição e pipeline de log de requisição.

5. Inspecione o resultado

• Evento de uso: registrado no servidor com status e latência.
• Contador mensal: incrementado para aplicação da cota e excedente.
• Log de requisição: prévias de requisição e resposta com dados sensíveis ocultados, visíveis ao consumidor e ao fornecedor.
• Painel: requisições, taxa de sucesso, gasto, latência, principais APIs e atividade recente.

Abra o painel do consumidor e o log de requisição. Você deve ver a requisição que acabou de fazer. Se não vir, verifique no terminal que executa o backend se há um traceback.

6. Publique uma versão (opcional)

No estúdio de fornecedor, abra a bancada de um produto, importe um contrato OpenAPI para uma versão de rascunho, reconcilie a documentação dos endpoints, execute o diff, envie para revisão e promova. Uma versão ativa exige um contrato OpenAPI não vazio e compatível, além de um catálogo de endpoints que corresponda exatamente.

Para o ciclo de vida completo, leia Produtos de API e versões.

Se a requisição falhar

Configuração sem sobrecarga

A maioria das instalações precisa apenas de um pequeno conjunto de configurações para funcionar. Comece pelo mínimo abaixo e depois adicione as integrações que você realmente usa. As tabelas longas mais adiante são referência, não uma lista de verificação.

Onde ficam as configurações

Configurações locais mínimas

Depois de copiar .env.example, estes são os únicos valores que você precisa alterar para a demonstração local:

DJANGO_DEBUG=True
DJANGO_SECRET_KEY=<generated-random-value>
FIELD_ENCRYPTION_KEY=<generated-fernet-key>
DATABASE_URL=sqlite:///db.sqlite3
FRONTEND_URL=http://localhost:5055
CORS_ALLOWED_ORIGINS=http://localhost:5055,http://127.0.0.1:5055
CSRF_TRUSTED_ORIGINS=http://localhost:5055,http://127.0.0.1:5055

Gere as duas chaves com os comandos em Instalação → Criar o arquivo de configuração do backend.

Configurações mínimas de produção

Produção adiciona PostgreSQL, Redis, um hostname real e origens HTTPS. Substitua cada placeholder pelos seus próprios valores.

DJANGO_DEBUG=False
DJANGO_SECRET_KEY=<50-plus-random-characters>
DJANGO_ALLOWED_HOSTS=api.example.com,www.example.com
DATABASE_URL=postgresql://user:password@db-host:5432/fastrestful
REDIS_URL=redis://redis-host:6379/0
FRONTEND_URL=https://www.example.com
CORS_ALLOWED_ORIGINS=https://www.example.com
CSRF_TRUSTED_ORIGINS=https://www.example.com
FIELD_ENCRYPTION_KEY=<fernet-key>

Como alterar configurações com segurança

1. Altere uma integração por vez.

   Configure, teste e verifique antes de passar para o próximo provedor. Isso torna as falhas óbvias.

2. Edite backend/.env no servidor.

   Não edite arquivos dentro de um contêiner em execução que será substituído. Mantenha os segredos no armazenamento de segredos da sua plataforma de implantação sempre que possível.

3. Reinicie o backend e os workers.

   As alterações de ambiente são lidas na inicialização do processo. Reinicie o Gunicorn, o worker do Celery e o beat do Celery após editar .env.

4. Recompile o frontend para alterações de NEXT_PUBLIC_*.

   Valores públicos do frontend são compilados no build. Reiniciar o frontend não é suficiente.

5. Execute a ação de teste do provedor.

   Use o checkout de teste, o e-mail de teste ou o log de entregas de webhook antes de enviar tráfego real.

Referência principal de ambiente

Ambiente do frontend

Gateway e roteamento por host

Autenticação e SSO

E-mail e newsletter

As configurações SMTP da newsletter também podem ser armazenadas no estúdio de newsletter e substituem o remetente do ambiente para campanhas. Consulte Estúdio de newsletter.

Referência de pagamentos e repasses

Admin → Gateways de pagamento armazena as mesmas credenciais no banco de dados. Um registro no banco substitui os campos de ambiente um a um, e desativá-lo desliga o provedor em todos os lugares mesmo que as chaves de ambiente continuem definidas.

Armazenamento de mídia e especificações

Links curtos

SHORTLINK_BASE_URL define a origem pública dos links curtos, por exemplo https://go.example.com. Quando vazio, recorre a NEWSLETTER_TRACKING_BASE_URL e depois a FRONTEND_URL. O comando checklinks pode ser agendado via cron ou Celery beat.

Precedência e recarregamentos

• Valores de ambiente fornecem padrões de implantação; registros de gateway no admin substituem campo a campo.
• Alterações no ambiente do backend exigem reinicialização do processo. Algumas configurações em cache (sinalizador de manutenção, localidade de origem) são limpas automaticamente ao salvar o modelo.
• Variáveis públicas do frontend são incorporadas no momento do build. Recompile após alterar valores de NEXT_PUBLIC_*.
• Após alterar lib/i18n/*.json, execute npm run export:i18n e reinicie o backend para que o pacote de origem em cache fique atualizado.

Implantação

Leve o FastRestful de uma demonstração local com SQLite para uma implantação em produção com PostgreSQL, Redis, armazenamento de objetos, um servidor WSGI, TLS e um frontend estático. A plataforma foi projetada para ser auto-hospedada.

Antes de implantar

• Um nome de domínio e acesso ao DNS para os hosts do frontend e da API.
• Um banco de dados PostgreSQL 16 e uma instância Redis 7.
• Terminação HTTPS, seja no seu proxy ou na borda.
• Um DJANGO_SECRET_KEY gerado e um FIELD_ENCRYPTION_KEY com backup.
• Um plano para armazenamento de mídia: disco local é aceitável apenas para um teste em servidor único; use armazenamento compatível com S3 em implantações reais.
• Um destino de backup fora do servidor da aplicação.

Ordem recomendada

1. Implante o backend e o banco de dados.

   Faça /api/health/ready passar antes de mexer no frontend.

2. Implante o frontend.

   Aponte-o para a origem da API e adicione a origem do frontend às configurações de CORS e CSRF.

3. Configure e-mail e armazenamento.

   Use Integrações externas. Verifique um e-mail de teste e um upload de teste.

4. Conecte pagamentos somente quando estiver pronto para vender.

   Use Gateways de pagamento, passo a passo e conclua primeiro o checkout de teste.

5. Ative a licença e agende os heartbeats.

   Use Licenciamento e atualizações oficiais.

6. Configure backups e monitoramento.

   Use Backups e atualizações e Observabilidade.

Topologia recomendada

Internet
  │
  ├── app.example.com ──► frontend (static/CDN or Node runtime)
  │                           │
  │                           └── /api/* ──► reverse proxy ──► Gunicorn / Django
  │
  ├── api.example.com ──► reverse proxy ──► Gunicorn / Django
  ├── *.api.example.com ──► wildcard product gateway
  │
  ├── PostgreSQL 16 (primary)
  ├── Redis 7 (cache + Celery broker)
  ├── S3 + CloudFront (media, optional specs)
  └── Celery worker + beat (billing, moderation, email, availability)

Você pode servir o frontend e a API na mesma origem ou separá-los. Se separar, defina NEXT_PUBLIC_API_URL como a origem da API, adicione a origem do frontend a CORS_ALLOWED_ORIGINS e CSRF_TRUSTED_ORIGINS, e defina FRONTEND_URL como a origem pública do frontend.

Docker Compose

O repositório inclui um arquivo Compose com PostgreSQL, a API, o Redis e perfis opcionais de worker/beat.

export DJANGO_SECRET_KEY="$(openssl rand -base64 64 | tr -d '\n')"
export FIELD_ENCRYPTION_KEY="$(python3.11 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
export DJANGO_ALLOWED_HOSTS="api.example.com,.api.example.com"
export CORS_ALLOWED_ORIGINS="https://app.example.com"
export CSRF_TRUSTED_ORIGINS="https://app.example.com"
export FRONTEND_URL="https://app.example.com"
export POSTGRES_PASSWORD="$(openssl rand -hex 24)"

docker compose up --build -d
docker compose --profile scheduler up --build -d

Execute migrações e seeds dentro do contêiner da API depois que o banco de dados estiver saudável:

docker compose exec api python manage.py migrate --noinput
docker compose exec api python manage.py seed_demo
docker compose exec api python manage.py seed_apis
docker compose exec api python manage.py seed_docs
docker compose exec api python manage.py collectstatic --noinput

Configuração manual de produção

Backend

cd /srv/fastrestful/backend
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gunicorn>=22.0 boto3 django-storages  # optional: S3 media

cp .env.example .env
# Fill production values, then:
python3.11 manage.py migrate --noinput
python3.11 manage.py collectstatic --noinput
python3.11 manage.py check --deploy

Gunicorn + systemd

[Unit]
Description=FastRestful Django API
After=network.target postgresql.service redis.service

[Service]
User=fastrestful
Group=fastrestful
WorkingDirectory=/srv/fastrestful/backend
EnvironmentFile=/srv/fastrestful/backend/.env
ExecStart=/srv/fastrestful/backend/.venv/bin/gunicorn \
  config.wsgi:application \
  --bind 127.0.0.1:8000 \
  --workers 3 \
  --timeout 60
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now fastrestful
sudo systemctl status fastrestful

Proxy reverso Nginx

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    client_max_body_size 8m;

    location /static/ {
        alias /srv/fastrestful/backend/staticfiles/;
        expires 30d;
        access_log off;
    }

    location /media/ {
        alias /srv/fastrestful/backend/media/;
        expires 7d;
        access_log off;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 65s;
    }
}

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

Host de produto com curinga

server {
    listen 443 ssl http2;
    server_name *.api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;  # product slug comes from this host
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Adicione um registro DNS curinga, emita um certificado curinga com um desafio DNS-01 e inclua o host curinga em DJANGO_ALLOWED_HOSTS. Defina FASTRESTFUL_API_HOST_SUFFIX=api.example.com.

Build e hospedagem do frontend

export NEXT_PUBLIC_API_URL="https://api.example.com"
export NEXT_PUBLIC_SITE_URL="https://app.example.com"
export NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_..."
npm run build

Implante a saída do build no seu host estático ou runtime compatível com Node. O build é autossuficiente e não requer um plano de controle de site gerenciado. Se usar Cloudflare, vincule D1/Images somente quando a implantação precisar desses recursos.

Arquivos estáticos e de mídia

• Estáticos: execute collectstatic, sirva /static/ pelo Nginx ou pela sua CDN.
• Mídia local: sirva /media/ pelo Nginx em implantações pequenas.
• Mídia em produção: use S3 + CloudFront com OAC, mantenha o bucket privado, defina MEDIA_STORAGE=s3 e não defina MEDIA_S3_ACL, a menos que sirva diretamente do S3.
• Especificações: deixe SPEC_STORAGE=db para uma instalação pequena; use S3 para arquivos de contrato maiores.

Verificações de integridade

Atualizações e backups

# 1. Back up PostgreSQL and media
pg_dump --format=custom "$DATABASE_URL" > fastrestful-$(date +%F).dump

# 2. Pull code and install dependencies
git pull --ff-only
pip install -r backend/requirements.txt
npm ci

# 3. Apply migrations and rebuild assets
python3.11 backend/manage.py migrate
npm run build

# 4. Restart API and workers
sudo systemctl restart fastrestful
sudo systemctl restart fastrestful-worker fastrestful-beat

# 5. Verify
curl -f https://api.example.com/api/health/ready

Critérios de produção

• DJANGO_DEBUG=False, segredo de 50+ caracteres, chave Fernet válida.
• PostgreSQL, Redis, origens HTTPS e hosts permitidos explícitos.
• Credenciais de administrador alteradas; usuários de demonstração removidos ou desativados.
• Webhooks de pagamento e repasse registrados com o segredo assinado correto.
• Credenciais de SMTP e provedores testadas; domínio do remetente autenticado.
• S3/CloudFront configurados se uploads de mídia estiverem ativados.
• Worker do agendador + beat em execução ou equivalentes em cron instalados.
• Backups testados por restauração em um ambiente separado.
• O monitoramento cobre prontidão, taxa de 5xx, latência do gateway, falhas de webhook e profundidade da fila.
• Páginas legais, termos, privacidade e contato de suporte revisados pelo operador.

Operações

Liquidação agendada, entrega de notificações, verificações de disponibilidade, retenção de telemetria, sondas de integridade e os comandos operacionais que mantêm o FastRestful saudável.

Agenda do Celery

celery -A config worker -l info -Q billing,celery
celery -A config beat -l info

Sem um broker, o Celery executa em modo eager no processo. Em produção, defina REDIS_URL ou CELERY_BROKER_URL e execute worker e beat como serviços separados.

Comandos operacionais

python3.11 manage.py generate_invoices --period 2026-10
python3.11 manage.py generate_payouts --period 2026-10
python3.11 manage.py prune_telemetry --request-log-days 90 --usage-event-days 365
python3.11 manage.py check_api_availability
python3.11 manage.py checklinks --limit 200 --timeout 6

Modo de manutenção

Ative Operações da plataforma → Modo de manutenção em Configurações do site. O frontend retorna uma página 503 com a marca, as chamadas de API e de gateway dos clientes retornam uma resposta maintenance_mode legível por máquina com Retry-After: 300, e documentação/Swagger ficam pausados.

O admin da equipe, as sondas de integridade, os callbacks do provedor de identidade e os webhooks assinados de pagamento/repasse permanecem disponíveis para que a plataforma possa se recuperar com segurança e os provedores não sejam descartados.

Monitoramento

• Sonda de prontidão para banco de dados + cache compartilhado.
• Taxa de 5xx da API e latência p95 por namespace.
• Taxa de erros de upstream do gateway e eventos de circuito aberto.
• Fila de falhas de webhook e exceções de repasse.
• Profundidade da fila do Celery e heartbeat do beat.
• Taxas de devolução/reclamação de e-mail e taxa de cancelamento de inscrição.
• Crescimento do armazenamento de mídia e taxa de acerto do cache da CDN.
• Conexões PostgreSQL, consultas lentas, disco e sucesso dos backups.

Backups

Notas de escalonamento

• Execute várias instâncias Gunicorn/Django atrás de um balanceador de carga; mantenha sessões e cache no Redis.
• Execute workers do Celery separadamente dos processos web e escale as filas de cobrança e padrão de forma independente.
• Os limites de taxa do gateway usam o cache compartilhado; uma indisponibilidade do cache retorna um 503 que permite nova tentativa em vez de falhar aberto.
• Use pool de conexões PostgreSQL se o número de workers crescer.
• Mova a mídia para S3/CloudFront antes que o tráfego torne o ciclo de vida do disco local doloroso.
• Mantenha a retenção de telemetria explícita; logs de requisição e eventos de uso não foram feitos para crescer para sempre.

Segurança

Comportamento crítico de segurança no FastRestful: custódia de chaves, isolamento de inquilinos, proteção SSRF do gateway, política de origem do navegador, armazenamento de segredos, evidências de auditoria e a lista de verificação de endurecimento para produção.

Custódia de chaves de API

• Chaves brutas são retornadas exatamente uma vez na criação ou rotação. Nunca são renderizadas novamente por serializadores ou pelo admin.
• Formas de armazenamento: um prefixo de busca, um hash SHA-256 para comparação em tempo constante e uma cópia criptografada com Fernet para uso do gateway no servidor.
• A rotação revoga a chave antiga e emite uma nova em uma única chamada. Uma chave revogada não pode ser usada para emitir substitutas.
• Os escopos restringem o acesso: full, execute ou read. Atualizações só podem restringir um escopo, nunca ampliá-lo.
• Uma chave é vinculada ao seu aplicativo e assinatura; ela não pode atravessar aplicativos ou espaços de trabalho.

Isolamento de inquilinos

• X-Organization seleciona o inquilino ativo. As permissões no servidor verificam novamente a associação para cada objeto.
• As leituras de fornecedores têm escopo duplo: um fornecedor vê seus próprios produtos, assinaturas, faturas e logs; um consumidor vê apenas seu próprio espaço de trabalho.
• Campos de propriedade são imutáveis pela API.
• Serializadores públicos são explícitos, não listas de permissão de um modelo privado. Métricas operacionais e campos privados ficam fora das respostas anônimas.
• Superusuários podem ler entre inquilinos para suporte, mas gravações ainda exigem o escopo proprietário correto, exceto em operações explícitas da plataforma.

Segurança do gateway

• Os upstreams devem usar HTTPS, resolver para endereços públicos, permanecer no host original e evitar padrões de travessia.
• Redirecionamentos não são seguidos. As respostas DNS são verificadas e o IP público selecionado é fixado pela conexão TLS para evitar rebinding.
• Tempos limite, limites de corpo, limites de upload e tentativas limitadas são aplicados antes do encaminhamento.
• Segredos de fornecedores são anexados apenas no servidor; eles nunca chegam ao navegador.
• Chaves de idempotência são armazenadas como hashes de token com uma impressão digital da requisição e uma resposta com dados sensíveis ocultados, nunca corpos de requisição brutos.
• As prévias de resposta têm tamanho limitado e ocultam Set-Cookie, Authorization e X-API-Key.
• Uma indisponibilidade do cache compartilhado retorna um 503 que permite nova tentativa antes da reserva de cota; o gateway não falha aberto.

Segurança do navegador e de origem

• Produção aplica HTTPS, HSTS, cookies seguros e uma política de referenciador estrita.
• CORS_ALLOWED_ORIGINS e CSRF_TRUSTED_ORIGINS devem nomear exatamente o frontend público.
• Cookies CSRF são legíveis pelo frontend porque a sessão compartilhada do Django é usada para gravações no admin e no console; nunca os exponha entre origens.
• Ativos CSS/JS personalizados são conteúdo confiável do operador. Use um nonce CSP, pré-visualize antes da ativação e revise o histórico de revisões.
• O modo de manutenção mantém callbacks de provedores e rotas do provedor de identidade disponíveis.

Gerenciamento de segredos

Endurecimento da autenticação

• Ative a autenticação de dois fatores obrigatória para a equipe e, opcionalmente, para todas as contas em Configurações do site.
• Use OIDC ou SAML para identidade corporativa; o login por senha pode permanecer como fallback.
• Mantenha tokens de acesso de curta duração (15 minutos) e tokens de atualização rotativos na lista de bloqueio após a rotação.
• Convites são armazenados como hash, de uso único, vinculados ao e-mail e expiram após sete dias.
• O acesso ao admin exige is_staff; o espaço de trabalho admin não é uma função de equipe da plataforma.
• Respostas de redefinição de senha não revelam se uma conta existe.

Auditoria e evidências

• Ações de admin, decisões de moderação, alterações de estado de cobrança, reconciliação de repasses, alterações de configurações e recuperação de contas geram eventos de auditoria.
• Os recibos de eventos do provedor são somente de acréscimo e rejeitam conflitos de payload, o que torna as novas tentativas seguras.
• Os lançamentos do razão são somente de acréscimo. Reembolsos após o repasse criam lançamentos de clawback e de reversão de tarifas.
• Tarefas de exportação de auditoria oferecem retenção e revisão sem acesso direto ao banco de dados.

Checklist de produção

DJANGO_DEBUG=0 \
DATABASE_URL=postgresql://… \
REDIS_URL=redis://… \
FRONTEND_URL=https://app.example.com \
DJANGO_ALLOWED_HOSTS=api.example.com,.api.example.com \
CORS_ALLOWED_ORIGINS=https://app.example.com \
CSRF_TRUSTED_ORIGINS=https://app.example.com \
DJANGO_SECRET_KEY=<50+ chars> \
FIELD_ENCRYPTION_KEY=<fernet key> \
python3.11 manage.py check --deploy

• Contas de demonstração e dados de seed removidos da produção.
• Dois fatores obrigatórios para a equipe; SSO testado de ponta a ponta.
• Webhooks de pagamento verificados com o segredo assinado do provedor.
• Bucket de mídia privado; CDN OAC configurado; sem acesso de gravação com curinga.
• Backups criptografados e com restauração testada.
• Os logs excluem segredos e ocultam dados de payload dos consumidores.
• Imagens de dependências e contêineres corrigidas em uma agenda.
• Contato de incidentes e canal de divulgação de vulnerabilidades publicados.

Licenciamento & atualizações oficiais

O FastRestful é código-fonte licenciado vendido pela Dakidarts. Conecte a chave de compra ao LicenseHub para verificar versões oficiais assinadas, instalar uma versão mais recente ou reverter para uma anterior. O gateway em execução continua funcionando se o LicenseHub estiver temporariamente indisponível.

O que a central de atualizações faz

Parte 1 — Ative sua licença

1. Compre o FastRestful e abra o painel da Dakidarts.

   Acesse Painel → Licenças e copie a chave completa. Ela começa com DK-FRST-….

2. Abra a central de atualizações.

   Entre como equipe e abra https://your-domain/admin/updates/. A barra lateral chama isso de Atualizações de software.

3. Cole a chave de licença.

   Use a chave completa, incluindo todos os hífens. Ela é criptografada em repouso e apenas uma forma mascarada é exibida após a ativação.

4. Confirme a URL do LicenseHub.

   O padrão é https://dakidarts.com. Mantenha-o a menos que a Dakidarts forneça uma origem diferente. HTTPS é obrigatório fora da depuração local.

5. Escolha o ambiente.

   Produção consome um assento de produção. Staging e Desenvolvimento consomem assentos fora de produção. Escolha o que corresponde a esta instalação.

6. Opcionalmente, adicione o domínio de produção.

   Por exemplo, api.example.com. Isso ajuda a identificar a instalação no portal do cliente.

7. Escolha um canal de versão.

   Comece com Stable. Use Beta ou Preview apenas em um ambiente de teste descartável.

8. Clique em Ativar licença.

   A ativação cria ou reutiliza um installation_id persistente e vincula um assento. A página então mostra a edição, as janelas de atualização e suporte, a contagem de ativações e o último heartbeat.

Se a ativação falhar, o erro será exibido na página. As causas mais comuns são chave expirada, limite de assentos ou chave copiada com um espaço no final.

Parte 2 — Instale uma atualização pelo admin

1. Faça um backup.

   Faça backup do PostgreSQL, da mídia, do .env e de quaisquer arquivos personalizados. Confirme a restauração do backup antes de precisar dele.

2. Abra Admin → Atualizações de software.

   A página mostra a versão em execução, a versão instalada e o status da conexão.

3. Clique em Verificar atualizações.

   O LicenseHub retorna todas as versões cobertas pela sua janela de atualização: mais recentes, atual e anteriores.

4. Clique em Baixar & preparar na versão desejada.

   O FastRestful baixa cada artefato, verifica o SHA-256, verifica a assinatura do manifesto Ed25519 e extrai o pacote em FASTRESTFUL_UPDATE_DIR/<version>/bundle/.

5. Clique em Instalar.

   O admin inicia um worker independente para que migrações ou um build não excedam o tempo limite da requisição web. A página é atualizada durante a execução.

6. Aguarde “instalado” e o banner de reinicialização.

   O processo em execução ainda usa o código antigo até você reiniciar. A página mostra Instalado … · reinicialização necessária.

7. Reinicie os serviços.

   Reinicie o Gunicorn ou seu servidor de aplicações, o worker e o beat do Celery, e o processo de frontend se ele rodar no mesmo host. Use seu gerenciador de serviços, não a página do admin. Exemplos de comandos systemd:

   exemplo systemdCopiar

   sudo systemctl restart fastrestful
   sudo systemctl restart fastrestful-worker fastrestful-beat
   # restart your frontend process too if it runs on this host

8. Verifique.

   Confirme a versão na central de atualizações, abra /api/health/ready e faça uma requisição de teste pelo gateway.

Parte 3 — Atualize pela linha de comando

Use isso quando o admin estiver indisponível ou quando você quiser a instalação em uma sessão de terminal.

cd /srv/fastrestful/backend
source .venv/bin/activate

python3.11 manage.py fastrestful_update status
python3.11 manage.py fastrestful_update check
python3.11 manage.py fastrestful_update download --release-version 1.2.0
python3.11 manage.py fastrestful_update install --release-version 1.2.0

A instalação pela CLI é síncrona e imprime o log do instalador capturado. A instalação pelo admin é assíncrona. Ambas verificam os mesmos artefatos assinados antes de executar o instalador.

Mantenha a concessão da licença em dia

A concessão do certificado é de 24 horas. Um heartbeat a cada seis horas deixa margem para indisponibilidades transitórias. Uma verificação diária basta para descobrir novas versões.

17 */6 * * * cd /srv/fastrestful/backend && /srv/fastrestful/.venv/bin/python manage.py license_heartbeat --check-updates >> /var/log/fastrestful-license.log 2>&1

Um heartbeat com falha registra o erro no admin, mas não interrompe o gateway.

Parte 4 — Reverta para uma versão anterior

1. Abra a lista de versões.

   Versões anteriores cobertas pela sua janela de atualização aparecem ao lado da versão atual.

2. Clique em Instalar versão anterior na versão desejada.

   A central de atualizações marca a instalação com essa versão. Esta é uma instalação normal de versão, não um reset destrutivo.

3. Reinicie os serviços.

   O processo reiniciado passa a usar a árvore de código-fonte anterior.

4. Verifique o banco de dados.

   Se a versão mais recente aplicou uma migração irreversível, restaure o backup do banco de dados anterior à atualização. Mantenha o backup do banco e o backup do código juntos.

Parte 5 — Canais e ambientes

O canal fica armazenado na conexão e é enviado em cada verificação. Altere-o na página de atualizações ou durante a ativação.

Parte 6 — Docker e implantações baseadas em imagem

O instalador padrão atualiza um checkout de código-fonte. Em um contêiner, as alterações no sistema de arquivos não são duráveis quando o contêiner é recriado. Escolha uma destas opções:

• Crie e implante uma nova imagem a partir da versão baixada no seu pipeline normal.
• Defina um FASTRESTFUL_UPDATE_INSTALL_SCRIPT personalizado que baixe a nova imagem ou dispare a implantação da sua plataforma.
• Use fastrestful_update download para buscar e verificar a versão e, em seguida, aplique-a fora do contêiner em execução.

Parte 7 — Configuração

Parte 8 — Solução de problemas

Parte 9 — Notas de segurança

• Apenas membros da equipe com licensing.change_licenseconnection podem abrir a central de atualizações.
• A proteção CSRF é aplicada em todas as ações.
• A chave de compra é criptografada em repouso e nunca é exibida após a ativação.
• Os downloads usam tokens de curta duração do LicenseHub. Os artefatos são verificados por SHA-256 e pela assinatura do manifesto Ed25519 antes da extração ou execução.
• A extração de arquivos rejeita caminhos absolutos, travessia, links simbólicos e hardlinks.
• Mantenha o diretório de atualizações privado. Não o sirva pelo Nginx nem pelo armazenamento de objetos.
• Uma indisponibilidade do LicenseHub ou uma janela de atualização expirada não deixam um gateway em execução offline. A revogação bloqueia downloads oficiais; ela não interrompe remotamente uma instalação perpétua existente.

Para mantenedores de versões

As versões oficiais são artefatos privados do LicenseHub. Um pacote pode conter um arquivo compactado de código-fonte ou vários artefatos (código-fonte, migrações, frontend, documentação). Todos os artefatos são extraídos no mesmo diretório bundle/ na ordem retornada pelo LicenseHub.

O pacote deve incluir um instalador em um destes caminhos:

• install.sh
• scripts/install.sh
• scripts/install-release.sh
• o caminho em FASTRESTFUL_UPDATE_INSTALL_SCRIPT

scripts/install-release.sh neste repositório é a implementação de referência. Copie-o para a raiz do pacote de versão como install.sh. Ele cria snapshots do código-fonte e do banco de dados anteriores, sobrepõe o novo código-fonte, preserva arquivos locais de segredos/mídia/banco de dados, instala dependências do backend, executa migrações do Django e imprime o requisito de reinicialização.

O instalador recebe FASTRESTFUL_RELEASE_DIR, FASTRESTFUL_BUNDLE_DIR, FASTRESTFUL_UPDATE_DIR, FASTRESTFUL_APP_ROOT, FASTRESTFUL_FROM_VERSION, FASTRESTFUL_TO_VERSION, FASTRESTFUL_PYTHON e FASTRESTFUL_INSTALL_LOG. Ele é executado com bash, um tempo limite e um log capturado. Deve ser não interativo e deixar a instalação recuperável em caso de falha.

Solução de problemas

As falhas que as equipes encontram com mais frequência — e as verificações que as resolvem.

A API retorna 401 ou 403

• 401: token bearer ausente/expirado, X-API-Key ausente ou uma chave que não resolve. Atualize o JWT ou emita uma nova chave.
• 403: autenticado, mas sem permissão. Verifique a participação no espaço de trabalho, a função, o status da assinatura e o direito ao endpoint.
• Chamadas externas ao gateway devem usar X-API-Key (ou uma chave bearer fr_live_…), não um JWT do painel.
• Chamadas do painel precisam de Authorization: Bearer <access> e X-Organization: <uuid>.

Requisições do navegador falham com CORS ou CSRF

• Adicione a origem exata do frontend a CORS_ALLOWED_ORIGINS e CSRF_TRUSTED_ORIGINS.
• Use o mesmo esquema, host e porta que o navegador usa. localhost e 127.0.0.1 são origens diferentes.
• Recrie o frontend após alterar NEXT_PUBLIC_API_URL ou NEXT_PUBLIC_SITE_URL.
• Para chamadas ao gateway a partir de origens arbitrárias de consumidores, configure regexes de CORS ou CORS permissivo apenas no host da API do produto.

A requisição ao gateway falha

As migrações falham ou o esquema está desatualizado

python3.11 manage.py showmigrations
python3.11 manage.py makemigrations --check --dry-run
python3.11 manage.py migrate --noinput
python3.11 manage.py check

Se uma migração conflitar com um branch personalizado, resolva em uma cópia do banco de dados e nunca edite uma migração já aplicada em produção.

A mídia retorna 404 ou um recurso de CDN desatualizado

• Modo local: confirme que MEDIA_ROOT permite gravação e que o Nginx serve /media/.
• Modo S3: verifique permissões do bucket, região, endpoint e origem da CDN. Mantenha o bucket privado ao usar OAC.
• Após substituir um recurso, purgue a distribuição da CDN ou use a ação de purga no admin.
• Confirme que MEDIA_CDN_DOMAIN não tem caminho final e corresponde ao certificado.

Os webhooks de pagamento estão falhando

Comece pela configuração específica do provedor em Gateways de pagamento, passo a passo. Depois, verifique estes itens na ordem:

1. A URL é exata e pública. Registre /api/v1/billing/stripe-webhook/, /paypal-webhook/, /flutterwave-webhook/, /paystack-webhook/ ou /razorpay-webhook/ no mesmo hostname que os usuários acessam. Localhost não funcionará.
2. Valores de teste e produção não estão misturados. Uma chave de teste com um ID de webhook de produção (ou o contrário) falha em todas as entregas.
3. O segredo é do tipo correto. O Stripe precisa do segredo de assinatura do endpoint (whsec_…), não da chave secreta da API. O Flutterwave precisa do hash secreto que você criou. O Razorpay precisa do segredo de assinatura do webhook.
4. O PayPal usa um ID de webhook, não um segredo. Coloque em PAYPAL_WEBHOOK_ID o ID do mesmo app e ambiente do PayPal. O FastRestful verifica cada evento com a API de verificação de assinatura do PayPal. Um ID ausente ou incorreto retorna Bad signature. Consulte Solução de problemas de webhook do PayPal.
5. O Paystack geralmente não precisa de segredo de webhook. Deixe PAYSTACK_WEBHOOK_SECRET em branco; o FastRestful verifica com PAYSTACK_SECRET_KEY.
6. Os tipos de evento estão selecionados. Um webhook que é acessível, mas não está inscrito no evento de liquidação, deixa a fatura em aberto.
7. Seu proxy preserva os cabeçalhos do provedor. Nginx, Cloudflare e balanceadores de carga devem encaminhar os cabeçalhos de assinatura sem alterações.
8. O valor e a moeda correspondem. O FastRestful rejeita uma liquidação que não corresponde à fatura.
9. Verifique o recibo. Abra Admin → Eventos de pagamento; IDs de evento duplicados são reconhecidos sem liquidação dupla. Reenvie o evento com falha pelo painel do provedor.

O e-mail não está sendo enviado

• O desenvolvimento usa o backend de e-mail de console. Verifique a saída do terminal.
• A produção usa SMTP por padrão. Teste host, porta, TLS, usuário e senha.
• As configurações de newsletter podem substituir o remetente do ambiente; confirme o provedor ativo no estúdio.
• Verifique SPF, DKIM e DMARC antes de culpar a fila. Taxas de rejeição e reclamação suprimem envios futuros.

Problemas de build ou rotas do frontend

• Execute npm run typecheck e npm test antes de depurar a implantação.
• Uma página em branco alimentada pela API geralmente significa que a origem da API está inacessível ou o CORS está incompleto.
• Se as páginas públicas de produto funcionam, mas /api/{slug} retorna 404, confirme que o proxy encaminha apenas namespaces do Django e não a rota de produto pertencente ao frontend.
• Após alterações de i18n, execute npm run export:i18n e reinicie o Django.

As edições de localidade não aparecem

• O francês incluído carrega do bundle do frontend; as sobreposições do admin vêm da API de localidade ativa.
• Salve a sobreposição do admin, confirme que a localidade está ativa e faça uma atualização forçada no navegador.
• Após alterar fr.json, exporte o código-fonte do backend e reinicie a API para limpar o cache do processo.
• Verifique se há uma preferência de localidade obsoleta no localStorage.

Autenticação & acesso

O FastRestful usa tokens de acesso JWT de curta duração, refresh tokens rotativos e uma sessão de navegador compartilhada do Django. O mesmo login pode abrir o console do consumidor, o estúdio do fornecedor e o admin da equipe.

Fluxos de autenticação

Cabeçalhos da requisição

Authorization: Bearer <access-token>
X-Organization: <organization-uuid>
Content-Type: application/json

X-API-Key: fr_live_…
# backwards-compatible alternative:
Authorization: Bearer fr_live_…

O painel usa JWT mais o cabeçalho explícito do espaço de trabalho ativo. Consumidores externos usam uma chave de API de produto com assinatura. Um JWT do painel não deve ser usado como chave de API do cliente, e uma chave de API bruta não deve ser enviada aos endpoints do painel.

Funções no espaço de trabalho

O acesso da equipe da plataforma é separado: exige is_staff e nunca decorre de uma função admin no espaço de trabalho. As permissões da equipe são aplicadas por modelo Django e ação administrativa.

Autenticação de dois fatores

• Inscrição de autenticador TOTP com QR/URI de provisionamento e códigos de recuperação de uso único.
• Os códigos de recuperação são exibidos uma vez, armazenados com hash e regenerados em conjunto.
• Um superusuário pode exigir dois fatores para todas as contas em Configurações do site.
• O acesso ao admin pode ser bloqueado até a confirmação da inscrição; o console mostra uma tela dedicada de configuração.

Convites para o espaço de trabalho

Proprietários e administradores convidam por e-mail e atribuem uma função. Os tokens de convite são armazenados com hash, de uso único, vinculados ao e-mail, expiram após sete dias e podem ser reenviados ou revogados. Aceitar um convite exige um usuário autenticado com o e-mail correspondente e pode reativar uma participação inativa.

GET  /api/v1/organization-invites/
POST /api/v1/organization-invites/          {"email": "...", "role": "developer"}
POST /api/v1/organization-invites/{id}/resend/
POST /api/v1/organization-invites/{id}/revoke/
POST /api/v1/auth/invites/accept/           {"token": "..."}

Configuração de SSO

OIDC

SSO_ISSUER=https://login.example.com/realms/acme
SSO_CLIENT_ID=fastrestful
SSO_CLIENT_SECRET=...
FRONTEND_URL=https://app.example.com

Registre a URL de callback https://api.example.com/api/v1/auth/sso/callback/ no provedor de identidade. Destinos relativos seguros e tokens de convite sobrevivem ao ciclo completo.

SAML 2.0

SSO_SAML_ENABLED=1
SSO_SAML_ENTITY_ID=fastrestful
SSO_SAML_SSO_URL=https://idp.example.com/sso
SSO_SAML_IDP_CERT="-----BEGIN CERTIFICATE-----..."
SSO_SAML_AUDIENCE=fastrestful

Instale lxml antes de habilitar o SAML. Os metadados são servidos em /api/v1/auth/saml/metadata/; configure o IdP com a URL do serviço de consumo de asserção desde o endpoint de início.

Ciclo de vida da chave de API

• Crie uma chave na aplicação selecionada; a chave completa aparece uma vez.
• Envie-a como X-API-Key ou uma credencial bearer fr_live_….
• Faça a rotação para revogar a chave antiga e emitir uma nova de forma atômica.
• Revogue imediatamente quando uma credencial for perdida; não há recuperação do valor completo.
• Use o escopo execute ou read para privilégio mínimo quando o cliente não precisar de gerenciamento completo.

Produtos de API & versões

Um produto é a identidade pública. Uma versão é o contrato imutável. Endpoints, documentação, política do gateway e direitos do plano acompanham essa fronteira de versão.

O modelo de produto

Crie e publique um produto

1. No estúdio do fornecedor, crie o produto com nome, slug, categoria, tagline, README e URL do upstream.
2. Crie uma versão em rascunho e importe um contrato OpenAPI 3.x ou Swagger 2.0.
3. Revise o catálogo de endpoints reconciliado e a documentação dos endpoints.
4. Crie pelo menos um plano público e configure cotas, limites de taxa e direitos.
5. Execute a prontidão de publicação; todas as quatro verificações devem passar.
6. Envie a versão para revisão e depois promova-a para ativa.
7. Publique o produto. A versão ativa anterior é desativada automaticamente.

Importação OpenAPI

curl --request POST \
  --url 'https://api.example.com/api/v1/products/signal-stack/import-spec/' \
  --header 'Authorization: Bearer <access>' \
  --header 'X-Organization: <vendor-org-uuid>' \
  --header 'Content-Type: application/json' \
  --data '{
    "version": "2.5.0",
    "openapi": { "openapi": "3.0.3", "paths": { } },
    "changelog": "Add delivery scheduling."
  }'

A importação cria ou atualiza uma versão em rascunho, reconcilia as linhas de endpoint a partir de paths, informa endpoints criados/atualizados/excluídos e preserva os campos de política do gateway nas operações mantidas. A importação de versão ativa é rejeitada.

Prontidão para publicação

Máquina de estados da versão

draft ──submit_review──► review ──promote──► live ──deprecate──► deprecated
  └───────────────────────promote────────────────┘

# product visibility
draft ──publish──► public ──unpublish──► draft
                       └──retire──► retired ──restore──► draft

• As versões ativas são imutáveis: edições são rejeitadas no nível do modelo e do serializer.
• A promoção desativa a versão ativa anterior para manter a invariante de uma única versão ativa.
• O contrato e o catálogo de endpoints devem corresponder exatamente antes da promoção.
• Os direitos de endpoint do plano são remapeados por método + caminho quando uma nova versão ativa substitui a anterior.

Relatórios de mudanças incompatíveis

GET /api/v1/versions/{version_id}/diff/?against={previous_version_id}

# Review added, removed, and changed operations before promotion.
# A release can be promoted only after the contract is validated.

Roteamento de hosts de produtos

Todo produto publicado tem duas portas de entrada equivalentes:

O middleware lê o primeiro rótulo do host como o slug do produto. Aliases de caminho são registrados como uma rota final, então rotas de API nomeadas sempre vencem. Produtos desconhecidos retornam 404 com uma dica; requisições sem chave para produtos desconhecidos retornam 401 para evitar enumeração.

Direitos do plano

• all concede todos os endpoints públicos da versão ativa.
• selected concede apenas o conjunto de endpoints configurado.
• Os direitos selecionados são aplicados no gateway, incluindo requisições de caminho bruto que ignoram o catálogo de endpoints.
• Os termos comerciais são bloqueados após a primeira assinatura; crie um plano substituto em vez de editar um plano com assinatura.

Gateway & medição

O gateway é o único caminho para os upstreams dos fornecedores. Ele resolve o produto, autentica a chave, aplica a política de assinatura e plano, reserva cota, encaminha com segurança, mede o uso e grava um rastreamento redigido.

Pipeline de requisição

1. Resolva o produto pelo host ou alias de caminho e encontre o endpoint da versão ativa por método + caminho.
2. Autentique com um JWT/sessão do painel ou uma credencial externa X-API-Key / bearer fr_live_….
3. Resolva a assinatura do produto e da aplicação. Apenas assinaturas ativas e em período de teste.
4. Valide o vínculo da chave e registre last_used_at. Uma chave não pode cruzar aplicações ou espaços de trabalho.
5. Reserve a cota no contador mensal e aplique limites de taxa por endpoint de forma atômica.
6. Execute verificações de segurança de rede: HTTPS, DNS público, sem redirecionamentos, sem travessia, IP fixado.
7. Encaminhe com tempo limite, limites de corpo, limites de upload e novas tentativas limitadas.
8. Meça: evento de uso, contador mensal, log de requisição redigido e prévia da resposta.

Chamadas diretas ao produto

curl --request POST \
  --url 'https://signal-stack.api.example.com/v2/deliveries' \
  --header 'X-API-Key: fr_live_…' \
  --header 'Content-Type: application/json' \
  --data '{"recipient":"maya@example.dev","template":"welcome"}'

curl --request GET \
  --url 'https://api.example.com/api/v1/signal-stack/v2/deliveries?limit=10' \
  --header 'X-API-Key: fr_live_…'

O envelope legado POST /api/v1/gateway/execute/ permanece para integrações e ferramentas de console existentes. Novos snippets usam a forma direta.

Cabeçalhos do gateway

Cotas e limites de taxa

• A cota mensal é reservada antes do encaminhamento e conta as requisições roteadas, incluindo falhas no upstream.
• Cota ilimitada remove apenas o teto mensal; o limite por minuto e o direito a endpoints continuam valendo.
• O limite de taxa por endpoint usa uma janela fixa atômica em cache. Uma indisponibilidade do cache compartilhado retorna 503 com nova tentativa antes da reserva de cota.
• O excedente é cobrado por 1.000 requisições quando configurado; zero significa apenas alerta.

Idempotência e novas tentativas

• As respostas concluídas são armazenadas com um hash SHA-256 do token, impressão digital da requisição e resposta redigida pelo TTL configurado.
• Replays retornam a resposta armazenada antes da cota ou de chamadas ao upstream.
• Reutilizar uma chave com dados de requisição diferentes retorna 409.
• As novas tentativas são limitadas e só se aplicam a falhas transitórias seguras; métodos não idempotentes não são repetidos às cegas.
• Um circuit breaker abre após falhas repetidas no upstream e retorna 503 com nova tentativa durante o resfriamento.

SSRF e segurança de rede

• Os upstreams devem ser HTTPS públicos. Respostas de DNS privadas, loopback, link-local e inseguras são rejeitadas.
• O caminho deve permanecer no host original. A travessia .. é rejeitada.
• Redirecionamentos não são seguidos.
• O endereço DNS público selecionado é fixado durante a conexão TLS para evitar rebinding.
• Os segredos do fornecedor são anexados no lado do servidor e nunca retornados ao navegador.
• As prévias de resposta têm limite de tamanho e ocultam cookies, autorização e cabeçalhos de chave de API.

Logs de requisição e medição

• Visão do consumidor: histórico de requisições do espaço de trabalho ativo com busca, filtros de status e exportação CSV.
• Visão do fornecedor: logs no nível da requisição em todos os produtos controlados, com consumidor, endpoint, latência, status e prévias redigidas.
• Eventos de uso: código de status, latência, assinatura, produto, endpoint e carimbo de data/hora.
• Contadores mensais: modelo de leitura de cotas e análises.
• A retenção é configurável com prune_telemetry.

Ambiente do gateway

Todos os tempos limite, limites, orçamentos de novas tentativas, limites de circuit breaker, TTL de idempotência, CIDRs de proxy confiáveis, limites de prévia de mídia e o sufixo do host do produto são definidos pelo ambiente. Consulte Configuração para a tabela completa.

Cobrança & repasses

A cobrança tem dois trabalhos: permitir que consumidores paguem por planos de API e permitir que o operador da plataforma cobre pela capacidade do espaço de trabalho. Ambos usam os mesmos provedores, faturas e liquidação de webhooks.

Os dois planos de cobrança

Pense nisso como dois caixas registradores separados:

Ambos usam checkout hospedado, webhooks assinados, faturas e conciliação. A receita de APIs dos fornecedores entra na liquidação de repasses; a receita de assinaturas da plataforma não.

Planos do fornecedor

• Intervalo mensal ou anual, moeda, preço e descrição.
• Cota mensal, limite de taxa por minuto, excedente por 1.000 requisições, dias de teste.
• Até oito linhas públicas de recursos e um plano público recomendado.
• Direito a endpoints all ou selected.
• Os termos comerciais são bloqueados após a primeira assinatura; use um plano substituto para alterações.

Checkout e liquidação

1. O consumidor seleciona um plano e aceita os termos da API.
2. Uma assinatura pendente e a fatura do primeiro período são criadas.
3. O provedor configurado abre o checkout hospedado.
4. O provedor envia um webhook assinado após o pagamento.
5. O FastRestful verifica a assinatura, registra o evento do provedor, valida valor/moeda e marca a fatura como paga.
6. O direito só é ativado após a liquidação. Redirecionamentos do navegador nunca concedem acesso.

POST /api/v1/billing/stripe-webhook/
POST /api/v1/billing/paypal-webhook/
POST /api/v1/billing/flutterwave-webhook/
POST /api/v1/billing/paystack-webhook/
POST /api/v1/billing/razorpay-webhook/

Suporte a provedores

Cada provedor abaixo tem um guia de configuração passo a passo em Gateways de pagamento, passo a passo.

Admin → Gateways de pagamento substitui as credenciais do ambiente campo a campo. Desativar um registro de gateway desliga esse provedor em todos os lugares, mesmo que as chaves de ambiente permaneçam.

Reembolsos

• Fornecedores com permissão de cobrança reembolsam faturas pagas pelo gateway original.
• Os reembolsos do Stripe são conciliados cumulativamente a partir de eventos de webhook; gateways hospedados confirmam de forma síncrona.
• Chaves de idempotência e solicitações de reembolso pendentes tornam as novas tentativas seguras.
• Reembolsos integrais marcam a fatura como reembolsada.
• Reembolsos após o repasse acrescentam lançamentos de clawback de receita do fornecedor e de reversão proporcional de tarifas no razão.
• Consumidores não podem se reembolsar; pagamentos manuais devem ser reembolsados pelo provedor.

Repasses

pending ──► in_transit ──► paid
   │              │
   ├──► failed ◄──┘
   └──► reversed

# Only paid invoices settle. Refunds reduce the next transfer.
# Gross collected revenue is stored separately from net transfer.
# Provider event IDs are unique and retries are idempotent.

• Configure um destino de fornecedor com PATCH /api/v1/orgs/{id}/payout-provider/ (acct_… para Stripe ou e-mail para PayPal).
• Inicie uma transferência com POST /api/v1/payouts/{id}/transfer/.
• Concilie com POST /api/v1/payouts/{id}/reconcile/; estados estritos exigem um ID de transferência ou motivo de falha.
• Os webhooks do Stripe conciliam transfer.created|paid|failed|reversed.

Assinaturas da plataforma

• Os planos da plataforma são gerenciados em Admin → Planos da plataforma; no máximo cinco planos.
• Cada plano pode definir limites de espaços de trabalho próprios e de listagem de APIs, benefícios e uma recomendação.
• Planos pagos permanecem não publicados até que um valor de exibição e um ID de preço recorrente correspondente no provedor sejam configurados.
• As sessões de Checkout e do Portal de Cobrança são criadas no servidor com destinos fixos FRONTEND_URL.
• A conciliação de assinaturas é somente leitura no admin, para que alterações da equipe não divirjam do provedor.

Comandos de liquidação

python3.11 manage.py generate_invoices --period 2026-10
python3.11 manage.py generate_payouts --period 2026-10

# Both commands are idempotent and safe to rerun.

A tarefa mensal do Celery é executada no dia 1 às 00:05 UTC. Sem um broker, invoque os comandos manualmente.

Ambiente do provedor

Consulte Configuração → Pagamentos e repasses para cada variável. No mínimo: segredo/webhook do Stripe, cliente/webhook do PayPal ou o trio público/secreto/webhook do gateway hospedado. A interface de cartão do frontend também precisa de NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY.

Gateways de pagamento, passo a passo

Conecte um provedor de pagamento real sem adivinhações. Cada seção de provedor tem duas partes: o que clicar no painel do provedor e depois o que inserir no FastRestful. O PayPal inclui um passo a passo completo de webhook, inclusive onde encontrar o ID de webhook que o FastRestful exige.

Antes de começar

Como o dinheiro circula no FastRestful

1. O FastRestful cria uma fatura.

   A assinatura e a fatura do primeiro período existem antes de o checkout abrir. Nada é marcado como pago ainda.

2. Para planos pagos, o provedor abre o checkout.

   O cliente paga na página hospedada do provedor. O FastRestful armazena apenas a referência do checkout.

3. O provedor envia um webhook assinado.

   O FastRestful verifica a assinatura, registra o evento uma vez e confere o valor e a moeda.

4. A fatura é liquidada.

   Só então a assinatura é ativada e o direito começa. Um redirecionamento do navegador nunca concede acesso.

Onde ficam as credenciais

Você pode colocar credenciais em backend/.env ou em Admin → Gateways de pagamento. Os registros do admin são mais fáceis de rotacionar e substituem os valores de ambiente campo a campo. Desativar um registro do admin desliga o provedor em todos os lugares, mesmo que as chaves de ambiente ainda existam.

Testando webhooks no seu notebook

Os provedores não conseguem alcançar http://127.0.0.1:5056. Use uma destas abordagens para testes locais.

Stripe CLI

1. Instale e faça login no Stripe CLI.

   Siga o guia de instalação do Stripe CLI e depois execute stripe login e aprove o prompt do navegador.

2. Encaminhe eventos para seu backend local.
   shellCopiar

   stripe listen --forward-to localhost:5056/api/v1/billing/stripe-webhook/

3. Copie o segredo de assinatura impresso.

   A CLI imprime whsec_…. Coloque-o em STRIPE_WEBHOOK_SECRET ou no registro do Stripe no admin. Mantenha a CLI em execução.

4. Dispare um evento de teste.
   shellCopiar

   stripe trigger checkout.session.completed
   stripe trigger invoice.paid

PayPal, Flutterwave, Paystack e Razorpay

Esses provedores precisam de uma URL HTTPS pública. Use um túnel como ngrok ou Cloudflare Tunnel e registre a URL do túnel no painel do provedor:

# Example with ngrok
ngrok http 5056

# Use the generated https URL, for example:
# https://abc123.ngrok-free.app/api/v1/billing/paypal-webhook/

Vai mudar a URL do túnel depois? Atualize o painel do provedor e o destino de webhook do FastRestful juntos. Uma URL desatualizada é a causa mais comum de "pagamento aprovado, mas a fatura nunca foi fechada".

O PayPal também oferece um simulador de webhook no painel do desenvolvedor. Aponte-o para a URL do túnel e use o ID de webhook do mesmo app de sandbox para que o FastRestful possa verificar o evento simulado.

Escolhendo um provedor

Stripe, passo a passo

1. Crie e ative uma conta Stripe

1. Crie uma conta Stripe e complete o perfil empresarial.
2. Mantenha o Test mode ativado enquanto você integra. O botão fica na barra superior do Stripe Dashboard.
3. Você pode fazer pagamentos de teste antes de o Stripe concluir a ativação da conta.

2. Copie as chaves de API

1. Abra Developers → API keys.

   No Stripe Dashboard, abra Developers e depois API keys.

2. Copie a chave secreta.

   Use primeiro a chave secreta de teste (sk_test_…). Coloque-a em STRIPE_SECRET_KEY ou no registro de administração do Stripe. Nunca coloque a chave secreta no código do frontend.

3. Copie a chave publicável.

   Coloque a chave publicável de teste (pk_test_…) em NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY se quiser a interface de cartão incorporada. Recompile o frontend depois de alterá-la.

3. Adicione o endpoint de webhook do Stripe

1. Abra Developers → Webhooks → Add endpoint.
2. Defina a URL do endpoint.
   URL de produção ou stagingCopiar

   https://api.example.com/api/v1/billing/stripe-webhook/

3. Selecione os eventos que o FastRestful concilia.
   • checkout.session.completed
   • invoice.paid e invoice.payment_succeeded
   • invoice.payment_failed
   • customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
   • charge.refunded
   • transfer.created, transfer.paid, transfer.failed, transfer.reversed (repasses)
4. Copie o segredo de assinatura.

   O Stripe mostra um valor que começa com whsec_…. Este é STRIPE_WEBHOOK_SECRET. Não é a chave secreta da API.

O Stripe assina cada entrega. O FastRestful rejeita assinaturas expiradas e falha de forma segura quando STRIPE_WEBHOOK_SECRET está ausente, portanto um segredo de assinatura correto é obrigatório.

4. Adicione o Stripe no FastRestful

Abra Admin → Payment gateways e edite a linha Stripe (recomendado), ou use variáveis de ambiente.

Se preferir usar variáveis de ambiente, defina STRIPE_SECRET_KEY e STRIPE_WEBHOOK_SECRET e reinicie o backend e os workers.

5. Planos da plataforma e Stripe Prices

Necessário apenas se você vender assinaturas da plataforma. Os planos de API dos fornecedores usam o preço do próprio produto e não precisam de um Stripe Price.

1. Crie um Product no Stripe.

   Abra Product catalog → Add product. Dê a ele o nome do seu plano da plataforma.

2. Adicione um Price recorrente.

   Use o valor, a moeda e o intervalo de cobrança exatos que o seu plano da plataforma exibe. Os preços mensal e anual devem ser Prices separados.

3. Copie cada Price ID.

   Os Price IDs começam com price_….

4. Cole-os no plano da plataforma.

   Abra Admin → Platform plans e preencha Stripe monthly price ID e Stripe annual price ID.

O FastRestful verifica o Price em relação ao valor, à moeda e ao intervalo do plano no checkout. Uma divergência retorna 409 com uma explicação, em vez de cobrar o valor errado.

6. Stripe Connect para repasses a fornecedores

1. Ative o Connect no Stripe e crie uma conta conectada para cada fornecedor que você paga.
2. Copie o ID da conta conectada (acct_…).
3. Armazene-o como destino do fornecedor com PATCH /api/v1/orgs/{id}/payout-provider/ ou nas configurações de repasse do fornecedor.
4. Opcionalmente, defina PAYOUT_PROVIDER=stripe para permitir apenas repasses via Stripe.
5. Mantenha os eventos transfer.* selecionados no webhook do Stripe.

7. Teste o Stripe

1. Use o cartão de teste 4242 4242 4242 4242, qualquer validade futura e qualquer CVC.
2. Conclua um checkout e confirme que a fatura fica paga.
3. Confirme que a assinatura fica ativa e que a chave do consumidor funciona.
4. Abra Admin → Payment events e confirme que o evento foi processado uma única vez.
5. Dispare um reembolso e confirme que o estado de reembolso da fatura está correto.

PayPal, passo a passo

O PayPal é o provedor com mais etapas do lado da plataforma. O FastRestful usa dois produtos diferentes do PayPal: Checkout orders para compras de planos de API de fornecedores e Billing subscriptions para planos da plataforma. Ambos usam as mesmas credenciais de app e o mesmo webhook.

1. Crie um app PayPal e copie as credenciais

1. Abra o PayPal Developer Dashboard.

   Acesse developer.paypal.com e entre com sua conta empresarial do PayPal.

2. Escolha Sandbox ou Live.

   Use o seletor Sandbox/Live no topo. Sandbox e live têm apps, credenciais e IDs de webhook separados.

3. Abra Apps & Credentials → Create App.

   Dê um nome como FastRestful e selecione a conta empresarial que deve receber os pagamentos.

4. Copie o Client ID e o Secret.

   Eles vão para PAYPAL_CLIENT_ID e PAYPAL_CLIENT_SECRET (ou para o registro de administração do PayPal). Se o secret estiver oculto, use a ação de regeneração do app e copie o novo valor.

2. Adicione o webhook do PayPal (obrigatório)

Esta é a etapa que a maioria das pessoas esquece. Sem um webhook ID, o FastRestful rejeita todos os eventos do PayPal e os pedidos pagos não são liquidados.

1. Abra seu app em Apps & Credentials.
2. Role até Webhooks e clique em Add Webhook.

   O rótulo exato pode ser Webhooks ou Add Webhook, dependendo da versão do dashboard do PayPal.

3. Insira a URL do webhook.
   URL do webhook do PayPalCopiar

   https://api.example.com/api/v1/billing/paypal-webhook/

   A URL precisa ser HTTPS pública. Um redirecionamento no navegador não é prova de pagamento; o PayPal envia eventos assinados para essa URL, e esses eventos liquidam a fatura.

4. Selecione os tipos de evento.

   Grupo de eventos	Selecionar	Por que o FastRestful precisa disso
   Checkout orders	CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED	Captura e liquida pagamentos de planos de API de fornecedores.
   Assinaturas	BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.EXPIRED	Ativa e atualiza assinaturas da plataforma. ACTIVATED é o evento que concede o direito de acesso.
   Pagamentos de assinatura	PAYMENT.SALE.COMPLETED	Registra renovações e reativa assinaturas da plataforma em atraso.
   Repasses	PAYMENT.PAYOUTS-ITEM.SUCCEEDED, PAYMENT.PAYOUTS-ITEM.FAILED, PAYMENT.PAYOUTS-ITEM.BLOCKED, PAYMENT.PAYOUTS-ITEM.RETURNED, PAYMENT.PAYOUTS-ITEM.CANCELED	Concilia transferências de repasse a fornecedores.

5. Salve o webhook e copie o Webhook ID.

   Abra o webhook salvo, se necessário. O PayPal mostra um webhook ID (uma string alfanumérica curta). Este é PAYPAL_WEBHOOK_ID. Ele não é a URL do webhook e não é o client secret.

3. Adicione o PayPal no FastRestful

Abra Admin → Payment gateways e edite a linha PayPal. Nesse formulário, Public key é o Client ID, Secret key é o Client secret e Webhook secret é o Webhook ID.

Se preferir variáveis de ambiente:

PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_WEBHOOK_ID=...
PAYPAL_ENV=sandbox          # use live in production
# PAYPAL_API_BASE=          # only for a proxy or custom host

Reinicie o backend e os workers depois de alterar valores de ambiente. Se usar o registro de administração, salve e ative-o; nenhum reinício é necessário.

4. Planos do PayPal Billing para assinaturas da plataforma

Pule esta etapa, a menos que você venda assinaturas da plataforma pelo PayPal. Os planos de API de fornecedores usam Checkout orders de pagamento único e não precisam de um plano do PayPal Billing.

1. Crie um Product no PayPal.

   No dashboard do PayPal, abra a área Billing/Subscriptions e crie um produto que represente sua plataforma.

2. Crie um Plan mensal e/ou anual.

   Defina o valor, a moeda e o intervalo exatos que correspondem ao plano no FastRestful. Crie um plano separado para cada intervalo.

3. Copie cada Plan ID.

   Os plan IDs do PayPal começam com P-….

4. Cole-os no plano da plataforma.

   Abra Admin → Platform plans e preencha PayPal monthly plan ID e PayPal annual plan ID.

5. Confirme que o webhook inclui eventos de assinatura.

   A assinatura é criada no estado PENDING. Ela só fica ativa depois que BILLING.SUBSCRIPTION.ACTIVATED chega.

5. PayPal Payouts para fornecedores

1. Confirme que a conta empresarial do PayPal está aprovada para Payouts.
2. Armazene o e-mail de recebimento PayPal do fornecedor como destino de repasse com PATCH /api/v1/orgs/{id}/payout-provider/.
3. Opcionalmente, defina PAYOUT_PROVIDER=paypal ou PAYOUT_PROVIDER=stripe,paypal para permitir ambos.
4. Mantenha os eventos PAYMENT.PAYOUTS-ITEM.* selecionados no webhook.

6. Teste o sandbox do PayPal

1. Use credenciais de sandbox.

   Defina PAYPAL_ENV=sandbox, use o Client ID e o secret do app de sandbox e o webhook ID de sandbox.

2. Crie uma conta de comprador de sandbox.

   O PayPal Developer Dashboard oferece contas pessoais de teste. Entre em sandbox.paypal.com com esse comprador quando o checkout abrir.

3. Conclua um pagamento de teste.

   Aprove o pedido e aguarde o redirecionamento de volta ao FastRestful.

4. Verifique o recebimento do webhook.

   Abra Admin → Payment events. Você deve ver CHECKOUT.ORDER.APPROVED, depois PAYMENT.CAPTURE.COMPLETED, e a fatura deve ficar paga.

5. Reenvie uma entrega, se necessário.

   No dashboard do PayPal, abra as entregas de eventos do webhook e reenvie o evento que falhou. O FastRestful deduplica por ID de evento.

Solução de problemas do webhook do PayPal

Flutterwave, passo a passo

1. Crie e verifique uma conta Flutterwave.

   Complete o perfil empresarial e o KYC antes de usar o modo live.

2. Copie as chaves de API.

   Abra Settings → API Keys. Copie a chave pública e a chave secreta. As chaves de teste e live são separadas.

3. Adicione a URL do webhook.

   Abra Settings → Webhooks e defina:

   URL do webhook do FlutterwaveCopiar

   https://api.example.com/api/v1/billing/flutterwave-webhook/

4. Crie um secret hash.

   Insira uma string aleatória longa como o secret hash do webhook. Coloque o mesmo valor em FLUTTERWAVE_WEBHOOK_SECRET ou no registro de administração. Este é um valor que você escolhe, não uma chave gerada pelo Flutterwave.

5. Insira as chaves no FastRestful.

   Edite a linha Flutterwave em Admin → Payment gateways, ou defina FLUTTERWAVE_PUBLIC_KEY, FLUTTERWAVE_SECRET_KEY e FLUTTERWAVE_WEBHOOK_SECRET.

6. Teste um checkout.

   O FastRestful trata charge.completed com status successful. Os demais eventos são confirmados e ignorados.

Paystack, passo a passo

1. Crie e ative uma conta Paystack.

   Conclua as etapas de ativação empresarial antes de usar chaves live.

2. Copie as chaves de API.

   Abra Settings → API Keys & Webhooks. Copie as chaves pública e secreta para o modo de teste ou live.

3. Adicione a URL do webhook.
   URL do webhook do PaystackCopiar

   https://api.example.com/api/v1/billing/paystack-webhook/

4. Deixe o segredo do webhook em branco.

   O Paystack assina cada webhook com sua chave secreta usando HMAC-SHA512. O FastRestful usa PAYSTACK_SECRET_KEY como fallback quando PAYSTACK_WEBHOOK_SECRET está vazio. Só defina uma substituição se o suporte do Paystack fornecer uma chave de assinatura separada.

5. Insira as chaves no FastRestful.

   Edite a linha Paystack em Admin → Payment gateways, ou defina PAYSTACK_PUBLIC_KEY e PAYSTACK_SECRET_KEY.

6. Teste um checkout.

   O FastRestful trata charge.success e compara o valor na menor unidade da moeda (por exemplo, kobo para NGN).

Razorpay, passo a passo

1. Crie e verifique uma conta Razorpay.

   Conclua o KYC e ative os pagamentos live.

2. Gere chaves de API.

   Abra Account & Settings → API Keys e gere uma chave. Copie o Key ID e o Key Secret.

3. Adicione o webhook.

   Abra Account & Settings → Webhooks → Add New Webhook e defina:

   URL do webhook do RazorpayCopiar

   https://api.example.com/api/v1/billing/razorpay-webhook/

   Selecione payment_link.paid. O FastRestful cria um Payment Link do Razorpay para o checkout e concilia esse evento. Defina um segredo de webhook forte; o Razorpay assina com HMAC-SHA256, e o mesmo valor deve ser armazenado no FastRestful.

4. Insira as chaves no FastRestful.

   Edite a linha Razorpay em Admin → Payment gateways, ou defina RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET e RAZORPAY_WEBHOOK_SECRET.

5. Teste um checkout.

   Abra o Payment Link, pague com um método de teste e confirme que a fatura foi paga e que o evento foi registrado uma única vez.

O teste de aceitação de 10 minutos

Execute isto para cada provedor antes de entrar em produção:

• O provedor aparece como configurado e ativado em Admin → Payment gateways.
• Um checkout de teste abre a página do provedor e retorna à URL correta do frontend.
• O webhook assinado chega e aparece uma única vez em Admin → Payment events.
• A fatura só fica paga depois do webhook, não no redirecionamento.
• A assinatura fica ativa e uma chave do consumidor funciona.
• Um reembolso retorna ao método de pagamento original e atualiza o razão.
• Se os repasses estiverem ativados, uma transferência de teste chega ao destino do fornecedor e é conciliada.
• Uma entrega duplicada de webhook é reconhecida sem liquidação dupla.

Erros comuns com webhooks

Lista de verificação para entrar em produção

1. Mude para credenciais live.

   Substitua chaves de teste, webhook IDs e segredos por valores live. Defina PAYPAL_ENV=live para o PayPal.

2. Registre as URLs de webhook de produção.

   Use seu hostname real de API, não um túnel, e confirme que o HTTPS funciona a partir da internet pública.

3. Defina a chave publicável do frontend.

   Use a chave publicável live do Stripe e recompile o frontend.

4. Faça os preços e plan IDs corresponderem.

   Confirme que os Stripe Price IDs e os PayPal Billing plan IDs apontam para objetos live com o valor, a moeda e o intervalo exatos.

5. Faça um pequeno pagamento real e reembolse-o.

   Verifique o webhook, a fatura, o direito de acesso, o reembolso e os lançamentos no razão. Esta é a única maneira de provar o caminho live.

6. Acompanhe o primeiro dia de eventos.

   Verifique Admin → Payment events em busca de falhas e confirme que o dashboard do provedor mostra entregas bem-sucedidas.

Biblioteca de mídia & CDN

Um único pipeline de armazenamento para recursos de mídia, logotipos de produtos, fotos de fornecedores, avatares de usuários e imagens do CMS. Sistema de arquivos local em desenvolvimento; S3 + CloudFront em produção.

Tipos e limites suportados

A validação verifica a extensão, o tipo de conteúdo declarado, a assinatura de magic bytes e o tamanho. Bytes idênticos dentro de um mesmo espaço de trabalho são deduplicados por checksum SHA-256. GET /api/v1/media/supported-types/ alimenta as dicas de aceitação da interface.

Modos de armazenamento

O modo S3 exige boto3 e django-storages no ambiente de produção. manage.py check falha se o bucket estiver ausente e avisa quando nem um domínio CDN nem uma ACL de leitura pública estiverem configurados.

Configuração do CloudFront

1. Crie um bucket privado com o bloqueio de todo acesso público ativado.
2. Crie uma distribuição CloudFront com a origem do bucket e o Origin Access Control (OAC).
3. Conceda à distribuição s3:GetObject em arn:aws:s3:::<bucket>/* por meio da política de bucket gerada.
4. Aponte MEDIA_CDN_DOMAIN para a distribuição ou para um CNAME com um certificado ACM.
5. Opcionalmente, defina MEDIA_CDN_DISTRIBUTION_ID para ativar ações de invalidação.

Fluxos de trabalho da biblioteca

• Console: a equipe envia e gerencia a biblioteca; os inquilinos veem uma estante do espaço de trabalho somente leitura em /dashboard/media ou /vendor/media.
• Coleções: pastas/categorias com escopo de espaço de trabalho, com busca, filtros e movimentações em lote.
• Predefinições de renomeação: kebab, snake, Title Case, UPPER ou manter, com prefixos, sufixos e sequências com preenchimento.
• Pontos focais: focal_x/focal_y por recurso (0–100), usados pelos blocos de imagem do CMS.
• Seleção de intervalo: clique com Shift para selecionar um intervalo, baixe, copie a URL e abra o recurso anterior/seguinte no painel lateral.
• Selos de uso: veja onde um recurso é referenciado antes de excluí-lo.

Funcionamento do seletor

Selecionar um recurso da biblioteca copia seus bytes para o campo de destino. Substituir ou excluir o recurso da biblioteca nunca quebra uma imagem selecionada, e cada modelo mantém seu próprio ciclo de vida de armazenamento. Recursos de outro espaço de trabalho são rejeitados.

Destinos conectados: logotipo do produto, perfil/capa do fornecedor, avatar do usuário, identidade visual do admin, imagens de categoria, imagens do CMS e mídia de blocos de conteúdo.

API de mídia

Ambiente

Consulte Configuração para a matriz de armazenamento de mídia e spec, incluindo URL do endpoint, domínio CDN, ID da distribuição e comportamento da ACL.

Estúdio de newsletter

Marketing por e-mail restrito à equipe, com públicos, modelos baseados em blocos, campanhas, testes A/B de assunto, segmentos, automações, análise por link e e-mails transacionais do sistema.

Início rápido

1. Abra /admin/newsletter/ → Settings e configure o provedor, o remetente, a URL pública do backend, o endereço postal e o texto de cancelamento de inscrição.
2. Lists & contacts → crie uma lista; adicione ou importe contatos como email, name, tags.
3. Templates → duplique um modelo inicial pronto ou comece do zero, crie com o editor de blocos e depois salve e visualize.
4. Campaigns → escolha um modelo, listas, segmento opcional, assunto(s) e envie um teste para você mesmo.
5. Automations → adicione etapas de e-mail e de espera; entradas em listas ou tags disparam a inscrição.
6. System emails → vincule modelos a gatilhos transacionais.

python3.11 manage.py newsletter_beat
# or schedule the Celery tasks:
# newsletter.send_due_campaigns
# newsletter.process_automations

Provedores de e-mail

Os segredos são criptografados em repouso. Um botão de teste envia pelo provedor selecionado antes de você lançar uma campanha.

Modelos e editor

• Blocos: cabeçalho, hero, texto, imagem, botão, divisor, espaçador, imagem + texto, destaques, citação, links sociais, HTML bruto, rodapé.
• Blocos avançados: colunas, depoimento, tabela, vídeo, cartão de produto, banner de CTA, nota de rodapé.
• Variantes para layouts de hero, tamanho/alinhamento de texto, molduras/legendas de imagem, estilo/tamanho/alinhamento de botão, estilo/largura de divisor, raio do tema e largura do conteúdo.
• Arrastar e soltar e reordenação por teclado, pré-visualização ao vivo com debounce, alternativa em texto simples, preheader e URLs sanitizadas.
• Placeholders: {{first_name}}, {{action_url}}, {{message}}, {{site_name}}, {{unsubscribe_url}}, {{preferences_url}}.
• 18 modelos integrados para lançamentos, resumos, webinars, estudos de caso, reconquista, NPS, promoções, registros de alterações, editoriais, destaques da comunidade, onboarding e anúncios de serviço.

Campanhas

• O público é composto pelas listas selecionadas (união) ∩ segmento opcional, sem duplicatas; apenas contatos inscritos, com endereços que apresentaram bounce ou reclamação excluídos.
• Os testes A/B de assunto dividem uma porcentagem dos destinatários, aguardam uma janela e depois enviam o vencedor para o restante. A opção manual “decidir vencedor agora” está disponível.
• Reenviar para não abertos cria um rascunho direcionado apenas aos contatos que não abriram a campanha original.
• Agendamento, pausa/retomada/cancelamento, envio de teste e calendário de campanhas.
• Relatórios: entregas, aberturas, cliques, cancelamentos de inscrição, comparação A/B, tabela de cliques por link, linha do tempo de engajamento e destinatários mais recentes.
• Os padrões de UTM são aplicados aos links da campanha; apenas destinos http(s) são aceitos.

Segmentos e automações

Os segmentos combinam listas, tags (todas/qualquer uma), status do contato, janelas de engajamento (abriu, clicou, não abriu em N dias) e recência de entrada. As contagens são avaliadas ao vivo e reutilizadas pelas campanhas.

As automações são disparadas por entrada em lista, tag, ação manual ou API. As etapas enviam um e-mail ou aguardam N horas. As execuções avançam de forma idempotente e registram falhas. A inscrição é deduplicada por contato.

E-mails do sistema

Se um modelo ativo do estúdio estiver vinculado a um gatilho, ele renderiza HTML + texto; caso contrário, a mensagem simples legada é enviada. As chaves vinculadas incluem boas-vindas, redefinição de senha, código de login, alerta de segurança, aviso da plataforma, fatura aberta, falha de pagamento, fornecedor aprovado, alerta de cota, convite para organização e resumo de atividades.

Inscrição pública e preferências

• POST /api/v1/newsletter/subscribe/ com confirmação opcional de double opt-in.
• GET /confirm/<token>/, GET /unsubscribe/<token>/ e POST de um clique do RFC 8058.
• Central de preferências em /api/v1/newsletter/preferences/<token>/ para alternar listas ou cancelar a inscrição globalmente.
• O pixel de abertura e os redirecionamentos de clique reescrevem os links quando o rastreamento está ativado.
• Os e-mails enviados incluem os cabeçalhos List-Unsubscribe e List-Unsubscribe-Post.

Entregabilidade e operações

• Gráficos de bounce, reclamações, cancelamentos de inscrição e crescimento; mantenha as taxas de bounce e reclamação próximas de zero.
• Mapa de calor de horário de envio por dia da semana local × hora, com recomendações de melhor janela.
• Estimativas de público e endereços de amostra antes do envio.
• Página de contatos com status, tags, campos personalizados, associações a listas, supressão, entregas, eventos e execuções de automação.
• Exportações CSV para contatos, destinatários de campanha e links.
• Execute newsletter_beat a cada poucos minutos para agendamentos, decisões A/B e atrasos de automação.

Anúncios & banners

Banners públicos criados no admin para barras superiores, posições no rodapé e anúncios dentro da página — com segmentação, agendamento, regras de dispensa, experimentos visuais e análise de impressões/cliques.

Posicionamentos

Um banner é exibido por posicionamento, escolhido por prioridade e depois por recência. Um banner pode ter vários posicionamentos como destino.

Segmentação e agendamento

• Caminhos: padrões de inclusão e exclusão como /pricing, /docs/* ou *.
• Público: todos, visitantes desconectados ou usuários conectados.
• Idioma e dispositivo: listas de permissão separadas por vírgula; tablet usa mobile como fallback quando mobile é permitido.
• Agendamento: carimbos de data/hora de início/fim e um interruptor de ativação.
• Prioridade: números maiores vencem quando vários banners correspondem.

Design e recursos integrados

• Layouts: barra, cartão, dividido, minimalista.
• Selo, título, corpo, rótulo/URL/estilo/nova aba do CTA, imagem, lado, cores, gradientes, alinhamento e pré-visualização ao vivo.
• Ícone/emoji opcional, padrões decorativos (pontos, grade, listras, brilho) e animações de entrada seguras para movimento reduzido.
• 32 banners integrados para lançamentos, confiança/status, promoções, eventos, ciclo de vida, editorial, comunidade e campanhas sazonais.
• HTML personalizado com placeholders {{click_url}}, {{dismiss_url}} e {{impression_url}} para que o rastreamento continue funcionando.
• Frequência de dispensa: a cada carregamento de página, uma vez por sessão, uma vez por dia ou uma vez para sempre.

Entrega e rastreamento

GET  /api/v1/announcements/?path=/pricing&locale=en&placement=topbar
POST /api/v1/announcements/<id>/impression/
POST /api/v1/announcements/<id>/dismiss/
GET  /api/v1/announcements/<id>/click/

Os payloads incluem HTML renderizado no servidor com estilos inline, além de impression_url, dismiss_url e frequency. Os eventos registram posicionamento, caminho, idioma, dispositivo, referenciador, user agent e IP.

Experimentos e relatórios

• Banners com a mesma prioridade compartilham o tráfego por peso (1–1000).
• Defina um nome de experimento e um rótulo de variante em vários banners; uma variante é escolhida por requisição com base no peso.
• Os relatórios de experimento mostram impressões, cliques, CTR e a variante líder.
• Os relatórios mostram a atividade diária de 30/90 dias e detalham posicionamento, páginas principais, dispositivos e eventos recentes.
• As listas do admin mostram contadores, ações de ativar/pausar e registros de eventos somente leitura.

Operações

Os eventos de banner são somente de adição. O estado de dispensa é armazenado no navegador do visitante e contado no servidor. O script público ignora user agents de bots; use um user agent de navegador normal para o QA de banners públicos.

Links curtos

Links curtos prontos para campanhas, redirecionamentos, códigos QR, padrões de UTM, fallbacks, análise de cliques e verificações de destinos quebrados — disponíveis tanto no painel do consumidor quanto no estúdio do fornecedor.

O que faz

• Crie links curtos com slug personalizado, destino, tags, tipo de redirecionamento, expiração e estado ativo.
• Redirecionamentos 301 ou 302; links expirados ou desativados podem usar um destino seguro como fallback ou uma página 410 com a sua marca.
• Padrões de UTM (utm_source, utm_medium, utm_campaign) acrescentados no momento do redirecionamento; parâmetros de campanha recebidos têm precedência.
• Geração de QR SVG com cor personalizada e metadados de campanha.
• Análise de cliques com país, dispositivo, referenciador e contexto de campanha.
• Verificações de integridade de destinos quebrados com detalhes do erro e nova verificação em um clique.
• Importação/exportação CSV e ações de seleção em lote.

Console

Abra Links no painel do consumidor (/dashboard/links) ou no estúdio do fornecedor (/vendor/links). O editor inclui título, destino, slug, tags, tipo de redirecionamento, expiração, interruptor de ativação e escopo de todo o site apenas para a equipe. A tabela oferece ações de copiar, QR, verificar novamente, editar, excluir, integridade e status.

Configuração

python3.11 manage.py checklinks --limit 200 --timeout 6

Resumo da API

Os redirecionamentos públicos resolvem por slug, registram o clique e então redirecionam. As listas do admin incluem colunas de cliques/integridade, ações de verificar novamente/ativar/desativar, uma ação rápida “Encurtar um link” e um registro de cliques somente leitura.

Site, CMS & idiomas

O plano de controle Django é responsável pelo shell público: identidade, padrões de busca/compartilhamento, navegação, páginas, posts do blog, documentos legais, CSS/JS personalizados, modo de manutenção e camadas de idioma.

Superfícies do operador

Configurações do site

• Logotipo, favicon e imagem de compartilhamento social com seletor de mídia e limpeza pós-commit.
• Título meta global, descrição e fallback da imagem de compartilhamento.
• Modo marketplace, porcentagem de taxa padrão, indicador de manutenção.
• Rótulo do CTA do cabeçalho + destino (devem ser fornecidos juntos).
• Banner de anúncio ativado/texto/url.
• Título do rodapé, resumo, direitos autorais, e-mail de suporte.
• Desafio integrado ou Google reCAPTCHA para formulários públicos.
• Política obrigatória de dois fatores para todas as contas.
• Cores do tema, fontes e pré-visualização ao vivo do shell público.

Conteúdo estruturado

Páginas e posts são montados a partir de seções ordenadas, não de HTML bruto. Os tipos de seção disponíveis incluem prosa, tabela, código, imagem, vídeo, dividido, citação, abas, código multilíngue, exemplo de endpoint, depoimentos, lista de recursos, FAQ, etapas, métricas, grade de cartões, divisor, hero, faixa de logos, linha do tempo, lista de links, destaque, coleção de API, coleção de categorias, APIs principais e artigos recentes.

• A prosa aceita parágrafos separados por uma linha em branco; os itens de lista são um por linha.
• As ações exigem um rótulo e um destino; os links aceitam caminhos do site, HTTPS, mailto ou tel.
• Rascunhos nunca aparecem publicamente; páginas publicadas aparecem no conteúdo do site, nos metadados e nas rotas do sitemap.
• O SEO no nível da página substitui os padrões globais campo a campo.
• Páginas legais entram no grupo legal padrão do rodapé somente após a publicação.

CSS & JS personalizados

Admin → Custom assets injeta CSS ou JavaScript no site público sem implantação. Cada trecho tem um tipo, posicionamento (head ou footer) e escopo (site inteiro, caminhos selecionados ou uma página). Os caminhos suportam correspondências exatas e curingas /prefix/*.

• Payload público: GET /api/v1/platform/assets/ retorna trechos ativos mais o csp_nonce configurado.
• Pré-visualização: cada trecho tem uma pré-visualização em iframe no admin com injeção forçada via ?fr_preview_asset=<id>.
• Revisões: cada salvamento cria um snapshot imutável com autor e nota; qualquer revisão pode ser restaurada como uma nova entrada.
• CSP: defina o mesmo nonce em Site settings e na sua política de edge; as tags o recebem automaticamente.

Idiomas e camadas de tradução

O inglês é o pacote de origem canônico. O francês é distribuído completo. Todos os outros idiomas são uma camada esparsa do admin mesclada sobre o inglês em tempo de execução.

• Abra Site locales → Manage translations para inspecionar a cobertura, editar o francês integrado ou adicionar um idioma.
• O francês integrado aparece com 100% de cobertura sem uma linha no banco de dados. Salvar um campo cria uma camada do admin sem alterar o fallback distribuído.
• Exporte JSON ou TypeScript, traduza offline e importe de volta. Chaves desconhecidas são ignoradas e informadas.
• A API pública de idiomas retorna as camadas ativas; o frontend as mescla sobre o inglês e o francês integrados.
• Depois de editar lib/i18n/*.json, execute npm run export:i18n e reinicie a API para atualizar o cache do processo.

Modo de manutenção

A manutenção pausa todas as rotas do frontend e as chamadas de API/gateway dos clientes. O admin da equipe, as sondas de integridade, os callbacks do provedor de identidade e os webhooks assinados de pagamento/repasse permanecem disponíveis. A disponibilidade pública é exposta anonimamente com o indicador de manutenção, o aviso e o intervalo de nova tentativa.

Contratos públicos

Integrações externas, passo a passo

E-mail, armazenamento de objetos, login único, infraestrutura e webhooks de saída. Cada seção informa o que fazer primeiro no site do provedor e depois exatamente quais valores copiar para o FastRestful.

Qual valor prevalece?

• As variáveis de ambiente fornecem os padrões de implantação.
• Os registros gerenciados no admin substituem os valores de ambiente correspondentes campo a campo.
• Desativar um registro do admin desliga esse provedor em todos os lugares, mesmo que as chaves de ambiente permaneçam definidas.
• Os valores de provedor do frontend são incorporados no momento do build. Recompile depois de alterar NEXT_PUBLIC_*.
• Execute a ação de teste do provedor antes de enviar tráfego real.

Provedores de e-mail e newsletter

O FastRestful pode enviar e-mails de campanha, automação e sistema pelo seu próprio provedor. Configure-o em Admin → Newsletter → Email settings, ou herde SMTP das variáveis de ambiente EMAIL_*. As chaves e os segredos de API são criptografados em repouso.

A configuração em seis etapas

1. Crie uma conta em um provedor.

   Use um provedor transacional como Amazon SES, Mailgun, SendGrid, Postmark, Brevo, Mailjet, SparkPost, Resend ou qualquer host SMTP.

2. Verifique seu domínio de envio ou endereço de remetente.

   A maioria dos provedores não entrega até que o domínio ou e-mail seja verificado. Adicione os registros DNS fornecidos pelo provedor.

3. Crie a chave de API ou as credenciais SMTP.

   Use a menor permissão que permita enviar e-mail. Para SMTP, copie o host, a porta, o usuário e a senha.

4. Insira os valores no FastRestful.

   Abra Admin → Newsletter → Email settings. Escolha o provedor, cole as credenciais e defina o nome do remetente, o e-mail do remetente, o reply-to, o endereço postal e o texto de cancelamento de inscrição.

5. Defina a URL pública do backend.

   Ela é usada em pixels de rastreamento, links de confirmação e links de cancelamento de inscrição. Deve ser a origem pública que chega ao Django, não o servidor de desenvolvimento do frontend.

6. Envie um e-mail de teste para você mesmo.

   Use a ação de teste integrada. Verifique o código-fonte completo da mensagem para confirmar o remetente e os links esperados antes de enviar uma campanha.

Guia rápido de provedores

Entregabilidade é um trabalho de DNS. Autentique SPF, DKIM e DMARC antes de aumentar o volume. Comece com envios pequenos, monitore rejeições e reclamações e mantenha o link de descadastro funcionando. Campanhas, automações e e-mails do sistema podem usar modelos diferentes, mas compartilham o mesmo provedor.

Armazenamento de objetos e CDN

O armazenamento no sistema de arquivos local é adequado para desenvolvimento. Em produção, use armazenamento compatível com S3 e uma CDN, para que os uploads sobrevivam às implantações e os assets carreguem rapidamente.

1. Crie o bucket S3 e as permissões

1. Crie um bucket privado.

   No console da AWS, crie um bucket na região desejada. Mantenha Bloquear todo o acesso público ativado. O CloudFront fará a leitura por meio do OAC.

2. Crie um usuário ou papel IAM.

   A cadeia de credenciais padrão é suportada: variáveis de ambiente, um perfil de instância ou IRSA no Kubernetes. Não codifique chaves diretamente no repositório.

3. Conceda apenas as permissões de que o FastRestful precisa.
   política IAM mínimaCopiar

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["s3:ListBucket"],
         "Resource": "arn:aws:s3:::my-media-bucket"
       },
       {
         "Effect": "Allow",
         "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
         "Resource": "arn:aws:s3:::my-media-bucket/*"
       }
     ]
   }

4. Instale as bibliotecas de armazenamento.

   Execute pip install boto3 django-storages no ambiente de backend e adicione-as aos requisitos de implantação.

5. Defina os valores de ambiente.
   backend/.envCopiar

   MEDIA_STORAGE=s3
   MEDIA_S3_BUCKET=my-media-bucket
   MEDIA_S3_REGION=us-east-1
   # MEDIA_S3_ENDPOINT_URL=   # only for S3-compatible providers
   # MEDIA_S3_ACL=            # omit when using CloudFront OAC

6. Reinicie e envie um asset de teste.

   Abra a biblioteca de mídia e envie uma imagem. Ela deve aparecer no bucket e carregar pela CDN ou URL S3 configurada.

2. Coloque o CloudFront na frente do bucket

1. Crie uma distribuição CloudFront.

   Escolha o bucket como origem e crie um Origin Access Control (OAC).

2. Atualize a política do bucket.

   Permita que a distribuição CloudFront leia os objetos. O console do CloudFront pode gerar a política para você.

3. Defina os valores do FastRestful.
   backend/.envCopiar

   MEDIA_CDN_DOMAIN=cdn.example.com
   MEDIA_CDN_DISTRIBUTION_ID=E1234567890ABC
   # MEDIA_S3_ACL=public-read   # only if serving S3 directly, not recommended

4. Permita a invalidação de cache.

   Adicione cloudfront:CreateInvalidation à política IAM se quiser que o botão de limpeza da biblioteca de mídia funcione.

5. Teste com um novo upload.

   Envie um novo arquivo, abra-o pelo domínio da CDN, substitua-o e use a ação de limpeza.

3. Provedores compatíveis com S3

Cloudflare R2, MinIO, DigitalOcean Spaces e serviços semelhantes funcionam pela API S3. Defina MEDIA_S3_ENDPOINT_URL como o endpoint S3 do provedor e mantenha o bucket privado se o provedor oferecer suporte a CDN ou URLs assinadas. Verifique upload, download e exclusão antes de confiar nisso em produção.

4. Armazenamento de especificações OpenAPI

Por padrão, os contratos OpenAPI importados são armazenados no banco de dados. Para armazená-los no S3, defina:

SPEC_STORAGE=s3
SPEC_S3_BUCKET=my-spec-bucket
SPEC_S3_PREFIX=specs/
SPEC_S3_REGION=us-east-1
# SPEC_S3_ENDPOINT_URL=

Consulte Biblioteca de mídia e CDN para limites de upload, tipos de arquivo suportados e comportamento da CDN.

Login único

OIDC e SAML preservam destinos relativos seguros e tokens de convite da organização. O login por senha pode permanecer ativado como alternativa.

OIDC, passo a passo

1. Crie um aplicativo OIDC no seu provedor de identidade.

   Use Okta, Auth0, Microsoft Entra ID, Google Workspace, Keycloak, Authentik ou qualquer provedor OIDC compatível.

2. Registre a URL de callback.
   URI de redirecionamentoCopiar

   https://api.example.com/api/v1/auth/sso/callback/

   Use o hostname exato que os usuários acessam. Uma diferença de barra final fará o callback falhar.

3. Permita o fluxo de código de autorização e os escopos.

   Solicite openid, email e profile.

4. Copie o emissor, o client ID e o client secret.
   backend/.envCopiar

   SSO_ISSUER=https://login.example.com/realms/acme
   SSO_CLIENT_ID=fastrestful
   SSO_CLIENT_SECRET=...

5. Reinicie o backend.

   O botão de SSO fica oculto até que o provedor seja configurado.

6. Teste com uma identidade real.

   Entre pelo botão e confirme se o callback retorna à rota esperada do frontend.

SAML 2.0, passo a passo

1. Instale a dependência opcional.

   Execute pip install lxml antes de ativar o SAML.

2. Copie os metadados do SP.

   Forneça esta URL ao seu provedor de identidade ou envie o XML que ele retornar:

   metadados do SPCopiar

   https://api.example.com/api/v1/auth/saml/metadata/

3. Defina a URL do ACS e o entity ID no IdP.

   O assertion consumer service é:

   URL do ACSCopiar

   https://api.example.com/api/v1/auth/saml/callback/

   O entity ID padrão é fastrestful. Você pode alterá-lo com SSO_SAML_ENTITY_ID.

4. Copie a URL de SSO do IdP e o certificado de assinatura.
   backend/.envCopiar

   SSO_SAML_ENABLED=1
   SSO_SAML_ENTITY_ID=fastrestful
   SSO_SAML_SSO_URL=https://idp.example.com/sso
   SSO_SAML_IDP_CERT=-----BEGIN CERTIFICATE-----...
   # SSO_SAML_AUDIENCE=fastrestful

5. Reinicie e teste.

   Inicie um login pelo frontend e confirme se a asserção do IdP retorna à página esperada.

Provedores de infraestrutura

Ferramentas de API e webhooks de saída

OpenAPI, Swagger e Postman

• Importação OpenAPI: importe OpenAPI 3.x ou Swagger 2.0 em uma versão de rascunho. O pipeline de versões reconcilia endpoints e sinaliza mudanças incompatíveis.
• Schema da plataforma: exporte-o em /api/schema/ com python3.11 manage.py spectacular --file schema.yml --validate.
• Swagger UI: disponibilizado em /api/docs/ pelo backend.
• Postman / kits iniciais: os endpoints de produto expõem pacotes para download aos consumidores.

Webhooks de saída, passo a passo

1. Crie o endpoint no FastRestful.

   Abra a seção de endpoints de webhook do plano de controle e adicione a URL do seu receptor. Ela deve usar HTTPS.

2. Escolha os eventos e um segredo de assinatura.

   Armazene um segredo forte. O FastRestful assina o corpo bruto da requisição com HMAC-SHA256.

3. Envie uma entrega de teste.

   Confirme se o seu receptor retorna uma resposta 2xx.

4. Verifique a assinatura no seu servidor.

   Compare seu próprio HMAC-SHA256 do corpo bruto com o header X-FastRestful-Signature. O valor é sha256=<hex>. O nome do evento está em X-FastRestful-Event.

5. Acompanhe o log de entregas.

   As novas tentativas são seguras e o histórico de entregas é evidência somente leitura. Trate nomes de eventos duplicados de forma idempotente.

Webhooks de pagamento são separados. Webhooks de provedores liquidam valores e são registrados no painel de cada provedor. Webhooks de saída do fornecedor são para as suas próprias integrações. Não aponte um provedor de pagamento para um endpoint de webhook de fornecedor.

Checklist de aceitação da integração

• O provedor aparece como configurado e ativado na página de administração ou configurações.
• Uma mensagem ou upload de teste real chega ao provedor e a URL retornada carrega.
• O e-mail de teste chega; SPF, DKIM e DMARC passam.
• A mídia enviada é armazenada no bucket e servida pela CDN.
• O callback OIDC ou SAML retorna à rota esperada do frontend.
• As assinaturas dos webhooks de saída são verificadas no receptor.
• As novas tentativas não duplicam efeitos colaterais.
• Credenciais de teste e de produção não são misturadas.

Backups & atualizações

Um caminho repetível de backup, restauração e atualização para uma implantação auto-hospedada do FastRestful. Os backups vêm primeiro; o método de atualização depende de como você comprou e implantou o produto.

O que fazer backup

Backup do PostgreSQL

pg_dump --format=custom "$DATABASE_URL" > fastrestful-$(date +%F-%H%M).dump
pg_dump --format=plain "$DATABASE_URL" | gzip > fastrestful-$(date +%F-%H%M).sql.gz

# Verify the dump is readable
pg_restore --list fastrestful-$(date +%F-%H%M).dump > /dev/null

Restaure em um banco de dados limpo

createdb fastrestful_restore
pg_restore --clean --if-exists --no-owner \
  --dbname=fastrestful_restore fastrestful-2026-10-21.dump

# Point a staging deployment at the restored database and run:
python3.11 manage.py migrate --check
python3.11 manage.py check

Teste restaurações trimestralmente. Um backup que nunca foi restaurado é uma suposição, não um plano de recuperação.

Duas formas de atualizar

Sequência de atualização manual

Use isto apenas para uma implantação personalizada que não é gerenciada pela central de atualizações oficial.

1. Leia as notas da versão e verifique mudanças de migração ou de ambiente.
2. Faça backup do PostgreSQL, da mídia e dos segredos.
3. Coloque a plataforma em modo de manutenção se uma migração exigir pausa de escrita.
4. Baixe o código e instale as dependências de backend e frontend.
5. Execute as migrações, colete os arquivos estáticos e faça o build do frontend.
6. Reinicie a API e os workers; verifique a prontidão e faça uma requisição de smoke test.
7. Saia do modo de manutenção e monitore a taxa de erros, a profundidade da fila e os recebimentos de webhook.

git pull --ff-only
pip install -r backend/requirements.txt
npm ci

python3.11 backend/manage.py migrate --noinput
python3.11 backend/manage.py collectstatic --noinput
npm run build

sudo systemctl restart fastrestful
sudo systemctl restart fastrestful-worker fastrestful-beat
curl -f https://api.example.com/api/health/ready

Rollback

• O rollback de código é simples apenas quando a versão anterior não exigiu uma migração de banco de dados irreversível.
• Mantenha um snapshot do banco de dados antes de cada migração. Restaure o snapshot e a versão de código correspondente juntos.
• Nunca edite uma migração já aplicada em produção; adicione uma nova migração corretiva.
• Após o rollback, execute novamente a requisição de smoke test e inspecione as tarefas enfileiradas em busca de suposições de schema.

Segurança das migrações

python3.11 manage.py showmigrations
python3.11 manage.py makemigrations --check --dry-run
python3.11 manage.py migrate --plan

• Primeiro mudanças aditivas, depois preenchimento, e a remoção dos campos antigos em uma versão posterior.
• Evite bloqueios longos de tabela em tabelas de alta volume de medição, log de requisições e auditoria.
• Use o modo de manutenção para migrações que alteram colunas de estado financeiro ou de versão.
• Mantenha o Celery pausado até que as migrações terminem.

Versões do frontend

O build do frontend é estático e autossuficiente. Mantenha a origem da API e a URL pública do site alinhadas com a implantação. Se você implantar um novo build que espera novos campos da API, lance o backend primeiro ou mantenha o contrato compatível com versões anteriores.

Observabilidade

Saúde, logs, métricas e filas para uma plataforma em que requisições, dinheiro e moderação deixam evidências.

Saúde e prontidão

Use a prontidão para a participação no balanceador de carga. Uma indisponibilidade de cache retorna 503 com a dependência com falha, em vez de servir com estado apenas local.

Contexto da requisição

• Toda resposta da API carrega metadados da requisição nos logs da aplicação. Preserve o request ID através do seu proxy reverso.
• Os logs de requisição do gateway incluem assinatura, produto, endpoint, status, latência e prévias com dados sensíveis mascarados.
• Os eventos de provedor armazenam IDs de evento e hashes de payload, não segredos brutos.
• Os eventos de auditoria vinculam ator, ação, organização, destino e metadados.

Sinais para monitorar

Regras de logging

• Nunca registre em log chaves de API brutas, segredos de provedores ou payloads completos de pagamento.
• Mantenha as prévias de requisição/resposta limitadas e com dados sensíveis mascarados.
• Registre IDs de eventos de provedor e resultados de liquidação, não dados de cartão.
• Use campos estruturados sempre que possível: request ID, organização, produto, endpoint, status.
• Separe as evidências de auditoria dos logs comuns da aplicação.

Filas e trabalhos agendados

celery -A config inspect ping
celery -A config inspect active
celery -A config inspect reserved
celery -A config inspect scheduled

Monitore as filas default e de cobrança de forma independente. A liquidação roda mensalmente; a moderação e as notificações rodam a cada 15 minutos; as verificações de disponibilidade rodam diariamente.

Conjunto mínimo de alertas

• Prontidão falhando por mais de 2 minutos.
• Taxa de 5xx da API acima do objetivo de serviço.
• Circuito do gateway aberto ou taxa de erros upstream em pico.
• Falhas de webhook ou eventos de provedor não processados.
• Heartbeat do Celery beat ausente; profundidade da fila crescendo.
• Saturação de disco e conexões do banco de dados.
• Falha de backup ou último backup bem-sucedido muito antigo.
• Queda inesperada na adesão à autenticação de dois fatores entre a equipe.

Comandos de diagnóstico

python3.11 manage.py check --deploy
python3.11 manage.py showmigrations
python3.11 manage.py prune_telemetry --request-log-days 90 --usage-event-days 365
python3.11 manage.py check_api_availability
python3.11 manage.py checklinks --limit 200 --timeout 6

Escalonamento

Onde o FastRestful escala sem problemas, onde precisa de infraestrutura e qual estado deve permanecer compartilhado.

Escale as camadas separadamente

edge / CDN
  ├── frontend static assets
  └── API reverse proxy
        ├── Django / Gunicorn replicas
        ├── Celery workers (default queue)
        ├── Celery workers (billing queue)
        ├── Celery beat (one instance)
        ├── PostgreSQL primary + read capacity
        └── Redis (shared cache + broker)

Camada web

• Execute várias instâncias Gunicorn/Django sem estado atrás de um balanceador de carga.
• As sessões ficam no banco de dados; o cache e os limites de taxa usam Redis. Não dependa de memória local em produção.
• Dimensione os workers para a requisição de gateway mais lenta (timeout padrão de 15 segundos).
• Termine o TLS na borda e preserve o host original para o roteamento de produtos.

Banco de dados

• Use PostgreSQL com pool de conexões à medida que o número de workers cresce.
• Tabelas de alto volume: eventos de uso, logs de requisição, eventos de auditoria, entregas de webhook.
• Remova telemetria periodicamente e arquive evidências de auditoria conforme a política.
• Mantenha as gravações de estado financeiro transacionais; não faça sharding de tabelas de fatura ou ledger sem um plano de migração.

Redis

• O cache compartilhado é obrigatório para os limites de taxa e a idempotência do gateway.
• Uma indisponibilidade do Redis retorna 503 com nova tentativa possível antes da reserva de cota; o gateway não recorre a estado por processo.
• Monitore evictions. A perda de registros de idempotência pode permitir chamadas upstream duplicadas após mudanças de TTL.
• Use um banco de dados ou uma instância Redis separada para o broker do Celery se a pressão de cache aumentar.

Capacidade do gateway

• As cotas e os limites de taxa são aplicados por assinatura e endpoint, não por processo.
• A latência upstream domina o tempo da requisição; mantenha timeouts e novas tentativas conservadores.
• O armazenamento de idempotência cresce com o volume de requisições; dimensione o Redis para o TTL configurado.
• Use roteamento por host de produto com TLS curinga para evitar um gargalo de caminho central na borda.

Workers e trabalhos agendados

• Execute uma única instância beat; vários agendadores beat podem duplicar trabalhos temporizados.
• Escale as filas de cobrança e default separadamente.
• Mantenha a liquidação idempotente; novas execuções são seguras por design.
• Aplique backpressure nas filas de e-mail e moderação com concorrência de workers, em vez de desativar novas tentativas.

Mídia e CDN

• Mova os uploads para o S3 antes que o ciclo de vida do disco local se torne um problema.
• Sirva pelo CloudFront com nomes de objeto imutáveis e cache de longa duração.
• Mantenha o acesso à origem privado; evite políticas de bucket públicas.
• Use a limpeza por asset apenas quando uma chave de objeto for reutilizada intencionalmente.

Checklist de capacidade

• Alertas de prontidão e 5xx estão conectados ao acionamento de plantão.
• O PostgreSQL tem folga para conexões, disco e IOPS.
• O Redis tem folga para cache e registros de idempotência.
• A profundidade da fila do Celery e o heartbeat do beat são monitorados.
• O armazenamento de objetos e a CDN estão fora do servidor web.
• A retenção de telemetria é configurada antes do crescimento, não depois.

Modelo de dados e permissões

As entidades que definem o FastRestful, os limites de inquilino em torno delas e as invariantes que mantêm dinheiro e versões consistentes.

Inquilinos

Organization é o limite do inquilino. Um usuário entra por meio de um Membership com um papel. A organização ativa é transmitida explicitamente e resolvida no servidor antes do acesso ao objeto.

Entidades principais

Invariantes

• Um produto tem apenas uma versão ativa por vez.
• O contrato e o catálogo de endpoints de uma versão ativa não podem ser editados.
• Uma assinatura tem termos comerciais imutáveis; alterações criam um novo plano.
• Uma chave de API pertence a exatamente um aplicativo e não pode transitar entre aplicativos.
• Um ID de evento de provedor é registrado uma única vez; reenvios não liquidam duas vezes.
• Os repasses seguem uma máquina de estados monotônica.
• Os lançamentos do ledger são somente de acréscimo.
• O último proprietário ativo do espaço de trabalho não pode ser removido nem rebaixado.

Verificações de permissão

Exclusão e retenção

• Tickets nunca são excluídos; eles permanecem como evidência de suporte.
• O histórico de versões ativas permanece disponível para auditoria mesmo após a descontinuação.
• Eventos de auditoria e recibos de provedores são somente de acréscimo.
• Logs de requisição e eventos de uso são removidos conforme a retenção configurada.
• As exclusões de mídia usam o ciclo de vida do asset e devem respeitar referências em uso.

Estendendo o modelo

1. Comece por um fluxo de trabalho real, não por um campo hipotético.
2. Mantenha dados exclusivos da plataforma fora de serializers anônimos.
3. Valide na camada de modelo/API; adicione restrições de banco de dados para dinheiro e transições de estado.
4. Adicione testes de contrato para permissões, limites de inquilino e idempotência.
5. Documente a superfície do operador antes de lançar o modelo.

Extensões

Estenda a experiência pública e o fluxo operacional sem bifurcar o núcleo: assets personalizados, seções de CMS, sobreposições de idioma, webhooks e padrões de administração.

CSS e JavaScript personalizados

Administração → Assets personalizados injeta um snippet no site público. Cada snippet tem um tipo, posicionamento, escopo e estado ativo.

• Cada salvamento cria uma revisão imutável com autor e nota; qualquer revisão pode ser restaurada como uma nova entrada.
• Visualize o site em produção em um iframe da administração com o snippet injetado à força.
• Use o nonce de CSP configurado tanto nas configurações do site quanto na política de borda; as tags injetadas o recebem automaticamente.
• Trate os snippets como código confiável do operador. Eles podem alterar o estilo ou instrumentar o site público.

Seções estruturadas do CMS

Páginas e posts são montados a partir de seções ordenadas. O editor inclui texto, tabela, código, imagem, vídeo, split, citação, abas, grupos de código, exemplos de endpoint, depoimentos, recursos, FAQ, etapas, métricas, cards, divisores, hero, faixa de logos, linha do tempo, lista de links, callouts, coleções de API, coleções de categoria, principais APIs e artigos recentes.

• Use seções estruturadas em vez de colar HTML arbitrário.
• Defina o rótulo da ação e o destino juntos.
• Use caminhos do site, HTTPS, mailto ou destinos tel.
• Mantenha textos alternativos de imagem significativos; o texto do corpo pode servir como legenda.
• Páginas publicadas entram na navegação e nos metadados do sitemap apenas quando estão ativas.

Sobreposições de idioma

O inglês é o bundle canônico; o francês é distribuído completo. Adicione outro idioma na administração, importe um bundle JSON ou TypeScript e substitua apenas as chaves necessárias.

• Os valores incluídos permanecem como fallback quando uma chave de sobreposição está vazia.
• Chaves desconhecidas são ignoradas e reportadas durante a importação.
• Exporte JSON ou TypeScript para tradução offline.
• Execute npm run export:i18n após editar o bundle do frontend e reinicie a API.

Webhooks de saída

Os webhooks de fornecedor entregam eventos assinados a endpoints HTTPS com histórico de entregas seguro para novas tentativas. Mantenha o segredo de assinatura no espaço de trabalho do fornecedor e verifique a assinatura antes de agir sobre um payload.

• Use uma URL de endpoint estável e retorne 2xx rapidamente.
• Trate os eventos como pelo menos uma vez e torne os handlers idempotentes.
• Use o log de entregas para inspecionar o status da resposta e as prévias.
• Não reutilize rotas de webhook de provedor de pagamento para eventos de fornecedor.

Padrão de extensão da administração

1. Registre o modelo com comportamento explícito de lista, filtro, busca e permissão.
2. Adicione um formulário de administração focado, em vez de expor campos internos brutos.
3. Use eventos de auditoria para ações que alteram estado.
4. Adicione uma página de prévia ou relatório apenas quando ela responder a uma pergunta real do operador.
5. Teste os limites de permissão e a separação entre serializers públicos e privados.

Padrão de extensão da API

• Mantenha o escopo de inquilino antes de cada consulta.
• Use serializers explícitos de requisição/resposta.
• Retorne códigos de erro estáveis para o comportamento do cliente.
• Torne as novas tentativas seguras com idempotência onde houver dinheiro ou estado envolvido.
• Adicione anotações OpenAPI para que o schema permaneça utilizável.

Administração

O plano de controle da equipe é uma superfície de administração do Django ciente de permissões para operações da plataforma. Ele não usa métricas de demonstração nem ignora permissões de modelo.

Limite de acesso

• O acesso da equipe exige is_staff. Um papel de admin no espaço de trabalho não é staff da plataforma.
• A autenticação de dois fatores pode ser exigida para todas as contas nas configurações do site.
• As permissões de modelo do Django e o comportamento registrado de ModelAdmin são respeitados.
• As leituras da administração podem ser mais amplas que as gravações; a propriedade do objeto e o estado do provedor ainda condicionam ações consequentes.
• Toda ação sensível deve criar um evento de auditoria com ator, destino e metadados.

Visão geral das operações

/admin/ mostra um snapshot ao vivo e somente leitura, construído a partir dos registros atuais: tráfego, APIs públicas, consumidores ativos, espaços de trabalho ativos, mensagens de contato, adoção de dois fatores, avisos da plataforma, filas de atenção, estado de pagamentos, fluxo de auditoria, experiência do site e cobertura de idiomas.

• Ações rápidas: criar API, revisar fornecedores, configurações do site, planos da plataforma, estúdio de conteúdo, newsletter, banners, links.
• Filas de decisão: fornecedores, moderação, recursos, restrições de segurança, suporte, webhooks com falha, repasses, faturas, caixa de entrada de contato.
• Painel de pagamentos: receita por provedor, assinaturas ativas, MRR, checkouts pendentes, recibos de webhook, reembolsos, links de gateway.

Seções do plano de controle

Moderação e segurança

• As denúncias carregam tipo/rótulo do alvo, categoria, evidências, prioridade, prazo de SLA, atribuição e resumos de resolução privados/públicos.
• A equipe configura janelas de SLA por prioridade, limites de escalonamento e janelas de recurso em Política de moderação.
• Denúncias encerradas elegíveis podem ser contestadas uma vez dentro da janela; a decisão pública original permanece anexada.
• Recursos aceitos reabrem o caso com um novo SLA derivado da política.
• Resolver uma denúncia mantida pode emitir uma medida de segurança auditável: advertência, restrição de comunidade, restrição de publicação ou restrição de plataforma.
• Os registros de aplicação de medidas mostram pontos, motivo público, datas de vigência e status, e somente o usuário afetado ou membros ativos do fornecedor podem lê-los.

Suporte e equipe

• Os tickets vinculam consumidor, produto, assinatura e contexto opcional de log de requisição.
• As mensagens avançam o timestamp de atividade do ticket para que as filas permaneçam ordenadas pela resposta mais recente.
• Convites de equipe, alterações de papel, desativação e remoção são exclusivos de proprietário/administrador; o último proprietário ativo não pode ser removido.
• Os convites são hasheados, de uso único, vinculados ao e-mail e expiram.

Planos da plataforma e reconciliação

• No máximo cinco planos de plataforma; os códigos permanecem estáveis após a criação.
• Preço de exibição, IDs de provedor mensal/anual, limite de espaços de trabalho, limite de listagem de APIs, benefícios e recomendação.
• Planos pagos ficam não publicados até existir um par de valor + ID de preço recorrente do provedor.
• A reconciliação de assinaturas da plataforma, somente leitura, mostra estado e direito sem permitir divergência da equipe em relação ao provedor.

Notificações da plataforma

Avisos criados pela equipe se distribuem em linhas de caixa de entrada por usuário. O público pode ser todas as contas ou apenas a equipe; os níveis são info, notice e critical. As contagens de entrega aparecem no snapshot de operações.

Auditoria e exportações

• Eventos de auditoria somente de acréscimo com ator, ação, organização, destino e metadados.
• Os trabalhos de exportação suportam fluxos de revisão de segurança e retenção.
• As listas da administração expõem visões filtradas, busca e CSV quando apropriado.
• Nunca coloque segredos brutos, chaves de API ou payloads de provedores nos metadados de auditoria.

Gerenciamento de idiomas

Idiomas do site → Gerenciar traduções mostra idiomas incluídos e gerenciados, cobertura e chaves ausentes. O francês incluído é editável por uma sobreposição da administração. A importação/exportação suporta JSON e literais TypeScript; chaves desconhecidas são ignoradas e reportadas.

Referência da API

A API do FastRestful é uma superfície do Django REST Framework com raiz em /api/v1/. O OpenAPI é servido pelo backend e é o contrato autoritativo.

URLs base e documentação

Autenticação

curl --request POST \
  --url 'https://api.example.com/api/v1/auth/token/' \
  --header 'Content-Type: application/json' \
  --data '{"username":"you@example.com","password":"..."}'

# Response
{"access":"...", "refresh":"...", "user": {...}}

curl --request GET \
  --url 'https://api.example.com/api/v1/dashboard/consumer/' \
  --header 'Authorization: Bearer <access>' \
  --header 'X-Organization: <organization-uuid>'

Namespaces

Mapa dos endpoints principais

Paginação e filtragem

Os endpoints de lista usam um contrato de número de página: page, page_size, search, ordering e filtros de recurso. As respostas usam {count, next, previous, results}. A ordenação aceita um nome de campo, opcionalmente prefixado com -.

GET /api/v1/products/?page=2&page_size=25&search=delivery&ordering=-rating_average
GET /api/v1/invoices/?status=paid&ordering=-created_at
GET /api/v1/request-logs/?status_class=server&ordering=-created_at

Formato dos erros

Erros de validação usam o objeto com chaves de campo do DRF. Erros de gateway e da plataforma usam um objeto JSON com um código legível por máquina, uma mensagem humana e metadados opcionais de nova tentativa.

{
  "detail": "Monthly quota exceeded.",
  "code": "quota_exceeded",
  "retry_after": 300
}

Formato da chamada ao gateway

GET https://signal-stack.api.example.com/v2/deliveries?limit=10
X-API-Key: fr_live_…
Idempotency-Key: request-8241

{
  "status": 200,
  "latency_ms": 84,
  "content_type": "application/json",
  "data_preview": "...",
  "headers": {...}
}

Webhooks

Existem dois tipos de webhook no FastRestful. Mantenha-os separados:

POST /api/v1/billing/stripe-webhook/
POST /api/v1/billing/paypal-webhook/
POST /api/v1/billing/flutterwave-webhook/
POST /api/v1/billing/paystack-webhook/
POST /api/v1/billing/razorpay-webhook/

• Os endpoints de webhook de fornecedor devem usar HTTPS e armazenar um segredo de assinatura.
• As entregas são assinadas, repetidas com segurança e registradas com status e prévia da resposta.
• Os webhooks de provedores de pagamento são registrados no painel de cada provedor, não na seção de webhooks de fornecedor.
• Os IDs de evento de provedor são únicos; eventos assinados duplicados são confirmados sem liquidação dupla.
• A configuração e as listas de eventos de webhook estão em Gateways de pagamento, passo a passo.

Fluxo de trabalho OpenAPI

cd backend
python3.11 manage.py spectacular --file schema.yml --validate

Use o schema gerado para SDKs, Postman ou testes de contrato. Os contratos OpenAPI de nível de produto são separados: eles são importados nas versões da API e promovidos pelo pipeline de versões.

Como destravar

Se um endpoint retornar um código inesperado, verifique primeiro o request ID, o método de autenticação, o header do espaço de trabalho e o estado da assinatura. O Guia de solução de problemas cobre os modos de falha comuns em ordem.