Configuración

Esta página documenta los parámetros necesarios para ejecutar IZ-CentralForms, consumir la API pública, configurar secretos y preparar ambientes superiores.

El proyecto se encuentra actualmente en ambiente local de desarrollo. La configuración productiva debe definirse por ambiente y no debe versionar secretos reales.

Configuración local actual

Configuración	Valor
Ambiente	Development
API local HTTP	http://localhost:5273
API local HTTPS	https://localhost:7122
Base de datos	(localdb)\MSSQLLocalDB
Database	CentralFormsDb
Swagger	Habilitado en desarrollo
SMTP local	localhost:1025
Mailpit UI	http://localhost:8025
SDK JS	/sdk/centralforms.js
Ejemplo SDK	/examples/contacto.html

Ambiente local

Los valores anteriores corresponden al entorno de desarrollo. En QA, staging o producción deben reemplazarse por valores propios del ambiente.

Connection strings

Desarrollo local

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=CentralFormsDb;Trusted_Connection=True;MultipleActiveResultSets=true"
  }
}

Servidor con usuario SQL

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=SERVIDOR_SQL;Database=CentralFormsDb;User Id=centralforms_user;Password=PASSWORD_SEGURO;TrustServerCertificate=True;MultipleActiveResultSets=true"
  }
}

Servidor con SQL Express local

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=.\\SQLEXPRESS;Database=CentralFormsDb;Trusted_Connection=True;TrustServerCertificate=True;MultipleActiveResultSets=true"
  }
}

LocalDB

(localdb)\MSSQLLocalDB solo debe usarse en desarrollo local. Para IIS, QA, staging o producción se requiere SQL Server real.

Permisos SQL

Si se usa Trusted_Connection=True en IIS, se deben otorgar permisos SQL al Application Pool. Si se usa usuario SQL, no es necesario crear login para IIS APPPOOL.

Email

Desarrollo local

{
  "Email": {
    "Host": "localhost",
    "Port": 1025,
    "EnableSsl": false,
    "UserName": "",
    "Password": "",
    "FromEmail": "no-reply@centralforms.local",
    "FromName": "CentralForms Dev"
  }
}

SMTP real o sandbox

{
  "Email": {
    "Host": "sandbox.smtp.mailtrap.io",
    "Port": 2525,
    "EnableSsl": true,
    "UserName": "USUARIO_SMTP",
    "Password": "PASSWORD_SMTP",
    "FromEmail": "no-reply@interzone.net",
    "FromName": "CentralForms"
  }
}

Campo	Tipo	Requerido	Descripción
Host	string	Sí	Servidor SMTP.
Port	integer	Sí	Puerto SMTP.
EnableSsl	boolean	Sí	Define si la conexión SMTP usa SSL/TLS.
UserName	string	Según proveedor	Usuario SMTP.
Password	string	Según proveedor	Password SMTP.
FromEmail	string	Sí	Correo remitente.
FromName	string	Sí	Nombre visible del remitente.

Secretos SMTP

No versionar usuarios ni passwords SMTP reales. Usar variables de entorno, User Secrets o mecanismo seguro equivalente.

Configuración segura por ambiente

Para ambientes compartidos o reales, evitar credenciales dentro de appsettings.json. ASP.NET Core permite sobrescribir configuración con User Secrets en desarrollo o variables de entorno en servidor.

User Secrets para SMTP en desarrollo

cd CentralForms.Api

dotnet user-secrets init
dotnet user-secrets set "Email:Host" "sandbox.smtp.mailtrap.io"
dotnet user-secrets set "Email:Port" "2525"
dotnet user-secrets set "Email:EnableSsl" "true"
dotnet user-secrets set "Email:UserName" "USUARIO_SMTP"
dotnet user-secrets set "Email:Password" "PASSWORD_SMTP"
dotnet user-secrets set "Email:FromEmail" "no-reply@centralforms.local"
dotnet user-secrets set "Email:FromName" "CentralForms Dev"

Variables de entorno para servidor

ASPNETCORE_ENVIRONMENT=Production
ConnectionStrings__DefaultConnection=Server=SERVIDOR_SQL;Database=CentralFormsDb;User Id=USUARIO_SQL;Password=PASSWORD_SQL;TrustServerCertificate=True;MultipleActiveResultSets=true
Admin__ApiKeyHash=HASH_SHA256_DE_LA_ADMIN_KEY
Email__Host=smtp.proveedor.com
Email__Port=587
Email__EnableSsl=true
Email__UserName=USUARIO_SMTP
Email__Password=PASSWORD_SMTP
Email__FromEmail=no-reply@interzone.net
Email__FromName=CentralForms
Swagger__Enabled=false
Seed__DemoData=false

Seguridad administrativa

Los endpoints administrativos usan el header:

X-Admin-Key: <admin_key>

La configuración debe almacenar el hash, no la clave real:

{
  "Admin": {
    "ApiKeyHash": "HASH_SHA256_DE_LA_ADMIN_KEY"
  }
}

Generar hash SHA-256

$key = "tu-api-key-real"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($key)
$hash = [System.Security.Cryptography.SHA256]::HashData($bytes)
[System.BitConverter]::ToString($hash).Replace("-", "").ToLowerInvariant()

API Keys

Las API Keys y Admin Keys reales no deben almacenarse en texto plano. Solo debe persistirse su hash.

API pública

GET formulario

Obtiene la definición del formulario y genera un token CSRF para usarlo en el POST.

GET /api/forms/{consumerCode}/{formCode}

Parámetros

Campo	Ubicación	Tipo	Requerido	Descripción
consumerCode	path	string	Sí	Código único del consumer.
formCode	path	string	Sí	Código único del formulario.
X-Api-Key	header	string	Sí	API Key pública del consumer.
Origin	header	string	Condicional	Origin enviado por navegador; se valida contra AllowedOrigins cuando viene informado.

Ejemplo de request

GET /api/forms/demo/contacto HTTP/1.1
Host: localhost:7122
X-Api-Key: demo-api-key
Origin: https://localhost:7122

Campos de respuesta 200 OK

Campo	Tipo	Descripción
consumerCode	string	Código del consumer.
formCode	string	Código del formulario.
title	string	Título del formulario.
description	string/null	Descripción del formulario.
csrfToken	string	Token CSRF stateful requerido para el POST.
fields	array	Lista de campos dinámicos del formulario.
fields[].name	string	Nombre técnico del campo.
fields[].label	string	Texto visible del campo.
fields[].type	string	Tipo de campo, por ejemplo text, email, textarea, select.
fields[].required	boolean	Indica si el campo es obligatorio.
fields[].order	integer	Orden de renderizado.
fields[].placeholder	string/null	Placeholder del campo.
fields[].options	array/null	Opciones disponibles para campos tipo lista.

Ejemplo de response

{
  "consumerCode": "demo",
  "formCode": "contacto",
  "title": "Formulario de Contacto",
  "description": "Escríbenos y te responderemos a la brevedad.",
  "csrfToken": "csrf_token_generado",
  "fields": [
    {
      "name": "nombre",
      "label": "Nombre completo",
      "type": "text",
      "required": true,
      "order": 1,
      "placeholder": "Ingrese su nombre",
      "options": null
    }
  ]
}

POST submission

Procesa el envío de un formulario. Si la validación es correcta, persiste la submission antes de ejecutar email o webhook.

POST /api/forms/{consumerCode}/{formCode}/submit

Parámetros

Campo	Ubicación	Tipo	Requerido	Descripción
consumerCode	path	string	Sí	Código único del consumer.
formCode	path	string	Sí	Código único del formulario.
X-Api-Key	header	string	Sí	API Key pública del consumer.
X-CSRF-Token	header	string	Sí	Token generado en el GET del formulario.
Origin	header	string	Condicional	Origin enviado por navegador; debe estar autorizado cuando viene informado.
Content-Type	header	string	Sí	Debe ser application/json.
data	body	object	Sí	Objeto con los valores enviados por el formulario.

Ejemplo de request

POST /api/forms/demo/contacto/submit HTTP/1.1
Host: localhost:7122
X-Api-Key: demo-api-key
X-CSRF-Token: TOKEN_DEL_GET
Origin: https://localhost:7122
Content-Type: application/json

{
  "data": {
    "nombre": "María González",
    "email": "maria@dominio.com",
    "servicio": "Consultoría",
    "mensaje": "Quisiera información sobre precios."
  }
}

Campos de response 200 OK

Campo	Tipo	Descripción
success	boolean	Indica si el submit fue aceptado.
message	string	Mensaje funcional para el consumidor.
submissionId	guid	Identificador de la submission persistida.

Ejemplo de response

{
  "success": true,
  "message": "Formulario enviado correctamente",
  "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error 400 Bad Request

{
  "success": false,
  "message": "Campos requeridos faltantes",
  "missingFields": ["nombre", "email"]
}

Códigos de respuesta

Origin en código actual

El header Origin se valida cuando viene informado. Si no se envía, el código actual no bloquea la solicitud por Origin. Para ambientes reales se recomienda tratarlo como obligatorio en escenarios de navegador o endurecer esta regla.

Código	GET formulario	POST submission
200 OK	Formulario retornado correctamente.	Submission validada y persistida.
400 Bad Request	No aplica normalmente.	Campos inválidos o requeridos faltantes.
401 Unauthorized	API Key inválida, ausente o consumer inactivo.	API Key inválida, ausente o consumer inactivo.
403 Forbidden	Origin no autorizado si el header fue informado.	Origin no autorizado o CSRF inválido.
404 Not Found	Consumer o formulario no existe.	Consumer o formulario no existe.
429 Too Many Requests	No aplica normalmente.	Rate limit superado.
500 Internal Server Error	Error interno.	Error al persistir o procesar.

Destinos configurables

CentralForms usa FormDestinations para ejecutar acciones después de persistir una submission.

Tipo	Uso	Valor esperado
email	Enviar notificación por correo.	Uno o más destinatarios.
webhook	Enviar submission a sistema externo.	URL destino.

Email

INSERT INTO FormDestinations (Id, FormId, [Type], [Value], IsActive)
VALUES (
    NEWID(),
    @FormId,
    'email',
    'destinatario@dominio.com',
    1
);

Value puede contener varios destinatarios separados por coma o punto y coma.

Webhook

INSERT INTO FormDestinations (Id, FormId, [Type], [Value], IsActive)
VALUES (
    NEWID(),
    @FormId,
    'webhook',
    'https://webhook.site/TU-URL-AQUI',
    1
);

Integraciones

Email y webhook se ejecutan después de persistir la submission. Su resultado debe revisarse en IntegrationLogs.

SDK Embed

Uso básico:

<div id="centralforms-contacto"></div>

<script src="https://localhost:7122/sdk/centralforms.js"></script>
<script>
  CentralForms.render({
    container: '#centralforms-contacto',
    apiBaseUrl: 'https://localhost:7122',
    consumerCode: 'demo',
    formCode: 'contacto',
    apiKey: 'demo-api-key',
    submitLabel: 'Enviar mensaje'
  });
</script>

Opciones principales

Opción	Tipo	Default	Requerido	Descripción
container	string/HTMLElement	—	Sí	Contenedor donde se renderiza el formulario.
apiBaseUrl	string	window.location.origin	Sí	URL base de CentralForms API.
consumerCode	string	—	Sí	Código del consumer.
formCode	string	—	Sí	Código del formulario.
apiKey	string	—	Sí	API Key enviada en X-Api-Key.
submitLabel	string	Enviar	No	Texto normal del botón.
submittingLabel	string	Enviando...	No	Texto durante el envío.
successMessage	string	Formulario enviado correctamente.	No	Mensaje después de un POST exitoso.
errorMessage	string	No se pudo enviar el formulario.	No	Mensaje ante error HTTP o de red.
resetOnSuccess	boolean	true	No	Limpia el formulario después de enviar.
refreshTokenOnSuccess	boolean	true	No	Solicita nuevo CSRF después de un envío exitoso.
themeColor	string	#111827	No	Color principal del botón y foco.
disableDefaultStyles	boolean	false	No	Desactiva CSS inyectado por el SDK.

Configuración por ambiente

Configuración	Local	QA / Staging	Producción
Connection string	LocalDB	SQL Server real	SQL Server real
Swagger	Habilitado	Habilitado o restringido	Restringido o deshabilitado
Seed demo	Activo	Solo si aplica	Desactivado
SMTP	Mailpit / Mailtrap	Mailtrap o SMTP real	SMTP real
API Keys	Demo/local	Secret seguro	Secret seguro
Admin Key	Demo/local	Secret seguro	Secret seguro
Origins	Localhost	Dominios QA	Dominios producción

Checklist mínimo

Antes de cambiar de ambiente validar:

• Connection string correcta.
• Base de datos creada y migrada.
• SMTP configurado.
• API Key y Admin Key configuradas como hash.
• Origins permitidos cargados.
• Swagger restringido según ambiente.
• Seed demo desactivado en producción.
• HTTPS habilitado fuera de local.