API para números de telefone e documentos

Com a ajuda da API é possível implementar a conexão e gestão dos números virtuais a partir da própria interface (painel admin) sem necessidade de entrar na área pessoal da Zadarma.

Todas as possibilidades e métodos da API da Zadarma - https://zadarma.com/pt/support/api/

Para a conexão do número é necessária a identificação do utilizador final. Os documentos do utilizador também são carregados pela API.

Possibilidades da API:

• seleção e conexão de números virtuais
• ajustes de números já conectados
• trabalho com documentos para a conexão de números (informação sobre os requisitos de conexão, upload de documentos, verificação de documentos já carregados para o pedido de um determinado número)

Sequência de passos para a conexão de um número através da API:

1. Obtenção da lista atual de países e destinos para o pedido, mostrar ao utilizador
2. Obtenção e visualização da lista de números disponíveis para conexão
3. Criação de grupo de documentos para o utilizador (se ainda não foi criado) e upload de documentos (em caso de necessidade)
4. Conexão do número selecionado ao grupo de documentos
5. Vinculação do número ao SIP ou a SIP URI (set_sip_id)

Conexão de novos números

Método GET /v1/direct_numbers/countries/ obtenção da lista de países em que se pode conectar o número, se a solicitação for enviada sem parâmetros a resposta será no idioma da área pessoal, ao adicionar o parâmetro opcional language é possível obter a resposta em um dos idiomas da área pessoal.

Método GET /v1/direct_numbers/country/ para obter a lista de destinos no país em que se pode conectar o número. Parâmetro obrigatório country - código ISO do país (ISO 3166-1 alpha-2); Parâmetros opcionais language e direction_id. Na resposta aparecerá o conjunto de dados com a descrição do número: país, cidade, custo de conexão, mensalidade, particularidades, possibilidade de receber SMS, etc.

Obtenção da lista de números disponíveis para conexão, método GET /v1/direct_numbers/available/<DIRECTION_ID>/ com parâmetros DIRECTION_ID - ID do destino ou ru495; e mask - parâmetro opcional para a busca de coincidências nos números.

É possível conectar o número com a ajuda do método POST /v1/direct_numbers/order/.

O número já conectado pode ser estendido pelos meses desejados pelo método POST /v1/direct_numbers/prolong/

Interação com os números já conectados

Método GET /v1/direct_numbers/ (sem parâmetros) devolve o conjunto com a informação dos números já conectados.

Método GET /v1/direct_numbers/number/ para obter a informação sobre um determinado número conectado, a solicitação é enviada com os parâmetros type e number

Estado de autorrenovação do número (será ou não automaticamente estendido para o próximo período ou será desativado ao final do período pago), pode ser conhecido através do método GET /v1/direct_numbers/autoprolongation/ com os parâmetros de solicitação type e number

Para modificar o estado de autorrenovação existe o método PUT /v1/direct_numbers/autoprolongation/ com parâmetros de solicitação type, number e value

Método PUT /v1/direct_numbers/set_caller_name/ - ajuste ou ativação do Nome do número (letras latinas, até 30 caracteres), também enviado no cabeçalho From em uma chamada entrante como CALLERID(name).

Através do método PUT /v1/direct_numbers/set_sip_id/ é possível enviar as chamadas do número virtual a um determinado SIP, servidor externo através de SIP URI ou ativar o modo de teste. Parâmetros obrigatórios de solicitação type, number e sip_id - SIP ou endereço do servidor externo, por exemplo 1234567890@myserver.com test_mode - opcional, (on|off) - para ativar o modo de teste.

Trabalho com documentos

O grupo de documentos são dados da pessoa ou empresa que será o utilizador final dos números virtuais, é possível ter vários grupos.

Criação de novos grupos de documentos, método POST /v1/documents/groups/create/

É possível atualizar os dados do grupo de documentos já existente com o método PUT /v1/documents/groups/update/<GROUPID>/ .

O upload do arquivo de documento para o grupo de documentos é realizado com o método POST /v1/documents/upload/ .

Com o método GET /v1/documents/groups/list/ é possível obter a lista de grupos de documentos e com o método GET /v1/documents/groups/get/<ID>/ onde ID é o identificador do grupo, 0 - grupo de documentos principal, é possível obter a informação sobre um grupo de documentos determinado.

O método GET /v1/documents/files devolve a lista de documentos/arquivos previamente carregados no grupo de documentos. group_id - parâmetro opcional, ID do grupo de documentos, (0 ou se não estabelecido - grupo de documentos principal).

Verificação: serve ou não o grupo de documentos para a conexão do número de uma determinada cidade/destino é realizada através do método GET /v1/documents/groups/valid/<ID>/ .