Instala FastRestful en tu computadora

Una primera instalación completa para alguien que nunca ha ejecutado una aplicación Django o Node. Sigue los pasos en orden. Cada paso termina con una comprobación para que sepas que funcionó antes de continuar.

Antes de empezar

No necesitas Docker, Redis, almacenamiento en la nube ni una cuenta de pago para la demo local. SQLite y una caché en memoria mantienen simple la primera ejecución.

1. Comprueba tus herramientas

Ejecuta estos comandos en tu terminal. Si falta alguno, instálalo primero y vuelve a abrir la terminal.

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

Deberías ver Python 3.11, Node 22.13 o superior y una versión de npm. Si no se encuentra python3.11, instala Python 3.11 desde python.org. Si Node es anterior a 22.13, instala la versión LTS actual desde nodejs.org.

2. Descarga el código

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

npm ci instala las versiones exactas de las dependencias del frontend desde el archivo de bloqueo. Puede tardar unos minutos. Deberías terminar con una carpeta node_modules y sin mensajes de error.

3. Crea el entorno del backend

Un entorno virtual mantiene los paquetes de Python de FastRestful separados del resto de tu computadora.

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

En Windows PowerShell, activa con .venv\Scripts\Activate.ps1 en lugar de source .venv/bin/activate. Cuando el entorno está activo, tu prompt suele comenzar con (.venv).

4. Crea el archivo de configuración del backend

Copia el archivo de ejemplo, luego genera dos secretos y pégalos en 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. Abre backend/.env en cualquier editor de texto.
2. Pega la primera salida en FIELD_ENCRYPTION_KEY=. Esto cifra las claves de API y los secretos de proveedores.
3. Pega la segunda salida en DJANGO_SECRET_KEY=.
4. Deja DJANGO_DEBUG=True, DATABASE_URL=sqlite:///db.sqlite3 y FRONTEND_URL=http://localhost:5055 para el desarrollo local.

5. Crea la base de datos y los datos de demostración

Asegúrate de que el entorno virtual siga activo y de que estés 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 crea las tablas de la base de datos. Los comandos de seed crean un marketplace de demostración, productos de API, contenido de documentación y perfiles de comunidad. Esto crea un archivo local backend/db.sqlite3.

6. Inicia el backend

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

Deja esta terminal abierta. El backend está listo cuando imprime Starting development server at http://127.0.0.1:5056/. Compruébalo en otra terminal con:

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

7. Inicia el frontend

Abre la segunda terminal y vuelve a la raíz del repositorio. El backend debe seguir ejecutándose en la terminal 1.

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

El servidor de desarrollo de Vite redirige las rutas de Django (/api/v1, /api/health, /api/schema, /api/docs, /admin, /static, /media) al backend en el puerto 5056. Las páginas públicas de productos como /api/{slug} siguen siendo servidas por el frontend.

8. Abre la aplicación e inicia sesión

Abre estas direcciones en tu navegador:

Inicia sesión en el plano de control con admin / Admin12345!.

Lista de comprobación de la primera ejecución

• El sitio público carga y el catálogo del marketplace es visible.
• El plano de control se abre y puedes iniciar sesión como admin.
• Configuración del sitio, Planes de plataforma y la sección de contenido del sitio se abren sin errores.
• Una cuenta de consumidor puede crear una aplicación y una clave de API.
• Una solicitud a través del gateway aparece en los registros de solicitudes.

Qué hacer a continuación

• Sigue Inicio rápido: tu primera solicitud al gateway para hacer una llamada de API con medición.
• Lee Configuración para entender qué ajustes importan primero.
• Conecta los pagos con Pasarelas de pago, paso a paso cuando estés listo para cobrar dinero real.
• Usa Despliegue antes de poner la aplicación en un servidor público.

Problemas comunes de instalación

Inicio rápido: tu primera solicitud al gateway

Pasa de una instalación local limpia a una llamada de API con medición. Te suscribirás a una API de demostración, crearás una clave, enviarás una solicitud y verás el evento de uso y el registro de la solicitud.

1. Inicia sesión y elige un espacio de trabajo

Abre http://127.0.0.1:5055 e inicia sesión con admin / Admin12345!, o registra una cuenta nueva. Un espacio de trabajo (organización) agrupa tus aplicaciones, claves, suscripciones y facturas.

El espacio de trabajo activo viaja en el encabezado X-Organization para las llamadas a la API. La consola del navegador lo establece automáticamente. Cuando llames a la API por tu cuenta, debes incluirlo, a menos que la solicitud use una clave de API en lugar de una sesión de navegador.

2. Suscríbete a un producto

Abre el marketplace, elige un producto con una versión publicada y selecciona un plan. El producto SignalStack incluido en el seed tiene una versión 2.4.0 publicada y tres planes.

Si el plan es gratuito, la activación es inmediata. Si el plan es de pago, FastRestful abre el proveedor de pago configurado. Una redirección del navegador nunca otorga acceso por sí sola: la suscripción se activa solo después de que un webhook firmado del proveedor liquide la primera factura.

3. Crea una aplicación y una clave

En la consola del consumidor, crea una aplicación y luego emite una clave de API. La clave sin procesar se muestra una vez, así que cópiala de inmediato en un gestor de contraseñas o en un archivo local .env.

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.

Los scopes son full, execute o read. Elige el scope más restrictivo que funcione. Si pierdes la clave, revócala y emite una nueva; la clave anterior deja de funcionar de inmediato.

4. Envía una solicitud a través del gateway

Reemplaza fr_live_… con la clave que acabas de crear. Este ejemplo usa el producto SignalStack incluido en el seed y su alias de ruta.

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'

Con el enrutamiento por host de producto habilitado, la misma solicitud usa https://{product-slug}.{FASTRESTFUL_API_HOST_SUFFIX}/.... Ambas puertas de entrada comparten la misma suscripción, cuota, límite de velocidad, idempotencia, medición y pipeline de registro de solicitudes.

5. Inspecciona el resultado

• Evento de uso: registrado del lado del servidor con estado y latencia.
• Contador mensual: incrementado para la aplicación de cuotas y el excedente.
• Registro de la solicitud: vistas previas redactadas de la solicitud y la respuesta, visibles para el consumidor y el proveedor.
• Panel: solicitudes, tasa de éxito, gasto, latencia, API principales y actividad reciente.

Abre el panel del consumidor y el registro de solicitudes. Deberías ver la solicitud que acabas de hacer. Si no la ves, revisa la terminal que ejecuta el backend por si hay un traceback.

6. Publica una versión (opcional)

En el estudio de proveedores, abre el banco de trabajo de un producto, importa un contrato OpenAPI en una versión en borrador, concilia la documentación de los endpoints, ejecuta el diff, envía a revisión y promociona. Una versión publicada requiere un contrato OpenAPI compatible y no vacío, y un catálogo de endpoints que coincida exactamente.

Para conocer el ciclo de vida completo, lee Productos de API y versiones.

Si la solicitud falla

Configuración, sin agobios

La mayoría de las instalaciones solo necesitan un pequeño conjunto de ajustes para funcionar. Empieza con el mínimo que se indica abajo y luego agrega las integraciones que realmente uses. Las tablas extensas que aparecen más adelante son de referencia, no una lista de comprobación.

Dónde viven los ajustes

Ajustes locales mínimos

Después de copiar .env.example, estos son los únicos valores que debes cambiar para la demo 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

Genera las dos claves con los comandos de Instalación → Crear el archivo de configuración del backend.

Ajustes mínimos de producción

Producción añade PostgreSQL, Redis, un nombre de host real y orígenes HTTPS. Reemplaza cada marcador de posición con tus propios 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>

Cómo cambiar los ajustes de forma segura

1. Cambia una integración a la vez.

   Configura, prueba y verifica antes de pasar al siguiente proveedor. Así los fallos son evidentes.

2. Edita backend/.env en el servidor.

   No edites archivos dentro de un contenedor en ejecución que será reemplazado. Cuando sea posible, guarda los secretos en el almacén de secretos de tu plataforma de despliegue.

3. Reinicia el backend y los workers.

   Los cambios de entorno se leen al iniciar el proceso. Reinicia Gunicorn, el worker de Celery y Celery beat después de editar .env.

4. Recompila el frontend para los cambios de NEXT_PUBLIC_*.

   Los valores públicos del frontend se compilan en la build. Reiniciar el frontend no es suficiente.

5. Ejecuta la acción de prueba del proveedor.

   Usa el checkout de prueba, el correo de prueba o el registro de entregas de webhooks antes de enviar tráfico real.

Referencia de variables de entorno principales

Entorno del frontend

Gateway y enrutamiento por host

Autenticación y SSO

Correo electrónico y newsletters

Los ajustes SMTP de la newsletter también se pueden guardar en el estudio de newsletters y anulan el remitente del entorno para las campañas. Consulta Estudio de newsletters.

Referencia de pagos y desembolsos

Admin → Pasarelas de pago guarda las mismas credenciales en la base de datos. Un registro de la base de datos anula el campo del entorno campo por campo, y deshabilitarlo apaga el proveedor en todas partes aunque las claves del entorno sigan definidas.

Almacenamiento de medios y especificaciones

Enlaces cortos

SHORTLINK_BASE_URL establece el origen público de los enlaces cortos, por ejemplo https://go.example.com. Cuando está vacío, usa NEWSLETTER_TRACKING_BASE_URL y luego FRONTEND_URL. El comando checklinks se puede programar desde cron o Celery beat.

Precedencia y recargas

• Los valores de entorno proporcionan los valores predeterminados del despliegue; los registros de gateway del admin anulan campo por campo.
• Los cambios del entorno del backend requieren reiniciar el proceso. Algunos ajustes en caché (indicador de mantenimiento, idioma de origen) se borran automáticamente al guardar el modelo.
• Las variables públicas del frontend se integran en el momento de la compilación. Recompila después de cambiar los valores de NEXT_PUBLIC_*.
• Después de cambiar lib/i18n/*.json, ejecuta npm run export:i18n y reinicia el backend para que su paquete de origen en caché esté actualizado.

Despliegue

Lleva FastRestful de una demo local con SQLite a un despliegue en producción con PostgreSQL, Redis, almacenamiento de objetos, un servidor WSGI, TLS y un frontend estático. La plataforma está diseñada para autoalojarse.

Antes de desplegar

• Un nombre de dominio y acceso a DNS para los hosts del frontend y de la API.
• Una base de datos PostgreSQL 16 y una instancia de Redis 7.
• Terminación HTTPS, ya sea en tu proxy o en el edge.
• Un DJANGO_SECRET_KEY generado y un FIELD_ENCRYPTION_KEY respaldado.
• Un plan para el almacenamiento de medios: el disco local solo es aceptable para una prueba en un único servidor; usa almacenamiento compatible con S3 para despliegues reales.
• Un destino de copias de seguridad fuera del servidor de aplicaciones.

Orden recomendado

1. Despliega el backend y la base de datos.

   Haz que /api/health/ready pase antes de tocar el frontend.

2. Despliega el frontend.

   Apúntalo al origen de la API y agrega el origen del frontend a los ajustes de CORS y CSRF.

3. Configura el correo y el almacenamiento.

   Usa Integraciones externas. Verifica un correo de prueba y una carga de prueba.

4. Conecta los pagos solo cuando estés listo para vender.

   Usa Pasarelas de pago, paso a paso y completa primero el checkout de prueba.

5. Activa la licencia y programa los heartbeats.

   Usa Licencias y actualizaciones oficiales.

6. Configura copias de seguridad y monitorización.

   Usa Copias de seguridad y actualizaciones y Observabilidad.

Topología 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)

Puedes servir el frontend y la API desde un mismo origen o separarlos. Si los separas, establece NEXT_PUBLIC_API_URL en el origen de la API, agrega el origen del frontend a CORS_ALLOWED_ORIGINS y CSRF_TRUSTED_ORIGINS, y establece FRONTEND_URL en el origen público del frontend.

Docker Compose

El repositorio incluye un archivo Compose con PostgreSQL, la API, Redis y perfiles opcionales 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

Ejecuta las migraciones y los seeds dentro del contenedor de la API después de que la base de datos esté sana:

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

Configuración manual de producción

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 inverso 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 producto comodín

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;
    }
}

Agrega un registro DNS comodín, emite un certificado comodín con un desafío DNS-01 e incluye el host comodín en DJANGO_ALLOWED_HOSTS. Establece FASTRESTFUL_API_HOST_SUFFIX=api.example.com.

Compilación y alojamiento del 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

Despliega la salida de la compilación en tu host estático o en un entorno de ejecución compatible con Node. La build es autocontenida y no requiere un plano de control de sitio gestionado. Si usas Cloudflare, vincula D1/Images solo cuando el despliegue necesite esas funciones.

Archivos estáticos y multimedia

• Estáticos: ejecuta collectstatic, sirve /static/ desde Nginx o tu CDN.
• Medios locales: sirve /media/ desde Nginx para despliegues pequeños.
• Medios en producción: usa S3 + CloudFront con OAC, mantén el bucket privado, establece MEDIA_STORAGE=s3 y no establezcas MEDIA_S3_ACL a menos que sirvas directamente desde S3.
• Especificaciones: deja SPEC_STORAGE=db para una instalación pequeña; usa S3 para archivos de contratos más grandes.

Comprobaciones de estado

Actualizaciones y copias de seguridad

# 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

Controles de producción

• DJANGO_DEBUG=False, secreto de 50 caracteres o más, clave Fernet válida.
• PostgreSQL, Redis, orígenes HTTPS y hosts permitidos explícitos.
• Credenciales de admin cambiadas; usuarios de demostración eliminados o deshabilitados.
• Webhooks de pago y desembolso registrados con el secreto firmado correcto.
• Credenciales SMTP y de proveedores probadas; dominio del remitente autenticado.
• S3/CloudFront configurados si las cargas de medios están habilitadas.
• Worker del planificador + beat en ejecución, o equivalentes de cron instalados.
• Copias de seguridad probadas restaurándolas en un entorno separado.
• La monitorización cubre la preparación, la tasa de 5xx, la latencia del gateway, los fallos de webhooks y la profundidad de la cola.
• Páginas legales, términos, privacidad y contacto de soporte revisados por el operador.

Operaciones

Liquidación programada, entrega de notificaciones, comprobaciones de disponibilidad, retención de telemetría, sondas de estado y los comandos operativos que mantienen FastRestful en buen estado.

Programación de Celery

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

Sin un broker, Celery se ejecuta en modo eager dentro del proceso. En producción, establece REDIS_URL o CELERY_BROKER_URL y ejecuta tanto el worker como beat como servicios separados.

Comandos operativos

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 mantenimiento

Habilita Operaciones de la plataforma → Modo de mantenimiento en la configuración del sitio. El frontend devuelve una página 503 con la marca, las llamadas a la API de clientes y al gateway devuelven una respuesta maintenance_mode legible por máquina con Retry-After: 300, y la documentación/Swagger se pausan.

El admin del personal, las sondas de estado, los callbacks del proveedor de identidad y los webhooks firmados de pago/desembolso siguen disponibles para que la plataforma pueda recuperarse de forma segura y no se pierdan proveedores.

Monitorización

• Sonda de preparación para la base de datos y la caché compartida.
• Tasa de 5xx de la API y latencia p95 por espacio de nombres.
• Tasa de errores del upstream del gateway y eventos de circuito abierto.
• Cola de fallos de webhooks y excepciones de pagos.
• Profundidad de la cola de Celery y heartbeat de beat.
• Tasas de rebote/queja de correo y tasa de bajas.
• Crecimiento del almacenamiento de medios y tasa de aciertos de la caché de CDN.
• Conexiones de PostgreSQL, consultas lentas, disco y éxito de las copias de seguridad.

Copias de seguridad

Notas de escalado

• Ejecuta varias instancias de Gunicorn/Django detrás de un balanceador de carga; mantén las sesiones y la caché en Redis.
• Ejecuta workers de Celery separados de los procesos web y escala las colas de facturación y predeterminada de forma independiente.
• Los límites de velocidad del gateway usan la caché compartida; una caída de la caché devuelve un 503 reintentable en lugar de fallar abierto.
• Usa pooling de conexiones de PostgreSQL si aumenta el número de workers.
• Mueve los medios a S3/CloudFront antes de que el tráfico haga doloroso el ciclo de vida del disco local.
• Mantén explícita la retención de telemetría; los registros de solicitudes y los eventos de uso no están pensados para crecer indefinidamente.

Seguridad

Comportamiento crítico de seguridad en FastRestful: custodia de claves, aislamiento de inquilinos, protección SSRF del gateway, política de origen del navegador, almacenamiento de secretos, evidencia de auditoría y la lista de comprobación de endurecimiento para producción.

Custodia de claves de API

• Las claves sin procesar se devuelven exactamente una vez al crearlas o rotarlas. Los serializadores o el admin nunca las vuelven a mostrar.
• Formas almacenadas: un prefijo de búsqueda, un hash SHA-256 para comparación en tiempo constante y una copia cifrada con Fernet para uso del gateway del lado del servidor.
• La rotación revoca la clave anterior y emite una nueva en una sola llamada. Una clave revocada no se puede usar para emitir reemplazos.
• Los scopes restringen el acceso: full, execute o read. Las actualizaciones solo pueden reducir un scope, nunca ampliarlo.
• Una clave está vinculada a su aplicación y suscripción; no puede cruzar aplicaciones ni espacios de trabajo.

Aislamiento de inquilinos

• X-Organization selecciona el inquilino activo. Los permisos del lado del servidor vuelven a comprobar la pertenencia de cada objeto.
• Las lecturas de proveedores tienen doble alcance: un proveedor ve sus propios productos, suscripciones, facturas y registros; un consumidor solo ve su propio espacio de trabajo.
• Los campos de propiedad son inmutables a través de la API.
• Los serializadores públicos son explícitos, no listas blancas de un modelo privado. Las métricas operativas y los campos privados quedan fuera de las respuestas anónimas.
• Los superusuarios pueden leer entre inquilinos por motivos de soporte, pero las escrituras siguen requiriendo el scope propietario correcto, salvo en operaciones explícitas de plataforma.

Seguridad del gateway

• Los upstreams deben usar HTTPS, resolverse a direcciones públicas, permanecer en el host original y evitar patrones de traversal.
• No se siguen las redirecciones. Se comprueban las respuestas DNS y la IP pública seleccionada se fija a través de la conexión TLS para evitar el rebinding.
• Los tiempos de espera, los límites de cuerpo, los límites de carga y los reintentos acotados se aplican antes de reenviar.
• Los secretos de los proveedores se adjuntan solo del lado del servidor; nunca llegan al navegador.
• Las claves de idempotencia se almacenan como hashes de token con una huella de la solicitud y una respuesta redactada, nunca como cuerpos de solicitud sin procesar.
• Las vistas previas de respuestas tienen un límite de longitud y redactan Set-Cookie, Authorization y X-API-Key.
• Una caída de la caché compartida devuelve un 503 reintentable antes de reservar cuota; el gateway no falla abierto.

Seguridad del navegador y de los orígenes

• Producción aplica HTTPS, HSTS, cookies seguras y una política de referrer estricta.
• CORS_ALLOWED_ORIGINS y CSRF_TRUSTED_ORIGINS deben nombrar exactamente el frontend público.
• El frontend puede leer las cookies CSRF porque la sesión compartida de Django se usa para escrituras del admin y de la consola; nunca las expongas entre orígenes.
• Los recursos CSS/JS personalizados son contenido de operador de confianza. Usa un nonce de CSP, previsualiza antes de activar y revisa el historial de revisiones.
• El modo de mantenimiento mantiene disponibles los callbacks de proveedores y las rutas del proveedor de identidad.

Gestión de secretos

Endurecimiento de la autenticación

• Habilita el segundo factor obligatorio para el personal y, opcionalmente, para todas las cuentas en la configuración del sitio.
• Usa OIDC o SAML para la identidad empresarial; el inicio de sesión con contraseña puede quedar como fallback.
• Mantén los tokens de acceso de corta duración (15 minutos) y los refresh tokens rotativos en lista negra después de la rotación.
• Las invitaciones se almacenan con hash, son de un solo uso, están vinculadas al correo y caducan a los siete días.
• El acceso al admin requiere is_staff; el espacio de trabajo admin no es un rol de personal de la plataforma.
• Las respuestas de restablecimiento de contraseña no revelan si existe una cuenta.

Auditoría y evidencia

• Las acciones del admin, las decisiones de moderación, los cambios de estado de facturación, la conciliación de pagos, los cambios de ajustes y la recuperación de cuentas generan eventos de auditoría.
• Los recibos de eventos del proveedor son de solo anexado y rechazan conflictos de payload, lo que hace seguros los reintentos.
• Los asientos del libro mayor son de solo anexado. Los reembolsos posteriores al desembolso crean asientos de recuperación y reversión de comisiones.
• Los trabajos de exportación de auditoría admiten retención y revisión sin acceso directo a la base de datos.

Lista de verificación para producción

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

• Cuentas de demostración y datos de inicialización eliminados de producción.
• Se requiere segundo factor para el personal; SSO probado de extremo a extremo.
• Webhooks de pago verificados con el secreto firmado del proveedor.
• Bucket de medios privado; OAC de CDN configurado; sin acceso de escritura con comodín.
• Copias de seguridad cifradas y con restauración probada.
• Los registros excluyen secretos y redactan los payloads de los consumidores.
• Dependencias e imágenes de contenedor parcheadas según un calendario.
• Contacto de incidentes y vía de divulgación de vulnerabilidades publicados.

Licencias & actualizaciones oficiales

FastRestful es código fuente con licencia que se vende a través de Dakidarts. Conecta la clave de compra a LicenseHub para verificar versiones oficiales firmadas, instalar una versión más reciente o volver a una anterior. El gateway en ejecución sigue funcionando si LicenseHub no está disponible temporalmente.

Qué hace el centro de actualizaciones

Parte 1 — Activa tu licencia

1. Compra FastRestful y abre el panel de Dakidarts.

   Ve a Panel → Licencias y copia la clave completa. Empieza por DK-FRST-….

2. Abre el centro de actualizaciones.

   Inicia sesión como personal y abre https://your-domain/admin/updates/. La barra lateral lo llama Actualizaciones de software.

3. Pega la clave de licencia.

   Usa la clave completa, incluidos los guiones. Se cifra en reposo y solo se muestra una forma enmascarada después de la activación.

4. Confirma la URL de LicenseHub.

   La predeterminada es https://dakidarts.com. Consérvala salvo que Dakidarts te indique otro origen. Se requiere HTTPS fuera de la depuración local.

5. Elige el entorno.

   Producción consume un asiento de producción. Staging y Desarrollo consumen asientos no de producción. Elige el que corresponda a esta instalación.

6. Opcionalmente, añade el dominio de producción.

   Por ejemplo, api.example.com. Esto te ayuda a identificar la instalación en el portal de clientes.

7. Elige un canal de versiones.

   Empieza con Stable. Usa Beta o Preview solo en un entorno de prueba desechable.

8. Haz clic en Activar licencia.

   La activación crea o reutiliza un installation_id persistente y vincula un asiento. Después, la página muestra la edición, las ventanas de actualización y soporte, el número de activaciones y el último latido.

Si la activación falla, el error se muestra en la página. Las causas más comunes son una clave caducada, un límite de asientos o una clave copiada con un espacio final.

Parte 2 — Instala una actualización desde el admin

1. Haz una copia de seguridad.

   Haz una copia de seguridad de PostgreSQL, los medios, .env y cualquier archivo personalizado. Confirma que la copia se restaura antes de necesitarla.

2. Abre Admin → Actualizaciones de software.

   La página muestra la versión en ejecución, la versión instalada y el estado de la conexión.

3. Haz clic en Buscar actualizaciones.

   LicenseHub devuelve todas las versiones que cubre tu ventana de actualización: más recientes, actuales y anteriores.

4. Haz clic en Descargar & preparar en la versión de destino.

   FastRestful descarga cada artefacto, verifica el SHA-256, verifica la firma del manifiesto Ed25519 y extrae el paquete en FASTRESTFUL_UPDATE_DIR/<version>/bundle/.

5. Haz clic en Instalar.

   El admin inicia un worker independiente para que las migraciones o una compilación no superen el tiempo de espera de la solicitud web. La página se actualiza mientras se ejecuta.

6. Espera a «instalado» y al aviso de reinicio.

   El proceso en ejecución sigue usando el código anterior hasta que reinicies. La página muestra Instalado … · reinicio requerido.

7. Reinicia los servicios.

   Reinicia Gunicorn o tu servidor de aplicaciones, el worker y beat de Celery, y el proceso del frontend si se ejecuta en el mismo host. Usa tu gestor de servicios, no la página de admin. Ejemplos de comandos de systemd:

   ejemplo de systemdCopiar

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

8. Verifica.

   Confirma la versión en el centro de actualizaciones, abre /api/health/ready y haz una solicitud de prueba a través del gateway.

Parte 3 — Actualiza desde la línea de comandos

Usa esto cuando el admin no esté disponible o cuando quieras instalar en una sesión 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

La instalación por CLI es síncrona e imprime el registro capturado del instalador. La instalación desde el admin es asíncrona. Ambas verifican los mismos artefactos firmados antes de ejecutar el instalador.

Mantén actualizado el arrendamiento de la licencia

El arrendamiento del certificado es de 24 horas. Un latido cada seis horas deja margen para cortes transitorios. Una comprobación diaria basta para descubrir versiones.

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

Un latido fallido registra el error en el admin, pero no detiene el gateway.

Parte 4 — Vuelve a una versión anterior

1. Abre la lista de versiones.

   Las versiones anteriores cubiertas por tu ventana de actualización aparecen junto a la versión actual.

2. Haz clic en Instalar versión anterior en la versión de destino.

   El centro de actualizaciones marca la instalación con esa versión. Es una instalación de versión normal, no un restablecimiento destructivo.

3. Reinicia los servicios.

   El proceso reiniciado toma el árbol de código anterior.

4. Comprueba la base de datos.

   Si la versión más reciente aplicó una migración irreversible, restaura la copia de seguridad de la base de datos previa a la actualización. Mantén juntas la copia de la base de datos y la del código.

Parte 5 — Canales y entornos

El canal se guarda en la conexión y se envía con cada comprobación. Cámbialo en la página de actualizaciones o durante la activación.

Parte 6 — Despliegues con Docker y basados en imágenes

El instalador predeterminado actualiza una copia de trabajo del código. En un contenedor, los cambios del sistema de archivos no son duraderos cuando se recrea el contenedor. Elige una de estas opciones:

• Compila y despliega una imagen nueva a partir de la versión descargada en tu pipeline habitual.
• Define un FASTRESTFUL_UPDATE_INSTALL_SCRIPT personalizado que extraiga la imagen nueva o active el despliegue de tu plataforma.
• Usa fastrestful_update download para obtener y verificar la versión, y luego aplícala fuera del contenedor en ejecución.

Parte 7 — Configuración

Parte 8 — Solución de problemas

Parte 9 — Notas de seguridad

• Solo el personal con licensing.change_licenseconnection puede abrir el centro de actualizaciones.
• La protección CSRF se aplica en cada acción.
• La clave de compra se cifra en reposo y nunca se muestra después de la activación.
• Las descargas usan tokens de LicenseHub de corta duración. Los artefactos se verifican con SHA-256 y la firma del manifiesto Ed25519 antes de extraerlos o ejecutarlos.
• La extracción de archivos rechaza rutas absolutas, recorridos, enlaces simbólicos y enlaces duros.
• Mantén privado el directorio de actualizaciones. No lo sirvas desde Nginx ni desde almacenamiento de objetos.
• Una interrupción de LicenseHub o una ventana de actualización caducada no dejan fuera de línea un gateway en ejecución. La revocación bloquea las descargas oficiales; no detiene de forma remota una instalación perpetua existente.

Para responsables de versiones

Las versiones oficiales son artefactos privados de LicenseHub. Un paquete puede contener un archivo de código o varios artefactos (código, migraciones, frontend, docs). Todos los artefactos se extraen en el mismo directorio bundle/ en el orden que devuelve LicenseHub.

El paquete debe incluir un instalador en una de estas rutas:

• install.sh
• scripts/install.sh
• scripts/install-release.sh
• la ruta en FASTRESTFUL_UPDATE_INSTALL_SCRIPT

scripts/install-release.sh en este repositorio es la implementación de referencia. Cópialo a la raíz del paquete de la versión como install.sh. Hace una instantánea del código y la base de datos anteriores, superpone el código nuevo, conserva los secretos, medios y archivos de base de datos locales, instala las dependencias del backend, ejecuta las migraciones de Django e imprime el requisito de reinicio.

El instalador recibe FASTRESTFUL_RELEASE_DIR, FASTRESTFUL_BUNDLE_DIR, FASTRESTFUL_UPDATE_DIR, FASTRESTFUL_APP_ROOT, FASTRESTFUL_FROM_VERSION, FASTRESTFUL_TO_VERSION, FASTRESTFUL_PYTHON y FASTRESTFUL_INSTALL_LOG. Se ejecuta con bash, un tiempo de espera y un registro capturado. Debe ser no interactivo y dejar la instalación recuperable si falla.

Solución de problemas

Los fallos con los que más se topan los equipos — y las comprobaciones que los resuelven.

La API devuelve 401 o 403

• 401: falta el token de portador o caducó, falta X-API-Key, o la clave no se resuelve. Actualiza el JWT o emite una clave nueva.
• 403: autenticado pero sin permiso. Comprueba la pertenencia al espacio de trabajo, el rol, el estado de la suscripción y el derecho al endpoint.
• Las llamadas externas al gateway deben usar X-API-Key (o una clave de portador fr_live_…), no un JWT del panel.
• Las llamadas del panel necesitan tanto Authorization: Bearer <access> como X-Organization: <uuid>.

Las solicitudes del navegador fallan con CORS o CSRF

• Añade el origen exacto del frontend a CORS_ALLOWED_ORIGINS y CSRF_TRUSTED_ORIGINS.
• Usa el mismo esquema, host y puerto que usa el navegador. localhost y 127.0.0.1 son orígenes distintos.
• Vuelve a compilar el frontend después de cambiar NEXT_PUBLIC_API_URL o NEXT_PUBLIC_SITE_URL.
• Para llamadas al gateway desde orígenes de consumidores arbitrarios, configura expresiones regulares de CORS o CORS permisivo solo en el host de la API del producto.

Falla una solicitud al gateway

Fallan las migraciones o el esquema está desactualizado

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

Si una migración entra en conflicto con una rama personalizada, resuélvelo en una copia de la base de datos y nunca edites una migración ya aplicada en producción.

Los medios devuelven 404 o un recurso de CDN obsoleto

• Modo local: confirma que MEDIA_ROOT tiene permisos de escritura y que Nginx sirve /media/.
• Modo S3: verifica los permisos del bucket, la región, el endpoint y el origen de la CDN. Mantén el bucket privado cuando uses OAC.
• Después de reemplazar un recurso, purga la distribución de CDN o usa la acción de purga del admin.
• Confirma que MEDIA_CDN_DOMAIN no tenga una ruta final y que coincida con el certificado.

Fallan los webhooks de pago

Empieza por la configuración específica del proveedor en Pasarelas de pago, paso a paso. Luego comprueba esto en orden:

1. La URL es exacta y pública. Registra /api/v1/billing/stripe-webhook/, /paypal-webhook/, /flutterwave-webhook/, /paystack-webhook/ o /razorpay-webhook/ en el mismo nombre de host al que llegan los usuarios. Localhost no funcionará.
2. Los valores de prueba y producción no se mezclan. Una clave de prueba con un ID de webhook de producción (o al revés) hace fallar todas las entregas.
3. El secreto es del tipo correcto. Stripe necesita el secreto de firma del endpoint (whsec_…), no la clave secreta de API. Flutterwave necesita el hash secreto que creaste. Razorpay necesita el secreto de firma del webhook.
4. PayPal usa un ID de webhook, no un secreto. Pon el ID de la misma app y entorno de PayPal en PAYPAL_WEBHOOK_ID. FastRestful verifica cada evento con la API de verificación de firmas de PayPal. Un ID faltante o incorrecto devuelve Bad signature. Consulta Solución de problemas de webhooks de PayPal.
5. Paystack normalmente no necesita secreto de webhook. Deja PAYSTACK_WEBHOOK_SECRET en blanco; FastRestful verifica con PAYSTACK_SECRET_KEY.
6. Los tipos de evento están seleccionados. Un webhook accesible pero no suscrito al evento de liquidación deja la factura abierta.
7. Tu proxy conserva las cabeceras del proveedor. Nginx, Cloudflare y los balanceadores de carga deben reenviar las cabeceras de firma sin cambios.
8. El importe y la moneda coinciden. FastRestful rechaza una liquidación que no coincide con la factura.
9. Revisa el recibo. Abre Admin → Eventos de pago; los ID de evento duplicados se confirman sin liquidar dos veces. Reenvía el evento fallido desde el panel del proveedor.

El correo no se envía

• Desarrollo usa el backend de correo de consola. Revisa la salida de la terminal.
• Producción usa SMTP de forma predeterminada. Prueba el host, el puerto, TLS, el nombre de usuario y la contraseña.
• La configuración del boletín puede anular el remitente del entorno; confirma el proveedor activo en el estudio.
• Comprueba SPF, DKIM y DMARC antes de culpar a la cola. Las tasas de rebotes y quejas suprimen envíos futuros.

Problemas de compilación o rutas del frontend

• Ejecuta npm run typecheck y npm test antes de depurar el despliegue.
• Una página en blanco basada en API suele significar que el origen de la API no es accesible o que CORS está incompleto.
• Si las páginas públicas de producto funcionan pero /api/{slug} devuelve 404, confirma que el proxy solo reenvíe los namespaces de Django y no la ruta de producto del frontend.
• Después de cambios de i18n, ejecuta npm run export:i18n y reinicia Django.

Los cambios de idioma no aparecen

• El francés incluido se carga desde el bundle del frontend; las superposiciones del admin vienen de la API de idioma activo.
• Guarda la superposición del admin, confirma que el idioma esté activo y fuerza la actualización del navegador.
• Después de cambiar fr.json, exporta el código del backend y reinicia la API para vaciar su caché de proceso.
• Comprueba si hay una preferencia de idioma obsoleta en localStorage.

Autenticación & acceso

FastRestful usa tokens de acceso JWT de corta duración, tokens de actualización rotativos y una sesión de navegador compartida de Django. El mismo inicio de sesión puede abrir la consola del consumidor, el estudio del proveedor y el admin del personal.

Flujos de autenticación

Cabeceras de solicitud

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

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

El panel usa JWT más la cabecera explícita del espacio de trabajo activo. Los consumidores externos usan una clave de API de producto suscrita. Un JWT del panel no debe usarse como clave de API de cliente, y una clave de API sin procesar no debe enviarse a los endpoints del panel.

Roles del espacio de trabajo

El acceso del personal de la plataforma es independiente: requiere is_staff y nunca se deriva de un rol admin del espacio de trabajo. Los permisos del personal se aplican por modelo y acción del admin de Django.

Autenticación de dos factores

• Inscripción de autenticador TOTP con QR/URI de aprovisionamiento y códigos de recuperación de un solo uso.
• Los códigos de recuperación se muestran una vez, se almacenan con hash y se regeneran como conjunto.
• Un superusuario puede exigir dos factores para todas las cuentas en Configuración del sitio.
• El acceso al admin puede bloquearse hasta confirmar la inscripción; la consola muestra una puerta de configuración dedicada.

Invitaciones a espacios de trabajo

Los propietarios y admins invitan por correo y asignan un rol. Los tokens de invitación se almacenan con hash, son de un solo uso, están vinculados al correo, caducan a los siete días y se pueden reenviar o revocar. Aceptar una invitación requiere un usuario autenticado con el correo coincidente y puede reactivar una membresía inactiva.

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": "..."}

Configuración de SSO

OIDC

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

Registra la URL de callback https://api.example.com/api/v1/auth/sso/callback/ con el proveedor de identidad. Los destinos relativos seguros y los tokens de invitación sobreviven al viaje de ida y vuelta.

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

Instala lxml antes de habilitar SAML. Los metadatos se sirven en /api/v1/auth/saml/metadata/; configura el IdP con la URL del servicio de consumo de aserciones del endpoint de inicio.

Ciclo de vida de las claves de API

• Crea una clave en la aplicación seleccionada; la clave sin procesar aparece una sola vez.
• Envíala como X-API-Key o como credencial de portador fr_live_….
• Rota para revocar la clave anterior y emitir una nueva de forma atómica.
• Revoca de inmediato cuando se pierda una credencial; no hay recuperación del valor sin procesar.
• Usa el alcance execute o read para privilegio mínimo cuando el cliente no necesite administración completa.

Productos de API & versiones

Un producto es la identidad pública. Una versión es el contrato inmutable. Los endpoints, la documentación, la política del gateway y los derechos del plan se mantienen dentro de ese límite de versión.

El modelo de producto

Crea y publica un producto

1. En el estudio del proveedor, crea el producto con nombre, slug, categoría, eslogan, README y URL del upstream.
2. Crea una versión en borrador e importa un contrato OpenAPI 3.x o Swagger 2.0.
3. Revisa el catálogo de endpoints reconciliado y la documentación de endpoints.
4. Crea al menos un plan público y configura cuotas, límites de velocidad y derechos.
5. Ejecuta la preparación para publicación; las cuatro comprobaciones deben pasar.
6. Envía la versión para revisión y luego promuévela a producción.
7. Publica el producto. La versión activa anterior se retira automáticamente.

Importación de 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."
  }'

La importación crea o actualiza una versión en borrador, reconcilia las filas de endpoints desde paths, informa de los endpoints creados, actualizados y eliminados, y conserva los campos de política del gateway en las operaciones retenidas. Se rechaza la importación sobre una versión activa.

Preparación para publicación

Máquina de estados de la versión

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

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

• Las versiones activas son inmutables: las ediciones se rechazan a nivel de modelo y serializador.
• La promoción retira la versión activa anterior para mantener una única versión activa.
• El contrato y el catálogo de endpoints deben coincidir exactamente antes de la promoción.
• Los derechos de endpoints del plan se reasignan por método + ruta cuando una nueva versión activa reemplaza a la anterior.

Informes de cambios incompatibles

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.

Enrutamiento de hosts de producto

Cada producto publicado tiene dos puertas de entrada equivalentes:

El middleware lee la primera etiqueta del host como slug del producto. Los alias de ruta se registran como una ruta final, por lo que las rutas de API con nombre siempre tienen prioridad. Los productos desconocidos devuelven un 404 con una pista; las solicitudes sin clave a productos desconocidos devuelven 401 para evitar la enumeración.

Derechos del plan

• all otorga todos los endpoints públicos de la versión activa.
• selected otorga solo el conjunto de endpoints configurado.
• Los derechos seleccionados se aplican en el gateway, incluidas las solicitudes de ruta sin procesar que evitan el catálogo de endpoints.
• Las condiciones comerciales se bloquean después de la primera suscripción; crea un plan de reemplazo en lugar de editar un plan suscrito.

Gateway & medición

El gateway es la única vía hacia los upstream de los proveedores. Resuelve el producto, autentica la clave, aplica la política de suscripción y plan, reserva cuota, reenvía de forma segura, mide el uso y escribe un rastro redactado.

Flujo de solicitudes

1. Resuelve el producto a partir del host o alias de ruta y encuentra el endpoint de la versión activa por método + ruta.
2. Autentica con un JWT/sesión del panel o una credencial externa X-API-Key / portador fr_live_….
3. Resuelve la suscripción del producto y la aplicación. Solo suscripciones activas y en prueba.
4. Valida el vínculo de la clave y marca last_used_at. Una clave no puede cruzar aplicaciones ni espacios de trabajo.
5. Reserva cuota contra el contador mensual y aplica los límites de velocidad por endpoint de forma atómica.
6. Ejecuta comprobaciones de seguridad de red: HTTPS, DNS público, sin redirecciones, sin recorrido de rutas, IP fijada.
7. Reenvía con tiempo de espera, límites de cuerpo, límites de carga y reintentos acotados.
8. Mide: evento de uso, contador mensual, registro de solicitudes redactado y vista previa de la respuesta.

Llamadas directas al producto

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":"[email protected]","template":"welcome"}'

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

El envoltorio heredado POST /api/v1/gateway/execute/ se mantiene para integraciones existentes y herramientas de consola. Los fragmentos nuevos usan la forma directa.

Cabeceras del gateway

Cuotas y límites de velocidad

• La cuota mensual se reserva antes de reenviar y cuenta las solicitudes enrutadas, incluidos los fallos del upstream.
• La cuota ilimitada elimina solo el límite mensual; el límite por minuto y el derecho a endpoints siguen aplicándose.
• El límite de velocidad por endpoint usa una ventana fija atómica en caché. Una interrupción de la caché compartida devuelve un 503 reintentable antes de reservar cuota.
• El excedente se factura por cada 1,000 solicitudes cuando está configurado; cero significa solo alertas.

Idempotencia y reintentos

• Las respuestas completadas se almacenan con un hash SHA-256 del token, una huella de la solicitud y una respuesta redactada durante el TTL configurado.
• Las repeticiones devuelven la respuesta almacenada antes de consumir cuota o llamar al upstream.
• Reutilizar una clave con una entrada de solicitud diferente devuelve 409.
• Los reintentos están acotados y solo se aplican a fallos transitorios seguros; los métodos no idempotentes no se reintentan a ciegas.
• Un cortacircuitos se abre tras fallos repetidos del upstream y devuelve un 503 reintentable durante el enfriamiento.

SSRF y seguridad de red

• Los upstream deben ser HTTPS públicos. Se rechazan las respuestas DNS privadas, de loopback, link-local y no seguras.
• La ruta debe permanecer en el host original. Se rechaza el recorrido con ...
• No se siguen redirecciones.
• La dirección DNS pública seleccionada se fija a través de la conexión TLS para evitar el rebinding.
• Los secretos del proveedor se adjuntan en el servidor y nunca se devuelven al navegador.
• Las vistas previas de respuestas tienen un límite y redactan las cabeceras de cookies, autorización y clave de API.

Registros de solicitudes y medición

• Vista del consumidor: historial de solicitudes del espacio de trabajo activo con búsqueda, filtros de estado y exportación CSV.
• Vista del proveedor: registros a nivel de solicitud de los productos propios, con consumidor, endpoint, latencia, estado y vistas previas redactadas.
• Eventos de uso: código de estado, latencia, suscripción, producto, endpoint y marca de tiempo.
• Contadores mensuales: modelo de lectura de cuotas y analítica.
• La retención se configura con prune_telemetry.

Entorno del gateway

Todos los tiempos de espera, límites, presupuestos de reintentos, umbrales de circuito, TTL de idempotencia, CIDR de proxy de confianza, límites de vista previa de medios y el sufijo del host del producto se controlan por entorno. Consulta Configuración para la tabla completa.

Facturación & desembolsos

La facturación tiene dos funciones: permitir que los consumidores paguen por los planes de API y que el operador de la plataforma cobre por la capacidad del espacio de trabajo. Ambas usan los mismos proveedores, facturas y liquidación por webhook.

Los dos planos de facturación

Piénsalo como dos cajas registradoras separadas:

Ambos usan checkout alojado, webhooks firmados, facturas y conciliación. Los ingresos de las API de los proveedores entran en la liquidación de desembolsos; los ingresos de suscripciones de la plataforma, no.

Planes de proveedor

• Intervalo mensual o anual, moneda, precio y descripción.
• Cuota mensual, límite de velocidad por minuto, excedente por cada 1,000 solicitudes, días de prueba.
• Hasta ocho líneas de funciones públicas y un plan público recomendado.
• Derecho a endpoints all o selected.
• Las condiciones comerciales se bloquean después de la primera suscripción; usa un plan de reemplazo para los cambios.

Checkout y liquidación

1. El consumidor selecciona un plan y acepta los términos de la API.
2. Se crean una suscripción pendiente y una factura del primer período.
3. El proveedor configurado abre el checkout alojado.
4. El proveedor envía un webhook firmado después del pago.
5. FastRestful verifica la firma, registra el evento del proveedor, valida el importe y la moneda, y marca la factura como pagada.
6. El derecho se activa solo después de la liquidación. Las redirecciones del navegador nunca conceden acceso.

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/

Compatibilidad de proveedores

Cada proveedor a continuación tiene una guía de configuración paso a paso en Pasarelas de pago, paso a paso.

Admin → Pasarelas de pago anula las credenciales del entorno campo por campo. Deshabilitar un registro de pasarela desactiva ese proveedor en todas partes, aunque las claves del entorno sigan presentes.

Reembolsos

• Los proveedores con permiso de facturación reembolsan facturas pagadas a través de la pasarela original.
• Los reembolsos de Stripe se concilian de forma acumulativa a partir de eventos de webhook; las pasarelas alojadas confirman de forma síncrona.
• Las claves de idempotencia y las solicitudes de reembolso pendientes hacen seguros los reintentos.
• Los reembolsos completos marcan la factura como reembolsada.
• Los reembolsos posteriores al desembolso añaden asientos contables de recuperación de ingresos del proveedor y reversión proporcional de comisiones.
• Los consumidores no pueden reembolsarse a sí mismos; los pagos manuales deben reembolsarse a través de su proveedor.

Pagos

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.

• Configura un destino de desembolso para el proveedor con PATCH /api/v1/orgs/{id}/payout-provider/ (acct_… para Stripe o correo para PayPal).
• Inicia una transferencia con POST /api/v1/payouts/{id}/transfer/.
• Concilia con POST /api/v1/payouts/{id}/reconcile/; los estados estrictos requieren un ID de transferencia o un motivo de fallo.
• Los webhooks de Stripe concilian transfer.created|paid|failed|reversed.

Suscripciones de plataforma

• Los planes de plataforma se gestionan en Admin → Planes de plataforma; máximo cinco planes.
• Cada plan puede definir límites de espacios de trabajo propios y de listados de API, beneficios y una recomendación.
• Los planes de pago permanecen sin publicar hasta que se configure un importe visible y un ID de precio recurrente del proveedor coincidente.
• Las sesiones de Checkout y Billing Portal se crean en el servidor con destinos fijos de FRONTEND_URL.
• La conciliación de suscripciones es de solo lectura en el admin para que los cambios del personal no se desvíen del proveedor.

Comandos de liquidación

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.

La tarea mensual de Celery se ejecuta el día 1 a las 00:05 UTC. Sin un broker, invoca los comandos manualmente.

Entorno del proveedor

Consulta Configuración → Pagos y desembolsos para cada variable. Como mínimo: Stripe secreto/webhook, PayPal cliente/webhook, o el trío público/secreto/webhook de la pasarela alojada. La interfaz de tarjetas del frontend también necesita NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY.

Pasarelas de pago, paso a paso

Conecta un proveedor de pago real sin adivinar. Cada sección de proveedor tiene dos partes: qué hacer clic en el panel del proveedor y luego qué introducir en FastRestful. PayPal incluye un recorrido completo de webhooks, incluso dónde encontrar el ID de webhook que FastRestful requiere.

Antes de empezar

Cómo se mueve el dinero en FastRestful

1. FastRestful crea una factura.

   La suscripción y la factura del primer período existen antes de que se abra el checkout. Aún no hay nada marcado como pagado.

2. Para los planes de pago, el proveedor abre el checkout.

   El cliente paga en la página alojada del proveedor. FastRestful solo guarda la referencia del checkout.

3. El proveedor envía un webhook firmado.

   FastRestful verifica la firma, registra el evento una vez y comprueba el importe y la moneda.

4. La factura queda liquidada.

   Solo ahora se activa la suscripción y comienza el derecho. Una redirección del navegador nunca concede acceso.

Dónde van las credenciales

Puedes poner las credenciales en backend/.env o en Admin → Pasarelas de pago. Los registros del admin son más fáciles de rotar y anulan los valores del entorno campo por campo. Deshabilitar un registro del admin desactiva el proveedor en todas partes, aunque las claves del entorno sigan existiendo.

Probar webhooks en tu portátil

Los proveedores no pueden alcanzar http://127.0.0.1:5056. Usa uno de estos enfoques para pruebas locales.

Stripe CLI

1. Instala la CLI de Stripe e inicia sesión.

   Sigue la guía de instalación de la CLI de Stripe, luego ejecuta stripe login y aprueba el aviso del navegador.

2. Reenvía eventos a tu backend local.
   shellCopiar

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

3. Copia el secreto de firma que se imprime.

   La CLI imprime whsec_…. Ponlo en STRIPE_WEBHOOK_SECRET o en el registro de Stripe del admin. Mantén la CLI en ejecución.

4. Activa un evento de prueba.
   shellCopiar

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

PayPal, Flutterwave, Paystack y Razorpay

Estos proveedores necesitan una URL HTTPS pública. Usa un túnel como ngrok o Cloudflare Tunnel y luego registra la URL del túnel en el panel del proveedor:

# Example with ngrok
ngrok http 5056

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

¿Cambias la URL del túnel más adelante? Actualiza juntos el panel del proveedor y el destino del webhook de FastRestful. Una URL obsoleta es la causa más común de «el pago se completó pero la factura nunca se cerró».

PayPal también ofrece un simulador de webhooks en el panel de desarrollador. Apúntalo a la URL del túnel y usa el ID de webhook de la misma app sandbox para que FastRestful pueda verificar el evento simulado.

Elegir un proveedor

Stripe, paso a paso

1. Crea y activa una cuenta de Stripe

1. Crea una cuenta de Stripe y completa el perfil empresarial.
2. Mantén Modo de prueba activado mientras integras. El interruptor está en la barra superior del panel de Stripe.
3. Puedes aceptar pagos de prueba antes de que Stripe termine la activación de la cuenta.

2. Copia las claves de API

1. Abre Developers → API keys.

   En el Stripe Dashboard, abre Developers y luego API keys.

2. Copia la clave secreta.

   Usa primero la clave secreta de prueba (sk_test_…). Colócala en STRIPE_SECRET_KEY o en el registro de administración de Stripe. Nunca pongas la clave secreta en el código del frontend.

3. Copia la clave publicable.

   Coloca la clave publicable de prueba (pk_test_…) en NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY si quieres la interfaz de tarjeta integrada. Recompila el frontend después de cambiarla.

3. Añade el endpoint de webhook de Stripe

1. Abre Developers → Webhooks → Add endpoint.
2. Define la URL del endpoint.
   URL de producción o stagingCopiar

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

3. Selecciona los eventos que FastRestful concilia.
   • checkout.session.completed
   • invoice.paid y 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 (pagos)
4. Copia el secreto de firma.

   Stripe muestra un valor que empieza por whsec_…. Este es STRIPE_WEBHOOK_SECRET. No es la clave secreta de la API.

Stripe firma cada entrega. FastRestful rechaza las firmas obsoletas y falla de forma segura cuando falta STRIPE_WEBHOOK_SECRET, por lo que es obligatorio un secreto de firma correcto.

4. Añade Stripe en FastRestful

Abre Admin → Payment gateways y edita la fila Stripe (recomendado), o usa variables de entorno.

Si prefieres usar variables de entorno, define STRIPE_SECRET_KEY y STRIPE_WEBHOOK_SECRET y luego reinicia el backend y los workers.

5. Planes de plataforma y Stripe Prices

Solo es necesario si vendes suscripciones de plataforma. Los planes de API de proveedor usan el precio propio del producto y no necesitan un Stripe Price.

1. Crea un Product en Stripe.

   Abre Product catalog → Add product. Ponle el nombre de tu plan de plataforma.

2. Añade un Price recurrente.

   Usa el importe, la moneda y el intervalo de facturación exactos que muestra tu plan de plataforma. Los precios mensuales y anuales deben ser Prices separados.

3. Copia cada Price ID.

   Los Price IDs empiezan por price_….

4. Pégalos en el plan de plataforma.

   Abre Admin → Platform plans y completa Stripe monthly price ID y Stripe annual price ID.

FastRestful comprueba el Price con el importe, la moneda y el intervalo del plan al pagar. Si no coinciden, devuelve 409 con una explicación en lugar de cobrar un importe incorrecto.

6. Stripe Connect para pagos a proveedores

1. Activa Connect en Stripe y crea una cuenta conectada para cada proveedor al que pagues.
2. Copia el ID de la cuenta conectada (acct_…).
3. Guárdalo como destino del proveedor con PATCH /api/v1/orgs/{id}/payout-provider/ o desde la configuración de pagos del proveedor.
4. Opcionalmente, define PAYOUT_PROVIDER=stripe para permitir solo pagos con Stripe.
5. Mantén seleccionados los eventos transfer.* en el webhook de Stripe.

7. Prueba Stripe

1. Usa la tarjeta de prueba 4242 4242 4242 4242, cualquier fecha de caducidad futura y cualquier CVC.
2. Completa un checkout y confirma que la factura pasa a pagada.
3. Confirma que la suscripción se activa y que la clave de consumidor funciona.
4. Abre Admin → Payment events y confirma que el evento se procesó una sola vez.
5. Genera un reembolso y confirma que el estado de reembolso de la factura es correcto.

PayPal, paso a paso

PayPal es el proveedor con más pasos del lado de la plataforma. FastRestful usa dos productos de PayPal distintos: Checkout orders para compras de planes de API de proveedores y Billing subscriptions para planes de plataforma. Ambos usan las mismas credenciales de aplicación y el mismo webhook.

1. Crea una aplicación de PayPal y copia las credenciales

1. Abre el PayPal Developer Dashboard.

   Ve a developer.paypal.com e inicia sesión con tu cuenta empresarial de PayPal.

2. Elige Sandbox o Live.

   Usa el conmutador Sandbox/Live de la parte superior. Sandbox y Live tienen aplicaciones, credenciales e IDs de webhook separados.

3. Abre Apps & Credentials → Create App.

   Ponle un nombre como FastRestful y selecciona la cuenta empresarial que debe recibir los pagos.

4. Copia el Client ID y el Secret.

   Estos van en PAYPAL_CLIENT_ID y PAYPAL_CLIENT_SECRET (o en el registro de administración de PayPal). Si el secreto está oculto, usa la acción de regeneración de la aplicación y copia el nuevo valor.

2. Añade el webhook de PayPal (obligatorio)

Este es el paso que más gente omite. Sin un ID de webhook, FastRestful rechaza todos los eventos de PayPal y los pedidos pagados siguen sin pagarse.

1. Abre tu aplicación en Apps & Credentials.
2. Desplázate hasta Webhooks y haz clic en Add Webhook.

   La etiqueta exacta puede ser Webhooks o Add Webhook según la versión del panel de PayPal.

3. Introduce la URL del webhook.
   URL del webhook de PayPalCopiar

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

   La URL debe ser HTTPS pública. Una redirección del navegador no prueba el pago; PayPal envía eventos firmados a esta URL, y esos eventos liquidan la factura.

4. Selecciona los tipos de evento.

   Grupo de eventos	Seleccionar	Por qué lo necesita FastRestful
   Checkout orders	CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED	Captura y liquida los pagos de planes de API de proveedores.
   Suscripciones	BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.EXPIRED	Activa y actualiza las suscripciones de plataforma. ACTIVATED es el evento que concede el derecho de uso.
   Pagos de suscripción	PAYMENT.SALE.COMPLETED	Registra renovaciones y reactiva suscripciones de plataforma vencidas.
   Pagos	PAYMENT.PAYOUTS-ITEM.SUCCEEDED, PAYMENT.PAYOUTS-ITEM.FAILED, PAYMENT.PAYOUTS-ITEM.BLOCKED, PAYMENT.PAYOUTS-ITEM.RETURNED, PAYMENT.PAYOUTS-ITEM.CANCELED	Concilia las transferencias de pagos a proveedores.

5. Guarda el webhook y copia el Webhook ID.

   Abre el webhook guardado si es necesario. PayPal muestra un webhook ID (una cadena alfanumérica corta). Este es PAYPAL_WEBHOOK_ID. No es la URL del webhook y no es el client secret.

3. Añade PayPal en FastRestful

Abre Admin → Payment gateways y edita la fila PayPal. En ese formulario, Public key es el Client ID, Secret key es el Client secret y Webhook secret es el Webhook ID.

Si prefieres variables de entorno:

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

Reinicia el backend y los workers después de cambiar los valores de entorno. Si usas el registro de administración, guárdalo y actívalo; no hace falta reiniciar.

4. Planes de PayPal Billing para suscripciones de plataforma

Omite esto a menos que vendas suscripciones de plataforma con PayPal. Los planes de API de proveedores usan pedidos Checkout de pago único y no necesitan un plan de PayPal Billing.

1. Crea un Product en PayPal.

   En el panel de PayPal, abre el área Billing/Subscriptions y crea un producto que represente tu plataforma.

2. Crea un Plan mensual o anual (o ambos).

   Define el importe, la moneda y el intervalo exactos que coincidan con el plan en FastRestful. Crea un plan separado para cada intervalo.

3. Copia cada Plan ID.

   Los Plan IDs de PayPal empiezan por P-….

4. Pégalos en el plan de plataforma.

   Abre Admin → Platform plans y completa PayPal monthly plan ID y PayPal annual plan ID.

5. Confirma que el webhook incluye eventos de suscripción.

   La suscripción se crea en estado PENDING. Solo se activa cuando llega BILLING.SUBSCRIPTION.ACTIVATED.

5. PayPal Payouts para proveedores

1. Confirma que la cuenta empresarial de PayPal está aprobada para Payouts.
2. Guarda el email receptor de PayPal del proveedor como su destino de pagos con PATCH /api/v1/orgs/{id}/payout-provider/.
3. Opcionalmente, define PAYOUT_PROVIDER=paypal o PAYOUT_PROVIDER=stripe,paypal para permitir ambos.
4. Mantén seleccionados los eventos PAYMENT.PAYOUTS-ITEM.* en el webhook.

6. Prueba el sandbox de PayPal

1. Usa credenciales de sandbox.

   Define PAYPAL_ENV=sandbox, usa el Client ID y el secret de la aplicación de sandbox, y el ID de webhook de sandbox.

2. Crea una cuenta de comprador de sandbox.

   El PayPal Developer Dashboard proporciona cuentas personales de prueba. Inicia sesión en sandbox.paypal.com con ese comprador cuando se abra el checkout.

3. Completa un pago de prueba.

   Aprueba el pedido y espera la redirección de vuelta a FastRestful.

4. Comprueba la recepción del webhook.

   Abre Admin → Payment events. Deberías ver CHECKOUT.ORDER.APPROVED, luego PAYMENT.CAPTURE.COMPLETED, y la factura debería quedar pagada.

5. Reenvía una entrega si es necesario.

   En el panel de PayPal, abre las entregas de eventos del webhook y reenvía el evento fallido. FastRestful deduplica por ID de evento.

Solución de problemas del webhook de PayPal

Flutterwave, paso a paso

1. Crea y verifica una cuenta de Flutterwave.

   Completa el perfil empresarial y el KYC antes de usar el modo live.

2. Copia las claves de API.

   Abre Settings → API Keys. Copia la clave pública y la clave secreta. Las claves de test y live son distintas.

3. Añade la URL del webhook.

   Abre Settings → Webhooks y define:

   URL del webhook de FlutterwaveCopiar

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

4. Crea un secret hash.

   Introduce una cadena aleatoria larga como secret hash del webhook. Pon el mismo valor en FLUTTERWAVE_WEBHOOK_SECRET o en el registro de administración. Es un valor que tú eliges, no una clave que genere Flutterwave.

5. Introduce las claves en FastRestful.

   Edita la fila Flutterwave en Admin → Payment gateways, o define FLUTTERWAVE_PUBLIC_KEY, FLUTTERWAVE_SECRET_KEY y FLUTTERWAVE_WEBHOOK_SECRET.

6. Prueba un checkout.

   FastRestful gestiona charge.completed con estado successful. Los demás eventos se confirman y se ignoran.

Paystack, paso a paso

1. Crea y activa una cuenta de Paystack.

   Completa los pasos de activación empresarial antes de usar claves live.

2. Copia las claves de API.

   Abre Settings → API Keys & Webhooks. Copia las claves pública y secreta para el modo test o live.

3. Añade la URL del webhook.
   URL del webhook de PaystackCopiar

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

4. Deja en blanco el secreto del webhook.

   Paystack firma cada webhook con tu clave secreta usando HMAC-SHA512. FastRestful recurre a PAYSTACK_SECRET_KEY cuando PAYSTACK_WEBHOOK_SECRET está vacío. Solo define un valor alternativo si el soporte de Paystack te da una clave de firma separada.

5. Introduce las claves en FastRestful.

   Edita la fila Paystack en Admin → Payment gateways, o define PAYSTACK_PUBLIC_KEY y PAYSTACK_SECRET_KEY.

6. Prueba un checkout.

   FastRestful gestiona charge.success y compara el importe en la unidad mínima de la moneda (por ejemplo, kobo para NGN).

Razorpay, paso a paso

1. Crea y verifica una cuenta de Razorpay.

   Completa el KYC y activa los pagos live.

2. Genera claves de API.

   Abre Account & Settings → API Keys y genera una clave. Copia el Key ID y el Key Secret.

3. Añade el webhook.

   Abre Account & Settings → Webhooks → Add New Webhook y define:

   URL del webhook de RazorpayCopiar

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

   Selecciona payment_link.paid. FastRestful crea un Razorpay Payment Link para el checkout y concilia ese evento. Define un secreto de webhook robusto; Razorpay firma con HMAC-SHA256 y el mismo valor debe guardarse en FastRestful.

4. Introduce las claves en FastRestful.

   Edita la fila Razorpay en Admin → Payment gateways, o define RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET y RAZORPAY_WEBHOOK_SECRET.

5. Prueba un checkout.

   Abre el Payment Link, paga con un método de prueba y confirma que la factura queda pagada y el evento se registra una sola vez.

La prueba de aceptación de 10 minutos

Ejecuta esto para cada proveedor antes de pasar a producción:

• El proveedor aparece configurado y habilitado en Admin → Payment gateways.
• Un checkout de prueba abre la página del proveedor y vuelve a la URL correcta del frontend.
• El webhook firmado llega y aparece una sola vez en Admin → Payment events.
• La factura se marca como pagada solo después del webhook, no con la redirección.
• La suscripción se activa y una clave de consumidor funciona.
• Un reembolso vuelve al método de pago original y actualiza el libro mayor.
• Si los pagos están habilitados, una transferencia de prueba llega al destino del proveedor y se concilia.
• Una entrega duplicada del webhook se confirma sin liquidar dos veces.

Errores comunes con webhooks

Lista de verificación para salir a producción

1. Cambia a credenciales live.

   Sustituye las claves, los IDs de webhook y los secretos de prueba por valores live. Define PAYPAL_ENV=live para PayPal.

2. Registra las URL de webhook de producción.

   Usa tu nombre de host real de API, no un túnel, y confirma que HTTPS funciona desde internet pública.

3. Define la clave publicable del frontend.

   Usa la clave publicable live de Stripe y recompila el frontend.

4. Haz coincidir los precios y los plan IDs.

   Confirma que los Stripe Price IDs y los PayPal Billing plan IDs apuntan a objetos live con el importe, la moneda y el intervalo exactos.

5. Realiza un pago real pequeño y reembólsalo.

   Verifica el webhook, la factura, el derecho de uso, el reembolso y los asientos del libro mayor. Es la única forma de probar el flujo live.

6. Vigila los eventos del primer día.

   Revisa Admin → Payment events en busca de fallos y confirma que el panel del proveedor muestra entregas correctas.

Biblioteca de medios y CDN

Un único flujo de almacenamiento para recursos multimedia, logotipos de productos, fotos de proveedores, avatares de usuarios e imágenes del CMS. Sistema de archivos local en desarrollo; S3 + CloudFront en producción.

Tipos admitidos y límites

La validación comprueba la extensión, el tipo de contenido declarado, la firma de bytes mágicos y el tamaño. Los bytes idénticos dentro de un mismo espacio de trabajo se deduplican mediante checksum SHA-256. GET /api/v1/media/supported-types/ determina las sugerencias de tipos aceptados en la UI.

Modos de almacenamiento

El modo S3 requiere boto3 y django-storages en el entorno de producción. manage.py check falla si falta el bucket y advierte cuando no se configura ni un dominio CDN ni una ACL de lectura pública.

Configuración de CloudFront

1. Crea un bucket privado con Block all public access habilitado.
2. Crea una distribución de CloudFront con el bucket como origen y Origin Access Control (OAC).
3. Concede a la distribución s3:GetObject sobre arn:aws:s3:::<bucket>/* mediante la política de bucket generada.
4. Apunta MEDIA_CDN_DOMAIN a la distribución o a un CNAME con un certificado ACM.
5. Opcionalmente, define MEDIA_CDN_DISTRIBUTION_ID para habilitar las acciones de purga.

Flujos de trabajo de la biblioteca

• Consola: el personal sube y gestiona la biblioteca; los inquilinos ven un estante de solo lectura de su espacio de trabajo en /dashboard/media o /vendor/media.
• Colecciones: carpetas o categorías por espacio de trabajo con búsqueda, filtros y movimientos masivos.
• Preajustes de renombrado: kebab, snake, Title Case, UPPER o mantener, con prefijos, sufijos y secuencias con relleno.
• Puntos focales: focal_x/focal_y por recurso (0–100) usados por los bloques de imagen del CMS.
• Selección por rango: haz clic con Mayús en un rango, descarga, copia la URL y abre el recurso anterior o siguiente en el panel lateral.
• Indicadores de uso: consulta dónde se referencia un recurso antes de eliminarlo.

Funcionamiento del selector

Elegir un recurso de la biblioteca copia sus bytes en el campo de destino. Sustituir o eliminar el recurso de la biblioteca nunca rompe una imagen elegida, y cada modelo conserva su propio ciclo de vida de almacenamiento. Los recursos de otros espacios de trabajo se rechazan.

Destinos conectados: logotipo de producto, perfil o portada de proveedor, avatar de usuario, identidad visual del administrador, imágenes de categoría, imágenes del CMS y medios de bloques de contenido.

API de medios

Entorno

Consulta Configuration para ver la matriz de almacenamiento de medios y especificaciones, incluidos la URL del endpoint, el dominio CDN, el ID de distribución y el comportamiento de la ACL.

Estudio de newsletter

Email marketing solo para personal con audiencias, plantillas basadas en bloques, campañas, pruebas A/B de asunto, segmentos, automatizaciones, analítica por enlace y correo transaccional del sistema.

Inicio rápido

1. Abre /admin/newsletter/ → Settings y configura el proveedor, el remitente, la URL pública del backend, la dirección postal y el texto de baja.
2. Lists & contacts → crea una lista; añade o importa contactos como email, name, tags.
3. Templates → duplica una plantilla inicial integrada o empieza en blanco, diseña con el editor de bloques y luego guarda y previsualiza.
4. Campaigns → elige una plantilla, listas, un segmento opcional y el asunto o asuntos, y envíate una prueba.
5. Automations → añade pasos de email y de espera; las altas en listas o las etiquetas activan la inscripción.
6. System emails → vincula plantillas a disparadores transaccionales.

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

Proveedores de email

Los secretos se cifran en reposo. Un botón de prueba envía a través del proveedor seleccionado antes de que lances una campaña.

Plantillas y diseñador

• Bloques: header, hero, texto, imagen, botón, separador, espaciador, imagen + texto, características, cita, enlaces sociales, HTML sin formato, footer.
• Bloques avanzados: columnas, testimonio, tabla, vídeo, tarjeta de producto, banner CTA, nota de footer.
• Variantes para diseños de hero, tamaño y alineación del texto, marcos y leyendas de imagen, estilo, tamaño y alineación del botón, estilo y ancho del separador, radio del tema y ancho del contenido.
• Arrastrar y soltar, reordenación con teclado, vista previa en vivo con debounce, alternativa en texto plano, preheader y URL saneadas.
• Placeholders: {{first_name}}, {{action_url}}, {{message}}, {{site_name}}, {{unsubscribe_url}}, {{preferences_url}}.
• 18 plantillas integradas para lanzamientos, resúmenes, webinars, casos prácticos, recuperación de clientes, NPS, promociones, registros de cambios, editoriales, destacados de la comunidad, onboarding y anuncios de servicio.

Campañas

• La audiencia es la unión de las listas seleccionadas ∩ el segmento opcional, sin duplicados; solo contactos suscritos, excluyendo las direcciones con rebotes o quejas.
• Las pruebas A/B de asunto dividen un porcentaje de destinatarios, esperan una ventana y luego envían la variante ganadora al resto. También puedes decidir el ganador manualmente cuando quieras.
• Reenviar a no abiertos crea un borrador dirigido solo a los contactos que no abrieron la campaña original.
• Programación, pausa, reanudación y cancelación, envío de prueba y calendario de campañas.
• Informes: entregas, aperturas, clics, bajas, comparación A/B, tabla de clics por enlace, cronología de interacción y destinatarios más recientes.
• Los valores UTM predeterminados se aplican a los enlaces de campaña; solo se aceptan destinos http(s).

Segmentos y automatizaciones

Los segmentos combinan listas, etiquetas (todas o cualquiera), estado del contacto, ventanas de interacción (abrió, hizo clic, no abrió en N días) y recencia de alta. Los recuentos se evalúan en vivo y los reutilizan las campañas.

Las automatizaciones se activan por alta en una lista, etiqueta, acción manual o API. Los pasos envían un email o esperan N horas. Las ejecuciones avanzan de forma idempotente y registran los fallos. La inscripción se deduplica por contacto.

Emails del sistema

Si una plantilla activa del estudio está vinculada a un disparador, se renderiza en HTML + texto; de lo contrario, se envía el mensaje plano heredado. Las claves vinculadas incluyen bienvenida, restablecimiento de contraseña, código de inicio de sesión, alerta de seguridad, aviso de plataforma, factura abierta, pago fallido, proveedor aprobado, alerta de cuota, invitación a organización y resumen de actividad.

Registro público y preferencias

• POST /api/v1/newsletter/subscribe/ con confirmación opcional de doble opt-in.
• GET /confirm/<token>/, GET /unsubscribe/<token>/ y POST de un clic según RFC 8058.
• Centro de preferencias en /api/v1/newsletter/preferences/<token>/ para activar o desactivar listas o darte de baja globalmente.
• El píxel de apertura y las redirecciones de clic reescriben los enlaces cuando el seguimiento está habilitado.
• El correo saliente incluye las cabeceras List-Unsubscribe y List-Unsubscribe-Post.

Entregabilidad y operaciones

• Gráficos de rebotes, quejas, bajas y crecimiento; mantén las tasas de rebotes y quejas cerca de cero.
• Mapa de calor de horas de envío por día de la semana local × hora, con recomendaciones de mejores ventanas.
• Estimaciones de audiencia y direcciones de muestra antes del envío.
• Página de contactos con estado, etiquetas, campos personalizados, pertenencias, supresiones, entregas, eventos y ejecuciones de automatización.
• Exportaciones CSV de contactos, destinatarios de campañas y enlaces.
• Ejecuta newsletter_beat cada pocos minutos para programaciones, decisiones A/B y esperas de automatización.

Anuncios y banners

Banners públicos diseñados desde el administrador para barras superiores, ubicaciones del footer y anuncios dentro de la página, con segmentación, programación, reglas de descarte, experimentos visuales y analítica de impresiones y clics.

Ubicaciones

Se sirve un banner por ubicación, elegido por prioridad y luego por recencia. Un banner puede dirigirse a varias ubicaciones.

Segmentación y programación

• Rutas: patrones de inclusión y exclusión como /pricing, /docs/* o *.
• Audiencia: todos, visitantes sin sesión o usuarios con sesión iniciada.
• Idioma y dispositivo: listas de permitidos separadas por comas; la tablet recurre a móvil cuando se permite móvil.
• Programación: marcas de tiempo de inicio y fin y un interruptor de activación.
• Prioridad: los números más altos ganan cuando coinciden varios banners.

Diseño y elementos integrados

• Diseños: barra, tarjeta, dividido, minimalista.
• Badge, titular, cuerpo, etiqueta, URL, estilo y apertura en nueva pestaña del CTA, imagen, lado, colores, degradados, alineación y vista previa en vivo.
• Icono o emoji opcional, patrones decorativos (puntos, cuadrícula, rayas, brillo) y animaciones de entrada seguras para movimiento reducido.
• 32 banners integrados para lanzamientos, confianza y estado, promociones, eventos, ciclo de vida, editorial, comunidad y campañas de temporada.
• HTML personalizado con los placeholders {{click_url}}, {{dismiss_url}} y {{impression_url}} para que el seguimiento siga funcionando.
• Frecuencia de descarte: en cada carga de página, una vez por sesión, una vez al día o una sola vez.

Entrega y seguimiento

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/

Los payloads incluyen HTML renderizado en el servidor con estilos inline, además de impression_url, dismiss_url y frequency. Los eventos registran ubicación, ruta, idioma, dispositivo, referrer, user agent e IP.

Experimentos e informes

• Los banners con la misma prioridad reparten el tráfico por peso (1–1000).
• Define un nombre de experimento y una etiqueta de variante en varios banners; se elige una variante por solicitud según el peso.
• Los informes de experimentos muestran impresiones, clics, CTR y la variante líder.
• Los informes grafican la actividad diaria de 30 y 90 días y desglosan por ubicación, páginas principales, dispositivos y eventos recientes.
• Las listas del administrador muestran contadores, acciones de activación y pausa, y registros de eventos de solo lectura.

Operaciones

Los eventos de banners son de solo añadido. El estado de descarte se guarda en el navegador del visitante y se cuenta en el servidor. El script público omite los user agents de bots; usa un user agent de navegador normal para las pruebas de banners públicos.

Enlaces cortos

Enlaces cortos listos para campañas, redirecciones, códigos QR, valores UTM predeterminados, alternativas, analítica de clics y comprobaciones de destinos rotos, disponibles tanto en el panel del consumidor como en el estudio del proveedor.

Qué hace

• Crea enlaces cortos con un slug personalizado, destino, etiquetas, tipo de redirección, caducidad y estado activo.
• Redirecciones 301 o 302; los enlaces caducados o deshabilitados pueden recurrir a un destino seguro o a una página 410 con marca.
• Valores UTM predeterminados (utm_source, utm_medium, utm_campaign) añadidos en el momento de la redirección; los parámetros de campaña entrantes tienen prioridad.
• Generación de QR en SVG con color personalizado y metadatos de campaña.
• Analítica de clics con país, dispositivo, referrer y contexto de campaña.
• Comprobaciones de estado de destinos rotos con detalles del error y nueva comprobación con un clic.
• Importación y exportación CSV y acciones de selección masiva.

Consola

Abre Links en el panel del consumidor (/dashboard/links) o en el estudio del proveedor (/vendor/links). El editor incluye título, destino, slug, etiquetas, tipo de redirección, caducidad, interruptor de activación y ámbito de todo el sitio solo para personal. La tabla ofrece acciones de copiar, QR, volver a comprobar, editar, eliminar, estado de salud y estado.

Configuración

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

Resumen de la API

Las redirecciones públicas resuelven por slug, registran el clic y luego redirigen. Las listas del administrador incluyen columnas de clics y estado, acciones de volver a comprobar, activar y deshabilitar, una acción rápida «Acortar un enlace» y un registro de clics de solo lectura.

Sitio, CMS e idiomas

El plano de control de Django es responsable del shell público: identidad, valores predeterminados de búsqueda y compartición, navegación, páginas, entradas del blog, documentos legales, CSS y JS personalizados, modo de mantenimiento y capas de idioma.

Superficies del operador

Configuración del sitio

• Logotipo, favicon e imagen para compartir en redes con selector de medios y limpieza tras la confirmación.
• Título y descripción meta globales, y fallback de imagen para compartir.
• Modo del marketplace, porcentaje de comisión predeterminado e indicador de mantenimiento.
• Etiqueta y destino del CTA del header (deben indicarse juntos).
• Banner de anuncio activado, texto y URL.
• Titular, resumen, copyright y email de soporte del footer.
• Desafío integrado o Google reCAPTCHA para formularios públicos.
• Política obligatoria de dos factores para todas las cuentas.
• Colores del tema, fuentes y vista previa en vivo del shell público.

Contenido estructurado

Las páginas y entradas se componen de secciones ordenadas, no de HTML sin formato. Los tipos de sección disponibles incluyen prosa, tabla, código, imagen, vídeo, dividido, cita, pestañas, código multilenguaje, ejemplo de endpoint, testimonios, lista de características, FAQ, pasos, métricas, cuadrícula de tarjetas, separador, hero, tira de logotipos, cronología, lista de enlaces, aviso destacado, colección de API, colección de categorías, APIs principales y artículos recientes.

• La prosa admite párrafos separados por una línea en blanco; los elementos de lista van uno por línea.
• Las acciones requieren una etiqueta y un destino; los enlaces aceptan rutas del sitio, HTTPS, mailto o tel.
• Los borradores nunca aparecen públicamente; las páginas publicadas aparecen en el contenido del sitio, los metadatos y las rutas del sitemap.
• El SEO a nivel de página sobrescribe los valores globales por campo.
• Las páginas legales se unen al grupo legal predeterminado del footer solo después de publicarse.

CSS y JS personalizados

Admin → Custom assets inyecta CSS o JavaScript en el sitio público sin necesidad de un despliegue. Cada fragmento tiene un tipo, una ubicación (head o footer) y un ámbito (todo el sitio, rutas seleccionadas o una página). Las rutas admiten coincidencias exactas y comodines /prefix/*.

• Payload público: GET /api/v1/platform/assets/ devuelve los fragmentos activos y el csp_nonce configurado.
• Vista previa: cada fragmento tiene una vista previa en un iframe dentro del administrador con inyección forzada mediante ?fr_preview_asset=<id>.
• Revisiones: cada guardado crea una instantánea inmutable con autor y nota; cualquier revisión se puede restaurar como una entrada nueva.
• CSP: define el mismo nonce en Site settings y en tu política de edge; las etiquetas lo reciben automáticamente.

Idiomas y capas de traducción

El inglés es el paquete de origen canónico. El francés se distribuye completo. Cualquier otro idioma es una capa dispersa del administrador que se combina sobre el inglés en tiempo de ejecución.

• Abre Site locales → Manage translations para inspeccionar la cobertura, editar el francés integrado o añadir un idioma.
• El francés integrado aparece al 100 % sin una fila en la base de datos. Guardar un campo crea una capa del administrador sin cambiar el fallback incluido.
• Exporta JSON o TypeScript, traduce sin conexión y vuelve a importar. Las claves desconocidas se ignoran y se notifican.
• La API pública de idiomas devuelve las capas activas; el frontend las combina sobre el inglés y el francés integrados.
• Después de editar lib/i18n/*.json, ejecuta npm run export:i18n y reinicia la API para actualizar su caché de proceso.

Modo de mantenimiento

El mantenimiento pausa todas las rutas del frontend y las llamadas a la API y al gateway de clientes. El admin del personal, las sondas de salud, los callbacks del proveedor de identidad y los webhooks firmados de pagos y pagos a proveedores siguen disponibles. La disponibilidad pública se expone de forma anónima con el indicador de mantenimiento, el aviso y el intervalo de reintento.

Contratos públicos

Integraciones externas, paso a paso

Email, almacenamiento de objetos, inicio de sesión único, infraestructura y webhooks salientes. Cada sección te indica primero qué hacer en el sitio web del proveedor y luego exactamente qué valores copiar en FastRestful.

¿Qué valor prevalece?

• Las variables de entorno proporcionan valores predeterminados para el despliegue.
• Los registros gestionados desde el administrador sobrescriben los valores de entorno coincidentes campo por campo.
• Desactivar un registro del administrador desactiva ese proveedor en todas partes, aunque las claves de entorno sigan definidas.
• Los valores del proveedor en el frontend se incorporan en tiempo de compilación. Recompila después de cambiar NEXT_PUBLIC_*.
• Ejecuta la acción de prueba del proveedor antes de enviar tráfico real.

Proveedores de email y newsletters

FastRestful puede enviar emails de campaña, automatizaciones y del sistema a través de tu propio proveedor. Configúralo en Admin → Newsletter → Email settings o hereda SMTP de las variables de entorno EMAIL_*. Las claves de API y los secretos se cifran en reposo.

La configuración en seis pasos

1. Crea una cuenta con un proveedor.

   Usa un proveedor transaccional como Amazon SES, Mailgun, SendGrid, Postmark, Brevo, Mailjet, SparkPost, Resend o cualquier host SMTP.

2. Verifica tu dominio de envío o dirección del remitente.

   La mayoría de los proveedores no entregarán hasta que se verifique el dominio o el email. Añade los registros DNS que te proporcione el proveedor.

3. Crea la clave de API o las credenciales SMTP.

   Usa el permiso mínimo que permita enviar email. Para SMTP, copia el host, el puerto, el usuario y la contraseña.

4. Introduce los valores en FastRestful.

   Abre Admin → Newsletter → Email settings. Elige el proveedor, pega las credenciales y define el nombre del remitente, el email del remitente, el reply-to, la dirección postal y el texto de baja.

5. Define la URL pública del backend.

   Se usa en píxeles de seguimiento, enlaces de confirmación y enlaces de baja. Debe ser el origen público que llega a Django, no el servidor de desarrollo del frontend.

6. Envíate un email de prueba.

   Usa la acción de prueba integrada. Revisa el código fuente completo del mensaje para comprobar el remitente y los enlaces esperados antes de enviar una campaña.

Guía rápida de proveedores

La entregabilidad es tarea del DNS. Autentica SPF, DKIM y DMARC antes de aumentar el volumen. Empieza con envíos pequeños, supervisa los rebotes y las quejas, y mantén operativo el enlace de baja. Las campañas, automatizaciones y el correo del sistema pueden usar plantillas distintas, pero comparten el mismo proveedor.

Almacenamiento de objetos y CDN

El almacenamiento en el sistema de archivos local es adecuado para desarrollo. En producción conviene usar almacenamiento compatible con S3 más una CDN, para que las cargas sobrevivan a los despliegues y los recursos se carguen rápido.

1. Crea el bucket de S3 y los permisos

1. Crea un bucket privado.

   En la consola de AWS, crea un bucket en la región que quieras. Mantén activado Block all public access. CloudFront lo leerá mediante OAC.

2. Crea un usuario o rol de IAM.

   Se admite la cadena de credenciales estándar: variables de entorno, un perfil de instancia o IRSA en Kubernetes. No codifiques las claves en el repositorio.

3. Concede solo los permisos que necesita FastRestful.
   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. Instala las bibliotecas de almacenamiento.

   Ejecuta pip install boto3 django-storages en el entorno del backend y añade las bibliotecas a los requisitos de tu despliegue.

5. Configura los valores de entorno.
   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. Reinicia y sube un recurso de prueba.

   Abre la biblioteca multimedia y sube una imagen. Debería aparecer en el bucket y cargarse desde la URL configurada de la CDN o de S3.

2. Coloca CloudFront delante del bucket

1. Crea una distribución de CloudFront.

   Elige el bucket como origen y crea un Origin Access Control (OAC).

2. Actualiza la política del bucket.

   Permite que la distribución de CloudFront lea los objetos. La consola de CloudFront puede generar la política por ti.

3. Configura los valores de 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. Permite la invalidación de caché.

   Añade cloudfront:CreateInvalidation a la política de IAM si quieres que funcione el botón de purga de la biblioteca de medios.

5. Prueba con una carga nueva.

   Sube un archivo nuevo, ábrelo a través del dominio de la CDN, sustituyelo y usa la acción de purga.

3. Proveedores compatibles con S3

Cloudflare R2, MinIO, DigitalOcean Spaces y servicios similares funcionan a través de la API de S3. Configura MEDIA_S3_ENDPOINT_URL con el endpoint S3 del proveedor y mantén el bucket privado si el proveedor admite una CDN o URLs firmadas. Verifica la carga, la descarga y la eliminación antes de depender de él en producción.

4. Almacenamiento de especificaciones OpenAPI

De forma predeterminada, los contratos OpenAPI importados se guardan en la base de datos. Para guardarlos en S3, configura:

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

Consulta Biblioteca multimedia y CDN para conocer los límites de carga, los tipos de archivo admitidos y el comportamiento de la CDN.

Inicio de sesión único

Tanto OIDC como SAML conservan destinos relativos seguros y tokens de invitación de organización. El inicio de sesión con contraseña puede seguir habilitado como alternativa.

OIDC, paso a paso

1. Crea una aplicación OIDC en tu proveedor de identidad.

   Usa Okta, Auth0, Microsoft Entra ID, Google Workspace, Keycloak, Authentik o cualquier proveedor OIDC compatible.

2. Registra la URL de callback.
   URI de redirecciónCopiar

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

   Usa el nombre de host exacto al que acceden los usuarios. Una barra final de más o de menos hará fallar el callback.

3. Permite el flujo de código de autorización y los ámbitos.

   Solicita openid, email y profile.

4. Copia el emisor, el ID de cliente y el secreto de cliente.
   backend/.envCopiar

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

5. Reinicia el backend.

   El botón de SSO permanece oculto hasta que se configure el proveedor.

6. Prueba con una identidad real.

   Inicia sesión con el botón y confirma que el callback vuelve a la ruta esperada del frontend.

SAML 2.0, paso a paso

1. Instala la dependencia opcional.

   Ejecuta pip install lxml antes de habilitar SAML.

2. Copia los metadatos SP.

   Entrega esta URL a tu proveedor de identidad o sube el XML que devuelva:

   metadatos SPCopiar

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

3. Configura la ACS URL y el ID de entidad en el IdP.

   El servicio de consumo de aserciones es:

   ACS URLCopiar

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

   El ID de entidad predeterminado es fastrestful. Puedes cambiarlo con SSO_SAML_ENTITY_ID.

4. Copia la URL de SSO del IdP y el certificado de firma.
   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. Reinicia y prueba.

   Inicia un inicio de sesión desde el frontend y confirma que la aserción del IdP vuelve a la página esperada.

Proveedores de infraestructura

Herramientas de API y webhooks salientes

OpenAPI, Swagger y Postman

• Importación de OpenAPI: importa OpenAPI 3.x o Swagger 2.0 a una versión en borrador. La canalización de versiones concilia los endpoints y marca los cambios incompatibles.
• Esquema de la plataforma: expórtalo en /api/schema/ con python3.11 manage.py spectacular --file schema.yml --validate.
• Swagger UI: el backend lo sirve en /api/docs/.
• Postman / kits de inicio: los endpoints del producto exponen paquetes descargables para los consumidores.

Webhooks salientes, paso a paso

1. Crea el endpoint en FastRestful.

   Abre la sección de endpoints de webhook del plano de control y añade la URL de tu receptor. Debe ser HTTPS.

2. Elige los eventos y un secreto de firma.

   Guarda un secreto robusto. FastRestful firma el cuerpo sin procesar de la solicitud con HMAC-SHA256.

3. Envía una entrega de prueba.

   Confirma que tu receptor devuelve una respuesta 2xx.

4. Verifica la firma en tu servidor.

   Compara tu propio HMAC-SHA256 del cuerpo sin procesar con la cabecera X-FastRestful-Signature. El valor es sha256=<hex>. El nombre del evento está en X-FastRestful-Event.

5. Observa el registro de entregas.

   Los reintentos son seguros y el historial de entregas es evidencia de solo lectura. Gestiona los nombres de evento duplicados de forma idempotente.

Los webhooks de pago son independientes. Los webhooks de proveedores liquidan dinero y se registran en el panel de cada proveedor. Los webhooks salientes de proveedores son para tus propias integraciones. No apuntes un proveedor de pagos a un endpoint de webhook de proveedor.

Lista de verificación de aceptación de la integración

• El proveedor aparece configurado y habilitado en la página de administración o de configuración.
• Un mensaje o una carga de prueba real llega al proveedor y la URL devuelta carga.
• El correo de prueba llega; SPF, DKIM y DMARC pasan.
• Los medios subidos se guardan en el bucket y se sirven a través de la CDN.
• El callback de OIDC o SAML vuelve a la ruta esperada del frontend.
• Las firmas de los webhooks salientes se verifican en el receptor.
• Los reintentos no duplican efectos secundarios.
• Las credenciales de prueba y de producción no se mezclan.

Copias de seguridad y actualizaciones

Una ruta repetible de copia de seguridad, restauración y actualización para un despliegue autoalojado de FastRestful. Las copias de seguridad van primero; el método de actualización depende de cómo compraste y desplegaste el producto.

Qué incluir en las copias de seguridad

Copia de seguridad de 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

Restaurar en una base de datos limpia

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

Prueba las restauraciones cada trimestre. Una copia de seguridad que nunca se ha restaurado es una suposición, no un plan de recuperación.

Dos formas de actualizar

Secuencia de actualización manual

Usa esto solo para un despliegue personalizado que no gestione el centro de actualizaciones oficial.

1. Lee las notas de la versión y comprueba si hay cambios de migración o de entorno.
2. Haz copias de seguridad de PostgreSQL, los medios y los secretos.
3. Pon la plataforma en modo de mantenimiento si una migración requiere pausar las escrituras.
4. Trae el código e instala las dependencias del backend y del frontend.
5. Ejecuta las migraciones, recopila los archivos estáticos y compila el frontend.
6. Reinicia la API y los workers; verifica la preparación y una solicitud de prueba.
7. Sal del modo de mantenimiento y supervisa la tasa de errores, la profundidad de las colas y la recepción de webhooks.

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

Reversión

• La reversión del código es sencilla solo si la versión anterior no requería una migración de base de datos irreversible.
• Conserva una instantánea de la base de datos antes de cada migración. Restaura la instantánea y la versión de código correspondiente a la vez.
• Nunca edites en producción una migración ya aplicada; añade una nueva migración correctiva.
• Tras la reversión, vuelve a ejecutar la solicitud de prueba e inspecciona las tareas en cola para detectar suposiciones sobre el esquema.

Seguridad de las migraciones

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

• Primero los cambios aditivos, después el relleno de datos y, en una versión posterior, elimina los campos antiguos.
• Evita bloqueos prolongados de tablas de medición, registro de solicitudes y auditoría con alto volumen.
• Activa el modo de mantenimiento para las migraciones que cambien columnas de estado de dinero o de estado de versión.
• Mantén Celery en pausa hasta que terminen las migraciones.

Versiones del frontend

La compilación del frontend es estática y autocontenida. Mantén el origen de la API y la URL del sitio público alineados con el despliegue. Si despliegas una compilación nueva que espera nuevos campos de la API, publica primero el backend o mantén el contrato compatible con versiones anteriores.

Observabilidad

Estado, logs, métricas y colas para una plataforma en la que las solicitudes, el dinero y la moderación dejan evidencia.

Estado y preparación

Usa la preparación para la pertenencia al balanceador de carga. Una caída de la caché devuelve 503 con la dependencia que falla, en lugar de servir con estado exclusivamente local.

Contexto de la solicitud

• Cada respuesta de la API incluye metadatos de la solicitud en los logs de la aplicación. Conserva el ID de solicitud a través de tu proxy inverso.
• Los logs de solicitudes del gateway incluyen suscripción, producto, endpoint, estado, latencia y vistas previas redactadas.
• Los eventos de proveedor almacenan IDs de evento y hashes de payload, no secretos sin procesar.
• Los eventos de auditoría vinculan actor, acción, organización, objetivo y metadatos.

Señales que supervisar

Reglas de registro

• Nunca registres claves de API sin procesar, secretos de proveedores ni payloads de pago completos.
• Mantén las vistas previas de solicitudes y respuestas acotadas y redactadas.
• Registra IDs de eventos de proveedor y resultados de liquidación, no datos de tarjetas.
• Usa campos estructurados cuando sea posible: ID de solicitud, organización, producto, endpoint y estado.
• Separa la evidencia de auditoría de los logs normales de la aplicación.

Colas y tareas programadas

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

Supervisa las colas default y billing por separado. La liquidación se ejecuta mensualmente; la moderación y las notificaciones cada 15 minutos; las comprobaciones de disponibilidad, a diario.

Conjunto mínimo de alertas

• Preparación fallando durante más de 2 minutos.
• Tasa de 5xx de la API por encima del objetivo de servicio.
• Circuito del gateway abierto o tasa de errores del upstream disparada.
• Fallos de webhooks o eventos de proveedor sin procesar.
• Falta el latido de Celery beat; la profundidad de la cola aumenta.
• Saturación de disco y de conexiones de la base de datos.
• Fallo de copia de seguridad o última copia correcta demasiado antigua.
• Caída inesperada de las inscripciones en dos factores del personal.

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

Escalado

Dónde escala FastRestful sin problemas, dónde necesita infraestructura y qué estado debe permanecer compartido.

Escala las capas por separado

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)

Capa web

• Ejecuta varias instancias de Gunicorn/Django sin estado detrás de un balanceador de carga.
• Las sesiones residen en la base de datos; la caché y los límites de velocidad usan Redis. No dependas de la memoria local en producción.
• Dimensiona los workers para la solicitud más lenta del gateway (tiempo de espera predeterminado: 15 segundos).
• Termina TLS en el edge y conserva el host original para el enrutamiento de productos.

Base de datos

• Usa PostgreSQL con agrupación de conexiones a medida que aumente el número de workers.
• Tablas de alto volumen: eventos de uso, registros de solicitudes, eventos de auditoría y entregas de webhooks.
• Purga la telemetría de forma programada y archiva la evidencia de auditoría según la política.
• Mantén las escrituras de estado de dinero en transacciones; no fragmentes las tablas de facturas ni de libro mayor sin un plan de migración.

Redis

• Se requiere una caché compartida para los límites de velocidad y la idempotencia del gateway.
• Una caída de Redis devuelve un 503 reintentable antes de reservar la cuota; el gateway no recurre a estado por proceso.
• Supervisa las expulsiones. Perder registros de idempotencia puede permitir llamadas duplicadas al upstream tras cambios de TTL.
• Usa una base de datos o instancia de Redis independiente para el broker de Celery si aumenta la presión de la caché.

Capacidad del gateway

• Las cuotas y los límites de velocidad se aplican por suscripción y endpoint, no por proceso.
• La latencia del upstream domina el tiempo de solicitud; mantén tiempos de espera y reintentos conservadores.
• El almacenamiento de idempotencia crece con el volumen de solicitudes; dimensiona Redis para el TTL configurado.
• Usa enrutamiento por host de producto con TLS comodín para evitar un cuello de botella de ruta central en el edge.

Workers y tareas programadas

• Ejecuta una sola instancia de beat; varios planificadores beat pueden duplicar tareas temporizadas.
• Escala las colas billing y default por separado.
• Mantén la liquidación idempotente; las reejecuciones son seguras por diseño.
• Aplica contrapresión a las colas de correo y moderación con la concurrencia de los workers en lugar de desactivar los reintentos.

Multimedia y CDN

• Mueve las cargas a S3 antes de que el ciclo de vida del disco local sea un problema.
• Sirve a través de CloudFront con nombres de objeto inmutables y caché de larga duración.
• Mantén privado el acceso al origen; evita políticas de bucket públicas.
• Usa la purga por recurso solo cuando se reutilice intencionadamente una clave de objeto.

Lista de verificación de capacidad

• Las alertas de preparación y de 5xx están conectadas al sistema de guardias.
• PostgreSQL tiene margen para conexiones, disco e IOPS.
• Redis tiene margen para la caché y los registros de idempotencia.
• Se supervisan la profundidad de las colas de Celery y el latido de beat.
• El almacenamiento de objetos y la CDN están fuera del servidor web.
• La retención de telemetría se configura antes del crecimiento, no después.

Modelo de datos y permisos

Las entidades que definen FastRestful, los límites de inquilino que las rodean y los invariantes que mantienen coherentes el dinero y las versiones.

Inquilinos

Organization es el límite del inquilino. Un usuario se une mediante una Membership con un rol. La organización activa viaja explícitamente y se resuelve en el servidor antes de acceder a los objetos.

Entidades principales

Invariantes

• Un producto tiene una sola versión activa a la vez.
• El contrato y el catálogo de endpoints de una versión activa no se pueden editar.
• Una suscripción tiene condiciones comerciales inmutables; los cambios crean un plan nuevo.
• Una clave de API pertenece exactamente a una aplicación y no puede cruzar entre aplicaciones.
• Un ID de evento de proveedor se registra una sola vez; las repeticiones no liquidan dos veces.
• Los pagos siguen una máquina de estados monótona.
• Las entradas del libro mayor son de solo anexado.
• El último propietario activo del espacio de trabajo no se puede eliminar ni degradar.

Comprobaciones de permisos

Eliminación y retención

• Los tickets nunca se eliminan; permanecen como evidencia de soporte.
• El historial de versiones publicadas sigue disponible para auditoría incluso después de la descontinuación.
• Los eventos de auditoría y los recibos de proveedores son de solo anexado.
• Los registros de solicitudes y los eventos de uso se purgan según la retención configurada.
• Las eliminaciones de medios usan el ciclo de vida de los recursos y deben respetar las referencias en uso.

Extender el modelo

1. Parte de un flujo de trabajo real, no de un campo hipotético.
2. Mantén los datos exclusivos de la plataforma fuera de los serializadores anónimos.
3. Valida en la capa de modelo/API; añade restricciones de base de datos para el dinero y las transiciones de estado.
4. Añade pruebas de contrato para permisos, límites de inquilino e idempotencia.
5. Documenta la superficie del operador antes de lanzar el modelo.

Extensiones

Amplía la experiencia pública y el flujo operativo sin bifurcar el núcleo: recursos personalizados, secciones del CMS, capas de idioma, webhooks y patrones de administración.

CSS y JavaScript personalizados

Admin → Recursos personalizados inyecta un fragmento en el sitio público. Cada fragmento tiene un tipo, una ubicación, un alcance y un estado activo.

• Cada guardado crea una revisión inmutable con autor y nota; cualquier revisión se puede restaurar como una entrada nueva.
• Previsualiza el sitio en vivo en un iframe de administración con el fragmento inyectado a la fuerza.
• Usa el nonce CSP configurado tanto en la configuración del sitio como en la política del edge; las etiquetas inyectadas lo reciben automáticamente.
• Trata los fragmentos como código de operador de confianza. Pueden cambiar el estilo o instrumentar el sitio público.

Secciones estructuradas del CMS

Las páginas y publicaciones se componen de secciones ordenadas. El editor incluye prosa, tabla, código, imagen, vídeo, split, cita, pestañas, grupos de código, muestras de endpoints, testimonios, funciones, FAQ, pasos, métricas, tarjetas, separadores, hero, franja de logotipos, cronología, lista de enlaces, avisos, colecciones de API, colecciones de categorías, API destacadas y artículos recientes.

• Usa secciones estructuradas en lugar de pegar HTML arbitrario.
• Define juntos la etiqueta de acción y el destino.
• Usa rutas del sitio o destinos HTTPS, mailto o tel.
• Mantén un texto alternativo de imagen significativo; el cuerpo del texto puede servir como pie de foto.
• Las páginas publicadas se incorporan a la navegación y a los metadatos del sitemap solo cuando están activas.

Capas de idioma

El inglés es el paquete canónico; el francés se incluye completo. Añade otro idioma en la administración, importa un paquete JSON o TypeScript y sobrescribe solo las claves que necesites.

• Los valores incluidos siguen siendo la alternativa cuando una clave de la capa está vacía.
• Las claves desconocidas se ignoran y se notifican durante la importación.
• Exporta JSON o TypeScript para traducir sin conexión.
• Ejecuta npm run export:i18n después de editar el paquete del frontend y reinicia la API.

Webhooks salientes

Los webhooks de proveedor entregan eventos firmados a endpoints HTTPS con un historial de entregas seguro para reintentos. Guarda el secreto de firma en el espacio de trabajo del proveedor y verifica la firma antes de actuar sobre un payload.

• Usa una URL de endpoint estable y devuelve un 2xx rápidamente.
• Trata los eventos como de entrega al menos una vez y haz que los manejadores sean idempotentes.
• Usa el registro de entregas para inspeccionar el estado de las respuestas y las vistas previas.
• No reutilices las rutas de webhook del proveedor de pagos para eventos de proveedores.

Patrón de extensión de la administración

1. Registra el modelo con comportamiento explícito de listado, filtrado, búsqueda y permisos.
2. Añade un formulario de administración específico en lugar de exponer campos internos sin procesar.
3. Usa eventos de auditoría para las acciones que cambian el estado.
4. Añade una página de vista previa o de informe solo cuando responda a una pregunta real del operador.
5. Prueba los límites de permisos y la separación entre serializadores públicos y privados.

Patrón de extensión de la API

• Aplica el alcance del inquilino antes de cada consulta.
• Usa serializadores explícitos de solicitud y respuesta.
• Devuelve códigos de error estables para el comportamiento del cliente.
• Haz que los reintentos sean seguros con idempotencia cuando haya dinero o estado involucrados.
• Añade anotaciones OpenAPI para que el esquema siga siendo utilizable.

Administración

El plano de control del personal es una superficie de administración de Django que tiene en cuenta los permisos para las operaciones de la plataforma. No usa métricas de demostración ni omite los permisos de modelo.

Límite de acceso

• El acceso del personal requiere is_staff. Un rol admin en un espacio de trabajo no es personal de la plataforma.
• Se puede exigir doble factor para todas las cuentas desde la configuración del sitio.
• Se respetan los permisos de modelo de Django y el comportamiento registrado de ModelAdmin.
• Las lecturas de administración pueden ser más amplias que las escrituras; la propiedad de los objetos y el estado del proveedor siguen condicionando las acciones con consecuencias.
• Toda acción sensible debe crear un evento de auditoría con actor, objetivo y metadatos.

Vista general de operaciones

/admin/ muestra una instantánea en vivo y de solo lectura creada a partir de los registros actuales: tráfico, API públicas, consumidores activos, espacios de trabajo activos, mensajes de contacto, adopción del doble factor, avisos de la plataforma, colas de atención, estado de pagos, flujo de auditoría, experiencia del sitio y cobertura de idiomas.

• Acciones rápidas: crear API, revisar proveedores, configuración del sitio, planes de plataforma, estudio de contenido, newsletter, banners, enlaces.
• Colas de decisión: proveedores, moderación, apelaciones, restricciones de seguridad, soporte, webhooks fallidos, pagos, facturas y bandeja de contacto.
• Panel de pagos: ingresos por proveedor, suscripciones activas, MRR, pagos pendientes, recepciones de webhooks, reembolsos y enlaces de gateway.

Secciones del plano de control

Moderación y seguridad

• Los informes incluyen tipo/etiqueta del objetivo, categoría, evidencia, prioridad, plazo de SLA, asignación y resúmenes de resolución privados y públicos.
• El personal configura las ventanas de SLA por prioridad, los umbrales de escalado y las ventanas de apelación en Moderation policy.
• Los informes cerrados elegibles se pueden apelar una vez dentro de la ventana; la decisión pública original permanece adjunta.
• Las apelaciones aceptadas reabren el caso con un SLA nuevo derivado de la política.
• Resolver un informe confirmado puede emitir una medida de seguridad auditable: advertencia, restricción de comunidad, restricción de publicación o restricción de plataforma.
• Los registros de medidas muestran puntos, motivo público, fechas de vigencia y estado, y solo el usuario afectado o los miembros activos del proveedor pueden leerlos.

Soporte y equipo

• Los tickets vinculan consumidor, producto, suscripción y, opcionalmente, el contexto del registro de solicitudes.
• Los mensajes actualizan la marca de tiempo de actividad del ticket para que las colas sigan ordenadas por la última respuesta.
• Las invitaciones de equipo, los cambios de rol, la desactivación y la eliminación solo pueden hacerlos propietarios o administradores; el último propietario activo no se puede eliminar.
• Las invitaciones se almacenan con hash, son de un solo uso, están vinculadas al correo y caducan.

Planes de plataforma y conciliación

• Máximo cinco planes de plataforma; los códigos permanecen estables después de su creación.
• Precio mostrado, IDs de proveedor anuales/mensuales, límite de espacios de trabajo, límite de publicaciones de API, beneficios y recomendación.
• Los planes de pago no se publican hasta que exista un importe y un ID de precio recurrente del proveedor.
• La conciliación de suscripciones de plataforma de solo lectura muestra el estado y los derechos sin permitir que el personal se desvíe del proveedor.

Avisos de la plataforma

Los avisos creados por el personal se distribuyen a bandejas de entrada por usuario. La audiencia puede ser todas las cuentas o solo el personal; los niveles son info, notice y critical. Los recuentos de entrega aparecen en la instantánea de operaciones.

Auditoría y exportaciones

• Eventos de auditoría de solo anexado con actor, acción, organización, objetivo y metadatos.
• Los trabajos de exportación admiten flujos de revisión de seguridad y retención.
• Las listas de administración ofrecen vistas filtradas, búsqueda y CSV cuando corresponde.
• Nunca incluyas secretos sin procesar, claves de API ni payloads de proveedores en los metadatos de auditoría.

Gestión de idiomas

Idiomas del sitio → Gestionar traducciones muestra los idiomas incluidos y gestionados, la cobertura y las claves que faltan. El francés incluido se puede editar mediante una capa de administración. La importación y exportación admiten literales JSON y TypeScript; las claves desconocidas se ignoran y se notifican.

Referencia de la API

La API de FastRestful es una superficie de Django REST Framework con raíz en /api/v1/. El backend sirve OpenAPI y este es el contrato autoritativo.

URLs base y documentación

Autenticación

curl --request POST \
  --url 'https://api.example.com/api/v1/auth/token/' \
  --header 'Content-Type: application/json' \
  --data '{"username":"[email protected]","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>'

Espacios de nombres

Mapa de endpoints principales

Paginación y filtrado

Los endpoints de listado usan un contrato de número de página: page, page_size, search, ordering y filtros de recursos. Las respuestas usan {count, next, previous, results}. La ordenación acepta un nombre de campo, opcionalmente precedido por -.

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

Forma del error

Los errores de validación usan el objeto de DRF indexado por campo. Los errores del gateway y de la plataforma usan un objeto JSON con un código legible por máquina, un mensaje para personas y metadatos de reintento opcionales.

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

Forma de la llamada al 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

Hay dos tipos de webhook en FastRestful. Mantenlos 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/

• Los endpoints de webhook de proveedores deben usar HTTPS y almacenar un secreto de firma.
• Las entregas se firman, se reintentan de forma segura y se registran con el estado y una vista previa de la respuesta.
• Los webhooks del proveedor de pagos se registran en el panel de cada proveedor, no en la sección de webhooks de proveedores.
• Los IDs de eventos de proveedor son únicos; los eventos firmados duplicados se confirman sin liquidar dos veces.
• La configuración y las listas de eventos de webhook están en Pasarelas de pago, paso a paso.

Flujo de trabajo de OpenAPI

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

Usa el esquema generado para SDKs, Postman o pruebas de contrato. Los contratos OpenAPI a nivel de producto son independientes: se importan en versiones de API y se promocionan a través de la canalización de versiones.

Cómo desbloquearte

Si un endpoint devuelve un código inesperado, comprueba primero el ID de solicitud, el método de autenticación, la cabecera del espacio de trabajo y el estado de la suscripción. La Guía de solución de problemas cubre los modos de fallo habituales en orden.