Enviar uma inscrição em uma lista telefônica

Enviar uma inscrição à lista telefônica de uma operadora

Envie o nome e o endereço a serem usados para inscrever em uma lista telefônica um número elegível que pertença a você na MultiTEL. Esta é uma atualização paga junto à operadora, não uma consulta ao nome de quem liga, um registro em uma agenda privada nem uma atualização geral do campo LIDB do inventário do portal.

Envie somente os dados que o cliente autorizou para inscrição em uma lista telefônica. Confirme se a operadora oferece suporte ao número antes de usar esta rota legada. O processador revisado não valida a elegibilidade do provedor nem o formato internacional do número; a solicitação à operadora pressupõe um número norte-americano e remove o primeiro dígito armazenado.

Requisitos da conta e do número

Use uma conta de API habilitada por meio de HTTPS, a partir de um endereço IP de origem permitido. O número exato deve constar em um registro não anulado de números comprados pertencente a essa conta. Use todos os dígitos internacionais do número conforme ele aparece no inventário, como o formato com código de país 1 para um número norte-americano compatível. Não use um identificador de plano de preços, um UUID de número nem um número pertencente a outra conta.

Solicitação POST com formulário

Defina NUMBER com o número que pertence a você. Substitua o exemplo fictício pelas informações autorizadas para a inscrição. Esta rota lê os campos de formulário de POST; ela não interpreta um corpo application/json.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "lastname=EXAMPLE" \
  --data-urlencode "firstname=EXAMPLE" \
  --data-urlencode "streetnum=1" \
  --data-urlencode "streetname=Example" \
  --data-urlencode "streetpredir=N" \
  --data-urlencode "streetpostdir=W" \
  --data-urlencode "city=Example City" \
  --data-urlencode "state=NY" \
  --data-urlencode "postalcode=10001" \
  "https://api.multitel.net/v3/directory/$NUMBER"

As orientações e o endereço do exemplo são dados ilustrativos, não um endereço postal recomendado. Não adicione uma orientação fictícia aos dados reais de um cliente. As verificações de campos obrigatórios da API são superficiais: elas não determinam se um endereço é válido ou aceito pela operadora, e o site legado aplicava requisitos de formulário diferentes.

A implementação pode emitir um aviso de chave ausente no array quando um componente de orientação opcional está ausente ou vazio. Se a resposta estiver malformada ou a operadora rejeitar o endereço, guarde a referência da solicitação e peça ao suporte que confirme a inscrição, em vez de enviar repetidamente endereços alterados com base em suposições.

Funcionamento das cobranças e das novas tentativas

O processador revisado verifica se há pelo menos 10.00 unidades de saldo antes de contatar a operadora. Depois que tanto a operadora quanto a atualização local do número informam sucesso, ele desconta 10.00 do saldo da conta e registra uma transação de inclusão na lista telefônica. Esses são os valores atualmente implementados, não uma nova proposta de preços; antes de enviar a solicitação, confirme a moeda de cobrança aplicável e o serviço compatível de acordo com as condições da sua conta.

A operação não possui chave de idempotência, proteção contra pedidos duplicados nem uma transação que englobe o envio à operadora, a atualização local e a cobrança. Uma solicitação repetida bem-sucedida pode causar outro envio à operadora e outra cobrança. Um tempo limite excedido ou um erro da API não comprova que a operadora rejeitou a solicitação anterior: o provedor pode tê-la aceitado antes de uma atualização local falhar.

Resposta

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": ""
}

A resposta normal de sucesso contém uma string vazia em response e não retorna um identificador de inscrição nem detalhes de conclusão. Isso significa que os fluxos da operadora e da atualização local informaram sucesso; não comprova a publicação em todas as listas telefônicas externas, a propagação imediata nem a exibição futura da identificação de chamadas.

Erros do sistema legado

Leia tanto o status HTTP quanto os campos do JSON status.code/status.msg. A autenticação e as restrições de IP de origem também podem impedir uma resposta utilizável. Não use GET nem parâmetros de consulta para solicitar uma atualização apenas porque o processador legado não possui uma verificação explícita do método HTTP.

Verifique antes de tentar novamente

1. Antes de enviar a solicitação, confirme o número que pertence a você, a elegibilidade junto à operadora, os dados autorizados da inscrição e a cobrança.
2. Envie a solicitação uma única vez e guarde o resultado da conta sem expor o endereço do cliente em registros públicos ou sistemas de análise.
3. Consulte a inscrição salva e o histórico de transações pelo procedimento compatível da conta ou por meio do suporte. Aguarde o tempo de processamento confirmado pela operadora; esta API não define um prazo garantido de propagação.
4. Quando o resultado for incerto, peça ao suporte que concilie o pedido da operadora e a cobrança local antes de tentar novamente. Uma solicitação repetida não é uma consulta de status idempotente.