Pular para conteúdo

📄 Gerenciar DIDs (ManageDID)

Visão Geral

A API de Gerenciamento de DIDs permite listar, criar, editar e excluir Números Entrantes (DIDs) e suas configurações de roteamento.

Base URL: /api/manageDID/{api_token}/{api_key}/

Formato: as requisições com body devem ser enviadas em JSON, com o header Content-Type: application/json.

Padrão de resposta:

  • Sucesso: {"error": 0, "reason": "OK", ...}
  • Falha: {"error": 1, "reason": "<CODIGO>", "message": "<descrição>"}

🔀 Endpoints Disponíveis

Método Endpoint Ação
GET /api/manageDID/{api_token}/{api_key}/{id} Lista os DIDs cadastrados.
PUT /api/manageDID/{api_token}/{api_key}/ Cria um novo DID.
POST /api/manageDID/{api_token}/{api_key}/{id} Atualiza os dados e o roteamento de um DID existente.
DELETE /api/manageDID/{api_token}/{api_key}/{id} Remove um DID.

As ações de criar, atualizar e excluir estão disponíveis apenas para contas Master.

📥 Consultar DIDs (GET)

Requisição: GET /api/manageDID/{api_token}/{api_key}/{id}

Parâmetros

Parâmetro Onde Obrigatório Descrição
{id} URL Não Conta Master ou Revenda: ID do cliente. Conta Assinante: ID do DID. Se não for informado, lista todos.
id_record Query string Não Conta Master ou Revenda: ID do DID. Ex: ?id_record=737

Exemplo cURL

curl -X GET "https://seu-servidor/api/manageDID/{api_token}/{api_key}/210"

Exemplo de Resposta (conta Master ou Revenda)

O primeiro item de data traz os DIDs em estoque da própria conta. Os itens seguintes trazem os clientes e seus DIDs.

{
    "error": 0,
    "reason": "OK",
    "records": 2,
    "data": [
        {
            "id": 1,
            "customer_type": "master",
            "nome_fantasia": "MINHA EMPRESA",
            "status": 1,
            "records": 0,
            "data": []
        },
        {
            "id": 210,
            "customer_type": "customer",
            "nome_fantasia": "CLIENTE TESTE",
            "status": 1,
            "records": 2,
            "data": [
                {
                    "id": 737,
                    "description": "teste registro did",
                    "did_number": "552130900017",
                    "did_type": 1,
                    "did_premium": 0,
                    "status": 1,
                    "device_id": 498,
                    "device_destination": "SIP/9907",
                    "destination_id": 0,
                    "did_type_name": "call_device"
                },
                {
                    "id": 738,
                    "description": "did da fila",
                    "did_number": "552130900018",
                    "did_type": 5,
                    "did_premium": 0,
                    "status": 1,
                    "device_id": 0,
                    "device_destination": null,
                    "destination_id": 12,
                    "did_type_name": "queue"
                }
            ]
        }
    ]
}

Exemplo de Resposta (conta Assinante)

Para contas Assinante, data é um objeto com os dados da própria conta.

{
    "error": 0,
    "reason": "OK",
    "records": 1,
    "data": {
        "id": 210,
        "customer_type": "customer",
        "nome_fantasia": "CLIENTE TESTE",
        "records": 1,
        "data": [
            {
                "id": 737,
                "description": "teste registro did",
                "did_number": "552130900017",
                "did_type": 1,
                "did_premium": 0,
                "status": 1,
                "device_id": 498,
                "device_destination": "SIP/9907",
                "destination_id": 0,
                "did_type_name": "call_device"
            }
        ]
    }
}

📋 Dicionário de Dados

Cliente

Campo Tipo Descrição
id int ID do cliente.
customer_type string master, reseller ou customer.
nome_fantasia string Nome fantasia do cliente.
status int 1 = ativo, 0 = inativo.
records int Quantidade de DIDs em data.
data array Lista de DIDs.

DID

Campo Tipo Descrição
id int ID do DID.
description string Descrição do DID.
did_number string Número do DID.
did_type int Funcionalidade do DID (ver tabela de funcionalidades).
did_type_name string Nome da funcionalidade do DID.
did_premium int 0 = Simples, 1 = Especial.
status int 1 = ativo, 0 = inativo.
device_id int ID da Linha IP de destino. 0 quando não há Linha IP.
device_destination string\ null Destino da Linha IP formatado (ex: SIP/9907). null quando não há Linha IP.
destination_id int ID da Fila de Atendimento ou do Menu de URA de destino. 0 quando não se aplica.

🏷️ Funcionalidades do DID (did_type)

did_type did_type_name Descrição
0 ip_forward Encaminhar por IP (padrão)
1 call_device Chamar Linha IP
2 voice_portal Portal de Voz
3 callingcard CallingCard
4 extension_menu Menu Ramal
5 queue Fila de Atendimento
6 ivr Menu de URA (IVR)
7 free_callback Callback Livre
8 auth_callback Callback Auth
9 reverse_ivr Menu de URA Reversa

📦 Campos do Body (PUT e POST)

Campo Tipo Padrão Descrição
did_number string — Obrigatório no PUT. Número do DID.
host string — Obrigatório no PUT. Endereço IP do servidor do fornecedor.
host_additional array [] Endereços IP adicionais do fornecedor.
tech string SIP Tecnologia.
description string gerado automaticamente Descrição do DID.
customer_id int 0 ID do assinante vinculado ao DID. 0 = DID em estoque.
owner_id int conta atual Somente POST. ID da conta dona do DID (Master ou Revenda).
rate_id int 0 ID do Plano de Prefixos.
did_premium int 0 0 = Simples, 1 = Especial.
did_type int 0 Funcionalidade do DID (ver tabela de funcionalidades).
device_id int 0 ID do destino do DID (ver tabela de roteamento).
did_type_id int 0 ID do Menu de URA, usado na URA Reversa (tipo 9).
port int 5060 Porta do servidor do fornecedor.
username string "" Usuário de autenticação no fornecedor.
password string "" Senha de autenticação no fornecedor.
register int 0 1 = registrar o DID no fornecedor (exige username e password).
techprefix1 string "" Tech prefix do destino 1 (Encaminhar por IP).
ip_address1 string "" IP do destino 1 (Encaminhar por IP).
port1 int 5060 Porta do destino 1 (Encaminhar por IP).
techprefix2 string "" Tech prefix do destino 2 (Encaminhar por IP).
ip_address2 string "" IP do destino 2 (Encaminhar por IP).
port2 int 5060 Porta do destino 2 (Encaminhar por IP).
callerid_add string "" CallerID adicional.
max_calls int 0 Chamadas simultâneas (0 = ilimitado).
codecs array\ string g729;ulaw;alaw Codecs liberados. Ex: ["g729","alaw"] ou "g729;alaw".
play_audio int 1 Reproduzir áudio em caso de erro.
hide_from_reseller int 1 Esconder os dados de autenticação da Revenda.
enable_fixed int 1 Permitir Fixo Nacional.
enable_mobile int 1 Permitir Móvel Nacional.
enable_ddi int 0 Permitir números DDI.
status int 1 1 = ativo, 0 = inativo.
annotations string "" Anotações.

Roteamento: o que enviar em cada funcionalidade

Quando o DID está vinculado a um assinante (customer_id informado), envie os campos abaixo conforme o did_type:

did_type Campos O que informar
0 - Encaminhar por IP device_id, ip_address1, port1, techprefix1 (destino 2 opcional) ID da Linha IP e os destinos de encaminhamento.
1 - Chamar Linha IP device_id ID da Linha IP.
4 - Menu Ramal device_id ID da Linha IP.
5 - Fila de Atendimento device_id ID da Fila de Atendimento.
6 - Menu de URA device_id ID do Menu de URA.
7 - Callback Livre device_id ID da Linha IP.
9 - URA Reversa device_id e did_type_id ID da Linha IP e ID do Menu de URA.
2, 3, 8 — Nenhum campo adicional.

Para DIDs em estoque (sem customer_id), não é necessário enviar roteamento.

➕ Criar DID (PUT)

Requisição: PUT /api/manageDID/{api_token}/{api_key}/

Body mínimo (DID em estoque)

{
    "did_number": "552130900017",
    "host": "200.100.50.10"
}

Body com assinante e roteamento para Linha IP

{
    "did_number": "552130900017",
    "description": "teste registro did",
    "host": "200.100.50.10",
    "customer_id": 210,
    "did_type": 1,
    "device_id": 498
}

Body completo

{
    "did_number": "552130900017",
    "description": "teste registro did",
    "tech": "SIP",
    "host": "200.100.50.10",
    "host_additional": ["200.100.50.11", "200.100.50.12"],
    "port": 5060,
    "username": "usuario_fornecedor",
    "password": "senha_fornecedor",
    "register": 1,
    "customer_id": 210,
    "rate_id": 3,
    "did_premium": 0,
    "did_type": 1,
    "device_id": 498,
    "did_type_id": 0,
    "techprefix1": "",
    "ip_address1": "",
    "port1": 5060,
    "techprefix2": "",
    "ip_address2": "",
    "port2": 5060,
    "callerid_add": "",
    "max_calls": 10,
    "codecs": ["g729", "ulaw", "alaw"],
    "play_audio": 1,
    "hide_from_reseller": 1,
    "enable_fixed": 1,
    "enable_mobile": 1,
    "enable_ddi": 0,
    "status": 1,
    "annotations": "DID criado via API"
}

Exemplo cURL

curl -X PUT "https://seu-servidor/api/manageDID/{api_token}/{api_key}/" \
  -H "Content-Type: application/json" \
  -d '{"did_number":"552130900017","host":"200.100.50.10","customer_id":210,"did_type":1,"device_id":498}'

Resposta

{
    "error": 0,
    "reason": "OK",
    "new_record": 737
}

new_record é o ID do DID criado, usado como {id} no POST e no DELETE.

✏️ Atualizar DID (POST)

Requisição: POST /api/manageDID/{api_token}/{api_key}/{id} ({id} = ID do DID)

Envie apenas os campos que deseja alterar. Os campos não enviados permanecem com o valor atual. Ao alterar o did_type, envie também os campos de roteamento correspondentes (ver Roteamento: o que enviar em cada funcionalidade).

Alterar dados cadastrais

{
    "description": "DID comercial",
    "max_calls": 20,
    "status": 1
}

Rotear para uma Linha IP (tipo 1)

{
    "customer_id": 210,
    "did_type": 1,
    "device_id": 498
}

Encaminhar por IP (tipo 0)

{
    "customer_id": 210,
    "did_type": 0,
    "device_id": 498,
    "techprefix1": "",
    "ip_address1": "200.100.60.20",
    "port1": 5060,
    "techprefix2": "",
    "ip_address2": "200.100.60.21",
    "port2": 5060
}

Rotear para uma Fila de Atendimento (tipo 5)

{
    "customer_id": 210,
    "did_type": 5,
    "device_id": 12
}

Rotear para um Menu de URA (tipo 6)

{
    "customer_id": 210,
    "did_type": 6,
    "device_id": 7
}

Rotear para URA Reversa (tipo 9)

{
    "customer_id": 210,
    "did_type": 9,
    "device_id": 498,
    "did_type_id": 7
}

Desvincular do assinante e mover para o estoque de uma Revenda

{
    "customer_id": 0,
    "owner_id": 55
}

Alterar dados do fornecedor

{
    "host": "200.100.50.20",
    "host_additional": ["200.100.50.21"],
    "port": 5060,
    "username": "novo_usuario",
    "password": "nova_senha",
    "register": 1,
    "codecs": "g729;alaw"
}

Ao enviar host ou host_additional, a lista de IPs do fornecedor passa a ser exatamente host + host_additional. Para manter IPs adicionais já cadastrados, envie-os novamente.

Exemplo cURL

curl -X POST "https://seu-servidor/api/manageDID/{api_token}/{api_key}/737" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":210,"did_type":5,"device_id":12}'

Resposta

{
    "error": 0,
    "reason": "OK"
}

🗑️ Excluir DID (DELETE)

Requisição: DELETE /api/manageDID/{api_token}/{api_key}/{id} ({id} = ID do DID). Não é necessário enviar body.

Exemplo cURL

curl -X DELETE "https://seu-servidor/api/manageDID/{api_token}/{api_key}/737"

Resposta

{
    "error": 0,
    "reason": "OK"
}

⚠️ Códigos de Erro

reason Descrição
API_NOT_FOUND Recurso não disponível para esta conta.
PERMISSION_DENIED A conta não tem permissão para esta operação.
DID_NOT_FOUND ID do DID não informado ou DID não encontrado.
INVALID_DID_NUMBER did_number não informado.
DID_NUMBER_EXISTS Número do DID já cadastrado.
OWNER_NOT_FOUND owner_id informado não foi encontrado.
INVALID_DEVICE_ID A funcionalidade escolhida exige device_id.
DEVICE_ID_NOT_FOUND Linha IP informada em device_id não foi encontrada.
QUEUE_NOT_FOUND Fila de Atendimento informada não foi encontrada.
IVR_NOT_FOUND Menu de URA informado não foi encontrado.
INVALID_HOST Endereço do fornecedor inválido.
MALFORMED_REQUEST Body da requisição não é um JSON válido.