Atualizar uma marca de mensagens

Corrigir uma marca de mensagens existente

Atualize a marca existente quando os dados de contato ou o endereço da empresa mudarem. Mantenha o identificador da marca; criar outro registro não é a maneira de corrigir os dados de uma empresa existente. Use uma conta de API habilitada por meio de HTTPS, a partir de um endereço IP de origem permitido. A marca deve pertencer a essa conta.

Comece consultando o registro atual. Mantenha sua cópia local privada, pois ela contém informações de identidade e contato da empresa.

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID" \
  --output current-brand.json

Preservar os campos atuais da marca

Prepare brand-update.json a partir do registro atual, selecionando apenas os campos da marca que podem ser alterados. Preserve a identidade da empresa e os demais valores obrigatórios ao aplicar a correção pretendida. Não envie a resposta GET inteira: brandId, resultados de identidade e estado, carimbos de data e hora e outros campos exclusivos da resposta não devem fazer parte da atualização.

O esquema de atualização exige entityType, displayName, country, email e brandRelationship. As regras específicas de cada tipo de entidade continuam se aplicando. Para uma organização, preserve a razão social, o identificador fiscal e o país emissor, o endereço e o setor, conforme aplicável. Para um empresário individual, preserve, em vez disso, os campos pertinentes de nome pessoal e contato por celular. Use os valores reais e atuais, não os valores ilustrativos de um exemplo de registro.

Grupos de campos para atualização da marca
Campos	Como usá-los
displayName, email, phone	Nome de marca reconhecível e dados de contato válidos. Comprimentos máximos: 255, 100 e 20 caracteres. Use o formato telefônico internacional com + e o código do país.
street, city, state, postalCode, country	Um endereço real da empresa com dados consistentes. Limites: 255, 100, 20, 10 e 2 caracteres. Use os códigos vigentes dos estados dos Estados Unidos quando aplicável.
entityType, companyName, ein, einIssuingCountry	Identidade legal. Essas alterações são restritas quando há campanhas ou processos de avaliação externa pendentes ou ativos. Não exclua campanhas em funcionamento apenas para contornar uma restrição de identidade.
firstName, lastName, mobilePhone, businessContactEmail	Dados de identidade ou de contato para verificação, quando apropriados ao tipo de entidade. Limites: 100, 100, 20 e 255 caracteres.
brandRelationship, vertical	Códigos atuais de relacionamento e setor. As alterações de relacionamento são limitadas a uma vez a cada três meses. O formulário normal de edição do portal não oferece alterações de relacionamento.
website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange	Site, identificação empresarial alternativa e dados de empresa de capital aberto, conforme aplicável. Preserve os valores necessários para a validação da entidade.
referenceId, ipAddress	Metadados aceitos de referência empresarial e de IP de origem. Nenhum deles define a qual conta a marca pertence nem atua como chave de idempotência da solicitação.

Use os catálogos de mensagens atuais para consultar os códigos. O esquema de atualização não oferece mock como forma de mudar o ambiente de uma marca. Use o fluxo separado e revisado de passagem do ambiente de testes para produção, em vez de alterar esse indicador durante uma edição.

Enviar a correção revisada

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @brand-update.json \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID"

Use uma única chave para esta atualização pretendida e preserve os bytes exatos do corpo da solicitação. Reutilizá-la com um método, caminho, consulta ou corpo diferente gera conflito; reformatar JSON também altera a impressão digital. Uma solicitação duplicada enquanto a original está em andamento pode retornar 409 com Retry-After. Uma solicitação concluída pode retornar novamente o resultado salvo, inclusive um erro. Mantenha os detalhes da solicitação ao esclarecer o resultado após o tempo limite, em vez de gerar automaticamente uma nova chave.

Verificar o registro salvo e o estado de validação

Uma atualização bem-sucedida retorna HTTP 200 e diretamente um objeto JSON da marca, sem o envelope legado da v3 com status/response. Confira seu brandId, consulte novamente a mesma marca usando GET e compare os campos que pretendia alterar. A rota pública de atualização não aceita o envelope changes/version do portal nem fornece sua verificação de concorrência otimista. Coordene as pessoas que editam simultaneamente; uma chave de idempotência impede envios duplicados, mas não as alterações de outra pessoa que esteja editando.

O portal atual consulta a marca, preserva seus campos editáveis, verifica a versão do formulário antes de salvar e consulta o resultado novamente. Ele bloqueia os campos principais de identidade legal quando encontra campanhas ativas. O registro pode impor restrições adicionais, inclusive restrições de avaliação externa, mesmo quando um formulário disponibilizou um campo para edição.

Salvar as informações corrigidas não solicita automaticamente uma nova verificação de identidade nem garante aprovação. A nova verificação é uma ação separada que pode ter uma taxa; use o portal para revisar o estado atual e confirmar explicitamente qualquer cobrança informada. As atualizações comuns de marca por PUT não geram um débito de registro separado no serviço de API atual. As cobranças existentes de campanhas, mensagens e outros serviços continuam separadas.

Resolver erros sem criar um registro duplicado

Consulte o estado HTTP e os detalhes do erro em JSON. Para 400, corrija o campo específico ou respeite a restrição de identidade ou relacionamento. Para 401, 403 ou 404, verifique as credenciais, o IP de origem permitido e se a marca pertence à conta. Para 429, respeite Retry-After. Um 500 ou 502 pode ocorrer depois que o registro tiver aceitado a atualização; preserve qualquer requestId e consulte o registro existente antes de enviar novamente.

Uma resposta de atualização não vazia, mas incompleta, pode deixar um retrato local incompleto; um corpo vazio em uma resposta de sucesso pode manter campos antigos desse retrato. Não deduza que os campos foram preservados apenas com base em um estado de sucesso. Consulte novamente a marca completa e resolva qualquer divergência com o suporte. Este guia não garante atualizações atômicas do registro, do cache local e do faturamento.