Desativar uma campanha de mensagens

Desativar uma campanha de mensagens existente

Use esta rota para encerrar uma campanha pertencente à conta. Guarde o identificador da campanha para conciliação e histórico. Para corrigir o conteúdo ou atualizar o texto de consentimento, use Atualizar uma campanha de mensagens como alternativa.

Autentique-se com uma conta de API habilitada, por HTTPS, a partir de um endereço IP de origem permitido. Consulte primeiro a campanha e verifique a marca associada e os números de envio. A desativação altera o registro; ela não cria uma campanha substituta nem transfere números para outra campanha.

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/campaign/$CAMPAIGN_ID"

Remova primeiro as atribuições dos números afetados

A operação pública DELETE de campanhas não desvincula os números de telefone da operadora de mensagens nem remove sua atribuição local. Use o fluxo de remoção da atribuição de um número a uma campanha para cada número afetado pertencente à conta e, em seguida, verifique sua atribuição. Remover uma atribuição não libera o número de telefone.

O fluxo mais abrangente do portal, Excluir marca, realiza a limpeza das campanhas e dos números dessa marca antes de excluí-la. Não use essa ação se pretende manter a marca e suas outras campanhas. O editor comum de campanhas não oferece atualmente um botão separado de exclusão de campanha equivalente a esta rota direta da API.

Envie a solicitação de desativação pretendida

Depois de revisar o identificador da campanha e a configuração de envio afetada, envie DELETE sem corpo JSON:

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  --request DELETE \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  "https://api.multitel.net/tcr/v2/campaign/$CAMPAIGN_ID"

A resposta de sucesso documentada é HTTP 204 com corpo vazio. Verifique o status HTTP em vez de esperar uma estrutura envoltória JSON do tipo status/response. Quando a exclusão é aceita, o serviço atual marca localmente o recurso da campanha como excluído e expirado e marca seu registro legado de campanha como expirado. A exclusão não se estende à marca em cascata.

Use uma única chave de idempotência para esta solicitação pretendida e preserve exatamente o método, o caminho, a consulta e os bytes do corpo para repeti-la. Uma solicitação duplicada cuja original esteja em processamento pode retornar 409 com Retry-After; solicitações concluídas podem reproduzir o resultado armazenado. Um erro em cache ou uma conexão interrompida não permite determinar se o registro já agiu. Guarde o identificador da campanha e requestId quando estiver presente.

Verifique tanto o registro quanto as atribuições

Verifique o estado atual da campanha e os números afetados no portal após a solicitação. A API pode manter metadados locais de titularidade após o encerramento, permitindo que um identificador pertencente à conta ainda seja consultado; não presuma que o mesmo identificador deva sempre retornar um 404 local. O registro determina o status retornado ou a disponibilidade do registro encerrado.

Se um número continuar atribuído, concilie essa atribuição existente. Não crie outra campanha apenas para tentar a desativação novamente nem presuma que um HTTP 204 comprove que a limpeza na operadora foi realizada. Se a sincronização local falhar depois que o registro aceitar a solicitação, a API poderá retornar 500 mesmo que a desativação externa já tenha ocorrido.

Resultados da desativação
Resultado	Próxima etapa
204	Não se espera um corpo de resposta. Verifique o estado da campanha e as atribuições de números, que são gerenciadas de forma independente.
400	Leia o erro de validação ou de estado do registro fornecido. Verifique o identificador exato da campanha e seu estado existente.
401, 403, 404	Verifique as credenciais da API, o IP de origem permitido e a titularidade da conta. Não use o identificador de outro cliente como substituto.
409, 429	Diferencie uma solicitação idempotente em andamento ou em conflito de uma limitação da taxa de solicitações; respeite Retry-After quando fornecido.
500, 502 ou tempo limite excedido	Guarde os detalhes da solicitação, consulte a campanha existente e concilie seu estado antes de enviar outra solicitação.

O encerramento é independente da liquidação da conta

O serviço DELETE atual não gera um débito imediato pelo registro da campanha. Isso não garante um reembolso, não anula um compromisso existente nem libera números alugados. Consulte no portal os termos das campanhas da conta e as faturas pendentes. O aluguel de números e o consumo de mensagens são independentes do registro da campanha.

Se todo o registro da empresa estiver sendo encerrado após a conciliação de suas campanhas e atribuições, prossiga com o encerramento da marca.