Comprar um número de telefone selecionado

Escolha o número e o preço em conjunto

Compre um número específico selecionado em uma pesquisa recente de números disponíveis. Use o campo info.uuid da entrada selecionada como ID do número e um dos valores de price[].uuid dessa mesma entrada como ID do preço. A rota também aceita o número completo armazenado, mas um ID de país, área ou prefixo não substitui a seleção de um número.

Pesquisar ou consultar preços salvos não reserva um número nem congela seu preço. Confirme o preço de instalação, o preço mensal, a tarifa por minuto de chamadas recebidas, os minutos e os canais incluídos na opção selecionada, além das permissões de compra e dos requisitos de registro da conta. O valor base inicial na função auxiliar analisada é a soma do preço de instalação com o preço mensal; todas as cobranças e condições específicas do fornecedor devem ser confirmadas para o plano selecionado.

Envie por POST uma solicitação de compra com verificações de proteção

Use uma conta de API habilitada por HTTPS a partir de um endereço IP de origem permitido. O comando a seguir efetua uma compra, não uma cotação nem uma simulação. Defina todas as variáveis a partir da mesma seleção recente de número e preço. Os campos de limite preservam o prefixo legado restore_quote_; o portal atual também os utiliza em compras de números específicos com verificações de proteção.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "restore_quote_price_id=$PRICE_ID" \
  --data-urlencode "restore_quote_setup=$SETUP_PRICE" \
  --data-urlencode "restore_quote_monthly=$MONTHLY_PRICE" \
  --data-urlencode "restore_quote_per_minute=$PER_MINUTE_PRICE" \
  --data-urlencode "restore_quote_channels=$CHANNELS" \
  "https://api.multitel.net/v3/rentnumber/$NUMBER_ID/$PRICE_ID"

Use POST com dados de formulário, conforme mostrado. A função auxiliar também interpreta JSON e estruturas que encapsulam opções, mas esta análise não estabelece equivalência completa para todos os fluxos de cotação e de fornecedores. Não use GET para compras, embora este coordenador legado não tenha uma verificação explícita do método.

Informe todos os campos numéricos da cotação sempre que informar o ID do preço da cotação. Um ID alterado, um preço acima de um limite, um limite ausente ou inválido, uma quantidade de canais alterada ou um bloqueio de cotação ocupado faz com que a API retorne o código 409 antes de acionar o fornecedor de locação selecionado. As comparações permitem uma pequena tolerância de ponto flutuante; use os valores reais exibidos para o plano, em vez de um preço arredondado manualmente.

As verificações de proteção não transformam todo o fluxo em uma simulação nem em uma transação. Consultas de registro, provisionamento de identidade ou outras operações da função auxiliar podem ocorrer antes dessas verificações. Elas também não congelam o estoque externo nem substituem as restrições de compra da conta.

Registro e ativação

Quando necessário, adicione o campo de formulário RegistrationID contendo o UUID do perfil de registro pertencente ao cliente. Não se trata do ID de um comprovante enviado, de um endereço do fornecedor nem de uma entidade de identidade separada. A função auxiliar localiza o perfil no âmbito da conta autenticada e rejeita perfis ausentes ou indisponíveis.

Parte do estoque compatível permite a compra antes da conclusão do registro; outra parte exige um perfil antes da compra. Ainda pode ser necessária validação ou provisionamento específico da operadora. Não interprete uma compra bem-sucedida ou a ausência de uma verificação inicial como dispensa de registro ou ativação imediata.

Quando presente, o campo registration_requirements da resposta identifica a consulta estruturada de requisitos por país e tipo de número. Use o catálogo de registro e o fluxo de comprovantes para cumprir os requisitos aplicáveis. O texto e os metadados retornados não aprovam, por si só, um perfil.

Evite a substituição silenciosa do plano

O coordenador legado pode inferir um preço omitido a partir dos dados do número em cache. Também pode recorrer ao preço mais recente da conta para um prefixo em cache quando um ID de preço informado explicitamente já não existe, e atualizar a seleção de preço permitido em cache. Não dependa dessas alternativas para selecionar o plano aprovado pelo cliente.

Informe explicitamente o preço selecionado e os campos correspondentes de proteção da cotação. A verificação do ID da cotação rejeita a substituição por outro ID antes de acionar a locação. Após um conflito por preço desatualizado, atualize a pesquisa e obtenha uma nova seleção aprovada, em vez de remover as verificações para forçar a compra.

Não há período de reserva garantido nem prazo de validade do cache aplicado universalmente a todos os fluxos. A disponibilidade do número, os limites de preço da conta e as políticas de compra são verificados novamente durante o fluxo, mas o comportamento completo específico de cada fornecedor continua em análise.

Avançado: padrões de roteamento da conta

Uma compra pode herdar os destinos de voz, os destinos de contingência, o destino de SMS e a preferência de tronco de originação existentes na conta. Revise esses padrões antes de fazer o pedido; omitir opções de roteamento não garante um número sem configuração. A função auxiliar analisada habilita a renovação automática por padrão.

Essas são as regras de funcionamento da função auxiliar compartilhada, não uma garantia de que todos os fornecedores salvem todas as configurações opcionais de forma idêntica. Existem outros campos legados de voz, correio de voz, fax e SMS, mas eles ainda exigem uma análise completa específica de cada fornecedor. Verifique a configuração salva do número comprado pelo fluxo da conta antes de depender de chamadas ou mensagens.

Resposta

Exemplo fictício de uma compra sem complicações; os valores e os recursos variam conforme o plano selecionado.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "price": {
      "per_minute": "0.0100",
      "free_minutes": "100",
      "setup_price": "2.00",
      "monthly_price": "4.00",
      "channels": "2",
      "overflow": "0"
    },
    "features": [
      "voice"
    ],
    "needs_registration": 0,
    "registration_requirements": null
  }
}

O coordenador usa seus próprios campos status.code/status.msg e a estrutura de resposta response sem garantir a presença do campo status.results. Um erro geralmente apresenta uma lista de resposta vazia. Em caso de sucesso, examine o número e o preço retornados e, em seguida, confira o inventário da conta e o estado do registro. A aceitação pelo fornecedor não é um teste real de voz, SMS ou fax.

Erros e resultados incertos

Leia o corpo efetivo da resposta da API, além do status HTTP. Um fornecedor externo pode aceitar uma locação antes de ocorrer uma falha na notificação local, no registro ou em outro processamento. Algumas alocações do estoque local usam transações de banco de dados, mas não existe reversão universal dos pedidos feitos a fornecedores externos. Este coordenador não oferece uma chave de idempotência do cliente.

Confira o resultado antes de tentar novamente

1. Guarde o número, o preço e os limites da cotação aprovados no registro do pedido da sua aplicação antes de enviar a solicitação uma única vez.
2. Consulte o inventário de números comprados e os detalhes do número na mesma conta após a solicitação, inclusive após um tempo limite excedido ou um erro.
3. Se o número existir, verifique seu preço, renovação, roteamento e estado do registro em vez de enviar outra solicitação de compra.
4. Se o resultado ainda for incerto, peça ao suporte que confira o pedido no fornecedor e o faturamento da conta antes de tentar novamente. Uma mensagem de erro ou um indicador de sucesso em um log legado, por si só, não constitui evidência suficiente.
5. Após confirmar a titularidade e a ativação, conclua as verificações habituais de roteamento e os testes de serviço da conta.