Consultar o estado de um projeto de portabilidade

Acesso à conta e ao projeto

Utilize uma conta de API ativa através de HTTPS, a partir de um endereço IP permitido. O projeto tem de pertencer a essa conta e não pode estar eliminado. Utilize o identificador único do projeto obtido no fluxo do pedido de portabilidade, não o identificador numérico da base de dados nem um número de telefone. Ao criar um pedido, codifique o identificador do projeto para utilização num URL.

Pedido

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/lnp/project/$PROJECT_ID/status"

Este ponto de acesso não lê qualquer corpo de pedido, parâmetro de paginação ou filtro de data.

Resposta

Exemplo de resposta fictício.

{
  "status": {
    "code": 200,
    "msg": "Project Status"
  },
  "response": {
    "uniqueid": "PROJECT_EXAMPLE",
    "status": 2,
    "status_str": "Completed",
    "counts": {
      "total": 2,
      "pending": 0,
      "in_progress": 0,
      "completed": 1,
      "rejected": 1
    }
  }
}

O campo externo status.code indica o resultado da API. O campo separado response.status é o resumo de portabilidade calculado a partir dos estados do projeto. Não confunda os dois campos.

Um resumo não representa o resultado de todos os números

O resumo seleciona In Progress se algum número tiver esse estado; caso contrário, seleciona Pending, depois Completed e, por fim, Rejected, de acordo com o primeiro estado presente nessa ordem. Se não houver correspondência com qualquer estado conhecido, utiliza Pending por predefinição. Assim, um projeto que contém tanto números com a portabilidade concluída como números rejeitados indica Completed, embora continue a ter números rejeitados.

Verifique sempre as contagens e a lista de números individuais antes de decidir que todo o projeto está concluído. counts.total inclui todas as linhas de números do projeto; os outros contadores abrangem apenas os quatro valores de estado conhecidos e a sua soma pode não corresponder ao total quando existem outros valores. Um projeto sem números apresenta zero em todos os contadores e um resumo Pending.

Interpretar o estado de portabilidade

Mantenha o estado numérico e aceite valores desconhecidos. Para designações desconhecidas, é utilizado o valor armazenado, sem garantia de uma nova designação. Um estado de conclusão ou uma data agendada armazenados não testam, por si só, o encaminhamento de entrada nem todos os serviços do número.

Erros e limites

Verifique tanto a resposta HTTP como status.code/status.msg. Um projeto inexistente, eliminado ou que não pertence à conta devolve o código API 404 com uma mensagem a indicar que o projeto não foi encontrado. Também se aplicam a autenticação e as restrições de endereço IP de origem. Os exemplos não efetuam qualquer pedido real e uma resposta bem-sucedida não prova que uma operadora tenha aceitado ou concluído uma transferência.

Efeitos

Este ponto de acesso lê as contagens armazenadas do projeto. No controlador revisto, não submete pedidos de transferência, altera estados, inicia chamadas nem debita a conta. Não disponibiliza consultas à operadora em tempo real nem subscrições de notificações por webhook.