Text Variation

1. Visão geral

A API TextVariation gera variações de um texto preservando o contexto geral da mensagem. Conforme a configuração contratada, o processamento pode aplicar geração por IA, sinônimos e outras estratégias configuradas pela Witime.

Este documento descreve o endpoint público, seus parâmetros e exemplos de integração. Todos os valores apresentados são fictícios.

2. Endpoint

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

Exemplo de endereço de produção:

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

A URL definitiva, a chave de acesso, o identificador da empresa e o nome da configuração são fornecidos pela Witime.

Cabeçalhos

Cabeçalho	Valor
`Content-Type`	`application/json; charset=utf-8`
`Accept`	`application/json`

Autenticação

A autenticação é feita pelo parâmetro de consulta chave.

Use somente HTTPS em ambientes não locais.
Nunca grave a chave diretamente no código-fonte.
Armazene-a em variável de ambiente ou cofre de segredos.
Não compartilhe URLs completas contendo a chave em tickets, capturas de tela ou logs.
A Chave devolvida dentro de Resultado é um identificador da requisição, não uma credencial de autenticação.

3. Corpo da requisição

{
  "Configuracao": "gpt-sinonimos-rcs",
  "Texto": "Oferta disponivel! Consulte as condicoes e saiba mais: https://example.com/oferta",
  "NumeroVariacoes": 3,
  "MaxTextLength": 155,
  "RemoveAcentos": true,
  "RemoveUnicode": false,
  "IdEmpresa": 12345
}

12345, example.com e o conteúdo do texto são apenas dados de demonstração.

Campos

Campo	Tipo	Obrigatoriedade	Descrição
`Configuracao`	string	Sim	Nome exato da configuração habilitada pela Witime, por exemplo `gpt-sinonimos-rcs`.
`Texto`	string	Sim	Texto original que será variado. Não pode ser vazio.
`NumeroVariacoes`	inteiro	Sim	Quantidade de variações finais solicitadas. Use um inteiro positivo dentro dos limites contratados.
`MaxTextLength`	inteiro	Recomendado	Tamanho máximo desejado para cada texto. Se for menor que `1`, o serviço adota `160`.
`RemoveAcentos`	booleano	Não	Quando `true`, remove acentos das saídas. Padrão: `true`.
`RemoveUnicode`	booleano	Não	Quando `true`, remove caracteres Unicode não aceitos e também força a remoção de acentos. Padrão: `true`. Use `false` quando emojis forem permitidos.
`IdEmpresa`	inteiro	Sim	Identificador da empresa fornecido pela Witime.

Observações de processamento

Links são protegidos durante a variação e restaurados na saída.
O link original deve aparecer integralmente no resultado; ainda assim, valide essa regra antes de enviar a mensagem ao destinatário.
O serviço pode reutilizar variações previamente processadas por meio de cache.
Candidatas inválidas, duplicadas ou incompatíveis com as regras podem ser descartadas.
O conteúdo gerado deve ser validado pelo sistema cliente antes do uso, especialmente valores, datas, condições comerciais, termos legais e opt-out.

4. Exemplo com cURL

Defina os valores sensíveis fora do comando e substitua os valores de exemplo:

export WITIME_BASE_URL="https://sms.witi.me"
export WITIME_API_KEY="sua-chave-fornecida-pela-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": "Oferta disponivel! Consulte as condicoes e saiba mais: https://example.com/oferta",
	"NumeroVariacoes": 3,
	"MaxTextLength": 155,
	"RemoveAcentos": true,
	"RemoveUnicode": false,
	"IdEmpresa": 12345
  }'

5. Exemplo com 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 = "Oferta disponivel! Consulte as condicoes e saiba mais: https://example.com/oferta"
	NumeroVariacoes = 3
	MaxTextLength = 155
	RemoveAcentos = $true
	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 falhou: $($response.Resultado.Mensagem)"
}

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

6. Resposta de sucesso

{
  "Variacoes": [
	{
	  "Texto": "Oferta disponivel! Veja as condicoes e saiba mais: https://example.com/oferta",
	  "Toxidades": 0
	},
	{
	  "Texto": "Confira a oferta e consulte as condicoes: https://example.com/oferta",
	  "Toxidades": 0
	},
	{
	  "Texto": "Saiba mais sobre a oferta e suas condicoes: https://example.com/oferta",
	  "Toxidades": 0
	}
  ],
  "Resultado": {
	"CodigoResultado": 0,
	"Mensagem": "3 textos gerados com sucesso",
	"Chave": "00000000-0000-0000-0000-000000000000",
	"Cobrado": true,
	"ValorCobrado": 3.0,
	"ElapsedTimeMS": 2500
  }
}

A resposta acima é ilustrativa. Textos, quantidades, identificador e tempo variam a cada processamento.

Campos da resposta

Campo	Tipo	Descrição
`Variacoes`	array	Lista de variações retornadas.
`Variacoes[].Texto`	string	Texto final da variação.
`Variacoes[].Score`	string ou nulo	Classificação de conteúdo, quando disponível. Pode não aparecer.
`Variacoes[].Toxidades`	inteiro	Indicador de toxicidades associado à variação. O nome `Toxidades` faz parte do contrato.
`Resultado.CodigoResultado`	inteiro	`0` indica sucesso. Outros valores indicam erro de negócio ou processamento.
`Resultado.Mensagem`	string	Descrição legível do resultado.
`Resultado.Chave`	UUID	Identificador de correlação da resposta. Não é a chave de acesso.
`Resultado.Cobrado`	booleano	Indica se houve registro de consumo.
`Resultado.ValorCobrado`	decimal	Valor de consumo registrado pelo serviço. A unidade deve ser confirmada no contrato comercial e pode não coincidir com o tamanho de `Variacoes`.
`Resultado.ElapsedTimeMS`	inteiro	Tempo decorrido no servidor, em milissegundos.

Para determinar sucesso, verifique sempre Resultado.CodigoResultado; não dependa somente do status HTTP ou do texto de Mensagem.

7. Códigos de resultado conhecidos

Código	Significado
`0`	Processamento concluído com sucesso.
`1`	Chave ausente ou configuração inexistente/inválida, conforme a mensagem.
`2`	Corpo da requisição vazio.
`3`	JSON inválido.
`4`	Texto vazio após a validação.
`5`	Saldo insuficiente para gerar variações.

A validação da chave e componentes internos podem devolver outros códigos. Registre CodigoResultado, Mensagem e Chave para suporte, sem registrar a chave de acesso nem conteúdo sensível.

Exemplo de erro

{
  "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. Recomendações de integração

Configure um timeout HTTP compatível com processamento por IA; ele pode levar vários segundos.
Trate a quantidade retornada como a fonte efetiva de resultados.
Não faça repetição automática indiscriminada: uma chamada pode registrar consumo mesmo se a resposta for perdida. Não há garantia de idempotência documentada.
Em falhas transitórias, aplique poucas tentativas com espera exponencial e registre a Chave de correlação quando disponível.
Valide comprimento, link, opt-out, informações obrigatórias e regras de negócio em cada variação.
Não envie dados pessoais ou confidenciais no texto sem base legal, autorização contratual e controles adequados.
Preserve a grafia exata dos campos JSON, inclusive Configuracao, NumeroVariacoes, IdEmpresa e Toxidades.

9. Checklist de homologação

URL de produção recebida por canal seguro.
Chave armazenada em cofre de segredos ou variável de ambiente.
IdEmpresa e Configuracao confirmados pela Witime.
Timeout e tratamento de erro configurados.
CodigoResultado validado em toda resposta.
Links comparados com o texto original.
Limite de caracteres validado pelo cliente.
Conteúdo e opt-out revisados antes do envio.
Logs sem credenciais, dados pessoais ou corpo integral da mensagem.

10. Informações para suporte

Em caso de falha, envie somente:

data e hora da chamada, com fuso horário;
ambiente utilizado;
Resultado.CodigoResultado;
Resultado.Mensagem;
Resultado.Chave;
IdEmpresa, se autorizado;
parâmetros técnicos sem o texto integral, quando possível.

Nunca envie a chave de acesso completa. Mascare também dados pessoais, links privados e conteúdo confidencial.

1. Visão geral​

2. Endpoint​

Cabeçalhos​

Autenticação​

3. Corpo da requisição​

Campos​

Observações de processamento​

4. Exemplo com cURL​

5. Exemplo com PowerShell​

6. Resposta de sucesso​

Campos da resposta​

7. Códigos de resultado conhecidos​

Exemplo de erro​

8. Recomendações de integração​

9. Checklist de homologação​

10. Informações para suporte​