Acesso à conta e ao projeto
Use uma conta de API habilitada por meio de HTTPS a partir de um endereço IP permitido. O projeto deve pertencer a essa conta e não pode estar excluído. Use o identificador único do projeto obtido no fluxo de trabalho do pedido de portabilidade, e não seu identificador numérico no banco de dados nem um número de telefone. Aplique a codificação de URL ao identificador do projeto ao montar uma solicitação.
Preparar a inclusão
Esta operação altera um projeto de portabilidade existente. Primeiro, confirme os números e a autorização do cliente por meio do seu fluxo de trabalho de pedidos de portabilidade. Formate cada número com todos os dígitos internacionais, remova as duplicatas por conta própria e confira a lista de números já existentes no projeto. Não use este ponto de acesso para testar números arbitrários.
O portal atual valida e normaliza os números antes de chamar esta rota. O ponto de acesso legado, usado diretamente, não oferece as mesmas proteções: remove os espaços no início e no fim da entrada, mas não valida o formato dos números de telefone, o código do país, as duplicatas nem o estado do projeto no fluxo de trabalho.
Solicitação POST
Crie um arquivo local chamado numbers.json com a estrutura a seguir. Os números são fictícios; substitua-os por números autorizados para o projeto selecionado.
{
"numbers": [
"12025550123",
"12025550124"
],
"isocode": "US"
}curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--header "Content-Type: application/json" \
--data-binary @numbers.json \
"https://api.multitel.net/v3/lnp/project/$PROJECT_ID/addnumbers"| Campo | Significado |
|---|---|
| numbers | Lista obrigatória e não vazia de cadeias de caracteres que contêm números, ou uma cadeia de caracteres com um número por linha. As entradas em branco são descartadas e os espaços no início e no fim são removidos. O texto separado por vírgulas não é dividido em números individuais. |
| isocode | Código do país opcional para os registros adicionados. Quando omitido ou vazio, é usada a localização do projeto. O manipulador remove os espaços no início e no fim do valor fornecido, mas não o converte em maiúsculas nem o valida. Forneça por conta própria o código correto do país em maiúsculas. |
Use POST com application/json neste exemplo. Os dados de formulário enviados por POST também são lidos. O método não define uma chave de idempotência nem uma garantia específica deste ponto de acesso sobre o tamanho seguro dos lotes; confira lotes de tamanho administrável em vez de confiar em um limite presumido.
Resultado informado
Exemplo fictício de resposta.
{
"status": {
"code": 200,
"msg": "Success add numbers"
},
"response": {
"uniqueid": "PROJECT_EXAMPLE",
"count": 2,
"numbers": [
{
"id": 21,
"number": "12025550123",
"status": 0,
"status_str": "Pending",
"isocode": "US"
},
{
"id": 22,
"number": "12025550124",
"status": 0,
"status_str": "Pending",
"isocode": "US"
}
]
}
}A resposta identifica como Pending as inclusões que foram tentadas. Ela não verifica o resultado de cada inserção no banco de dados antes de informá-lo. Portanto, uma contagem ou um identificador retornado, por si só, não comprova que todos os registros foram armazenados de forma persistente. Uma inclusão com estado Pending não equivale à aceitação pela operadora, a uma transferência agendada nem a uma ativação concluída.
Conferir antes de tentar novamente
- Consulte a lista de números do projeto antes de adicionar números e guarde os detalhes da inclusão pretendida nos seus próprios registros de solicitações.
- Envie a solicitação de inclusão uma única vez.
- Consulte novamente a lista de números do projeto e compare cada número que pretendia adicionar. Verifique as duplicatas e os estados de cada número.
- Se a solicitação exceder o tempo limite, retornar um erro ou informar um resultado ambíguo, consulte os dados novamente antes de repetir a tentativa. Algumas inclusões podem já existir.
- Resolva os registros ausentes ou duplicados por meio do fluxo de trabalho de pedidos de portabilidade ou do suporte, em vez de repetir cegamente a solicitação completa.
O manipulador insere as entradas uma de cada vez, sem uma transação nem proteção contra duplicatas. Uma interrupção pode manter as gravações anteriores; uma inserção que falhe e retorne false ainda pode ser incluída na contagem informada. Repetir uma solicitação pode adicionar registros duplicados. O manipulador não registra por si só um evento nem conclui uma transferência com a operadora.
Erros do sistema legado
Um método diferente de POST retorna o código 403 da API. Um projeto inexistente, excluído ou que não pertença à conta retorna o código 404 da API. Uma entrada de números vazia também retorna o código 404 da API. Aplicam-se a autenticação e as restrições de IP de origem. Esses códigos legados não comprovam que nenhuma inserção anterior tenha ocorrido após o início do processamento.
Escopo de cobrança e transferência
O manipulador revisado insere registros de números do projeto e não realiza débito direto na conta nem envio à operadora. Isso não torna gratuito o serviço de portabilidade como um todo nem anula as tarifas de portabilidade acordadas. Cumpra os requisitos de autorização, documentação e revisão do projeto antes de esperar que uma transferência seja realizada.