Text Variation

1. Descripción general

La API TextVariation genera variaciones de un texto fuente mientras preserva su contexto general. Dependiendo de la configuración habilitada para el cliente, el procesamiento puede utilizar generación de IA, sinónimos y otras estrategias administradas por Witime.

Este documento describe el punto final público, sus parámetros y ejemplos de integración. Todos los valores que se muestran a continuación son ficticios.

2. Endpoint

POST <BASE_URL>/witime/chatbot/textvariation.aspx?chave=<ACCESS_KEY>

Ejemplo de URL de producción:

https://sms.witi.me/witime/chatbot/textvariation.aspx?chave=<ACCESS_KEY>

Witime proporciona la URL final, la clave de acceso, el identificador de la empresa y el nombre de la configuración.

Encabezados

Encabezado	Valor
`Content-Type`	`application/json; charset=utf-8`
`Accept`	`application/json`

Autenticación

La autenticación utiliza el parámetro de consulta chave.

Utilice HTTPS fuera de los entornos de desarrollo local.
Nunca codifique la clave de acceso en el código fuente.
Guárdela en una variable de entorno o bóveda de secretos.
No comparta URLs completas que contengan la clave en tickets, capturas de pantalla o registros.
El Chave devuelto bajo Resultado es un identificador de solicitud, no una credencial de autenticación.

3. Cuerpo de la solicitud

{
  "Configuracao": "gpt-sinonimos-rcs",
  "Texto": "Offer available! Read the terms and learn more: https://example.com/offer",
  "NumeroVariacoes": 3,
  "MaxTextLength": 155,
  "RemoveAcentos": false,
  "RemoveUnicode": false,
  "IdEmpresa": 12345
}

12345, example.com, y el contenido del mensaje son solo datos de demostración.

Campos

Campo	Tipo	Requerido	Descripción
`Configuracao`	string	Sí	Nombre exacto de configuración habilitado por Witime, como `gpt-sinonimos-rcs`.
`Texto`	string	Sí	Texto fuente a variar. No debe estar vacío.
`NumeroVariacoes`	integer	Sí	Número solicitado de variaciones finales. Utilice un entero positivo dentro de los límites contractuales.
`MaxTextLength`	integer	Recomendado	Longitud máxima deseada para cada texto. El servicio utiliza `160` cuando el valor es menor que `1`.
`RemoveAcentos`	boolean	No	Elimina diacríticos cuando es `true`. Predeterminado: `true`.
`RemoveUnicode`	boolean	No	Elimina caracteres Unicode no admitidos y también fuerza la eliminación de diacríticos cuando es `true`. Predeterminado: `true`. Use `false` cuando se permitan emojis.
`IdEmpresa`	integer	Sí	Identificador de empresa proporcionado por Witime.

Notas de procesamiento

Los enlaces están protegidos durante la variación y se restauran en la salida.
El enlace original completo debe estar presente en el resultado; el cliente aún debe validarlo antes de enviar un mensaje.
El servicio puede reutilizar variaciones previamente procesadas desde la caché.
Los candidatos inválidos, duplicados o incompatibles con las reglas pueden ser descartados.
El cliente debe revisar el contenido generado antes de usarlo, especialmente precios, fechas, términos comerciales, redacción legal e instrucciones de exclusión.

4. Ejemplo de cURL

Mantenga los valores sensibles fuera del comando y reemplace los valores de ejemplo:

export WITIME_BASE_URL="https://sms.witi.me"
export WITIME_API_KEY="your-key-provided-by-witime"

curl --request POST \
  "${WITIME_BASE_URL}/witime/chatbot/textvariation.aspx?chave=${WITIME_API_KEY}" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "Accept: application/json" \
  --data '{
	"Configuracao": "gpt-sinonimos-rcs",
	"Texto": "Offer available! Read the terms and learn more: https://example.com/offer",
	"NumeroVariacoes": 3,
	"MaxTextLength": 155,
	"RemoveAcentos": false,
	"RemoveUnicode": false,
	"IdEmpresa": 12345
  }'

5. Ejemplo PowerShell

$baseUrl = $env:WITIME_BASE_URL
$apiKey = [Uri]::EscapeDataString($env:WITIME_API_KEY)
$uri = "$baseUrl/witime/chatbot/textvariation.aspx?chave=$apiKey"

$body = @{
	Configuracao = "gpt-sinonimos-rcs"
	Texto = "Offer available! Read the terms and learn more: https://example.com/offer"
	NumeroVariacoes = 3
	MaxTextLength = 155
	RemoveAcentos = $false
	RemoveUnicode = $false
	IdEmpresa = 12345
} | ConvertTo-Json

$response = Invoke-RestMethod `
	-Method Post `
	-Uri $uri `
	-ContentType "application/json; charset=utf-8" `
	-Headers @{ Accept = "application/json" } `
	-Body $body

if ($response.Resultado.CodigoResultado -ne 0) {
	throw "TextVariation failed: $($response.Resultado.Mensagem)"
}

$response.Variacoes | ForEach-Object { $_.Texto }

6. Respuesta exitosa

{
  "Variacoes": [
	{
	  "Texto": "Offer available! Review the terms and learn more: https://example.com/offer",
	  "Toxidades": 0
	},
	{
	  "Texto": "Check the offer and read its terms: https://example.com/offer",
	  "Toxidades": 0
	},
	{
	  "Texto": "Learn more about the offer and its terms: https://example.com/offer",
	  "Toxidades": 0
	}
  ],
  "Resultado": {
	"CodigoResultado": 0,
	"Mensagem": "3 textos gerados com sucesso",
	"Chave": "00000000-0000-0000-0000-000000000000",
	"Cobrado": true,
	"ValorCobrado": 3.0,
	"ElapsedTimeMS": 2500
  }
}

La respuesta anterior es ilustrativa. Los textos, cantidades, identificadores y tiempos de procesamiento varían en cada solicitud.

Campos de respuesta

Campo	Tipo	Descripción
`Variacoes`	array	Lista de variaciones devueltas.
`Variacoes[].Texto`	string	Texto de variación final.
`Variacoes[].Score`	string o null	Clasificación de contenido cuando esté disponible. Puede ser omitido.
`Variacoes[].Toxidades`	integer	Indicador de toxicidad asociado con la variación. `Toxidades` es el nombre exacto del campo de contrato.
`Resultado.CodigoResultado`	integer	`0` significa éxito. Otros valores indican un error comercial o de procesamiento.
`Resultado.Mensagem`	string	Descripción del resultado legible por humanos. Los mensajes pueden devolverse en portugués.
`Resultado.Chave`	UUID	Identificador de correlación de respuesta. No es la clave de acceso.
`Resultado.Cobrado`	boolean	Indica si se registró el consumo.
`Resultado.ValorCobrado`	decimal	Valor de consumo registrado por el servicio. Confirme su unidad en el acuerdo comercial; puede diferir del tamaño de `Variacoes`.
`Resultado.ElapsedTimeMS`	integer	Tiempo transcurrido en el servidor en milisegundos.

Siempre inspeccione Resultado.CodigoResultado para determinar el éxito. No confíe exclusivamente en el estado HTTP o el texto de Mensagem.

7. Códigos de resultado conocidos

Código	Significado
`0`	Procesamiento completado exitosamente.
`1`	Clave de acceso faltante o configuración faltante/inválida, según el mensaje.
`2`	Cuerpo de solicitud vacío.
`3`	JSON inválido.
`4`	Texto vacío después de la validación.
`5`	Saldo insuficiente para generar variaciones.

La validación de la clave de acceso y los componentes internos pueden devolver códigos adicionales. Para soporte, registre CodigoResultado, Mensagem y Chave, pero nunca registre la clave de acceso o contenido sensible.

Ejemplo de error

{
  "Variacoes": [],
  "Resultado": {
	"CodigoResultado": 5,
	"Mensagem": "Saldo insuficiente para gerar variações de texto.",
	"Chave": "00000000-0000-0000-0000-000000000000",
	"Cobrado": false,
	"ValorCobrado": 0.0,
	"ElapsedTimeMS": 20
  }
}

8. Recomendaciones de integración

Configure un tiempo de espera HTTP adecuado para el procesamiento de IA; las solicitudes pueden tardar varios segundos.
Trate el tamaño de la lista devuelta como el recuento de resultados efectivo.
No reintente indiscriminadamente: una solicitud puede registrar consumo incluso si se pierde su respuesta. No se documenta garantía de idempotencia.
Para fallos transitorios, use un pequeño número de reintentos con retroceso exponencial y conserve la correlación Chave cuando esté disponible.
Valide la longitud, enlaces, redacción de exclusión, información obligatoria y reglas comerciales para cada variación.
No envíe datos personales o confidenciales sin una base legal, autorización contractual y controles apropiados.
Preserve la ortografía exacta de los campos JSON, incluyendo Configuracao, NumeroVariacoes, IdEmpresa y Toxidades.

9. Lista de verificación de aceptación

URL de producción recibida a través de un canal seguro.
Clave de acceso almacenada en una bóveda de secretos o variable de entorno.
IdEmpresa y Configuracao confirmados por Witime.
Tiempo de espera y manejo de errores configurados.
CodigoResultado verificado en cada respuesta.
Enlaces de salida comparados con el texto fuente.
Límites de caracteres validados por el cliente.
Contenido y redacción de exclusión revisados antes de enviar.
Los registros no contienen credenciales, datos personales o cuerpos de mensaje completos.

10. Información de soporte

Al solicitar soporte, proporcione solo:

fecha y hora de la solicitud, incluida la zona horaria;
nombre del entorno;
Resultado.CodigoResultado;
Resultado.Mensagem;
Resultado.Chave;
IdEmpresa, cuando esté autorizado;
parámetros técnicos sin el texto fuente completo cuando sea posible.

Nunca envíe la clave de acceso completa. Enmascare también datos personales, enlaces privados y contenido confidencial.

1. Descripción general​

2. Endpoint​

Encabezados​

Autenticación​

3. Cuerpo de la solicitud​

Campos​

Notas de procesamiento​

4. Ejemplo de cURL​

5. Ejemplo PowerShell​

6. Respuesta exitosa​

Campos de respuesta​

7. Códigos de resultado conocidos​

Ejemplo de error​

8. Recomendaciones de integración​

9. Lista de verificación de aceptación​

10. Información de soporte​