Comprar números de telefone a partir de um prefixo

Comprar a partir de um prefixo

Utilize esta operação quando o catálogo de prefixos indicar que deve comprar uma quantidade a partir de um prefixo em vez de escolher números disponíveis individualmente. Comece por países, áreas ou estados, e prefixos. Guarde o identificador do prefixo e o plano de preços do mesmo resultado atualizado. Para um número específico selecionado numa lista de números disponíveis, utilize Comprar um número de telefone selecionado.

Este pedido pode comprar números e gerar cobranças. Não é uma cotação de preços, uma reserva nem uma simulação. Antes de o enviar, reveja os custos de ativação e as mensalidades, as tarifas por minuto de chamadas recebidas, os minutos incluídos, os canais, os requisitos de registo e os limites de compra da conta. Um resultado do catálogo não reserva inventário nem fixa preços. As verificações de carregamento de saldo da conta podem ocorrer antes do processamento da compra; um erro, por si só, não prova que não houve uma compra ou um carregamento de saldo da conta.

Enviar a compra

Utilize uma conta de API habilitada através de HTTPS, a partir de um endereço IP de origem autorizado. Defina as variáveis com base na sua seleção atual do catálogo e na sua configuração de entrega aprovada. O comando seguinte compra um número.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Acima é apresentado um POST de formulário. O coordenador também lê um objeto JSON quando Content-Type é application/json. Os campos JSON sobrepõem-se aos campos correspondentes do formulário/pedido. Utilize uma única codificação de forma consistente; não envie valores contraditórios nos parâmetros de consulta e no corpo.

Definições de entrega e renovação

Escolha as mesmas definições de entrega que utilizaria para o número no portal. Estes são valores de configuração avançada, não instruções para criar uma central telefónica alojada ou um tronco de originação. Reutilize uma configuração da conta que saiba estar a funcionar e verifique o número guardado após a compra. A aceitação de uma compra, por si só, não confirma que a entrega de voz ou SMS funciona.

Estes campos são normalizados e transmitidos à finalização da compra, mas a sua persistência difere entre os fluxos de inventário. A rota atual de pedidos não disponibiliza, como proteções equivalentes, os campos de limite rigoroso da cotação descritos no guia de compra de um número selecionado. Utilize as permissões de compra e os limites de preço da conta e verifique a configuração resultante do número.

Ler o resultado completo

Analise o corpo JSON e verifique status.code e status.msg, mesmo quando o pedido HTTP é bem-sucedido. Esta rota escreve a sua própria resposta JSON, e a função auxiliar de resposta partilhada também não associa necessariamente o código da aplicação ao estado HTTP. Os códigos da aplicação podem ser números JSON ou cadeias de caracteres numéricas. Não exija status.results; esse campo não está presente no resultado normal de um pedido.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

O identificador, o número e os preços acima são fictícios. Trate o ID do pedido como opaco. numbers lista os números que esta resposta indica como comprados; compare o comprimento da lista com a quantidade que solicitou. Os montantes dos preços são cadeias de caracteres e esta resposta arredonda as tarifas monetárias para duas casas decimais, incluindo per_minute; utilize o catálogo atualizado para obter a precisão original das tarifas. Os minutos incluídos e os canais podem chegar como valores numéricos ou cadeias de caracteres numéricas.

O bloco de preços descreve o plano selecionado utilizado para construir a resposta, não uma fatura detalhada de cada número nem o total do pedido. Os vários candidatos do inventário podem ter planos diferentes. Concilie os números comprados individualmente e as transações da conta, em vez de multiplicar os valores deste bloco e presumir que isso comprova o total final.

Compras parciais e resultados incertos

Um código de aplicação 200 pode vir acompanhado de um aviso e de menos números do que os solicitados. Uma falha posterior não anula a compra dos números já comprados. Guarde o ID do pedido, os números e a mensagem devolvidos. Concilie esses números com o seu inventário e as transações da conta antes de decidir se deve comprar a quantidade em falta.

Um tempo limite excedido, uma ligação interrompida durante o pedido, uma resposta malformada ou um erro após o envio não provam que nada aconteceu. Não envie automaticamente outra compra, mesmo com a mesma referência. Guarde o pedido original, a referência e qualquer ID de pedido devolvido, verifique o inventário e as transações da conta e contacte o suporte quando o resultado continuar incerto.

Um pedido não confirmado pode devolver o código de aplicação 400 com uma mensagem a indicar que ainda está em confirmação. Guarde o ID de pedido devolvido e concilie essa compra; isto não é uma instrução para a enviar novamente. A recuperação de pedidos registados acompanha internamente o pedido original. Um novo pedido a esta operação cria uma tentativa de compra distinta em vez de retomar um pedido através da sua referência, pelo que pode comprar e gerar cobranças por mais números. Não utilize pedidos de compra repetidos para verificar o estado ou pesquisar o inventário.

Registo e ativação

Um número comprado ou alocado pode ainda precisar de registo ou ativação. Se needs_registration for 1, verifique restrictions e registration_requirements. Este último campo pode indicar v3/get_requirements com valores de country e number_type. Conclua o processo aplicável de verificação de identidade/morada e confirme o estado do número antes de depender da receção de chamadas ou de mensagens.

features descreve as funcionalidades anunciadas; não confirma o encaminhamento em funcionamento, a aprovação de campanhas, a entrega de SMS nem a receção de fax. Verifique as definições de entrega guardadas e realize o teste de serviço adequado quando o número estiver ativo.

Notificações de retorno dos pedidos

As notificações de retorno enviam, através de POST, JSON com o estado e a resposta do pedido, acrescentando a sua referência quando fornecida. São enviadas para as compras comunicadas, incluindo resultados parciais. Uma falha na notificação de retorno não anula a compra. A entrega pode ser repetida, pelo que deve tratar os duplicados pelo ID do pedido e conciliar os números em vez de efetuar outra compra.

Esta rota não acrescenta uma assinatura criptográfica à notificação de retorno. Trate-a como uma notificação a conciliar com o inventário obtido através de autenticação, não como uma autorização independente para cobrar, provisionar ou conceder acesso. Não coloque credenciais de API no URL de notificação de retorno. Enviar outra compra com um URL de notificação de retorno diferente não atualiza o pedido original; cria uma tentativa de compra distinta. Guarde o ID do pedido original ao solicitar ao suporte que investigue a respetiva notificação de retorno.

Falhas a tratar