• Instruções para a integração do sistema CRM e telefónico da Zadarma
• Integração do próprio sistema CRM e Zadarma
• Webhook para funcionamento do IVR: um robô de voz criado por si
• Criação de contactos no CRM a partir do formulário Web
• Como integrar o webphone no seu sistema
• Telefonia com a sua própria marca (White Label)
• Trabalhar com números virtuais através da API

• visualização e alteração das definições SIP e central telefónica virtual;
• visualização de estatísticas e dados de saldo;
• envio de chamadas (CallBack para números de extensão externos e internos) e mensagens SMS;
• notificação do servidor externo sobre cada chamada recebida para a central telefónica virtual, bem como encaminhamento de chamadas externas.

Cada solicitação que requer autorização é acompanhada de um cabeçalho adicional, como:

"Authorization: senha_do_usuário: assinatura"

As palavras-passe de autorização devem ser obtidas na área pessoal.

A assinatura é realizada de acordo com o seguinte algoritmo:

• um conjunto de parâmetros transmitidos (GET, POST, PUT, DELETE) ordenados alfabeticamente pelo nome da tecla;
• do conjunto obtido gera-se uma cadeia de consulta (por exemplo, a função http_build_query no PHP), exemplo "from=DATEFROM&to=DATETO…";
• etc - une-se através da fórmula: linha = nome_método linha_solicitação md5(linha_solicitação), onde "nome_método" - linha da solicitação, começando pelo domínio (indicando a versão API), antes da enumeração de parâmetros, por exemplo - '/v1/sip/'
• a cadeia resultante é transformada através da função de hash de acordo com o algoritmo sha1 com uma palavra-passe do utilizador: hash = hash(linha palavra-passe_secreta)
• e em seguida o hash é codificado em base64 assinatura = base64_encode(hash)

                                    ksort($params);
$paramsStr = http_build_query($params, null, '&', PHP_QUERY_RFC1738);
$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));
$header = 'Authorization: ' . $userKey . ':' . $sign;

A classe preparada em PHP para trabalhar com a API pode ser descarregada no GitHub.

Formatos de resposta: json (por padrão) e xml.

Para obter resposta na API em formato xml, adicione um parâmetro à cadeia de consulta "format=xml".

                                    {
    "status":"error",
    "message":"Check phone's number"
}

                                    <?xml version="1.0"?>
<answer>
    <status>error</status>
    <message>Check phone number</message>
</answer>

A resposta também contém informações sobre os limites e a solicitação atual, por exemplo:

X-Zadarma-Method: /v1/ X-RateLimit-Reset: 1434371160 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99

onde,

• X-Zadarma-Method - método de chamada atual;
• X-RateLimit-Remaining - número de solicitações restantes, considerando o limite no método e por usuário;
• X-RateLimit-Limit - número total de acessos por minuto;
• X-RateLimit-Reset - tempo de reinício do limite.

Limitações gerais - 100 solicitações por minuto, em métodos estatísticos: 3 solicitações por minuto.

Em caso de bloqueio, o método dá a resposta 429 com o cabeçalho "You exceeded the rate limit".

A resposta é composta pela chave obrigatória "status" (success ou error). Além disso, dependendo do método, são fornecidas as chaves correspondentes com as informações solicitadas.

Em caso de erro, é fornecida uma chave adicional "message" com a descrição do erro.

Da mesma forma, todas as respostas são acompanhadas pelos correspondentes cabeçalhos HTTP..

saldo de utilizador

                                    {
    "status":"success", 
    "balance":10.34, 
    "currency":"USD"
}

                                    <?xml version="1.0">
<answer>
    <status>success</status>
    <balance>10.34</balance>
    <currency>USD</currency>
</answer>

o custo de uma chamada com base no tarifário atual do utilizador

                                    {
    "status":"success",
    "info": {
        "prefix":"4420",
        "description":"United Kingdom, London",
        "price":"0.009",
        "currency":"USD",
    }
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <prefix>4420</prefix>
        <description>United Kingdom, London</description>
        <price>0.009</price>
        <currency>USD</currency>
    </info>
</answer>

Parámetros

• number – número de telefone
• caller_id (opcional) – CallerID, que se utiliza para efetuar a chamada.


fuso horário do utilizador

                                    {
    "status":"success",
    "unixtime":1483228800,
    "datetime":"2017-01-01 00:00:00",
    "timezone":"UTC+0"
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <unixtime>1483228800</unixtime>
    <datetime>2017-01-01 00:00:00</datetime>
    <timezone>UTC+0</timezone>
</answer>

informações sobre a tarifa atual do utilizador

                                    {
    "status":"success",
    "info": {
        "tariff_id":5,
        "tariff_name":"Standart, special",
        "is_active":false,
        "cost":0,
        "currency":USD,
        "used_seconds":1643,
        "used_seconds_mobile":34,
        "used_seconds_fix":726,
        "tariff_id_for_next_period":5,
        "tariff_for_next_period":Standart, special
    }
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <tariff_id>5</tariff_id>
        <tariff_name>Standart, special</tariff_name>
        <is_active>false</is_active>
        <cost>0</cost>
        <currency>USD</currency>
        <used_seconds>1643</used_seconds>
        <used_seconds_mobile>726</used_seconds_mobile>
        <used_seconds_fix>726</used_seconds_fix>
        <tariff_id_for_next_period>5</tariff_id_for_next_period>
        <tariff_for_next_period>Standart, special</tariff_for_next_period>
    </info>
</answer>

onde

• tariff_id – ID do tarifário atual do utilizador;
• tariff_name – nome do tarifário atual do utilizador;
• is_active – tarifário atual ativa ou inativa;
• cost – custo do tarifário;
• currency – moeda do tarifário;
• used_seconds – quantidade de segundos utilizados do tarifário;
• used_seconds_mobile – quantidade de segundos usados em números móveis;
• used_seconds_fix – quantidade de segundos utilizados do tarifário para números fixos;
• used_seconds_speech_recognition – quantidade de segundos utilizados para o reconhecimento de voz;
• tariff_id_for_next_period – ID do tarifário do utilizador no próximo período;
• tariff_for_next_period – nome do tarifário do utilizador no próximo período.

retorno de chamada

                                    {
    "status":"success", 
    "from":442037691880, 
    "to":442037691881, 
    "time":1435573082
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <time>1435573082</time>
</answer>

Parâmetros

• from – o seu número de telefone ou SIP, ou a extensão da central telefónica virtual, ou o número do script da central telefónica para a qual é efetuada a chamada de retorno;
• to – número de telefone ou SIP, para o qual é efetuada a chamada;
• sip (opcional) – número SIP do utilizador ou extensão da central telefónica virtual (por exemplo 100), através do qual se realiza a chamada. Vai ser utilizado o CallerID deste número, e nos dados estatísticos será mostrado este número SIP/АТС. Se o número especificado incluir gravação de chamadas ou prefixos de marcação, também serão utilizados.
• predicted (opcional) – se este indicador for especificado, então a solicitação é preditiva (o sistema liga inicialmente para o número "to" e só se a chamada for atendida, se conecta ao teu número SIP ou número de telefone);

confirmação do número

                                    {
    "status":"success",
    "from":442037691880,
    "to":442037691881,
    "lang":"fr",
    "time":1612779278
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <lang>fr</lang>
    <time>1612779327</time>
</answer>

Parâmetros

• caller_id - número apresentado nas chamadas, disponível apenas para os números ligados à Zadarma,
• to - número de telefone ou número SIP para o qual estão a ligar,
• code - código que se pretende reproduzir. Apenas dígitos e comprimento inferior a 20 caracteres,
• lang - idioma do texto. Na sua ausência, é selecionada a língua da área pessoal do cliente e é verificada a presença das línguas do sistema.

atualização da base de clientes

Parâmetros

• numbers – lista de números a atualizar em formato internacional.

Se os números contiverem 1 número, o resultado será devolvido imediatamente; se for indicada uma lista de números, o resultado será enviado para o endereço indicado na página de atualização de contactos ou para o endereço de correio eletrónico, se não for indicado qualquer outro destino.

*Atenção!**as definições para este método são configuradas na página de atualização da base de clientes da área pessoal.

Exemplo de resposta para 1 número:

(Resposta 1)

                                    Resposta 1:
{
    "status":"success",
    "info":{
        "mcc":"24702",
        "mnc":"02",
        "mccName":"Latvia",
        "mncName":"Tele2",
        "ported":false,
        "roaming":false,
        "errorDescription":"No Error"
    }
}

Exemplo de resposta para vários números:

(Resposta 2)

                                    Resposta 2:
{
    "status":"success"
}

Exemplo do resultado enviado para o endereço indicado na página de atualização:

(Resposta 3)

                                    Resposta 3:
{
    "success":true,
    "description":"Success",
    "result": [
        {
            "mcc":"24702",
            "mnc":"02",
            "ported":false,
            "roaming":false,
            "errorDescription":"No Error",
            "mccName":"Latvia",
            "mncName":"Tele2",
            "number":"3712812858",
        }, ...
    ]
}

Lista de moedas

                                    {
    "status": "success",
    "currencies": [
        "USD",
        "EUR",
        "GBP",
        "PLN"
    ]
}

Lista de línguas disponíveis na área pessoal

                                    {
    "status": "success",
    "languages": [
        "en",
        "es",
        "de",
        "pl",
        "ru",
        "ua",
        "fr"
    ]
}

Lista de tarifários

                                    {
    "status": "success",
    "currency": "EUR",
    "tariffs": [
        {
            "tariff_id": 5,
            "name": "Standard",
            "cost": 0,
            "days": "30"
        },
        ...
    ],
    "package_tariffs": [
        {
            "id": 1,
            "name": "EU",
            "tariffs": [
                {
                    "tariff_id": 23,
                    "name": "Office",
                    "cost": 22,
                    "cost_annual": 216
                },
                ...
            ]
        },
        ...
    ]
}

Parámetros:

• currency – moeda

lista de números SIP do utilizador

                                    {
    "status":"success",
    "sips":[
        {"id":"00001", "display_name":"SIP 1", "lines":3},
        {"id":"00002", "display_name":"SIP 2", "lines":3}
    ],
    "left":3
}

                                    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <sips>
            <value>
                <id>00001</id>
                <display_name>SIP 1</display_name>
                <lines>3</lines>
            </value>
            <value>
                <id>00002</id>
                <display_name>SIP 2</display_name>
                <lines>3</lines>
            </value>
        </sips>
        <left>1</left>
    </answer>

onde

• id– SIP-id;
• display_name – nome a ser exibido;
• lines – número de linhas;
• left – número de SIP restantes que podem ser criados (depende do saldo do utilizador e do número total de SIP já criados).

estado online do número SIP do utilizador

                                    {
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <is_online>false</is_online>
</answer>

alteração do CallerID

                                    {
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <new_caller_id>442037691880</new_caller_id>
</answer>

Parâmetros

• id – ID do SIP ao qual o Caller ID é alterado;
• number – número a ser alterado no formato internacional (da lista de números confirmados ou comprados pelos utilizadores)

visualização do reencaminhamento atual por números SIP do utilizador

                                    {
    "status":"success",
    "info": [
        {
            "sip_id":"00001",
            "status":"on",
            "condition":"always",
            "destination":"phone",
            "destination_value":"442037691880"
        },
    ...
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <sip_id>00001</sip_id>
            <status>on</status>
            <condition>always</condition>
            <destination>phone</destination>
            <destination_value>442037691880</destination_value>
        </value>
    ...
    </info>
</answer>

Parâmetros

• id – (opcional) Seleção de id específico SIP. donde

• sip_id– Id de SIP do utilizador;

• status – estado atual: on ou off;

• condition – condições de reencaminhamento: sempre - sempre (predefinição), indisponível - no caso de não atender a chamada ou no caso de ausência de uma conexão SIP;

• destination – destino do reencaminhamento: telefone - para o número de telefone, central telefónica - para a central telefónica virtual;

• destination_value – Número de desvio: número de telefone ou ID da central telefónica virtual..

ativação/desativação do reencaminhamento com base no número SIP

                                    {
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <current_status>on</current_status>
</answer>

Parâmetros

• id – SIP id;
• status – o estado apresentado no número SIP selecionado.

alteração dos parâmetros de encaminhamento

                                    {
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <destination>442037691880</destination>
</answer>

Parâmetros

• id – SIP id;
• type – tipo de reencaminhamento: telefone - para telefone;
• number – número de telefone.
• condition – parâmetro facultativo, condição de reencaminhamento (sempre - sempre, indisponível - no caso de não estar fora do descanso ou de não haver ligação SIP)

Adicionar SIP

                                    {
    "status": "success",
    "sip": "123456"
}

Parâmetros

• name - nome exibido;
• password - palavra-passe;
• callerid - número para CallerID;
• redirect_to_phone - parâmetro opcional, reencaminhamento SIP para o telefone;
• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por parceiros.

Alteração da palavra-passe no SIP

Parâmetros

                                    {
    "status":"success",
    "sip":$sip,
}

• value - nova palavra-passe;
• user_id - parâmetro opcional, disponível apenas para utilização por revendedores e apenas para os utilizadores por eles criados.

obtenção de estatísticas gerais

(Resposta 1)

                                    Resposta 1:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":442037691880,
            "to":442037691881,
            "description":"United Kingdom, London",
            "disposition":"busy",
            "billseconds":0,
            "cost":0.1950,
            "billcost":0.0000,
            "currency":"USD"
        },
        …
    ]
}

                                    Resposta 1:
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 13:58:22</end>
    <stats>
        <value>
            <id>155112249</id>
            <sip>00001</sip>
            <callstart>2015-06-02 12:20:25</callstart>
            <description>United Kingdom, London</description>
            <disposition>busy</disposition>
            <billseconds>0</billseconds>
            <cost>0.195</cost>
            <billcost>0</billcost>
            <currency>USD</currency>
            <from>442037691880</from>
            <to>442037691881</to>
        </value>
        …
    </stats>
</answer>

Parâmetros

• start - data de início da visualização das estatísticas (formato - AAAA-MM-DD HH:MM:SS);
• end - data final da visualização das estatísticas (formato - AAAA-MM-DD HH:MM:SS);
• sip (opcional) - filtrar de acordo com um determinado número SIP;
• cost_only (opcional) - ver apenas o montante gasto durante o período;
• type ( opcional - apenas nas estatísticas gerais) - tipo de consulta: geral (não indicado no requerimento), toll-free e ru-495 (para estatísticas de números 800 e números 495 gratuitos);
• skip (opcional - não é considerado para este parâmetro cost_only) - o número de linhas a omitir na seleção, a saída começará a partir da quebra de linha + 1 (utilizado para paginação juntamente com o parâmetro limit, o valor por defeito é 0); -limit(opcional - não é contabilizado para cost_only) é o limite do número de linhas de saída (utilizado para paginação com o parâmetro predefinido, valor máximo 1000, a predefinição é 1000).

Prazo máximo para a receção de dados estatísticos - mês. Em caso de aumento do limite do pedido, o prazo é automaticamente reduzido para 30 dias. Se a data de início da seleção não for indicada, é selecionado o início do mês em curso. Se a data final da seleção não for indicada, a seleção é limitada à data e hora atuais.

Número máximo de linhas introduzidas para um pedido - 1000. Para a paginação, utilizar os parâmetros skip e limit.

?type=cost_only:

(Resposta 2)

                                    Resposta 2:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"USD",
            "seconds":9785
        }
    ]
}

                                    Resposta 2:
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 14:03:30</end>
    <stats>
    <value>
        <cost>38.094</cost>
        <currency>USD</currency>
        <seconds>9785</seconds>
    </value>
    </stats>
</answer>

de onde

• start – data de início da visualização das estatísticas;
• end – data final da visualização das estatísticas;
• id – id de chamada;
• sip – número SIP;
• callstart – hora do início da chamada;
• description – descrição do destino da chamada;
• disposition – estado da chamada:
  • 'answered' – chamada,
  • 'busy' – ocupado,
  • 'cancel' - cancelado,
  • 'no answer' - sem resposta
  • 'call failed' - não foi possível,
  • 'no money' - sem saldo, limite excedido,
  • 'unallocated number' -o número não existe,
  • 'no limit' - o limite foi ultrapassado,
  • 'no day limit' - o limite diário foi ultrapassado,
  • 'line limit' - o limite da linha foi ultrapassado,
  • 'no money, no limit' - o limite foi ultrapassado;
• billseconds – número de segundos da chamada;
• cost – custo por minuto de uma chamada para este destino;
• billcost –custo dos minutos subscritos;
• currency – moeda do pagamento da chamada;
• from – a partir de que número foi efetuada a chamada;
• to – onde foi chamado.

estatísticas da central telefónica

Atenção! se precisar de estatísticas atualizadas da central telefónica não é necessário solicitar a cada minuto o método statistics/pbx/. Active as notificações webhooks e obtenha a informação de cada chamada no momento do seu início e fim.

                                    {
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "version":2,
    "stats":[
        {
            "call_id":1439981389.2702773,
            "sip":200,
            "callstart":"2015-06-01 15:04:00",
            "clid":200,
            "destination":5,
            "disposition":"answered",
            "seconds":5,
            "is_recorded":true,
            "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
        },
        …
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success<</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-30 23:59:59</end>
        <version>2</version>
        <stats>
        <value>
            <call_id>1439981389.2702773</call_id>
            <sip>200</sip>
            <callstart>2015-06-01 15:04:00</date>
            <clid>200</clid>
            <destination>5</destination>
            <disposition>answered</disposition>
            <seconds>5</seconds>
            <is_recorded>true</is_recorded>
            <pbx_call_id>in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d</pbx_call_id>
        </value>
        …
    </stats>
</answer>

Parâmetros

• start - data de início para revisão dos dados estatísticos (formato - YYYY-MM-DD HH:MM:SS);
• end - data de fim para revisão dos dados estatísticos (formato - YYYY-MM-DD HH:MM:SS);
• version - formato de entrada dos dados estatísticos (2 - novo, 1 - antigo);
• skip (opcional) - número de linhas a serem ignoradas na seleção, a seleção começa a partir da linha skip +1 (usado para paginação junto com o parâmetro limit que, por defeito é igual a 0);
• limit (opcional) - limite de linhas a serem retornadas (usado para paginação junto com o parâmetro skip, valor máximo 1000, valor padrão é 1000);
• call_type (opcional) - tipo de chamada ('in' para chamadas recebidas, 'out' para as efetuadas). Se não for especificado, todas as chamadas serão retornadas.

onde

• start – data de início da visualização das estatísticas;
• end – data de término da visualização das estatísticas
• version -formato de entrada das estatísticas (2 - novo, 1 - antigo)
• call_id – ID único da chamada, este ID é mencionado no nome do arquivo de gravação da chamada (único para cada gravação nos dados estatísticos);
• sip – número SIP;
• callstart – hora de início da chamada;;
• clid – CallerID;
• destination – destino da chamada;
• disposition – estado da chamada:
  • 'answered' – atendida,
  • 'busy' – ocupada,
  • 'cancel' - cancelada,
  • 'no answer' - sem resposta,
  • 'call failed' - falha na chamada,
  • 'no money' - sem saldo, limite excedido,
  • 'unallocated number' - número não existe,
  • 'no limit' - limite excedido,
  • 'no day limit' - limite diário excedido,
  • 'line limit' - limite de linhas excedido,
  • 'no money, no limit' - sem saldo, sem limite;
• seconds – duração da chamada em segundos;
• is_recorded – (true, false) indicando se a chamada foi gravada ou não;;
• pbx_call_id – ID permanente da chamada externa para a central virtual (não altera com scripts, menus de voz, transferências, etc., mostrado nas estatísticas e notificações);

dados estatísticos do widget de chamada de retorno

                                    {
    "status":"success",
    "start":"2016-09-01 00:00:00",
    "end":"2016-09-30 23:59:59",
    "stats":[
        {
            "id":"57d16d6a1e46c53d1f8ce323",
            "widget_id":"1",
            "sip":"00001",
            "ip":"127.0.0.1",
            "actions":[
                {
                    "kind":"come",
                    "date":"2016-09-08 16:53:45",
                    "referrer_url":"http://test.domain.com/page1/",
                    "url":"http://home.domain.com/page2/"
                },
                {
                    "kind":"show",
                    "date":"2016-09-08 16:53:46",
                    "rate":15
                },
                {
                    "kind":"call_request",
                    "date":"2016-09-08 16:54:07",
                    "number":"442037691880",
                    "request_call_date":"2016-09-09 10:00:00",
                    "redial":"n"
                },
                {
                    "kind":"close",
                    "date":"2016-09-08 16:54:35"
                }
            ]
        },
        ...
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2016-09-01 00:00:00</start>
    <end>2016-09-30 23:59:59</end>
    <stats>
        <value>
            <id>57d16d6a1e46c53d1f8ce323</id>
            <widget_id>1</widget_id>
            <sip>00001</sip>
            <ip>127.0.0.1</ip>
            <actions>
                <value>
                    <kind>come</kind>
                    <date>2016-09-08 16:53:45</date>
                    <referrer_url>http://test.domain.com/page1/</referrer_url>
                    <url>http://home.domain.com/page2/</url>
                </value>
                <value>
                    <kind>show</kind>
                    <date>2016-09-08 16:53:46</date>
                    <rate>15</rate>
                </value>
                <value>
                    <kind>call_request</kind>
                    <date>2016-09-08 16:54:07</date>
                    <number>442037691880</number>
                    <request_call_date>2016-09-09 10:00:00</request_call_date>
                    <redial>n</redial>
                </value>
                <value>
                    <kind>close</kind>
                    <date>2016-09-08 16:54:35</date>
                </value>
            </actions>
        </value>
            ...
    </stats>
</answer>

Parâmetros

• start - data de início da visualização das estatísticas (formato - YYYY-MM-DD HH:MM:SS);
• end - data final de exibição das estatísticas (formato - YYYY-MM-DD HH:MM:SS);
• widget_id - (opcional) - o ID do widget; na ausência de um parâmetro, as estatísticas são recolhidas para todos os widgets;

Prazo máximo para receber estatísticas mês. Se o limite for ultrapassado no pedido, o prazo é automaticamente reduzido para 30 dias. Se a data de início da amostra não for especificada, é selecionado o início do mês atual. Se a data de fim da amostra não for especificada, a amostra é limitada à data e hora atuais.

de onde

• start – data de início da visualização das estatísticas;
• end – data final da visualização das estatísticas;
• id – id da secção;
• widget_id – id da sessão;
• sip – número SIP;
• ip – Endereço IP do visitante;
• kind – tipo de evento:
  • 'come' – o visitante chegou à página com o widget;
  • 'show' – é apresentado o formulário do widget,
  • 'call' – solicitação de callback,
  • 'call_request' –pedido de callback diferido,
  • 'rate' – o visitante avaliou a chamada,
  • 'fail' – o visitante indicou que não houve retorno de chamada,
  • 'close' – o visitante fechou o ícone do widget;
• date – data e hora do evento;
• referrer_url – endereço da página a partir da qual o visitante chegou à página através do widget (apenas para o evento “come”);
• url – endereço da página do widget (apenas para o evento “come”);
• rate – para o evento “show” - número de pontos, para o evento “rate” - classificação da conversa;
• request_call_date – data e hora indicadas pelo visitante, conforme conveniente para a chamada de retorno (apenas para o evento) 'call_request');
• redial – (true, false)devolvido ou não em resposta a um pedido de retorno de chamada diferido (apenas para um evento) 'call_request');
• number – número introduzido pelo visitante (para o evento “call”, “call_request”, “rate”, “fail”).

Obtenção de estatísticas completas das chamadas recebidas

                                    {
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":442037691880,
            "to":442037691881,
            "billseconds":0,
            "disposition":"busy",
            "description":"United Kingdom, London"
        },
        …
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 13:58:22</end>
    <stats>
        <value>
            <id>155112249</id>
            <sip>00001</sip>
            <callstart>2015-06-02 12:20:25</callstart>
            <from>442037691880</from>
            <to>442037691881</to>
            <billseconds>0</billseconds>
            <disposition>busy</disposition>
            <description>United Kingdom, London</description>
        </value>
        …
    </stats>
</answer>

Parâmetros

• start - data de início da seleção de estatísticas (formato - YYYY-MM-DD HH:MM:SS);
• end - data de término da seleção de estatísticas (formato - YYYY-MM-DD HH:MM:SS);
• sip (opcional) - filtro por um SIP específico;
• skip (opcional - não se aplica ao definir o parâmetro cost_only) - número de linhas a serem ignoradas na seleção; a seleção começa a partir da linha skip + 1 (usado para paginação junto com o parâmetro limit, padrão é 0);
• limit (opcional - não se aplica ao definir o parâmetro cost_only) - limite no número de linhas de saída (usado para paginação junto com o parâmetro skip, e o valor máximo é 1000, o valor predefinido é 1000).

Período máximo para obtenção de estatísticas é de - um mês. Se o limite for excedido na solicitação, o período será automaticamente reduzido para 30 dias. Se a data de início não for especificada, será selecionada a partir do início do mês atual. Se a data de término não for especificada, a seleção será limitada até a data e hora atuais.

Número máximo de linhas de saída por solicitação é - 1000. Para paginação, utilize os parâmetros skip e limit.

Onde:

• start – data de início da seleção de estatísticas;
• end – data de término da seleção de estatísticas;
• id – ID da chamada;
• sip – SIP;
• callstart –horário de início da chamada;
• from – número do qual a chamada foi feita;
• to – número para onde a chamada foi feita;
• billseconds – duração da chamada em segundos;
• disposition – estado da chamada:
  • 'answered' – atendida,
  • 'busy' – ocupado,
  • 'cancel' - cancelada,
  • 'no answer' - sem resposta,
  • 'failed' - falha na chamada,
  • 'no money' - sem saldo, limite excedido,
  • 'unallocated number' - número não existente,
  • 'no limit' - limite excedido,
  • 'no day limit' - limite diário excedido,
  • 'line limit' - limite de linhas excedido,
  • 'no money, no limit' - sem saldo, sem limite;
• description – descrição do destino da chamada.

modificação dos parâmetros de reencaminhamento na extensão da central telefónica virtual

                                    {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer"
}

                                    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <current_status>on</current_status>
    <pbx_id>1234</pbx_id>
    <pbx_name>100</pbx_name>
    <type>phone</type>
    <destination>79123456789</destination>
    <condition>noanswer</condition>
    </answer>

Parâmetros

Para ativar e configurar o reencaminhamento:

• pbx_number – extensão da central telefónica virtual, por exemplo, 100;
• status – on;
• type – tipo de reencaminhamento correio de voz ou telefone;
• destination – telefone ou correio eletrónico, consoante o parâmetro anterior;
• condition – a condição de reencaminhamento, valores possíveis: sempre ou sem resposta;
• voicemail_greeting – notificação sobre reenvio, valores possíveis: não, standard, próprio. Indica-se apenas para type = voicemail;
• greeting_file – ficheiro com notificação no formato mp3 ou wav até 5 MB. Indica-se apenas para type = voicemail e voicemail_greeting = próprio;

Para ativação do reencaminhamento:

• pbx_number – extensão da central telefónica virtual, por exemplo, 100;
• status – off;

obtenção de parâmetros de encaminhamento na extensão da central telefónica virtual

                                    {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
}

Parâmetros

• pbx_number – extensão da central telefónica virtual, por exemplo, 100;

pedido de um ficheiro de registo de chamadas

Parâmetros

• call_id – identificação única da chamada, esta identificação é indicada no nome do ficheiro com a gravação da chamada (única para cada gravação nos dados estatísticos);
• pbx_call_id – ID permanente da chamada externa para a central telefónica virtual (não se altera ao mudar de cenário, menu de voz, transferência, etc., reflete-se nos dados estatísticos e nas notificações).;
• lifetime – (opcional) duração da ligação em segundos (mínimo - 180, máximo - 5184000, predefinição - 1800).

Atenção: é suficiente especificar um dos dois parâmetros de identificação (pbx_call_id ou call_id), quando se especifica o pbx_call_id da ligação numa consulta, pode haver várias.

Exemplo de resposta quando se especifica somente a call_id, existe apenas uma ligação:

(Resposta 1)

                                    Resposta 1:
{
    "status":"success",
    "link": "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
    "lifetime_till": "2016-01-01 23:56:22"
}

                                    Resposta 1:
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <link>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</link>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Exemplo de resposta quando apenas é especificado pbx_call_id, podem estar presentes múltiplas referências:

(Resposta 2)

                                    Resposta 2:
{
    "status":"success",
    "links":[
        "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
        "https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
    ],
    "lifetime_till": "2016-01-01 23:56:22"
}

                                    Resposta 2:
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <links>
        <value>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3<</value>
        <value>https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3</value>
    </links>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Parâmetros

• link – ligação para o arquivo da conversa;
• lifetime_till – até que dia a ligação continuará a funcionar.

carregar melodia

Parâmetros:

• file - o arquivo

agir/desactar melodia da central telefónica

Parâmetros:

• state - estado (on - act, off - desact);
• melody - tipo de melodia (none - predefinição, sem melodia, mymelody - a melodia carregada pelo utilizador anteriormente).

apagar melodia

obter ajustes da central telefónica call info

                                    {
    "status": "success",
    "url": "",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Parámetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados pelo parceiro.

alterar o url para pbx call info

                                    {
    "status": "success",
    "url": ""
}

Parâmetros:

• url - link;
• user_id - parâmetro opcional, disponível para uso de parceiros ou usuários criados por este.

modificar a reação ao evento NOTIFY_* para pbx call info

                                    {
    "status": "success",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Parâmetros:

• user_id -parâmetro opcional, disponível para uso de parceiros ou usuários criados por este;
• notify_start - "true" ou "false" parâmetro opcional;
• notify_internal - "true" ou "false" parâmetro opcional
• notify_end - "true" ou "false" parâmetro opcional;
• notify_out_start - "true" ou "false" parâmetro opcional;
• notify_out_end - "true" ou "false" parâmetro opcional;
• notify_answer - "true" ou "false" parâmetro opcional.

eliminar url para da central telefónica call info

                                    {
    "status": "success",
    "url": ""
}

Parámetros:

• user_id - parâmetro opcional, disponível para ser utilizado por parceiros ou utilizadores criados pelo parceiro.

criar uma central telefónica virtual

                                    {
    "status": "success",
    "stop_datetime": "2021-12-31 23:59:59"
}

Parâmetros:

• sip_id - SIP para associar à central telefônica; se não for atribuído, será selecionado um SIP livre (parâmetro opcional);;
• password - palavra-passe para a primeira extensão da central telefónica '100';
• user_id - parâmetro opcional, disponível para uso por parceiros ou utilizadores criados por este.

obter definições de webhooks da central telefónica

                                    {
    "status": "success",
    "url": "",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Parámetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados pelo parceiro.

alterar para pbx webhooks

                                    {
    "status": "success",
    "url": ""
}

Parámetros:

• user_id - parâmetro opcional, disponível para uso por parceiros ou usuários criados por estes;
• url - link.

modificar a reação ao evento para outras notificações (atualização de contactos, seguimento de chamadas, SMS e análise do discurso)

                                    {
    "status": "success",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Parâmetros:

• user_id - parâmetro opcional, disponível para uso por parceiros ou usuários criados por estes;
• number_lookup - "true" ou "false" parâmetro opcional;
• call_tracking - "true" ou "false" parâmetro opcional;
• sms - "true" ou "false" parâmetro opcional;
• speech_recognition - "true" ou "false" parâmetro opcional.

remover o url para outras notificações (atualização de contactos, rastreio de chamadas, SMS e análise de discurso)

                                    {
    "status": "success",
    "url": ""
}

Parámetros:

• user_id - parâmetro opcional, disponível para ser utilizado por parceiros ou utilizadores criados por ele.

visualização das extensões da central telefónica virtual

                                    {
    "status":"success",
    "pbx_id":1234,
    "numbers": [
        100,
        101,
        ...
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <numbers>
        <value>100</value>
        <value>101</value>
        ...
    </numbers>
</answer>

onde

• pbx_id – ID da central telefónica do pareceiro;
• numbers –lista de extensões.

estado em linha das extensões da central telefónica virtual

                                    {
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <number>100</number>
    <is_online>false</is_online>
</answer>

onde

• pbx_id – central telefónica-id;
• number – extensão da central telefónica virtual;
• is_online – estado online (true|false).

informações sobre a extensão da central telefónica

                                    {
    "status": "success",
    "pbx_id": 12345,
    "number": 100,
    "name": "Extension 100",
    "caller_id": "+44000000000",
    "caller_id_app_change": "true",
    "caller_id_by_direction": "false",
    "lines": "3",
    "ip_restriction": "1.1.1.1",
    "record_store": "For automatic speech recognition",
    "record_email": "email@server.com",
    "supervisor_status": 1
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>12345</pbx_id>
    <number>100</number>
    <name>Extension 100</name>
    <caller_id>+44000000000</caller_id>
    <caller_id_app_change>true</caller_id_app_change>
    <caller_id_by_direction>false</caller_id_by_direction>
    <lines>3</lines>
    <ip_restriction>1.1.1.1</ip_restriction>
    <record_store>For automatic speech recognition</record_store>
    <record_email>email@server.com</record_email>
   <supervisor_status>1</supervisor_status>
</answer>

onde:

• pbx_id – id da central telefónica;
• number – extensão da central telefónica;
• name – nome a mostrar;
• caller_id – CallerID;
• caller_id_app_change – alteração do CallerID a partir da aplicação (true|false);
• caller_id_by_direction – CallerID por destino (true|false);
• lines – número de líneas;
• ip_restriction – restrição de acesso ip (false si no estabelecido);
• record_store – gravação de chamadas na nuvem (Without recognition|For manual recognition|For automatic speech recognition|false);
• record_email – e-mail para enviar gravações de chamadas (falso se estiver desativado).

ativação da gravação de chamadas na extensão da central telefónica virtual

                                    {
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com",
    "speech_recognition":"all"
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <internal_number>100</internal_number>
    <recording>on</recording>
    <email>on</email>
    <speech_recognition>all</speech_recognition>
</answer>

Parâmetros

• id – extensão da central telefónica virtual;
• estado – estado: "on" - ativar, "off" - desativar, "on_email" - conectar apenas a gravação ao email, "off_email" - desativar apenas a gravação ao email, "on_store" - ativar apenas a gravação ao repositório, "off_store" - desativar apenas a gravação ao repositório;
• email – (opcional) mudança do endereço de email para o qual são enviadas as gravações das chamadas. Podes indicar até 3 endereços de email separados por vírgulas. speech_recognition – (opcional) a modificação das configurações de reconhecimento de voz: "all" - reconhecer tudo, "optional" - reconhecimento seletivo a partir da estatística, "off" - desativar.

criar extensão da central telefónica

                                    {
    "status": "success",
    "numbers": [
        {
            "number": 200,
            "password": "PASSWORD"
        },
        {
            "number": 201,
            "password": "PASSWORD"
        }
    ]
}

Parámetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados pelo parceiro;
• start_number - iniciar o número 100 ...999 ou “any” iniciar a partir de qualquer número disponível entre 100-999;
• quantity - quantidade de extensões criadas;
• return_password - parâmetro opcional, se “true” na resposta mostrará as palavras-passe das extensões já criadas.

solicitação de palavra-passe para a extensão da central telefónica, palavra-passe exibida disponível durante um determinado período de tempo

Parâmetros:

• user_id - parâmetro opcional, disponível apenas para utilização por revendedores e apenas para os utilizadores por eles criados.

Exemplo de resposta:

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200,
    "password": "PASSWORD"
}

onde

• password - pode ter o valor de hidden se a palavra-passe não estiver disponível para visualização

alterar a palavra-passe da extensão

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200
}

Parâmetros:

• value - nova palavra-passe;
• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por estes

alteração da extensão da central telefónica virtual

Parámetros

• supervisor_status - estado do supervisor, 0 - desativado, 1 - ativado;
• user_id - parâmetro opcional, disponível para utilização pelos concessionários e utilizadores que tenham sido criados por estes.

lista dos ficheiros armazenados no quadro de distribuição

carregar ficheiro

Parâmetros:

• name - nome do ficheiro;
• file - o ficheiro.

eliminar ficheiro por ID

Parâmetros:

• id - identificador do ficheiro

lista de IVR

                                    {
    "status": "success",
    "pbx_id": 114,
    "ivrs": [
        {
            "menu_id": "0",
            "title": "",
            "type": "file",
            "status": "on",
            "waitexten": 5,
            "auto_responder": {
                "status": "on",
                "waitexten": 1,
                "working_days": [
                    {
                        "day": "mon",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    {
                        "day": "tue",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    ...
                    {
                        "day": "sun",
                        "is_active": false
                    }
                ]
            },
            "dinner_status": "on",
            "dinner_time": {
                "begin": {
                    "hour": 12,
                    "minute": 0
                },
                "end": {
                    "hour": 13,
                    "minute": 0
                }
            }
        },
        {
            "menu_id": "1",
            "title": "Menu 1",
            "type": "readtext",
            "status": "off",
            "waitexten": 5,
            "auto_responder": {
                "status": "off",
                "waitexten": 1
            }
        },
        ...
    ]
}

Parámetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados pelo parceiro.

criar IVR

                                    {
    "status": "success",
    "menu_id": 2
}

Parâmetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados pelo parceiro;
• buy - 'true' - criar um menu de pagamento.

eliminar IVR

                                    {
    "status": "success"
}

Parâmetros:

• user_id - parâmetro opcional, disponível para ser utilizado por parceiros ou utilizadores criados pelo parceiro.;
• menu_id - deve ser > 0.

lista de cenários de IVR

                                    {
    "status": "success",
    "scenarios": [
        {
            "id": "132",
            "title": "-1",
            "push_button": -1,
            "first_sips": [
                "102"
            ],
            "second_sips": [],
            "second_sips_delay": 10,
            "third_sips": [],
            "third_sips_delay": 20
        },
        ...
    ]
}

Parámetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados pelo parceiro.
• menu_id - ID menu/IVR.

criar cenário IVR

                                    {
    "status": "success",
    "menu_id": 0,
    "scenario_id": 2
}

Parâmetros:

• push_button - aplicar o cenário ao pressionar o botão: se o chamador não pressionar nenhum botão, o cenário é executado sem pressionar nada, 0-9 - botões, 10 - atendedor automático, 11-30 - cenários adicionais;
• title - nome;
• extension - extensão ou extensões separadas por espaços ou "fax";
• menu_id - ID do menu/IVR;
• user_id - parâmetro opcional, disponível para uso por parceiros ou usuários criados por estes.
• trigger_to_did_ext_lines - parâmetro opcional. Indica para quais números se aplica o cenário em chamadas. Pode conter o número ou a lista de números separados por espaços;
• trigger_from_clid_numbers - parâmetro opcional. Indica de quais números se aplica o cenário em chamadas. Pode conter o número ou a lista de números separados por espaços.

modificação do cenário do IVR

Corpo PUT de solicitação:

(Resposta 1)

                                    Resposta 1:
[
  "id": "630cb6b3dc666e947503a77a",
  "title": "Scenario 1",
  "queue_strategy": "off",
  "queue_announce_position": 0,
  "numbers": [
    [
      "number": 100,
      "delay": 0,
      "duration": 20
    ],
    [
      "number": 101,
      "delay": 20,
      "duration": 20
    ],
    [
      "number": 102,
      "delay": 40,
      "duration": 20
    ],
  ]
]

Descrição:

• id - ID do cenário;
• title - nome;
• queue_strategy - estratégia de distribuição de chamadas entre extensões por turnos (off, random, roundrobin, leastrecent, rrmemory, fewestcalls)
• queue_announce_position - comunicar o número na fila
• numbers - conjunto de extensões
  • parâmetros de espera e duração da chamada na extensão:
  • number - extensão ou "fax";
  • delay - atraso da chamada em segundos
  • duration - duração da chamada em segundos

Descrição das estratégias de distribuição de chamadas na fila entre extensões:

• off - fila desativada
• random - distribuir aleatoriamente
• roundrobin - distribuir uniformemente, priorizar quem não falou por mais tempo, considerar todas as chamadas
• leastrecent - distribuir uniformemente, priorizar quem não falou por mais tempo, considerar apenas as chamadas atendidas
• rrmemory - distribuir uniformemente, priorizar quem menos falou, considerar todas as chamadas
• fewestcalls - distribuir uniformemente, priorizar quem menos falou, considerar apenas as chamadas atendidas Parâmetros de atraso e duração da chamada das extensões são usados apenas com a fila de chamadas ativada (queue_strategy : "off").

Resposta: (Resposta 2)

                                    Resposta 2:

{"status": "success"}

Erro: (Resposta 3)

                                    Resposta 3:

{"status": "error","message": "Wrong parameters!"}

remover o cenário IVR

                                    {
    "status": "success"
}

Parâmetros:

• scenario_id - ID do cenário;
• user_id - parâmetro opcional, disponível para uso de parceiros ou utilizadores criados por estes.

obter o resultado do reconhecimento

                                    {        
    "status":"success",
    "lang":"en-EN",
    "recognitionStatus":"in progress",
    "otherLangs":["es-ES"],
    "words": [
        {
            "result": [
                {
                    "s": 0.02,
                    "e": 0.22,
                    "w": "word",
                },
                {
                    "s": 0.31,
                    "e": 0.56,
                    "w": "one",
                }
            ],
            "channel": 1
        }
    ],
    "phrases":[
        {
            "result": "word one",
            "channel": 1
        }
    ]
}

Parámetros:

• call_id – id único da chamada, este ID é indicado no nome do ficheiro com a gravação da chamada (único para cada gravação nas estatísticas);
• lang - idioma de reconhecimento (opcional);
• return - resultado a ser devolvido. Opções: words - palavras, phrases - frases (opcional. a predefinição é phrases).;
• alternatives - se deve devolver opções alternativas. Opções: 0 - não, 1 - sim (não é necessário. predefinição 0).

onde

• lang – língua;
• recognitionStatus: estado de reconhecimento. Opções:
  • in progress - em processo de reconhecimento,
  • error - ocorreu um erro no reconhecimento,
  • recognized - reconhecido
  • ready for recognize - gravação pronta para reconhecimento,
  • not available for recognize - registo não disponível para reconhecimento.
• result:
  • words - conjunto:
    • result - lista de palavras (conjunto):
      • s - hora de início do discurso
      • e - hora do fim do discurso
      • w - palavra
    • channel - número de canal
  • phrases - conjunto:
    • result - frase
    • channel - número de canal

O lançamento do reconhecimento de chamadas nas estatísticas da central telefônica requer que o reconhecimento seletivo seja ativado previamente nas configurações do número interno

                                    {
    "status":"success"
}

Parâmetros

• call_id – id único da chamada, este id é especificado no nome do ficheiro com o registo da chamada (único para cada registo nas estatísticas);
• lang - Idioma de reconhecimento (opcional).

informações sobre os números das linhas directas para os utilizadores

                                    {
    "status":"success",
    "info": [
        {
            "number":"442030000000",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "number_name":null,
            "sip":00001,
            "sip_name":null,
            "start_date":"2015-01-01 18:14:44",
            "stop_date":"2016-02-11 18:14:40",
            "monthly_fee":2,
            "currency":USD,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false",
            "type":"common"
        },
    ...
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <number>442037691880</number>
            <status>on</status>
            <country>Великобритания</country>
            <description>Лондон</description>
            <number_name>null</number_name>
            <sip>00001</sip>
            <sip_name>Example</sip_name>
            <start_date>2015-01-01 18:14:44</start_date>
            <stop_date>2016-02-11 18:14:40</stop_date>
            <monthly_fee>2</monthly_fee>
            <currency>USD</currency>
            <channels>2</channels>
            <autorenew>true</autorenew>
            <is_on_test>false</is_on_test>
            <type>common</type>
        </value>
    ...
    </info>
</answer>

Parâmetros

Dependendo do tipo de número, o conjunto de campos pode diferir! Descrição dos campos:

• number – número comprado do utilizador;
• status – estado do número;
  • on - número ativado;
  • parking - número desativado (falta de pagamento) mas permanece na conta por 7 dias e pode ser restabelecido após o carregamento;
  • checking - número conectado, pago, todos os documentos foram carregados, à espera de ativação;
  • checking_upload - número conectado, pago, à espera do carregamento de documentos;
  • reserved_on - número reservado até ao momento do pagamento;
  • reserved_checking -número reservado até ao momento do pagamento, todos os documentos foram carregados;
  • reserved_checking_upload - número reservado até ao momento do pagamento, à espera do carregamento de documentos;
• country – país (para common e revenue);
• description – descrição: cidade ou tipo (para common e revenue);
• number_name – "nome" do número virtual (criado pelo utilizador);
• sip – SIP vinculado ao número;
• sip_name – "nome" SIP, vinculado ao número;
• start_date – data de compra do número pelo utilizador;
• stop_date – data de término do prazo de pagamento do número pelo utilizador
• monthly_fee – custo do número (para common);
• currency – moeda do custo do número (para common);
• channels – número de linhas no número (para common);
• minutes – duração geral das chamadas recebidas no mês atual (para revenue);
• autorenew – se está ativada a extensão do prazo de vigência do número (para common, revenue, rufree);
• is_on_test –se o número está em fase de testes;
• type – tipo de número: common (número virtual), rufree (número moscovita gratuito), order (reservado mas não conectado)

informações sobre o número ligado

                                    {
    "status": "success",
    "info": {
    "number": "35924913550",
        "status": "on",
        "country": "Bulgaria",
        "description": "Sofia",
        "number_name": "TT",
        "sip": "00004",
        "sip_name": "SIP",
        "start_date": "2016-06-08 14:32:17",
        "stop_date": "2016-06-29 10:52:18",
        "monthly_fee": 2,
        "currency": "USD",
        "channels": "2",
        "autorenew": "true",
        "receive_sms": null,
        "is_on_test": "false"
    }
}

Parámetros

• type - pode conter um dos 3 valores:
  • 'revenue' - Número de telefone em formato internacional;
  • 'common' - Número geral, todos os outros números;
• number - número;

estado de auto-renovação

                                    {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "on"
}

Parâmetros

• number - número.

receção de informações sobre documento ou erro de verificação de endereço

                                    {
   "status":"success",
   "info":{
      "wrong_document":{
         "document_type":"contract",
         "message":"The passport has expired. It is considered invalid."
      },
      "wrong_address":{
         "message":"Invalid address"
      }
   }
}

Parámetros

• group_id - id do grupo de documentos.

alterar o estado de auto-renovação

                                    {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "off"
}

Parâmetros

• type - pode conter um dos 2 valores:
  • 'revenue' - Número de telefone em formato internacional;
  • 'common' - Número geral, todos os outros números;
• number - número;
• value - novo estado de auto-renovação, on ou off.

listado de países en los que se puede conectar el número

                                    {
    "status": "success",
    "info": [
        {
            "countryCode": "61",
            "countryCodeIso": "AU",
            "name": "Australia"
        },
        ...
    ]
}

Parámetros

• language - opcional; se não for definido, regressará na língua da área pessoal.

lista de destinos no país aos quais o número pode ser ligado

                                    {
    "status": "success",
    "info": [
        {
            "id": "3753",
            "countryCode": "49",
            "areaCode": "800",
            "name": "800 number (Toll-free)",
            "connect_fee": 0,
            "monthly_fee": 15,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Certificate of registration copy or passport or ID copy (both sides)",
                    "Proof of address (a copy of utility bill no older than of 6 months) - 
                    your current address (city, street, number and postal code). 
                    The address must be located in the country of ordered phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "true",
            "feature": "Available from all networks"
            "connect_time": "0"
        },
        {
            "id": "3766",
            "countryCode": "49",
            "areaCode": "821",
            "name": "Augsburg",
            "connect_fee": 3,
            "monthly_fee": 3,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Passport or ID copy (both sides)"
                ],
                "specify": [
                    "You current address (city, street, number and postal code). 
                    The address must be located in the region of the city 
                    where you ordered the phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "false",
            "feature": null,
            "connect_time": "0"
        },
        ...
    ]
}

Parámetros

• language - opcional; se não for definido, regressará na língua da área pessoal.
• country - código iso do país (ISO 3166-1 alpha-2).

Configuração do nome do número (caracteres latinos e até 30 dígitos)

                                    {
    "status": "success",
    "number": "+44000000000",
    "caller_name": "test"
}

Parâmetros

• type - pode conter um dos 2 valores:
  • 'revenue' - Número de telefone em formato internacional;
  • 'common' - Número geral, todos os outros números;
• number - número;
• caller_name - para eliminar, basta deixar o campo vazio.

ligação do número ao sip ou ativação do modo de teste

                                    {
    "status": "success",
    "number": "+44000000000",
    "sip_id": "00001"
}

Parâmetros

• type - pode conter um dos 3 valores:
  • 'revenue' - Número de telefone em formato internacional;
  • 'common' - Número geral, todos os outros números;
• number - número;
• sip_id - endereço do servidor SIP ou externo (SIP URI);
• test_mode - opcional, (on|off) - para ativar o modo de teste.

números disponíveis para conexão

                                    {
    'status': 'success',
    'numbers': [
        {
            'id': 1712p0D1643D0t42r198658,
            'direction_id': 13755,
            'number': '+44000000001'
        },
        {
            'id': 184bdf85006c3f1676be200,
            'direction_id': 13755,
            'number': '+44000000000'
        },
        ...
    ]
}

Parámetros:

• DIRECTION_ID - ID do destino;
• mask - parámetro opcional, para a pesquisa de correspondência por número.

pedido/compra do número

                                    {
    'status': 'success',
    'number': '+44000000000',
    'is_reserved': 'false',
    'is_activated': 'true'
}

Parâmetros:

• number_id - ID do número solicitado, obtido pelo método GET /v1/direct_numbers/available/<DIRECTION_ID>/ por exemplo: 1712p0D1643D0t42r198658 (se a seleção do número estiver ausente, o parâmetro não é utilizado));
• direction_id - ID destino/cidade;
• documents_group_id - ID do grupo de documentos do utilizador;
• purpose - descrição do objetivo da utilização do número (apenas se necessário);
• receive_sms - 1 -ativação da recepção de SMS (somente se o número suporta a receção de SMS);
• period - 'month' - um mês, '3month' - três meses (parâmetro opcional, a receção de SMS é ativado nos números conectados por um período mínimo de 3 meses);
• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por ele.

prolongamento do número por um determinado período de meses

                                    {
    'status': 'success',
    'number': '+44000000000',
    'stop_date': '2021-05-01 12:00:00',
    'total_paid': {
        'amount': 2,
        'currency': 'USD'
    }
}

Parámetros:

• number - número a prolongar;
• months - quantidade de meses;
• user_id - parámetro opcional, disponível para utilização por parceiros ou utilizadores criados por ele.

ativação da receção de SMS (apenas se o número suportar a receção de SMS)

                                    {
    "status": "success", 
    "number": "", 
    "receive_sms": "on"
}

Parâmetros:

• number - número
• value - valor (puede ser "on" u "off")
• documents_group_id - parâmetro opcional, ID do grupo de documentos da conta
• user_id - parâmetro opcional, disponível para utilização pelos dealers e utilizadores que tenham sido criados por estes

lista de ficheiros/documentos no grupo de documentos

                                    {
    "status": "success",
    "documents": [
        {
            "type": "passport",
            "is_verified": "true",
            "source": "upload",
            "name": "file1.jpg"
        },
        {
            "type": "receipt",
            "is_verified": "false",
            "source": "upload",
            "name": "file2.jpg"
        }
    ]
}

Parâmetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por ele;
• group_id - parâmetro opcional, ID do grupo de documentos, (0 ou se não for determinado - grupo de documentos principais).

lista de grupos de documentos

                                    {
    "status": "success",
    "groups": [
        {
            "id": 0,
            "email": "email@server.com",
            "salutation": 'MR',
            "nationality": null,
            "first_name": "John",
            "middle_name": "Richard",
            "last_name": "Smith",
            "organization": "Company",
            "organization_description": null,
            "organization_reg_number": null,
            "country": "DE",
            "region": "",
            "city": "Berlin",
            "address": "Brudden Strasse 8, 76611",
            "zip_code": '76611',
            "street": 'Brudden Strasse',
            "street_code": null,
            "municipality_code": null,
            "building_number": "8",
            "building_letter": null,
            "phone": "4900000000",
            "type_of_id": "",
            "id_number": "123000099",
            "issuing_authority": null,
            "issuing_date": null,
            "is_readonly": true
        }
    ]
}

Parâmetros:

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por este.

dados de um determinado grupo

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Parámetros:

• ID - ID de grupo, 0 - grupo de documentos principal;
• user_id - parâmetro opcional, disponível para ser utilizado por parceiros ou utilizadores criados por ele.

verificação - se o grupo de documentos serve uma determinada cidade/destino

                                    {
    "status": "success",
    "is_information_match": "true",
    "is_documents_uploaded": "true",
    "is_documents_verified": "true",
    "is_address_match": "true"
}

Parâmetros:

• ID - ID de grupo, 0 - grupo de documentos principais;
• user_id - parâmetro opcional, disponível para utilização por sócios ou utilizadores criados por ele;
• direction_id - ID de destino/cidade.

criar um novo grupo de documentos

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Parâmetros:

• user_id - parâmetro opcional, disponível para utilização por utilizadores parceiros ou criados por parceiros.
• email - email;
• salutation - saudações 'MR', 'MS', 'COMPANY';
• nationality - nacionalidade, código iso2 do país;
• first_name - nome;
• middle_name - parâmetro opcional, segundo apelido;
• last_name - primeiro apelido;
• date_of_birth - parâmetro opcional, data de nascimento;
• organization - parâmetro opcional, nome da empresa/organização;
• organization_description - parâmetro facultativo, descrição da atividade da empresa;
• organization_reg_number - parâmetro facultativo, número de registo da empresa;
• country - país, código de país iso2;
• region - parâmetro opcional, província/região;
• city - cidade;
• address - endereço completo;
• zip_code - código postal;
• street - rua;
• street_code - parâmetro facultativo, código da rua, apenas para a Dinamarca;
• municipality_code - parâmetro facultativo, código do município, apenas para a Dinamarca;
• building_number - número;
• building_letter - parâmetro facultativo, letra;
• phone - número de telefone de contacto;
• type_of_id - parâmetro opcional, tipo de documento: "PASSPORT", "DNI", "NIE", "RESIDENCE_PERMIT", "NATIONAL_ID_CARD", "BUSINESS_REGISTRATION";
• id_number - parâmetro opcional, número de documento;
• issuing_authority - parâmetro opcional, autoridade emissora;
• issuing_date - parâmetro opcional, data de emissão;
• direction_id - parâmetro opcional, ID do destino/cidade para verificar a conformidade.

atualização dos dados do grupo de documentos

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Parámetros:

• user_id - parâmetro opcional, disponível para utilização por utilizadores parceiros ou criados por parceiros.
• email - email;
• salutation - saudações 'MR', 'MS', 'COMPANY';
• nationality - nacionalidade, código iso2 do país;
• first_name - nome;
• middle_name - parámetro opcional, segundo apelido;
• last_name - primeiro apelido;
• date_of_birth - parámetro opcional, data de nascimento;
• organization - parâmetro opcional, nome da empresa/organização;
• organization_description - parâmetro opcional, descrição da atividade da empresa;
• organization_reg_number - parâmetro opcional, número de registo da empresa;
• country - país, código iso2 do país;
• region - parámetro opcional, província/região;
• city - cidade;
• address - endereço completo;
• zip_code - código postal;
• street - rua;
• street_code - parâmetro opcional, código da rua, apenas para a Dinamarca;
• municipality_code - parâmetro opcional, código do município, apenas para a Dinamarca;
• building_number - número;
• building_letter - parámetro opcional, letra;
• phone - número de telefone de contacto;
• type_of_id - parâmetro opcional, tipo de documento: "PASSPORT", "DNI", "NIE", "RESIDENCE_PERMIT", "NATIONAL_ID_CARD", "BUSINESS_REGISTRATION";
• id_number - parâmetro opcional, número de documento;
• issuing_authority - parâmetro opcional, autoridade emissora;
• issuing_date - parâmetro opcional, data de emissão;
• direction_id - parâmetro opcional, ID do destino/cidade para verificar a conformidade.

carregar ficheiro para grupo de documentos

Parâmetros:

• user_id - parâmetro opcional, disponível para utilização por sócios ou utilizadores criados por ele; ;
• group_id - ID de grupo, 0 - grupo de documentos principal;
• document_type - tipo de documento: 'certificate', 'contract', 'company_letter', 'inn_ua', passport', 'phone_bill', 'photo_with_doc', 'photo_with_passport', 'receipt', 'driver_id_us_ca', 'driver_id_other';
• file - uploaded file.

Exemplo da solicitação:

                                    $zd = new \Zadarma_API_Test\Api(KEY, SECRET);
$zd->request(
    'documents/upload',
    [
        'group_id' => 0,
        'document_type' => 'passport',
        'file' => new CURLFile('passport.jpg', 'image/jpeg', 'passport.jpg')
    ],
    'post'
);

Exemplo de resposta:

                                    {
    "status": "success",
    "message": "The File passport.jpg has been successfully uploaded to the website.",
    "doc_name": "passport.jpg"
}

informações sobre a conta de membro

                                    {
    "status": "success",
    "balance": 123,
    "credit": 0,
    "currency": "USD",
    "reseller_fee": 10,
    "user_fee": 10
}

Transferir o saldo da conta do sócio para o saldo de outra conta relacionada ou vice-versa

                                    {
    "status": "success",
    "user": {
        "balance": "62.0000",
        "currency": "EUR"
    },
    "reseller": {
        "balance": "94.825",
        "currency": "USD"
    }
}

Parâmetros

• amount - montante;
• currency - moeda;
• type - destino da transferência "to_reseller" e "to_user".

Lista dos números de telefone de contacto do utilizador

                                    {
    "status": "success",
    "list": [
        {
            "id": 0,
            "number": "49025000897",
            "is_proved": false
        }
    ]
}

Parâmetros

• user_id - id do utilizador;

Adicionar número de telefone de contacto do utilizador

                                    {
    "status": "success",
    "id": 98,
    "number": "359000000001",
    "is_proved": true
}

Parâmetros

• user_id - id do utilizador;
• number - número.

Editar o número de telefone do utilizador

                                    {
    "status": "success",
    "id": 99,
    "number": "359000000002",
    "is_proved": false
}

Parâmetros

• user_id - id do utilizador;
• id - ID do número, 0 - número de telefone principal do perfil;
• number - número.

Pedido de confirmação do número de telefone de contacto do utilizador

                                    {
    "number": "359000000002",
    "status": "success",
    "message": "You were sent an SMS message with a code. Code is valid for 1 hour."
}

Parâmetros

• user_id - id do utilizador;
• number - número.
• confirm_number_reuse - confirmação do número utilizado noutra conta (parâmetro opcional)

Pedido de confirmação do número de contacto do utilizador (será feita uma chamada e o cliente receberá o código de confirmação ao atender a chamada).

                                    {
    "number": "359000000002",
    "status": "success",
    "message": "You were sent an SMS message with a code. Code is valid for 1 hour."
}

Parâmetros:

• user_id - parâmetro obrigatório, id do utilizador;
• number - parâmetro obrigatório, número a confirmar (em formato internacional)
• caller_id - número apresentado numa chamada, só estão disponíveis os números conectados no sistema.;
• language - idioma reproduzido
• sip_id - parâmetro opcional, se não for selecionado será escolhido o SIP do primeiro revendedor,
• confirm_number_reuse - parâmetro opcional, confirmação do número utilizado noutra conta

Confirmação do número de contacto por código SMS

                                    {
    "status": "success",
    "message": "Your number confirmed!",
    "number": "35900000019"
}

Parâmetros

• user_id - id do utilizador;
• number - número.
• code - código de confirmação.

Registo do utilizador

                                    {
    "status": "success",
    "user_id": 12345,
    "message": "You registered a new user in the system."
},{
    "status": "success",
    "message": "You registered a new user in the system. A registration confirmation link was sent to the email address you provided. To activate the account the user needs to click on that link, after which they can log in on the website."
},{
    "status": "success",
    "message": "You registered a new user in the system. A registration confirmation code was sent to the email address you provided. To activate the account the user needs to send code to you, after which you can confirm registration using API."
}

Parâmetros

• email - endereço eletrónico do cliente;
• first_name -nome do cliente;
• last_name - parâmetro opcional;
• middle_name - parâmetro opcional;
• organization - parâmetro opcional;
• country - código ISO2 do país;
• city;
• address - parâmetro opcional;
• phone - parâmetro opcional;
• password - parâmetro opcional;
• tariff - ID do tarifário, (ID pode ser obtido pelo método GET /v1/info/lists/tariffs/) ;
• tariff_period - parâmetro opcional, período do tarifário month | year;
• language - parâmetro opcional, código de idioma, en;
• currency - parâmetro opcional, código de moeda, USD;
• promocode - parâmetro opcional, código promocional;
• gmt - parâmetro opcional, GMT;
• id_card - parâmetro opcional, número do documento de DNI, passaporte.

Confirmar o registo do utilizador

                                    {
    "status": "success",
    "user_id": 12345
}

Parâmetros

• code -código do email enviado por correio eletrónico ao utilizador;
• email - endereço de email.

Lista de utilizadores do sócio por página (50)

                                    {
    "status": "success",
    "total": 205,
    "total_pages": 5,
    "page": 1,
    "users": [
        {
            "id": "1234",
            "email": "test@domain.com",
            "first_name": "Test",
            "last_name": "Test",
            "organization": "",
            "phone": "+44000000001",
            "created": "2021-01-26 14:21:04",
            "last_login": "2021-01-30 09:46:31",
            "balance": "0.4000",
            "currency": "GBP",
            "sips_count": "1",
            "is_active": true,
            "allow_topup": true,
            "allow_api_requests": true
        },
        ...
    ]
}

Parâmetros

• page - número da página.

Procurar uma conta por critérios (um de ID, email, sip)

                                    {
    "status": "success",
    "user": {
        "id": "1234",
        "email": "test@domain.com",
        "first_name": "Test",
        "last_name": "Test",
        "organization": "",
        "phone": "+44000000001",
        "created": "2021-01-26 14:21:04",
        "last_login": "2021-01-30 09:46:31",
        "balance": "0.4000",
        "currency": "GBP",
        "sips_count": "1",
        "is_active": true,
        "allow_topup": true,
        "allow_api_requests": true
    }
}

Parâmetros

• id - opcional;
• sip - opcional;
• email - opcional.

Transferir o saldo do sócio para o saldo do utilizador da conta

                                    {
    "status": "success",
    "user_topup": {
        "amount": 10,
        "currency": "GBP"
    },
    "reseller_withdraw": {
        "amount": 10,
        "currency": "GBP"
    }
}

Parâmetros

• user_id - id do utilizador;
• amount- montante;
• currency - moeda.

Obter as chaves de acesso do utilizador atual para a API

                                    {
    "status": "success",
    "user_id": 1234,
    "last_request_datetime": "2021-02-18 10:45:01",
    "allow_reset": true,
    "key": "hidden",
    "secret": "hidden"
},{
    "status": "success",
    "user_id": 1234,
    "last_request_datetime": "2021-02-26 15:59:50",
    "allow_reset": false,
    "key": "abscd",
    "secret": "12345"
}

Parâmetros

• user_id id do utilizador.

Obter novas chaves de acesso de utilizador da API

                                    {
    "status": "success",
    "user_id": 1234,
    "key": "abscd",
    "secret": "12345"
}

Parâmetros

• user_id - id do utilizador.

envio de SMS

                                    {
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD",
    "sms_detalization":[
        {
            "senderid":"xxxxxxxxxxx",
            "number":"1234567890",
            "cost":0.06
        }
    ],
    "denied_numbers":[
        {
            "number":"1234567890",
            "message":"The reason for the SMS not being sent to the number"
        }
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <value>
        <messages>1</messages>
        <cost>0.24</cost>
        <currency>1</currency>
        <sms_detalization>
            <value>
                <callerid>xxxxxxxxx</callerid>
                <number>1234567890</number>
                <cost>0.06</cost>
            </value>
        </sms_detalization>
        <denied_numbers>
            <value>
                <number>1234567890</number>
                <message>The reason for the SMS not being sent to the number</message>
            </value>
        </denied_numbers>
    </value>
</answer>

Parâmetros

• number – número de telefone para enviar SMS (podem ser indicados vários números separados por vírgulas)
• message – mensagem (restrições normais de comprimento do SMS, em caso de exceder o limite, dividir em vários SMS);
• sender – (opcional) o remetente do SMS (número virtual ou texto) a lista de valores disponíveis pode ser obtida pelo método GET /v1/sms/senderid/
• language – (opcional) língua do modelo de SMS. Se não for indicada, será utilizada a língua da área pessoal.

Obter a lista de modelos de SMS

                                    {
"list": [
    {
        "cath_id":"1",
         "title":"The name of the template category",
        "templates": [
            {
                "id":"1",
                "text":"The template text with a variable {$var}"
            },
            {
                "id":"2",
                "text":"Second template text"
            },
        ]
    }
]
}

                                    <answer>
<list>
    <value>
        <cath_id>1</cath_id>
        <title>The name of the template category</title>
        <templates>
            <value>
                <id>1</id>
                <text>The template text with a variable {$var}</text>
            </value>
            <value>
                <id>2</id>
                <text>Second template text</text>
            </value>
        </templates>
    </value>
</list>
</answer>

Parámetros

• skip – (opcional) número de modelos a oscilar antes do início da seleção, por defeito 0;
• limit – (opcional) número de modelos a apresentar (por defeito 24, máximo 1000);
• language – (opcional) Idioma do modelo de SMS. Se não for selecionado, será utilizado o idioma da área pessoal da conta.

Obter a lista de remetentes de SMS disponíveis para o número indicado.

                                    {
    "senders": ["Teamsale", "1234567890"]
}

                                    <answer>
	<senders>
		<value>1234567890</value>
		<value>Teamsale</value>
	</senders>
</answer>

Parâmetros

• phones – número de telefone para o qual pretende obter a lista de remetentes disponíveis.

obter chave para o widget webrtc. Tempo de vida da chave - 72 horas.

                                    {
    "status":"success",
    "key": YOUR_KEY
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <key>YOUR_KEY</key>
</answer>

Parâmetros:

• sip – Início de sessão da extensão SIP ou central telefónica.

Criar integração de widgets WebRTC

                                    {
    "status": "success"
}

Parâmetros

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por parceiros;
• domain - nome do domínio.

Modificar as definições de integração do widget WebRTC

                                    {
    "status": "success"
}

Parâmetros

• user_id - parâmetro facultativo, disponível para utilização por parceiros ou utilizadores criados por parceiros;
• shape - Forma do widget, valores possíveis: " square", "rounded".;
• position - localização do widget, valores possíveis: "top_left", "top_right", "bottom_right", "bottom_left".

Dados de integração do widget WebRTC

                                    {
    "status": "success",
    "is_exists": true,
    "domains": [
        "test.domain.com"
    ],
    "settings": {
        "shape": "square",
        "position": "top_right"
    }
}

Parâmetros

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por parceiros;

Adicionar domínio da integração do widget WebRTC

                                    {
   "status": "success"
}

Parâmetros

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por parceiros;
• domain - nome do domínio.

Remover domínio da integração do widget WebRTC

                                    {
   "status": "success"
}

Parâmetros

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por parceiros;
• domain - nome do domínio.

Remover a integração do widget WebRTC

                                    {
   "status": "success"
}

Parâmetros

• user_id - parâmetro opcional, disponível para utilização por parceiros ou utilizadores criados por parceiros.

Lista de dispositivos compatíveis com eSIM

Descrição da resposta de sucesso (Resposta 1)

                                    Resposta 1:
{
    "status": "success",
    "devices": {
        "acer": [
            "ACER Swift 3",
            "ACER Swift 7"
        ],
        "asus": [
            "ASUS Mini Transformer T103HAF",
            "ASUS NovaGo TP370QL",
            "ASUS Vivobook Flip 14 TP401NA"
        ],
        "xiaomi": [
            "Xiaomi 12T Pro",
            "Xiaomi 13 Lite"
        ]
    }
}

• devices (object[]) — lista de dispositivos agrupados por marcas

Descrição da resposta em caso de erro interno (Resposta 2)

                                    Resposta 2:
{
  "status": "error",
  "message": "Getting devices internal error"
}

• message (string) — contém a mensagem de erro

Lista de todos os pacotes disponíveis

Descrição da resposta de sucesso (Resposta 1)

                                    Resposta 1:
{
  "status": "success",
  "packages": [
    {
      "duration": 7,
      "countries": [
        {
          "iso2": "cn",
          "name": "China",
          "aliases": []
        }
      ],
      "networks": [
        {
          "iso2": "CN",
          "network": "China Unicom",
          "type": "LTE"
        }
      ],
      "region": null,
      "id": "1-cn-7days-1gb",
      "price": 5,
      "data": 1,
      "duration_unit": "days",
      "data_unit": "GB",
      "top_up": true,
      "kyc_verify": false,
      "activation_policy": "first-usage",
      "activation_limit_days": null,
      "price_multi_currency": {
        "eur": 5,
        "usd": 5,
        "gbp": 4,
        "pln": 19,
        "kzt": 2000,
        "uah": 200
      },
    }
  ]
}

• packages (object[]) — contém a lista de pacotes disponíveis
• packages.*.duration (integer) — prazo de validade da eSIM. A unidade de medida deste valor está contida no parâmetro duration_unit
• packages.*.countries (object[]) — lista de países onde a eSIM funciona
• packages.*.networks (object[]) — lista de países onde a eSIM oferece acesso à internet móvel
• packages.*.region (null|string, europe|america|latin-america|asia|caribbean-islands|africa|south-africa|middle-east|oceania|iberica|scandinavia|eastern-europe) — região onde a eSIM funciona
• packages.*.id (string) — identificador interno da eSIM
• packages.*.price (float) — preço da eSIM
• packages.*.data (integer) — volume de tráfego disponível. A unidade de medida deste valor está contida no parâmetro data_unit
• packages.*.duration_unit (string, days) — unidade de medida do prazo de validade do parâmetro duration
• packages.*.data_unit (string, GB|KB|MB) — unidade de medida do tráfego do parâmetro data
• packages.*.top_up (boolean) — tem o valor true se a eSIM estiver disponível para recarga
• packages.*.kyc_verify (boolean) — indicador de necessidade de verificação de documentos para comprar a eSIM
• packages.*.activation_policy (null|string, first-usage|installation) — política de ativação. Se tiver o valor "first-usage", é ativada no momento do primeiro uso. Se tiver o valor "installation", é ativada no momento da instalação da eSIM no dispositivo. Se for null, não tem política de ativação
• packages.*.price_multi_currency (object) — objeto com os preços em cada moeda
• packages.*.activation_limit_days (null|integer) — pode conter o número de dias em que a eSIM deve ser ativada após a conexão. Se for null, não há essa restrição

Descrição da resposta em caso de erro interno (Resposta 2)

                                    Resposta 2:
{
  "status": "error",
  "message": "Getting packages error"
}

• message (string) — contém a mensagem de erro

Lista de pacotes conectados

Parâmetros

• user_id (integer)
  Campo opcional
  ID do utilizador solicitado. Disponível apenas para uso por revendedores e apenas para os utilizadores criados por eles. Por defeito, será usado o ID do utilizador atual.

Descrição da resposta de sucesso (Resposta 1)

                                    Resposta 1:
{
  "status": "success",
  "orders": [
    {
      "iccid": "8937204017175532566",
      "status": "inactive",
      "packages": [
        {
          "iccid": "8937204017175532566",
          "price": 4.5,
          "currency": "USD",
          "countries": [
            {
              "iso2": "al",
              "name": "Albania",
              "aliases": []
            }
          ],
          "duration": 30,
          "data": 1,
          "region": null,
          "id": "3-al-30days-1gb",
          "data_remaining": 1,
          "top_up": true,
          "created_at": 1730978058,
          "auto_prolong": false,
          "activated_at": null,
          "expired_at": null,
          "reference_id": "672ca10a84a28e977c0cfe39"
        }
      ],
      "title": null,
      "msisdn": null,
      "activation_code": "LPA:1$smdp.io$K2-2627GZ-1UM3Z3Y",
      "created_at": 1730978058
    }
  ]
}

• orders (object[]) — lista de pacotes conectados. A descrição detalhada dos dados do pacote pode ser encontrada no método /v1/esim/order/<iccid>/

Descrição da resposta em caso de user_id incorreto (Resposta 2)

                                    Resposta 2:
{
    "status": "error",
    "message": "You are not a reseller of the requested user"
}

• message (string) — contém a mensagem de erro

Informação sobre o pacote conectado pelo ICCID

Parâmetros

• iccid (string)
  Campo obrigatório
  ICCID solicitado
• user_id (integer)
  Campo opcional
  ID do utilizador solicitado. Disponível apenas para uso por revendedores e apenas para os utilizadores criados por eles. Por defeito, será usado o ID do utilizador atual.

Descrição da resposta de sucesso (Resposta 1)

                                    Resposta 1:
{
  "status": "success",
  "order": {
    "iccid": "8937204017175532566",
    "status": "inactive",
    "packages": [
      {
        "iccid": "8937204017175532566",
        "price": 4.5,
        "currency": "USD",
        "countries": [
          {
            "iso2": "al",
            "name": "Albania",
            "aliases": []
          }
        ],
        "duration": 30,
        "data": 1,
        "type": "one-off",
        "region": null,
        "id": "3-al-30days-1gb",
        "data_remaining": 1,
        "top_up": true,
        "created_at": 1730978058,
        "auto_prolong": false,
        "activated_at": null,
        "expired_at": null,
        "reference_id": "672ca10a84a28e977c0cfe39"
      }
    ],
    "title": null,
    "msisdn": null,
    "activation_code": "LPA:1$smdp.io$K2-2627GZ-1UM3Z3Y",
    "created_at": 1730978058
  }
}

• order.iccid (string) — ICCID do pacote eSIM
• order.status (string, active|inactive|archived|blocked) — estado do pacote — ativo, inativo, arquivado ou bloqueado
• order.packages (object[]) — pacotes conectados. Os dados para este elemento estão descritos no método /v1/esim/esim/packages
• order.packages.*.data_remaining (float) — volume de tráfego disponível. A unidade de medida deste valor está contida no parâmetro order.packages.*.data_unit
• order.packages.*.expired_at (null|integer) — timestamp caso o prazo de validade da eSIM tenha expirado
• order.title (null|string) — nome personalizado da eSIM adquirida
• order.msisdn (null|string) — MSISDN se existir
• order.activation_code (string) — chave para geração de QR Code ou configuração manual
• order.created_at (integer) — timestamp da ativação da eSIM

Descrição da resposta de erro em caso de envio de um ICCID inexistente (Resposta 2)

                                    Resposta 2:
{
  "status": "error",
  "message": "Not found"
}

• message (string) — mensagem de erro

Conectar o pacote

Parâmetros

• package_id (string)
  Campo obrigatório
  ID do pacote para conexão, packages.*.id do método /v1/esim/packages/
• user_id (integer)
  Campo opcional
  ID do utilizador para conexão. Disponível apenas para uso por revendedores e apenas para os utilizadores criados por eles. Por defeito, será usado o ID do utilizador atual.

Descrição da resposta de sucesso (Resposta 1)

                                    Resposta 1:
{
    "status": "success",
    "order": {
        "iccid": "8937204016150824154",
        "activation_code": "LPA:1$smdp.io$K2-1UYQA7-Z8B3BF",
        "status": "inactive",
        "packages": [
            {
                "iccid": "8937204016150824154",
                "price": 11.01,
                "currency": "EUR",
                "countries": [
                    {
                        "iso2": "us",
                        "name": "США",
                        "aliases": []
                    }
                ],
                "duration": 30,
                "data": 0,
                "data_remaining": 0,
                "top_up": true,
                "type": "one-off",
                "region": "change",
                "created_at": 1720700977,
                "auto_prolong": false,
                "activated_at": null,
                "expired_at": null,
                "reference_id": null,
                "id": "3-change-30days-0gb"
            }
        ],
        "created_at": 1720700977,
        "title": null,
        "msisdn": null
    }
}

• order (object) — dados sobre o pacote conectado. A descrição detalhada está disponível no método /v1/esim/order/<iccid>/

Descrição da resposta de erro em caso de saldo insuficiente (Resposta 2)

                                    Resposta 2:
{
  "status": "error",
  "message": "Not enough money on your account"
}

• message (string) — contém a mensagem de erro

Pedido de verificação com envio de notificação ao utilizador

O tempo de validade do pedido de verificação é de 10 minutos.

Parâmetros gerais (para todos os canais)

• channel (string, sms|call_code|email|call_button)
  Campo obrigatório
  Canal para o envio da mensagem

Descrição do canal "sms"

Uma mensagem SMS com o código de confirmação será enviada para o número do destinatário.
O envio através deste canal pode implicar custos, pelo que o utilizador da API deve ter um saldo positivo.

Parâmetros

• to (string)
  Campo obrigatório
  Número de telefone do destinatário no formato E.164
• code (integer)
  Campo opcional
  Código de verificação de seis dígitos. Se não for especificado, será gerado automaticamente
• language (string, en|es|de|pl|ru|ua|fr)
  Campo opcional
  Idioma da mensagem. Se não for especificado, será utilizado o idioma do utilizador.
• template_id (integer)
  Campo opcional
  ID do modelo personalizado para SMS. Se não for especificado, será utilizado o modelo padrão.
• caller_id (string)
  Campo opcional
  Número do remetente. Por defeito, "Teamsale".

Descrição do canal "call_code"

Ao selecionar este canal, será feita uma chamada para o número do destinatário, onde o código de confirmação será anunciado.
O envio por este canal pode ter custos adicionais, sendo necessário que o utilizador da API tenha saldo positivo.

Requisitos

Para utilizar este canal, o utilizador da API deve ter um número registado no sistema Zadarma.

Parâmetros

• to (string)
  Campo obrigatório
  Número de telefone do destinatário no formato E.164
• from (string)
  Campo opcional
  Número de telefone no formato E.164 a partir do qual será feita a chamada. Necessário se o utilizador tiver mais do que um número no sistema Zadarma
• code (integer)
  Campo opcional
  Código de verificação de seis dígitos. Se não for especificado, será gerado automaticamente
• language (string, en|es|de|pl|ru|ua|fr)
  Campo opcional
  Idioma da mensagem. Se não for especificado, será utilizado o idioma do utilizador.

Descrição do canal "email"

Ao optar por este canal, um e-mail contendo o código de confirmação será enviado para o endereço indicado. Para utilizar este canal, o utilizador da API deve ter a integração de e-mail previamente ativada no sistema Teamsale CRM.

Parâmetros

• to (string)
  Campo obrigatório
  Endereço de e-mail do destinatário
• from (string)
  Campo opcional
  Endereço de e-mail do remetente. Deve ser especificado se o utilizador tiver mais do que uma integração de e-mail ativa
• code (integer)
  Campo opcional
  Código de verificação de seis dígitos. Se não for especificado, será gerado automaticamente
• language (string, en|es|de|pl|ru|ua|fr)
  Campo opcional
  Idioma da mensagem. Se não for especificado, será utilizado o idioma do utilizador
• email_subject (string)
  Campo opcional
  Assunto do e-mail enviado. Se não for especificado, será utilizado o valor predefinido
• email_body (string)
  Campo opcional
  Corpo do e-mail enviado. Deve conter a string "{#code#}" para a inserção automática do código de confirmação. Se não for especificado, será utilizado o valor predefinido

Descrição do canal "call_button"

Este canal realiza uma chamada para o número do destinatário, durante a qual o utilizador deve seguir as instruções dos ficheiros de áudio e premir a tecla "1" para confirmar.
O envio por este canal pode ter custos adicionais, sendo necessário que o utilizador da API tenha saldo positivo.

Para utilizar este canal, é necessário:

• Ter um número de telefone registado no sistema Zadarma.
• Ter a central telefónica virtual (PBX) ativada.
• Configurar os alertas de eventos.

Características: o resultado da verificação através deste canal é validado usando o webhook NOTIFY_OUT_END, e não pelo método /v1/verify/check/.

Parâmetros

• to (string)
  Campo obrigatório
  Número de telefone do destinatário no formato E.164
• from (string)
  Campo opcional
  Número de telefone no formato E.164 a partir do qual será feita a chamada. Necessário se o utilizador tiver mais do que um número de telefone na central telefónica (PBX)
• greeting_sound_id (string)
  Campo obrigatório
  ID do ficheiro de áudio que o utilizador ouvirá ao atender a chamada
• button_1_sound_id (string)
  Campo obrigatório
  ID do ficheiro de áudio que o utilizador ouvirá após premir a tecla "1"
• fallback_sound_id (string)
  Campo obrigatório
  ID do ficheiro de áudio que será reproduzido caso o utilizador não pressione a tecla "1", carregue noutra tecla ou não realize nenhuma ação

Para gerir os ficheiros de áudio utilizados nos parâmetros greeting_sound_id, button_1_sound_id e fallback_sound_id, utilize os métodos da API disponíveis na secção /v1/pbx/ivr/sounds/*.

Exemplos

Quando o pedido é enviado com sucesso através dos canais sms, call_code, email (Resposta 1)

                                    Resposta 1:
{
    "status": "success",
    "request_id": "NDlLMWlNcW5mR3EvOFkraWVtOWF1Q2c9"
}

• request_id (string) — ID do pedido, necessário para a verificação posterior do código de validação

Ao utilizar o canal call_button, a resposta bem-sucedida não contém request_id, uma vez que a verificação do resultado é realizada através do webhook NOTIFY_OUT_END (Resposta 2)

                                    Resposta 2:
{
    "status": "success"
}

Em caso de um pedido inválido, a API retorna uma resposta com o estado error e a descrição do erro no campo message (Resposta 3)

                                    Resposta 3:
{
    "status": "error",
    "message": "\"to\" param is required"
}

Se o pedido for enviado através do canal email e o parâmetro from for obrigatório mas não estiver especificado, o sistema devolverá uma resposta com o estado "error" e uma mensagem a indicar a ausência do parâmetro necessário (Resposta 4)

                                    Resposta 4:
{
    "status": "error",
    "message": "Can't find active email integration for the \"from\" param's email"
}

Verificação do código no pedido de validação para os canais SMS, call_code e email

Parâmetros

• code (integer)
  Campo obrigatório
  Código de seis dígitos que deve ser verificado.
• request_id (string)
  Campo obrigatório
  ID do pedido no qual o código deve ser validado.

Descrição da resposta bem-sucedida, caso o parâmetro code corresponda ao código do pedido de verificação (Resposta 1)

                                    Resposta 1:
{
    "status": "success",
    "message": "Code is correct"
}

• status (string) — contém o valor "success"
• message (string) — contém o valor "Code is correct"

Descrição da resposta de erro, caso o pedido tenha expirado ou o request_id não seja encontrado (Resposta 2)

                                    Resposta 2:
{
    "status": "error",
    "message": "No such request id"
}

• message (string) — contém a mensagem de erro

Descrição da resposta de erro, caso o parâmetro code não corresponda ao código do pedido (Resposta 3)

                                    Resposta 3:
{
    "status": "error",
    "message": "Invalid verification code"
}

• message (string) — contém a mensagem de erro

Para verificar o canal call_button, é necessário utilizar o webhook NOTIFY_OUT_END.

Devolve a lista de clientes

Parámetros

• search (opcional) - barra de pesquisa. A pesquisa é realizada de forma combinada por::
  • nome do cliente
  • números de telefone do cliente
  • descrição do cliente
  • morada e código postal
  • site
  • e-mail
  • Messengers
  • nomes dos empregados
  • números de telefone dos empregados
  • descrição dos empregados
  • e-mail dos empregados
  • Messengers dos empregados
• filter (opcional) — filtro de clientes. Estrutura do filtro:

(Resposta 1)

                                    Resposta 1:
{
  "status": "company",
  "type": "client",
  "country": "GB",
  "city": "London",
  "label": 12,
  "utm": 19,
  "employees_count": "50",
  "responsible": 20
}

donde:

• status — estado do cliente. Valores disponíveis:
  • individual — pessoa física
  • company — empresa
• type — tipo de cliente. Valores possíveis:
  • potential — cliente potencial
  • client — cliente
  • reseller — revendedor
  • partner — colaborador
• country — país del cliente. Código de duas letras (ES, US, etc)
• city — cidade do cliente
• label — etiqueta (identificador)
• employees_count — número de empregados. Valores possíveis:
  • 50 — inferior a 50
  • 50_250 — 50 – 250
  • 250_500 — 250 – 500
• responsible — responsável (identificador do utilizador)

Qualquer um dos parâmetros do filtro pode ser omitido, ou seja, é opcional.

• sort (opcional) — classificação do cliente. Estrutura dos parâmetros:

(Resposta 2)

                                    Resposta 2:
{
    "attr": "name",
    "desc": 0
}

donde:

• attr — campo de ordenação. Valores disponíveis:
  • name — nome do cliente
  • status — estado do cliente
  • type — tipo do cliente
• desc — sentido de classificação. Valores disponíveis:
  • 0 — crescente
  • 1 — decrescente
  • take (para a amostra por página) - quantos clientes devem ser devolvidos (predefinição: 20)
  • skip (para a amostra por página) - quantos clientes devem ser ignorados (predefinição 0)

Resposta

(Resposta 3)

                                    Resposta 3:
{
  "totalCount": 82,
  "customers": [
    {
      "id": 65,
      "name": "Good company",
      "status": "company",
      "type": "client",
      "responsible_user_id": 20,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "created_at": "2020-04-28 05:47:47",
      "created_by": 20,
      "lead_source": "manual",
      "lead_created_at": null,
      "lead_created_by": null,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 12,
          "label": "Best clients"
        }
      ],
      "utms": [
        {
          "id": 19,
          "param": "utm_source",
          "value": "google",
          "display_value": "Google"
        }
      ]
    }
  ]
}

donde:

• totalCount — número total de clientes (incluindo barra de pesquisa e filtro)
• customers — conjunto de clientes (tendo em conta a amostra por página). Cada elemento do conjunto contém os seguintes parâmetros:
  • id — identificador do cliente
  • name — nombre do cliente
  • status — estado do cliente. Valores possíveis:
    • individual — pessoa singular
    • company — empresa
  • type — tipo de cliente. Valores possíveis:
    • potential — cliente potencial
    • client — cliente
    • reseller — revendedor
    • partner — parceiro
  • responsible_user_id — responsável (identificador do utilizador)
  • employees_count — número de empregados. Valores possíveis:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descrição do cliente
  • country — país do cliente. Código de duas letras (ES, US, etc.)
  • city — cidade do cliente
  • address — endereço do cliente
  • zip — código postal
  • website — site do cliente
  • created_at — data e hora de criação do cliente (no formato YYYY-MM-DD HH:mm:ss)
  • created_by — criado por (identificador do utilizador)
  • lead_source — fonte. Valores possíveis:
    • manual — manual
    • call_incoming — chamada recebida
    • call_outgoing — chamada efectuada
    • form — forma
  • lead_created_at — data e hora da criação do lead, se o cliente tiver sido criado através do lead (en formato YYYY-MM-DD HH:mm:ss)
  • lead_created_by — por quem o contacto foi criado, se o cliente tiver sido criado através do contacto (identificador do utilizador)
    • type — tipo de número. Valores possíveis:
      • work — de trabalho
      • personal — pessoal
    • phone — valor do número
  • contacts — conjunto de contactos do cliente. Cada contacto deve conter os seguintes campos:
    • type — tipo de contacto. Valores possíveis:
      • email_work — e-mail de trabalho
      • email_personal — e-mail pessoal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor do contacto
  • labels — conjunto de etiquetas atribuídas ao cliente. Cada etiqueta contém os seguintes campos:
    • id — identificador de etiqueta
    • label — valor da etiqueta

Devolve o cliente pelo seu ID

Parâmetros de endereço

• c_id — identificador do cliente

Resposta

                                    {
  "id": 65,
  "name": "Good Company",
  "status": "company",
  "type": "client",
  "responsible_user_id": 20,
  "employees_count": "50",
  "comment": "",
  "country": "GB",
  "city": "London",
  "address": "",
  "zip": "",
  "website": "",
  "created_at": "2020-04-28 05:47:47",
  "created_by": 20,
  "lead_source": "manual",
  "lead_created_at": null,
  "lead_created_by": null,
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 12,
      "label": "Best clients"
    }
  ],
  "utms": [
    {
      "id": 19,
      "param": "utm_source",
      "value": "google",
      "display_value": "Google"
    }
  ],
  "custom_properties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty",
      "value": "high"
    }
  ]
}

donde:

• name — nome do cliente
• status — estado do cliente. Valores possíveis:
  • individual — pessoa singular
  • company — empresa
• type — tipo de cliente. Valores possíveis:
  • potential — cliente potencial
  • client — cliente
  • reseller — revendedor
  • partner — colaborador
• responsible_user_id — responsável (identificador de utilizador)
• employees_count — número de empregados. Valores possíveis:
  • 50 — inferior a 50
  • 50_250 — 50 – 250
  • 250_500 — 250 – 500
• comment — descrição do cliente
• country — país do cliente. Código de duas letras (ES, US, etc.)
• city — cidade do cliente
• address — endereço do cliente
• zip — código postal
• website — site do cliente
• lead_source — fonte. Valores possíveis:
  • manual — manual
  • call_incoming — chamada recebida
  • call_outgoing — chamada efetuada
  • form — forma
• lead_created_at — data e hora da criação do lead, se o cliente tiver sido criado através do lead (no formato YYYY-MM-DD HH:mm:ss)
• lead_created_by — por quem o contacto foi criado, se o cliente tiver sido criado através do lead (identificador do utilizador)
• phones — conjunto de números de telefone de clientes. Cada número deve conter os seguintes campos:
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos de clientes. Cada contacto deve conter os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor do contacto
• labels — conjunto de etiquetas vinculadas al cliente. Cada etiqueta contém os seguintes campos:
  • id — identificador da etiqueta
  • label — valor da etiqueta
• custom_properties — conjunto de propriedades adicionais. Cada propriedade adicional contém os seguintes campos:
  • id — identificador de propriedade adicional ou:
  • key — nome único da propriedade adicional
  • value — valor da propriedade adicional

Criar um novo cliente com os dados indicados

Parâmetros

• customer — dados dos novos clientes. Estrutura do cliente:

(Resposta 1)

                                    Resposta 1:
{
    "name": "Good Company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work", 
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 18,
        "value": "high"
      }
    ]
}

onde:

• name — nome do cliente
• status — estado do cliente. Valores possíveis:
  • individual — pessoa singular
  • company — empresa
• type — tipo de cliente. Valores possíveis:
  • potential — cliente potencial
  • client — cliente
  • reseller — revendedor
  • partner — colaborador
• responsible_user_id — responsável (identificador do utilizador)
• employees_count — quantidade de empregados. Valores possíveis:
  • 50 — inferior a 50
  • 50_250 — 50 – 250
  • 250_500 — 250 – 500
• comment — descrição do cliente
• country — país do cliente. Código de duas letras (ES, US, etc.)
• city — cidade do cliente
• address — endereço do cliente
• zip — código postal
• website — página web do cliente
• lead_source — fonte. Valores possíveis:
  • manual — manual
  • call_incoming — chamada recebida
  • call_outgoing — chamada efetuada
  • form — forma
• phones — conjunto de números de telefone. Cada número deve conter os seguintes campos:
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do cliente. Cada contacto deve conter os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor do contacto
• labels — conjunto de etiquetas adicionadas ao cliente. Cada elemento deve conter:
  • id — identificador da etiqueta existente
• custom_properties — conjunto de propriedades adicionais. Cada elemento deve conter:
  • id — identificador de propriedade adicional ou:
  • key — nome único da propriedade adicional
  • value — valor da propriedade adicional

Resposta:

(Resposta 2)

                                    Resposta 2:
{
  "id": 65
}

onde:

• id — Identificador do cliente criado.

Actualize o cliente existente com o ID fornecido

Parâmetros de endereço

• c_id — identificador do cliente

Parâmetros

• customer — dados de novos clientes. Estrutura do cliente:

                                    {
    "name": "Good Company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 18,
        "value": "high"
      }
    ]
}

onde:

• name —nome do cliente
• status — estado do cliente. Valores possíveis:
  • individual — persona física
  • company — empresa
• type — tipo do cliente. Valores possíveis:
  • potential — cliente potencial
  • client — cliente
  • reseller — revendedor
  • partner — sócio
• responsible_user_id — responsável (identificador do utilizador)
• employees_count — número de empregados. Valores possíveis:
  • 50 — inferior a 50
  • 50_250 — 50 – 250
  • 250_500 — 250 – 500
• comment — descrição do cliente
• country — país do cliente. Código de dos letras (ES, US, etc.)
• city — cidade do cliente
• address — endereço do cliente
• zip — código postal
• website — site do cliente
• lead_source — fonte. Valores possíveis:
  • manual — manual
  • call_incoming — chamada recebida
  • call_outgoing — chamada efetuada
  • form — forma
• phones — conjunto de números de telefone. Cada número deve conter os seguintes campos:
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do cliente. Cada contacto contém os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor do contacto
• labels — conjunto de etiquetas adicionadas ao cliente. Cada elemento deve conter:
  • id — identificador da etiqueta existente
• custom_properties — conjunto de parâmetros adicionais. Cada elemento deve conter:
  • id — identificador de propriedade adicional ou:
  • key — nome único da propriedade adicional
  • value — valor da propriedade adicional

Elimina o cliente pelo seu ID

Parâmetros de endereço

• c_id — identificador do cliente

Exibe o conjunto de todas as etiquetas de origem e as suas estatísticas.

Resposta

                                    [
  {
    "id": 78,
    "param": "utm_source",
    "value": "google",
    "display_value": "Google",
    "count": 1267
  }
]

Onde cada etiqueta de analítica contém os seguintes campos:

• id — identificador da etiqueta de fonte
• param — tipo de etiqueta de fonte. Valores possíveis:
  • utm_source
  • utm_medium
  • utm_campaign
  • utm_content
  • phone — telefone
  • custom — livre
• value — valor real da etiqueta de fonte
• display_value — valor mostrado da etiqueta de fonte
• count — número de clientes e clientes potenciais que utilizam esta etiqueta de fonte

Adicione uma nova etiqueta de origem

Parâmetros

• utm — dados da nova etiqueta de fonte. Estrutura da etiqueta:

(Resposta 1)

                                    Resposta 1:
{
  "param": "utm_source",
  "value": "google",
  "display_value": "Google"
}

Onde:

• param — tipo de etiqueta de fonte. Valores possíveis:
  • utm_source
  • utm_medium
  • utm_campaign
  • utm_content
  • phone — teléfono
  • custom — libre
• value — valor real da etiqueta de fonte
• display_value (opcional) — valor mostrado da etiqueta de fonte

Resposta

(Resposta 2)

                                    Resposta 2:
{
  "id": 78
}

Onde:

• id — identificador da etiqueta de fonte

Actualize a etiqueta de origem existente com o ID fornecido

Parâmetros de endereço

• utm_id — identificador da etiqueta de origem

Parâmetros

• utm — novos dados da etiqueta de origem. Estrutura da etiqueta de origem:

                                    {
  "param": "utm_source",
  "value": "google",
  "display_value": "Google"
}

Onde:

• param — tipo de etiqueta da origem. Valores possíveis:
  • utm_source
  • utm_medium
  • utm_campaign
  • utm_content
  • phone — telefone
  • custom — personalizado
• value — valor real da etiqueta de origem
• display_value — valor apresentado da etiqueta de origem

Remove a etiqueta de rastreio de chamadas pelo seu ID

Parâmetros de endereço

• utm_id — identificador da etiqueta de origem

Devolve a lista de todas as etiquetas e as suas estatísticas.

Resposta

                                    {
  "totalCount": 5,
  "labels": [
    {
      "id": 12,
      "label": "Best clients",
      "count": 14
    }
  ]
}

onde:

• totalCount — número total de etiquetas no sistema
• labels — conjunto de etiquetas. Cada etiqueta contém os seguintes campos:
  • id — identificador da etiqueta
  • label — nome da etiqueta
  • count — número de clientes e leads que utilizam esta etiqueta

Criar uma nova etiqueta

Parâmetros

• name — nome da nova etiqueta

Resposta

                                    {
  "id": 13,
  "label": "Very best clients",
  "count": 0
}

donde:

• id — identificador da etiqueta criada
• label — nome da etiqueta
• count — número de clientes e contactos que utilizam esta etiqueta (sempre igual a 0)

Remove a etiqueta do sistema pelo seu ID

Parâmetros de endereço

• l_id — identificador da etiqueta

Devolve todos os parâmetros adicionais

Resposta

                                    {
  "totalCount": 8,
  "customProperties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty"
    }
  ]
}

onde:

• totalCount — quantidade de propriedades adicionais.
• customProperties — matriz de propriedades adicionais. Cada propriedade adicional contém os seguintes parâmetros:
  • id — identificador de propriedade adicional
  • key — nome único da propriedade adicional
  • title — nome apresentado da propriedade adicional

Devolve notas no fluxo de actividades do cliente

Parâmetros de endereço

• c_id — identificador do cliente

Resposta

                                    {
  "totalCount": 17,
  "items": [
    {
      "id": 37825,
      "type": "note",
      "content": "Call to the client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "John Beam",
      "call_id": null,
      "call_type": null,
      "call_status": null,
      "call_phone": null,
      "call_duration": null,
      "call_record": null,
      "call_contact_name": null,
      "attached_files": [
        {
          "file_id": 576,
          "original_filename": "document.doc"
        }
      ]
    }
  ]
}

donde:

• totalCount — a quantidade total de gravações
• items — conjunto de gravações. Cada gravação contém os seguintes atributos:
  • id — identificador da gravação
  • type — tipo de gravação. Valores possíveis:
    • event — evento
    • note — nota de texto
    • call — chamada
  • content — conteúdo do registo. Se o tipo da gravação for uma nota, este atributo contém o conteúdo de uma nota de texto. Se o tipo de registo for um evento, este atributo contém o identificador, por exemplo:
    • CUSTOMER_CREATED — evento de criação do cliente
    • LEAD_CREATED — evento de criação do lead
  • time — hora de gravação em formato YYYY-MM-DD hh:mm:ss
  • user_id — identificador do utilizador que criou a gravação
  • user_name — nome de utilizador que criou a gravação
  • call_id — identificador de chamada (se o tipo de registo for uma chamada)
  • call_type — tipo de chamada. Valores possíveis:
    • incoming — chamada recebida
    • outgoing — chamada efetuada
  • call_status — estado da chamada. Valores possíveis:
    • answer — chamada bem sucedida
    • noanswer — sem resposta
    • cancel — cancelada
    • busy — ocupado
    • failed — falhou
  • call_phone — número de telefone da chamada
  • call_duration — duração da chamada em segundos
  • call_record — se a gravação de chamadas estiver ativada
  • call_contact_name — nome do contacto da chamada
  • attached_files — conjunto de arquivos anexados à nota (se o tipo de registo for nota). Cada elemento do conjunto contém os seguintes atributos:
    • file_id — identificador do arquivo
    • original_filename — nome original do arquivo

Adiciona nota de texto no fluxo de atividade do cliente com capacidade de anexar ficheiros

Parâmetros do endereço

• c_id — identificador do cliente

Parâmetros

• content — conteúdo no texto da nota
• files — matriz dos anexos

Resposta

                                    {
  "id": 37825,
  "type": "note",
  "content": "Call to the client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "John Beam",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "document.doc"
    }
  ]
}

donde:

• id — identificador de gravação
• type — tipo de gravação. Neste caso, é igual:
  • note — nota de texto
• content — conteúdo no texto da nota
• time — hora do registo em formato YYYY-MM-DD hh:mm:ss
• user_id — identificador do utilizador que criou a gravação
• user_name — nome do utilizador que criou a gravação
• attached_files — matriz de ficheiros anexados a uma nota (se o tipo de gravação for uma nota). Cada elemento da matriz contém os seguintes atributos:
  • file_id — identificador de ficheiro
  • original_filename — nome do ficheiro original

Actualiza o conteúdo da nota de texto existente pelo seu ID

Parâmetros de endereço

• c_id — identificador do cliente
• i_id — identificador da nota de texto

Parâmetros

• content — novo texto de nota

Elimina a nota no fluxo de atividade do cliente pelo seu ID

Parâmetros de endereço

• c_id — identificador do cliente
• i_id — identificador de nota

Devolve a lista de empregados do cliente por ID

Parâmetros de endereço

• c_id — identificador do cliente

Resposta

                                    {
  "totalCount": 5,
  "employees": [
    {
      "id": 23,
      "customer_id": 11,
      "name": "Steven Knight",
      "position": "manager",
      "position_title": "",
      "comment": "",
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "s.knight@example.com"
        }
      ]
    }
  ]
}

onde:

• totalCount — número de funcionários do cliente
• employees — matriz de empregados do cliente. Cada elemento contém os seguintes atributos:
  • id — identificador do funcionário
  • customer_id — identificador de cliente associado ao funcionário - name — nome do funcionário
  • position — cargo do funcionário. Valores possíveis:
    • ceo — diretor-geral
    • director — diretor
    • manager — gestor
    • sales_manager — comercial
    • hr — RRHH
    • support — suporte
    • custom — outro
  • position_title — nome de outros cargos (paraposição = custom)
  • comment — descrição do funcionário
  • phones — matriz de números de telefone de empregados. Cada número contém os seguintes campos:
    • type — tipo de número. Valores possíveis:
      • work — de trabalho
      • personal — pessoal
    • phone — valor do número
  • contacts — matriz de contactos dos funcionários. Cada contacto contém os seguintes campos:
    • type — tipo de contacto. Valores possíveis:
      • email_work — e-mail de trabalho
      • email_personal — e-mail pessoal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor do contacto

Devolve o empregado do cliente por ID

Parâmetros de endereço

• c_id — identificador do cliente
• e_id — identificador do funcionário

Resposta

                                    {
  "id": 23,
  "customer_id": 11,
  "name": "Steven Knight",
  "position": "manager",
  "position_title": "",
  "comment": "",
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "s.knight@example.com"
    }
  ]
}

onde:

• id — identificador do funcionário
• customer_id — identificador do cliente vinculado ao funcionário
• name — nome do funcionário
• position — cargo do funcionário. Valores possíveis:
  • ceo — diretor-geral
  • director — diretor
  • manager — gestor
  • sales_manager — comercial
  • hr — RRHH
  • support — suporte
  • custom — outro
• position_title — nome do cargo próprio (para cargo = custom)
• comment — descrição do funcionário
• phones — conjunto de números de telefone de empregados. Cada número contém os seguintes campos:
  • type — tipo de número. Valores possíveis:
    • work — de tranalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do cliente. Cada contacto contém os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valores de contacto

Crie e guarde um novo empregado para o cliente selecionado.

Parâmetros de endereço

• c_id — identificador do cliente

Parâmetros

• employee — dados de novos empregados. Estrutura do empregado:

(Resposta 1)

                                    Resposta 1:
{
    "name": "Steven Knight",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "s.knight@example.com"
      }
    ]
}

onde:

• name — nome do funcionário
• position — cargo do empregado. Valores possíveis:
  • ceo — diretor general
  • director — diretor
  • manager — agente
  • sales_manager — comercial
  • hr — RRHH
  • support — suporte
  • custom — outro
• position_title — nome do cargo próprio (para cargo = custom)
• comment — descrição do funcionário
• phones — conjunto de números de telefone dos funcionários. Cada número contém os seguintes campos:
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do cliente. Cada contacto contém os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor de contacto

Resposta

(Resposta 2)

                                    Resposta 2:
{
  "id": 23
}

onde:

• id — identificador do novo funcionário

Devolve o empregado existente com o ID indicado

Parâmetros de endereço

• c_id — identificador do cliente
• e_id — identificador do funcionário

Parámetros

• employee — dados de novos empregados. Estrutura:

                                    {
    "name": "Steven Knight",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "john@example.com"
      }
    ]
}

onde:

• name — nome do funcionário
• position — cargo do empregado. Valores possíveis:
  • ceo — diretor-geral
  • director — diretor
  • manager — gestor
  • sales_manager — comercial
  • hr — RRHH
  • support — suporte
  • custom — outro
• position_title — nome do próprio cargo (para cargo = custom)
• comment — descrição do trabalhador
• phones — conjunto de números de telefone dos funcionários. Cada número contém os seguintes campos:
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do cliente. Cada contacto contém os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor de contacto

Remova o empregado por ID

Parâmetros de endereço

• c_id — identificador do cliente
• e_id — identificador do funcionário

Devolve a lista de leads

Parâmetros

• search (opcional) - barra de pesquisa. A pesquisa é efectuada de forma combinada por:
  • nome do contacto
  • número de telefone do contacto
  • descrição do contacto
  • endereço e código postal
  • site
  • endereço eletrónico
  • Mensagens
• filter (opcional) - filtro de leads. Estrutura do filtro:

(Resposta 1)

                                    Resposta 1:
{
    "source": "call_incoming",
    "responsible": 32,
    "label": 12,
    "utm": 19,
    "createdAfter": "2020-06-11 12:24:00",
    "createdBefore": "2020-06-26 12:24:00"
}

onde

• source — fonte do lead. Valores possíveis:
  • manual — adicionado manualmente
  • call_incoming — chamada recebida
  • call_outgoing — chamada efetuada
  • form — forma de contactar
• responsible — responsável (identificador do utilizador). O parâmetro permite símbolos especiais:
  • null — devolve todos os leads atribuídos
  • –1 — devolve os leads não geridos
  • –2 — devolve todos os contactos (atribuídos e não geridos)
• label — etiqueta (identificador)
• createdAfter — mostra apenas os contactos criados após o período selecionado (formato: YYYY-MM-DD hh:mm:ss)
• createdBefore — mostrar apenas os contactos criados até ao período selecionado (formato: YYYY-MM-DD hh:mm:ss)

Qualquer um dos parâmetros do filtro pode ser omitido, ou seja, é opcional.

• sort (opcional) - classificação dos leads. Estrutura dos parâmetros:

(Resposta 2)

                                    Resposta 2:
{
    "attr": "name",
    "desc": 0
}

onde

• attr — campo de classificação. Valores possíveis:
  • name — nome do lead
  • lead_source — fonte do lead
  • lead_status — estado do lead
  • responsible_user_id — utilizador responsável
  • lead_created_at — data de criação do contacto
• desc — sentido da classificação. Valores possíveis:
  • 0 — crescente
  • 1 — decrescente
  • take (para a amostra por página) - o número de contactos a devolver (predefinição: 20)
  • skip (para amostra por página) - quantos leads devem ser ignorados (predefinição 0)

Resposta

(Resposta 3)

                                    Resposta 3:
{
  "totalCount": 100,
  "uncategorizedCount": 10,
  "leads": [
    {
      "id": 3486,
      "name": "Good Company",
      "responsible_user_id": 234,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "lead_status": "not_processed",
      "lead_source": "manual",
      "lead_created_at": "2020-04-28 05:47:47",
      "lead_created_by": 234,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 22,
          "label": "Best clients"
        }
      ],
      "utms": [
        {
          "id": 19,
          "param": "utm_source",
          "value": "google",
          "display_value": "Google"
        }
      ]
    }
  ]
}

onde

• totalCount — total de contactos encontrados (incluindo contactos da barra de pesquisa e filtros)
• uncategorizedCount — total de contactos não geridos (tendo em conta a barra de pesquisa e os filtros)
• leads — conjunto de pistas (tendo em conta a amostra por página). Cada elemento do conjunto contém os seguintes parâmetros:
  • id — identificador do lead
  • name — nome do lead
  • responsible_user_id — responsável (identificador de utilizador)
  • employees_count — número total de empregados. Valores possíveis:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descrição do lead
  • country — país do lead. Código de dos letras (ES, US, etc.)
  • city — cidade do lead
  • address — endereço do lead
  • zip — código postal
  • website — página web do lead
  • lead_status — estado do lead. Valores possíveis:
    • not_processed — não processado
    • in_progress — em processo
    • finished — finalizado
  • lead_source — fonte do lead. Valores possíveis:
    • manual — manual
    • call_incoming — chamada recebida
    • call_outgoing — chamada efetuada
    • form — forma
  • lead_created_at — data e hora da criação do contacto (em formato YYYY-MM-DD HH:mm:ss)
  • lead_created_by — criador do contacto (identificador do utilizador)
  • phones — conjunto de números de telefone principais. Cada número contém os seguintes campos:
    • type — tipo de número. Valores possíveis:
      • work — de trabalho
      • personal — pessoal
    • phone — valor do número
  • contacts — conjunto de contactos do lead. Cada contacto deve conter os seguintes campos:
    • type — tipo de contacto. Valores possíveis:
      • email_work — e-mail de trabalho
      • email_personal — e-mail pessoal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto
  • labels — conjunto de etiquetas atribuídas ao contacto. Cada etiqueta contém os seguintes campos:
    • id — identificador da etiqueta
    • label — valor da etiqueta

Devolve o lead pelo seu ID

Resposta

                                    {
  "id": 3486,
  "name": "Good Company",
  "responsible_user_id": 234,
  "employees_count": "50",
  "comment": "",
  "country": "GB",
  "city": "London",
  "address": "",
  "zip": "",
  "website": "",
  "lead_status": "not_processed",
  "lead_source": "manual",
  "lead_created_at": "2020-04-28 05:47:47",
  "lead_created_by": 234,
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 22,
      "label": "Лучшие клиенты"
    }
  ],
  "utms": [
    {
      "id": 19,
      "param": "utm_source",
      "value": "google",
      "display_value": "Google"
    }
  ],
  "custom_properties": [
    {
      "id": 12,
      "key": "loyalty",
      "title": "Лояльность",
      "value": "high"
    }
  ]
}

onde

• id — identificador do lead
• name — nome do lead
• responsible_user_id — responsável (identificador do utilizador)
• employees_count — número de empregados. Valores possíveis:
  • 50 — inferior a 50
  • 50_250 — 50 – 250
  • 250_500 — 250 – 500
• comment — descrição do lead
• country — país do chefe de fila. Código de duas letras (ES, US, etc.)
• city — cidade do lead
• address — endereço do lead
• zip — código postal
• website — página web do lead
• lead_status — estado do lead. Valores possíveis:
  • not_processed — não processado
  • in_progress —em processo
  • finished — finalizado
• lead_source — fonte do lead. Valores possíveis:
  • manual — manual
  • call_incoming — chamada recebida
  • call_outgoing — chamada efetuada
  • form — forma
• lead_created_at — data e hora da criação do lead (no formato YYYY-MM-DD HH:mm:ss)
• lead_created_by — conjunto de números de telefone do lead. Cada número deve conter os seguintes campos:
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do cliente potencial. Cada contacto deve conter os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor de contacto
• labels — conjunto de etiquetas atribuídas ao lead. Cada etiqueta contém os seguintes campos:
  • id — identificador de etiqueta
  • label — valor de etiqueta

Criar um novo contacto com os dados indicados

Parâmetros

• convert — converter o contacto em cliente. Valores possíveis:
  • 0 — não converter, criar lead
  • 1 — criar cliente
  • 2 — inadequado (a transação será cancelada - nem o contacto nem o cliente serão criados)
• lead — novos dados do contacto. Estrutura do lead:

(Resposta 1)

                                    Resposta 1:
{
    "name": "Good Company",
    "responsible_user_id": 234,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "lead_status": "in_progress",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 22 },
      { "id": 23 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 12,
        "value": "high"
      }
    ]
}

onde

• name — nome de lead
• responsible_user_id — responsável (identificador de utilizador)
• employees_count — quantidade de empregados. Valores possíveis:
  • 50 — inferior a 50
  • 50_250 — 50 – 250
  • 250_500 — 250 – 500
• comment — descrição do lead
• country — país do lead. Código de dos letras (ES, US, etc.)
• city — cidade do lead
• address — endereço do lead
• zip — código postal
• website — site do lead
• lead_source — fonte do lead. Valores possíveis:
  • manual — manual
  • call_incoming — chamada recebida
  • call_outgoing — chamada efetuada
  • form — forma
• lead_status — estado do lead. Valores possíveis:
  • not_processed — não processado
  • in_progress — em processo
  • finished — finalizado
• phones — conjunto de números de telefone. Cada contacto deve conter os seguintes campos:
  • type — tipo de números. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do lead. Cada contacto deve conter os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor de contacto
• labels — conjunto de etiquetas atribuídas ao contacto. Cada etiqueta contém os seguintes campos:
  • id — identificador da etiqueta
  • custom_properties — conjunto de propriedades adicionais. Cada elemento deve conter:
    • id — identificador de propriedade adicional ou:
    • key — nome único da propriedade adicional
    • value — valor dos bens adicionais

Resposta

(Resposta 2)

                                    Resposta 2:
{
  "id": 123
}

onde

• id — identificador de chumbo criado

Atualizar o lead existente com o ID fornecido

Parâmetros

• convert — converter o contacto em cliente. Valores possíveis:
  • 0 — não converter
  • 1 — criar cliente
  • 2 — inadequado (eliminar o lead)
• lead — novos dados do lead. Estrutura do lead:

                                    {
    "name": "Good Company",
    "responsible_user_id": 234,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "lead_status": "in_progress",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 22 },
      { "id": 23 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 12,
        "value": "high"
      }
    ]
}

onde

• name — nome do lead
• responsible_user_id — responsável (identificador do utilizador)
• employees_count — quantidade de empregados. Valores possíveis:
  • 50 — inferior a 50
  • 50_250 — 50 – 250
  • 250_500 — 250 – 500
• comment — descrição do lead
• country — país do lead. Código de duas letras (ES, US, etc.)
• city — cidade do lead
• address — endereço do lead
• zip — código postal
• website — site do lead
• lead_source — fonte do lead. Valores possíveis:
  • manual — manual
  • call_incoming — chamada recebida
  • call_outgoing — chamada efetuada
  • form — forma
• lead_status — estado do lead. Valores possíveis:
  • not_processed — não processado
  • in_progress — em processo
  • finished — finalizado
• phones —conjunto de números de telefone. Cada contacto deve conter os seguintes campos:
  • type — tipo de números. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
  • phone — valor do número
• contacts — conjunto de contactos do lead. Cada contacto deve conter os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor de contacto
• labels — conjunto de etiquetas atribuídas ao contacto. Cada etiqueta contém os seguintes campos:
  • id — identificador da etiqueta
• custom_properties — conjunto de propriedades adicionais. Cada elemento deve conter:
  • id — identificador da propriedade adicional ou:
  • key — nome único da propriedade adicional
  • value — valor da propriedade adicional

Elimina o lead pelo seu ID

Devolve a lista de utilizadores

Resposta)

                                    {
  "totalCount": 2,
  "users": [
    {
      "id": 234,
      "email": "john@example.com",
      "name": "John Beam",
      "group_id": 653,
      "is_superadmin": 1,
      "enabled": 1,
      "created_at": "2020-04-27 01:01:31",
      "avatar": 2457,
      "role": "",
      "status": "",
      "language": "en",
      "color": "220",
      "color_hex": "5678BD",
      "internal_number": "100",
      "timezone": "Europe/London",
      "first_day": 1,
      "device": "webphone",
      "phone_widget_location": "right",
      "phones": [
        {
          "phone": "+44123456789",
          "type": "work"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "ivanov@example.com"
        }
      ]
    }
  ]
}

onde

• totalCount — total de utilizadores
• users — conjunto de utilizadores. Cada elemento do conjunto contém os seguintes parâmetros:
  • id — identificador do utilizador
  • email — e-mail da conta do utilizador
  • name — nome do utilizador
  • group_id — identificador de grupo de utilizador
  • is_superadmin — mostra se o utilizador é um super administrador (1 o 0)
  • enabled — se o utilizador está desbloqueado (1 o 0)
  • created_at — data e hora da criação do utilizador (no formato YYYY-MM-DD hh:mm:ss)
  • avatar — avatar do utilizador (identificador do arquivo)
  • role — cargo do utilizador
  • status — estado do utilizador
  • language — língua da interface do utilizador. Alternativas possíveis:
    • de — alemão
    • en — inglês
    • es — espanhol
    • pl — polaco
    • ru — russo
    • ua — ucraniano
  • color — cor do utilizador na interface Teamsale CRM (apenas valor de matiz - de 0 a 359)
  • color_hex —cor do utilizador na interface do Teamsale CRM (representação hex)
  • internal_number — extensão da central telefónica do utilizador
  • timezone — fuso horário do utilizador
  • first_day — determina que dia é o início da semana:
    • 0 — domingo
    • 1 — segunda-feira
  • device — o que utiliza para as chamadas. Valores possíveis:
    • webphone — telefone web
    • softphone — softphone externo
  • phone_widget_location — localização do widget do telemóvel web. Valores possíveis:
    • left — colocar o widget do telemóvel no lado esquerdo
    • right — colocar o widget do telemóvel no lado direito
  • phones — colocar o widget do telemóvel no lado direito
    • phone — valor de número
    • type — tipo de número. Valores possíveis:
      • work — de trabalho
      • personal — pessoal
  • contacts — conjunto de contactos do utilizador. Cada contacto contém os seguintes campos:
    • type — tipo de contacto. Valores possíveis:
      • email_work — e-mail de trabalho
      • email_personal — e-mail pessoal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto

Devolve o utilizador pelo seu ID

Resposta

                                    {
  "id": 234,
  "email": "john@example.com",
  "name": "John Beam",
  "group_id": 653,
  "is_superadmin": 1,
  "enabled": 1,
  "created_at": "2020-04-27 01:01:31",
  "avatar": 2457,
  "role": "",
  "status": "",
  "language": "en",
  "color": "220",
  "color_hex": "5678BD",
  "internal_number": "100",
  "timezone": "Europe/London",
  "first_day": 1,
  "device": "webphone",
  "phone_widget_location": "right",
  "phones": [
    {
      "phone": "+44123456789",
      "type": "work"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "simpson@example.com"
    }
  ],
  "pending_email_change_request": false
}

onde

• id — identificador de utilizador
• email — e-mail da conta do utilizador
• name — nome do utilizador
• group_id — identificador de grupo do utilizador
• is_superadmin — mostra se o utilizador é um super administrador (1 o 0)
• enabled — se o utilizador está desbloqueado (1 o 0)
• created_at — data e hora da criação do utilizador (em formato YYYY-MM-DD hh:mm:ss)
• avatar — avatar do utilizador (identificador de ficheiro)
• role — cargo do utilizador
• status — estado do utilizador
• language — idioma da interface do utilizador. Alternativas possíveis:
  • de — alemão
  • en — inglês
  • es — espanhol
  • pl — polaco
  • ru — russo
  • ua — ucraniano
• color — cor do utilizador na interface Teamsale CRM (apenas valor de matiz - de 0 a 359)
• color_hex — cor do utilizador na interface do Teamsale CRM (representação hex)
• internal_number — extensão da central telefónica do utilizador
• timezone — fuso horário do utilizador
• first_day — determina que dia é o início da semana:
  • 0 — domingo
  • 1 — Segunda-feira
• device — o que utiliza para as chamadas. Valores possíveis:
  • webphone — telefone web
  • softphone — softphone externo
• phone_widget_location — localização do widget do telemóvel web. Valores possíveis:
  • left — colocar o widget do telemóvel do lado esquerdo
  • right — colocar o widget do telemóvel do lado direito
• phones — conjunto de números de telefone do utilizador. Cada número contém os seguintes campos:
  • phone — valor do número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
• contacts — conjunto de contactos do utilizador. Cada contacto contém os seguintes campos:
  • type — tipo de contacto. Valores possíveis:
    • email_work — e-mail de trabalho
    • email_personal — e-mail pessoal
    • skype
    • telegram
    • viber
    • whatsapp
  • value — valor de contacto
• pending_email_change_request — se o pedido de alteração do correio eletrónico da conta tiver sido enviado mas ainda não tiver sido confirmado, este parâmetro será definido como verdadeiro

Devolve as horas de trabalho do utilizador

Resposta

                                    {
  "schedulePeriod": 7,
  "scheduleWorkingHours": [
    {
      "time_start": "2020-06-15 09:00:00",
      "time_end": "2020-06-15 18:00:00"
    }
  ],
  "scheduleFixes": [
    {
      "index": 2,
      "repeat_index": 1,
      "time_start": "2020-06-24 09:00:00",
      "time_end": "2020-06-24 13:00:00",
      "deleted": 0
    }
  ],
  "customWorkingHours": [
    {
      "time_start": "2020-06-27 11:00:00",
      "time_end": "2020-06-27 15:00:00"
    }
  ]
}

donde

• schedulePeriod — periodicidade do horário "como" se repete. Para a semana laboral normal são 7 dias, para horários "dia sim dia não" são dois dias e assim sucessivamente.
• scheduleWorkingHours — conjunto de períodos de trabalho. Cada período de trabalho contém os seguintes atributos:
  • time_start — início do dia de trabalho em formato YYYY-MM-DD hh:mm:ss
  • time_end — fim do horário de trabalho em YYYY-MM-DD hh:mm:ss
• scheduleFixes — conjunto de alterações efetuadas ao tempo de trabalho determinado no parâmetro scheduleWorkingHours. Cada elemento do conjunto contém os seguintes atributos:
  • index — índice do elemento no scheduleWorkingHours, ou seja, o período que foi alterado
  • repeat_index —taxa de repetição das horas de trabalho em que ocorre a mudança do horário de trabalho
  • time_start — novo início do horário de trabalho YYYY-MM-DD hh:mm:ss
  • time_end — novo fim do dia útil YYYY-MM-DD hh:mm:ss
  • deleted — se for igual a 1, o período de trabalho foi completamente eliminado
• customWorkingHours — conjunto de períodos de trabalho personalizados e únicos. Cada período de trabalho contém os seguintes atributos:
  • time_start — inicio do horário laboral YYYY-MM-DD hh:mm:ss
  • time_end — inicio do horário laboral YYYY-MM-DD hh:mm:ss

Devolve grupos e direitos de utilizador para cada grupo

Resposta

                                    {
  "totalCount": 4,
  "groups": [
    {
      "id": 45,
      "type": "manager",
      "title": "",
      "permissions": {
        "customers_create": true,
        "customers_edit": true,
        "customers_delete": true,
        "customers_import_export": true,
        "customers_view_all": false,
        "calendar_other_users_access": false,
        "calls_other_users_access": false,
        "leads_view": false,
        "leads_edit": false,
        "leads_delete": false,
        "leads_import_export": false,
        "team_add": false,
        "team_edit": false
      }
    }
  ]
}

onde

• totalCount — número total de grupos
• groups — conjunto de grupos. Cada grupo contém os seguintes atributos:
  • id — identificador de grupos
  • type — tipo de grupos. Valores possíveis:
    • admin — administradores
    • manager — agentes
    • chat_operator — operadores
    • trainee — estagiários
    • custom — personalizado
  • title — nome personalizado do grupo (paratype = custom)
  • permissions — direitos dos utilizadores do grupo. Os administradores têm acesso total, pelo que, para os administradores, este objeto permanecerá vazio. Todos os outros grupos contêm os seguintes atributos (cada um deles pode ser igual a true ou false):
    • customers_create — permitir a criação de clientes
    • customers_edit — permitir a edição de clientes
    • customers_delete — permitir eliminar clientes
    • customers_import_export — permitir a importação e exportação de clientes
    • customers_view_all — permitir a visualização de todos os clientes, incluindo os atribuídos a outros utilizadores
    • calendar_other_users_access — permitir a visualização das tarefas de outros utilizadores
    • calls_other_users_access — permitir o acesso às chamadas de outros utilizadores
    • leads_view — permitir ver os contactos de outros utilizadores
    • leads_edit — permitir a edição de leads de outros utilizadores
    • leads_delete — permitir a eliminação de leads de outros utilizadores
    • leads_import_export — permitir a importação e exportação de leads
    • team_add — para convidar e adicionar outros utilizadores ao grupo
    • team_edit — permitir editar utilizadores

Devolve a lista de todos os contactos (clientes, empregados, contactos potenciais, utilizadores) com números de telefone.

Parâmetros

• search (opcional) - barra de pesquisa. A pesquisa é realizada de forma combinada por:
  • aos nomes e números de clientes, leads, funcionários e usuários
  • as extensões dos utilizadores da central telefónica
• take (para a amostra por página) - quantos contatos devolver (por defeito 20)
• skip (para a amostra por página) - quantos contatos passar (por defeito 0)

Resposta

(Resposta 1)

                                    Resposta 1:
{
  "totalCount": 128,
  "contacts": [
    {
      "contact_type": "customer",
    },
    {
      "contact_type": "employee",
    },
    {
      "contact_type": "lead",
    },
    {
      "contact_type": "user",
    }
  ]
}

onde

• totalCount — número total de contactos (incluindo a barra de pesquisa)
• contacts — conjunto de contactos. Cada um dos contactos, dependendo do seu tipo (cliente, funcionário, lead, usuário), irá conter o seu próprio conjunto de atributos.

Cliente

(Resposta 2)

                                    Resposta 2:
{
    "contact_type": "customer",
    "id": 3486,
    "name": "Good Company",
    "status": "company",
    "type": "client",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "John Beam",
      "ext_num": "100"
    }
}

donde

• contact_type — tipo de contacto:
  • customer — cliente
• id — identificador do cliente
• name — nome do cliente
• status — estado do cliente. Valores possíveis:
  • individual — pessoa singular/li>
  • company — empresa
• type — tipo de cliente. Valores possíveis:
  • potential — cliente potencial
  • client — cliente
  • reseller — agente
  • partner — colaborador
• phone — número de telefone. Contem os seguintes campos:
  • phone — somente número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
• responsible — utilizador responsável. Contém os seguintes campos:
  • id — identificador de utilizador
  • name — nome do utilizador
  • ext_num — extensão da central telefónica virtual do utilizador

Funcionário do cliente

(Resposta 3)

                                    Resposta 3:
{
    "contact_type": "employee",
    "id": 8,
    "name": "Michael Simpson",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "position": {
      "position": "manager",
      "title": ""
    },
    "customer": {
      "id": 3486,
      "name": "Good Company"
    },
    "responsible": {
      "id": 234,
      "name": "John Beam",
      "ext_num": "100"
    }
}

onde

• contact_type — tipo de contacto:
  • employee — funcionário
• id — identificador do funcionário
• name — nome do funcionário
• phone — número de telefone. Contém os seguintes campos:
  • phone — somente o número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
• position — cargo do funcionário. Contém os seguintes campos:
  • position — valor do cargo. Valores possíveis:
    • ceo — diretor geral
    • director — diretor
    • manager — gestor
    • sales_manager — comercial
    • hr — RRHH
    • support — suporte
    • custom — outro
  • title — nome de outro cargo (paraposition = custom)
• customer — cliente atribuído ao funcionário. Contém os seguintes campos:
  • id — identificador do cliente
  • name — nome do cliente
  • responsible — utilizador responsável pelo cliente matriz. Contém os seguintes campos:
    • id — identificador do utilizador
    • name — nome do utilizador
    • ext_num — extensão da central telefónica do utilizador

Lead

(Resposta 4)

                                    Resposta 4:
{
    "contact_type": "lead",
    "id": 3486,
    "name": "Good Company",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "John Beam",
      "ext_num": "100"
    }
}

onde

• contact_type — tipo de contacto:
  • lead — lead
• id — identificador do lead
• name — nome do lead
• phone — número de telefone. Contém os seguintes campos:
  • phone — somente o número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
• responsible — utilizador responsável. Contém os seguintes campos:
  • id — identificador do utilizador
  • name — nome do utilizador
  • ext_num — extensão da central telefónica do utilizador

Utilizador

(Resposta 5)

                                    Resposta 5:
{
    "contact_type": "user",
    "id": 234,
    "name": "John Beam",
    "avatar": 2457,
    "role": "",
    "status": "",
    "phone": {
      "phone": "100",
      "type": "internal"
    },
    "group": {
      "type": "admin",
      "title": ""
    }
}

onde

• contact_type — tipo de contacto:
  • user — utilizador
• id — identificador do utilizador
• name — nome do utilizador
• avatar — avatar do utilizador (identificador do arquivo)
• role — função do utilizador
• status — estado do utilizador
• phone — número de telefone. Contém os seguintes campos:
  • phone — somente o número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
    • internal — extensão da central telefónica do utilizador
• group — grupo do utilizador Contém os seguintes campos.
  • type — tipo de grupo. Valores possíveis:
    • admin — administradores
    • manager — agentes
    • chat_operator — operadores
    • trainee — estagiários
    • custom — personalizado
  • title — nome dol grupo personalizado (para type = custom)

Identifica o contacto (cliente, empregado, lead, utilizador) por número de telefone

Parâmetros

• phone — número de telefone

Resposta

A resposta dependerá do tipo de contacto encontrado (cliente, empregado, lead, utilizador).

Cliente

(Resposta 1)

                                    Resposta 1:
{
  "contact_type": "customer",
  "id": 3486,
  "name": "Good Company",
  "status": "company",
  "type": "client",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "John Beam",
    "ext_num": "100"
  }
}

onde

• contact_type — tipo de contacto:
  • customer — cliente
• id — identificador de cliente
• name — nome de cliente
• status — estado de cliente. Valores possíveis:
  • individual — pessoa física
  • company — empresa
• type — tipo de cliente. Valores possíveis:
  • potential — cliente potencial
  • client — cliente
  • reseller — agente
  • partner — colaborador
• phone — número de telefone. Contém os seguintes campos:
  • phone — só número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
• responsible — utilizador responsável. Contém os seguintes campos:
  • id — identificador de utilizador
  • name — nome de utilizador
  • ext_num — extensão da central telefónica do utilizador

Empregado do cliente

(Resposta 2)

                                    Resposta 2:
{
  "contact_type": "employee",
  "id": 8,
  "name": "Michael Simpson",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "position": {
    "position": "manager",
    "title": ""
  },
  "customer": {
    "id": 3486,
    "name": "Good Company"
  },
  "responsible": {
    "id": 234,
    "name": "John Beam",
    "ext_num": "100"
  }
}

onde

• contact_type — tipo de contacto:
  • employee — empregado
• id — identificador de empregado
• name — nome de empregado
• phone — número de telefone. Contém os seguintes campos:
  • phone — só número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
• position — cargo do empregado. Contém os seguintes campos:
  • position — valor do cargo. Valores possíveis:
    • ceo — diretor geral
    • director — diretor
    • manager — agente
    • sales_manager — comercial
    • hr — RH
    • support — suporte
    • custom — outro
  • title — nome do cargo próprio (para position = custom)
• customer — cliente ao qual o empregado está vinculado. Contém os seguintes campos:
  • id — identificador de cliente
  • name — nome de cliente
• responsible — utilizador responsável pelo cliente matriz. Contém os seguintes campos:
  • id — identificador de utilizador
  • name — nome de utilizador
  • ext_num — extensão da central telefónica do utilizador

Lead

(Resposta 3)

                                    Resposta 3:
{
  "contact_type": "lead",
  "id": 3486,
  "name": "Good Company",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "John Beam",
    "ext_num": "100"
  }
}

onde

• contact_type — tipo de contacto:
  • lead — lead
• id — identificador de lead
• name — nome de lead
• phone — número de telefone. Contém os seguintes campos:
  • phone — só número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
• responsible — utilizador responsável. Contém os seguintes campos:
  • id — identificador de utilizador
  • name — nome de utilizador
  • ext_num — extensão da central telefónica do utilizador

Utilizador

(Resposta 4)

                                    Resposta 4:
{
  "contact_type": "user",
  "id": 234,
  "name": "John Beam",
  "avatar": 2457,
  "role": "",
  "status": "",
  "phone": {
    "phone": "100",
    "type": "internal"
  },
  "group": {
    "type": "admin",
    "title": ""
  }
}

onde

• contact_type — tipo de contacto:
  • user — utilizador
• id — identificador de utilizador
• name — nome de utilizador
• avatar — avatar de utilizador (identificador de ficheiro)
• role — papel de utilizador
• status — estado de utilizador
• phone — número de telefone. Contém os seguintes campos:
  • phone — só número
  • type — tipo de número. Valores possíveis:
    • work — de trabalho
    • personal — pessoal
    • internal — extensão da central telefónica do utilizador
• group — grupo de utilizador. Contém os seguintes campos:
  • type — tipo de grupo. Valores possíveis:
    • admin — administradores
    • manager — agentes
    • chat_operator — operadores
    • trainee — estagiários
    • custom — personalizado
  • title — nome de grupo personalizado (para type = custom)

Apresenta a lista de acordos

Parâmetros

• search (opcional) — linha de pesquisa. A pesquisa de acordos é efetuada por nome.

• filter (opcional) — filtro de acordo. Estrutura do filtro:

(Resposta 1)

                                    Resposta 1:
{
  "currency": "USD",
  "responsible_user": 20,
  "status": "new"
}

Onde:

• currency — moeda do acordo. Código de 3 dígitos ISO 4217: EUR, USD, etc.
• responsible_user — responsável (identificador de utilizador)

• status — estado do acordo. Valores possíveis:

  • new — novo acordo
  • in_progress — na gestão
  • decision — a aguardar a decisão
  • payment — a aguardar pelo pagamento
  • success — acordo bem sucedido
  • canceled — acordo cancelado

  Qualquer um dos parâmetros do filtro pode ser omitido, ou seja, é opcional.

• sort (opcional) — filtro de concordância. Estrutura dos parâmetros:

(Resposta 2)

                                    Resposta 2:
{
  "attr": "name",
  "desc": 0
}

Onde:

• attr — campo de filtro. Valores possíveis:
  • title — nome do acordo
  • budget — orçamento do acordo
  • status — estado do acordo
  • created_at — data de criação do acordo
• desc — tipo de filtro. Valores possíveis:
  • 0 — crescente
  • 1 — decrescente

• take (para pesquisa de páginas) - resultado a apresentar (predefinição 20)

• skip (para pesquisa por página) - resultado a ocultar (predefinição 0)

Resposta

(Resposta 3)

                                    Resposta 3:
{
  "totalCount": 82,
  "deals": [
    {
      "id": 83,
      "title": "Good deal",
      "budget": 990.00,
      "currency": "USD",
      "status": "new",
      "responsible_user": 20,
      "created_at": "2021-10-05 12:40:10",
      "created_by": 20,
      "customer_id": 65,
      "customer_is_lead": 0,
      "customer_name": "Good company",
      "customer_responsible_user": 20
    }
  ]
}

Donde:

• totalCount — total de acordos (com barra de pesquisa e filtro)
• deals — conjunto de acordos (tendo em conta o resultado por página). Cada elemento do conjunto contém os seguintes parâmetros:
  • id — identificador do acordo
  • title — nome do acordo
  • budget —orçamento do acordo
  • currency — moeda do acordo. Código ISO 4217 de três dígitos: EUR, USD, etc.
  • status — estado de acordo. Valores possíveis:
    • new — novo acordo
    • in_progress — em progresso
    • decision — no aguardo da decisão
    • payment —no aguardo do pagamento
    • success — acordo bem sucedido
    • canceled — acordo cancelado
  • responsible_user — responsável (identificador de utilizador)
  • created_at — data e hora do acordo (em formato YYYY-MM-DD HH:mm:ss)
  • created_by — criado por (identificador do utilizador)
  • customer_id — identificador do cliente relacionado com o acordo
  • customer_is_lead — sinalizador que indica se o cliente é um lead
  • customer_name — nome do cliente relacionado com o acordo
  • customer_responsible_user — responsável pelo cliente (identificador do utilizador)

Apresenta o acordo pelo seu ID

Parâmetros de endereço

• deal_id — identificador de acordo

Resposta

                                    {
  "id": 83,
  "title": "Good deal",
  "budget": 990.00,
  "currency": "USD",
  "status": "new",
  "responsible_user": 20,
  "created_at": "2021-10-05 12:40:10",
  "created_by": 20,
  "customer_id": 65,
  "customer_is_lead": 0,
  "customer_name": "Good company",
  "customer_responsible_user": 20
}

Onde:

• id — identificador do acordo
• title — nome do acordo
• budget — orçamento do acordo
• currency — moeda do acordo. Código de 3 dígitos ISO 4217: EUR, USD, etc.
• status — estado do acordo. Valores possíveis:
  • new — novo acordo
  • in_progress — em progresso
  • decision — no aguardo de toma da decisão
  • payment — no aguardo do pagamento
  • success — acordo bem sucedido
  • canceled — acordo cancelado
• responsible_user — responsável (identificador do utilizador)
• created_at — data e hora do acordo (em formato YYYY-MM-DD HH:mm:ss)
• created_by — criada por (identificador de utilizador)
• customer_id — identificador do cliente relacionado com o acordo
• customer_is_lead — sinalizador que indica se o cliente é um cliente potencial
• customer_name — nome do cliente relacionado com o acordo
• customer_responsible_user — responsável pelo cliente (identificador do utilizador)

Criar um novo contrato com os dados especificados

Parâmetros

• deal — dados do novo acordo. Estrutura do acordo:

(Resposta 1)

                                    Resposta 1:
{
  "title": "Good deal",
  "budget": 990.00,
  "currency": "USD",
  "status": "new",
  "responsible_user": 20,
  "customer_id": 65
}

Donde:

• title — nome do acordo
• budget — orçamento do acordo
• currency — moeda do acordo. Código de 3 dígitos ISO 4217: EUR, USD, etc.
• status — estado de acordo. Valores possíveis:
• new — novo acordo
• in_progress — em progresso
• decision — no aguardo da decisão
• payment — no aguardo do pagamento
• success — acordo bem sucedido
  • canceled — acordo cancelado
• responsible_user — responsável (identificador de utilizador)
• customer_id — identificador do cliente relacionado com o acordo

Resposta

(Resposta 2)

                                    Resposta 2:
{
  "id": 83
}

Donde:

• id — identificador do acordo criado

Actualize o acordo existente com o ID fornecido

Parâmetros de endereço

• deal_id — identificador de acordo

Parâmetros

• deal — novos pormenores do acordo. Estrutura do acordo:

                                    {
  "title": "Good deal",
  "budget": 990.00,
  "currency": "USD",
  "status": "new",
  "responsible_user": 20
}

Onde:

• title — nome do acordo
• budget — orçamento do acordo
• currency — moeda do acordo. Código ISO 4217 de três dígitos: EUR, USD, etc.
• status — estado do acordo. Valores possíveis:
  • new — novo acordo
  • in_progress — em progresso
  • decision — a aguardar a decisão
  • payment — a aguardar pelo pagamento
  • success — acordo bem sucedido
  • canceled — acordo cancelado
• responsible_user — responsável (identificador do utilizador)

Elimina a convenção pelo seu ID

Parâmetros de endereço

• deal_id — identificador de acordo

Devolve os registos no ficheiro do acordo

Parâmetros da direção

• deal_id — identificador do acordo

  Resposta

                                    {
  "totalCount": 17,
  "items": [
    {
      "id": 37825,
      "type": "note",
      "content": "Call to the client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "John Beam",
      "attached_files": [
        {
          "file_id": 576,
          "original_filename": "document.doc"
        }
      ]
    }
  ]
}

Onde:

• totalCount — número total de registros
• items — conjunto de registros. Cada registo contém os seguintes atributos:
  • id — identificador de registro
  • type — tipo de registro. Valores possíveis:
    • event — evento
    • note — nota de texto
  • content — conteúdo do registo. Se o tipo de entrada for uma nota, este atributo contém o conteúdo de texto da nota. Se o tipo de registo for um evento, este atributo contém o identificador do evento, por exemplo:
    • DEAL_CREATED — evento de criação de registo
    • DEAL_STATUS_CHANGED: success — evento de mudança de estado do acordo: o acordo de sucesso
  • time — hora de registro no formato YYYY-MM-DD hh:mm:ss
  • user_id — id do utilizador criador do registo
  • user_name — nome do utilizador criador do registo
  • attached_files — conjunto de ficheiros anexados a uma nota (se o tipo de entrada for uma nota). Cada elemento do conjunto contém os seguintes atributos:
    • file_id — identificador do ficheiro
    • original_filename — nome original do ficheiro

Adiciona uma nota de texto no ficheiro do acordo com a possibilidade de anexar ficheiros

Parâmetros de endereço

• deal_id — identificador do acordo

Parámetros

• content — conteúdo no texto da nota
• files — conjunto de anexos

Resposta

                                    {
  "id": 37825,
  "type": "note",
  "content": "Call to the client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "John Beam",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "document.doc"
    }
  ]
}

Onde:

• id — identificador de registro
• type — tipo de registro. Neste caso igual:
  • note — nota de texto
• content — conteúdo em texto da nota
• time — hora de registro em formato YYYY-MM-DD hh:mm:ss
• user_id — identificador do utilizador criador do registo
• user_name — nome do utilizador criado do registro
• attached_files — conjunto de ficheiros anexados a uma nota (se o tipo de entrada for uma nota). Cada elemento do conjunto contém os seguintes atributos:
  • file_id — identificador do arquivo
  • original_filename — nome original do arquivo

Atualize o conteúdo de uma nota de texto existente pelo seu ID

Parâmetros de endereço

• deal_id — identificador do acordo
• i_id — identificador da nota

Parâmetros

• content — novo texto da nota

Atualize a nota no ficheiro de acordo com o seu ID

Parâmetros de endereço

• deal_id — identificador de acordo
• i_id — identificador da nota

Devolve a lista de tarefas

Parâmetros

• search (opcional) — barra de pesquisa. A pesquisa é efectuada de forma combinada por:
  • nome das tarefas
  • descrição das tarefas
  • comentários sobre tarefas terminadas
• filter (opcional) - filtro de tarefas. Estrutura do filtro:

(Resposta 1)

                                    Resposta 1:
{
    "responsible": 456,
    "createdBy": 456,
    "start": "2020-06-03 02:56:00",
    "end": "2020-06-12 02:56:00",
    "completed": 1
}

onde:

• responsible — responsável (identificador do utilizador)
• createdBy — criado por (identificador do utilizador)
• start — apresenta as tarefas iniciadas após o período selecionado (em formato YYYY-MM-DD hh:mm:ss)
• end — apresenta as tarefas iniciadas antes do período selecionado (em formato YYYY-MM-DD hh:mm:ss)
• completed — selecione 1 para ver também as tarefas concluídas

• sort (opcional) - classificação das tarefas. Estrutura do parâmetro: (Resposta 2)

                                      Resposta 2:
  {
      "attr": "start",
      "desc": 0
  }

onde:

• attr — campo de classificação. Valores possíveis:
  • responsible — utilizador responsável
  • title — nome da tarefa
  • start — hora de início da tarefa
  • end — hora d o fim da tarefa
• desc — sentido da classificação. Valores possíveis:
  • 0 — crescente
  • 1 — decrescente

Resposta

(Resposta 3)

                                    Resposta 3:
{
  "totalCount": 4,
  "events": [
    {
      "id": 40,
      "type": "task",
      "title": "Create text for Good Company",
      "description": "",
      "start": "2020-05-26 09:00:00",
      "end": "2020-05-26 12:30:00",
      "allDay": false,
      "created_by": 234,
      "responsible_user": 234,
      "phone": "",
      "call_done": 0,
      "completed": 0,
      "completed_comment": "",
      "members": [234, 235],
      "customers": [
        {
          "id": 3486,
          "name": "Good Company",
          "status": "company",
          "type": "client",
          "lead_source": "manual",
          "lead_status": "not_processed",
          "contact_type": "customer"
        }
      ]
    }
  ]
}

onde

• totalCount — número total de tarefas
• events — conjunto de tarefas. Cada tarefa contém os seguintes atributos:
  • id — identificador da tarefa
  • type — tipo de tarefa. Valores possíveis:
    • task — tarefa
    • call — chamada
  • title — nome da tarefa
  • description — descrição da tarefa (em formato Quill Delta)
  • start — data e hora de início da tarefa (em formato YYYY-MM-DD hh:mm:ss)
  • end — data e hora de fim da tarefa (em formato YYYY-MM-DD hh:mm:ss)
  • allDay — tarefa para todo o dia (true ou false) — a data é determinada pelo parâmetro start
  • created_by — identificador do utilizador que criou a tarefa
  • responsible_user — identificador do utilizador responsável pela tarefa
  • phone — número de telefone para a chamada (se o tipo de tarefa for chamada)
  • call_done — mostra se a chamada foi efetuada
  • completed — mostra que a tarefa está marcada como concluída.
  • completed_comment — comentário sobre a tarefa concluída
  • members — conjunto de participantes na tarefa (apenas identificadores de utilizadores)
  • customers — conjunto de clientes e leads ligados à tarefa. Cada elemento do conjunto contém os seguintes campos:
    • id — identificador do cliente / lead
    • name — nome do cliente / lead
    • status — estado de cliente. Valores possíveis:
      • individual — pessoa singular
      • company — empresa
  • type — tipo de cliente. Valores possíveis:
    • potential — cliente potencial
    • client — cliente
    • reseller — revendedor
    • partner — sócio
  • lead_source — fonte do lead. Valores possíveis:
    • manual — manual
    • call_incoming — chamada recebida
    • call_outgoing — chamada efetuada
    • form — forma
  • lead_status — estado do lead. Valores possíveis:
    • not_processed — não processado
    • in_progress — em processo
    • finished — finalizado
  • contact_type — tipo de contacto. Valores possíveis:
    • customer — cliente
    • lead — lead

Devolve a tarefa pelo seu ID

Resposta

                                    {
  "id": 40,
  "type": "task",
  "title": "Create text for Good Company",
  "description": "",
  "start": "2020-05-26 09:00:00",
  "end": "2020-05-26 12:30:00",
  "allDay": false,
  "created_by": 234,
  "responsible_user": 234,
  "phone": "",
  "call_done": 0,
  "completed": 0,
  "completed_comment": "",
  "members": [234, 235],
  "customers": [
    {
      "id": 3486,
      "name": "Good Company",
      "status": "company",
      "type": "client",
      "lead_source": "manual",
      "lead_status": "not_processed",
      "contact_type": "customer"
    }
  ]
}

onde

• id — identificador da tarefa
• type — tipo de tarefa. Valores possíveis:
  • task — tarefa
  • call — chamada
• title — nome da tarefa
• description —descrição da tarefa (em formato Quill Delta)
• start — data e hora de início da tarefa (em formato YYYY-MM-DD hh:mm:ss)
• end — data e hora de fim da tarefa (em formato YYYY-MM-DD hh:mm:ss)
• allDay — tarefa para todo o dia (true ou false)
• created_by — identificador de utilizador do criador da tarefa
• responsible_user — identificador do utilizador responsável pela tarefa
• phone — número de telefone para a chamada (se o tipo de tarefa for chamada)
• call_done — mostra se a chamada foi efetuada
• completed — mostra que a tarefa está marcada como concluída.
• completed_comment — comentário sobre a tarefa concluída
• members — conjunto de participantes na tarefa (apenas identificadores de utilizador)
• customers — conjunto de clientes e leads ligados à tarefa. Cada elemento do conjunto contém os seguintes campos:
  • id — identificador do lead / cliente
  • name — nome do lead / cliente
  • status — estado do cliente. Valores possíveis:
    • individual — pessoa singular
    • company — empresa
  • type — tipo de cliente. Valores possíveis:
    • potential — cliente potencial
    • client — cliente
    • reseller — revendedor
    • partner — sócio
  • lead_source — fonte do lead. Valores possíveis:
    • manual — manual
    • call_incoming — chamada recebida
    • call_outgoing — chamada efetuada
    • form — forma
  • lead_status — estado do lead. Valores possíveis:
    • not_processed — não processado
    • in_progress — em processo
    • finished — finalizado
  • contact_type — tipo de contacto. Valores possíveis:
    • customer — cliente
    • lead — lead

Criar uma nova tarefa com os dados indicados

Parâmetros

• event — dados da nova tarefa. Estrutura:

(Resposta 1)

                                    Resposta 1:
{
    "type": "task",
    "title": "Create text for Good Company",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

onde

• type — tipo de tarefa. Valores possíveis:
  • task — tarefa
  • call — chamada
• title — nome da tarefa
• description — descrição da tarefa (em formato Quill Delta)
• start — data e hora de início da tarefa (em formato YYYY-MM-DD hh:mm:ss)
• end — data e hora de fim da tarefa (em formato YYYY-MM-DD hh:mm:ss)
• allDay — tarefa para todo o dia (true ou false)
• responsible_user — identificador do utilizador responsável pela tarefa
• phone — número de telefone para a chamada (se o tipo de tarefa for chamada)
• members — conjunto de participantes na tarefa (apenas identificadores de utilizador)
• customers — conjunto de clientes e contactos ligados à tarefa (apenas identificadores de clientes e leads)

Resposta

(Resposta 2)

                                    Resposta 2:
{
  "id": 7216
}

onde

• id — identificador da tarefa criada

Actualiza a tarefa existente com o ID fornecido

Parâmetros

• event — novos dados da tarefa. Estrutura:

                                    {
    "title": "Create text for Good Company",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "created_by": 234,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

onde

• title — nome da tarefa
• description — descrição da tarefa (em formato Quill Delta)
• start — data e hora de início da tarefa (em formato YYYY-MM-DD hh:mm:ss)
• end — data e hora do fim da tarefa (em formato YYYY-MM-DD hh:mm:ss)
• allDay — tarefa para todo o dia (true ou false)
• responsible_user — identificador do utilizador responsável pela tarefa
• phone — número de telefone para a chamada (se o tipo de tarefa for chamada)
• members — conjunto de participantes na tarefa (apenas identificadores de utilizador)
• customers — conjunto de clientes e contactos ligados à tarefa (apenas identificadores de clientes e leads)

Conclui (fecha) a tarefa

Parâmetros

• comment (opcional) - comentário

Eliminar a tarefa pelo seu ID

Devolve a lista de chamadas

Parâmetros

• search (opcional) — barra de pesquisa. A pesquisa é efectuada de forma combinada por:
  • de número de telefone
  • número de contactos (clientes, empregados, contactos potenciais ou utilizadores)
• filter (opcional) — filtro de chamada. Estrutura do filtro:
• take (para amostra por página) - quantas chamadas devem ser devolvidas (predefinição: 20)
• skip (para amostra por página) - quantas chamadas devem ser ignoradas (predefinição 0)

(Resposta 1)

                                    Resposta 1:
{
    "user": 23,
    "type": "incoming",
    "status": "answer",
    "dateFrom": "2020-06-03 14:56:00",
    "dateTo": "2020-06-26 14:56:00"
}

onde

• user — utilizador (identificador)
• type — tipo de chamada. Valores possíveis:
  • incoming — chamada recebida
  • outgoing — chamada efetuada
• status — estado da chamada. Valores possíveis:
  • answer — chamada de sucesso
  • noanswer — sem resposta
  • cancel — cancelada
  • busy — ocupado
  • failed — falhou
• dateFrom — ver apenas as chamadas efetuadas após a hora selecionada (formato: YYYY-MM-DD hh:mm:ss)
• dateTo — ver apenas as chamadas efectuadas antes da hora selecionada (formato: YYYY-MM-DD hh:mm:ss)

Qualquer um dos parâmetros do filtro pode ser omitido, ou seja, é opcional..

• sort (opcional) — filtro de chamadas. Estrutura do parâmetro:

(Resposta 2)

                                    Resposta 2:
{
    "attr": "time",
    "desc": 0
}

onde

• attr — campo de ordenação. Valores possíveis:
  • phone — número de telefone
  • status — estado da chamada
  • duration —duração da chamada
  • time — hora de chamada
• desc — sentido de classificação. Valores possíveis:
  • 0 — crescente
  • 1 — descrente

Resposta

(Resposta 3)

                                    Resposta 3:
{
  "totalCount": 233,
  "calls": [
    {
      "id": 127,
      "type": "outgoing",
      "status": "answer",
      "phone": "+44123456789",
      "user_id": 179,
      "time": "2019-07-31 17:58:40",
      "duration": 9,
      "pbx_call_id": "out_807ghh1h7f09fa7a188dbf8a6998b1c9ghg4ij06",
      "record": 1,
      "record_url_till": "2020-07-24 20:08:10",
      "contact_type": "customer",
      "contact_name": "Good Company",
      "contact_customer_id": 3486,
      "contact_employee_id": null,
      "employee_customer_id": null,
      "contact_user_id": null,
      "is_lead": 1,
      "record_urls": [
        {
          "url": "https ://api.zadarma.com/v1/pbx/record/download/[...]/[...]/[...].mp3"
        }
      ]
    }
  ]
}

onde

• totalCount — número total de chamadas (incluindo barra de pesquisa e filtro)
• calls — conjunto de chamadas (tendo em conta a amostra por página). Cada elemento do conjunto contém os seguintes parâmetros:
  • id — identificador de chamada
  • type — tipo de chamada. Valores possíveis:
    • incoming — chamada recebida
    • outgoing — chamada efetuada
  • status — estado da chamada. Valores possíveis:
    • answer — chamada de êxito
    • noanswer — sem resposta
    • cancel — cancelada
    • busy — ocupado
    • failed — falhou
  • phone — número de telefone
  • user_id — utilizador que efetua ou recebe a chamada
  • time — hora da chamada em formato YYYY-MM-DD hh:mm:ss
  • duration — duração da chamada em segundos
  • pbx_call_id — identificação de chamadas na central telefónica Zadarma
  • record — se a gravação de chamadas estiver ativada
  • record_url_till — tempo durante o qual a gravação de chamadas funcionará
  • contact_type — tipo de contacto. Valores possíveis:
    • customer — cliente ou contacto (ver parâmetro is_lead)
    • employee — empregado do cliente
    • user — utilizadores
  • contact_name — nome de contacto
  • contact_customer_id — identificador do cliente o lead (se a chamada está vinculada ao cliente)
  • contact_employee_id — identificador do empregado (se a chamada estiver vinculada ao empregado)
  • employee_customer_id — identificador do cliente principal (se a chamada estiver relacionada com o empregado)
  • contact_user_id — identificador do utilizador (se a chamada estiver relacionada com o utilizador)
  • is_lead — mostra se a chamada está relacionada com o lead
  • record_urls — conjunto de registos de chamadas (pode estar em falta, uma vez que tem de ser explicitamente solicitado). Cada elemento do conjunto - objeto que contém o seguinte campo:
    • url — ligação para a gravação da chamada

Devolve o ficheiro pelo seu ID

início da chamada recebida na central telefónica virtual

Parâmetros que se enviam para o link para a notificação:

• event – evento (NOTIFY_START)
• call_start – hora de início da chamada;
• pbx_call_id – id da chamada;
• caller_id – número do chamador;
• called_did – número para o qual a chamada foi realizada.

Redação da assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

Para as solicitações NOTIFY_START e NOTIFY_IVR pode-se modificar "em tempo real" o cenário da chamada em curso, enviando como resposta uma das seguintes alternativas:

Reproduzir o arquivo:

(Resposta 1)

                                    Resposta 1:
{
    "redirect": ID,
    "return_timeout": TIMEOUT (необязательное)
}

onde,

• ivr_play – valor da coluna ID na lista de arquivos carregados/inseridos do arquivo requerido.

Reproduzir uma frase popular:

(Resposta 2)

                                    Resposta 2:
{
    "hangup": 1
}

onde,

• ivr_saypopular – número da frase na lista;

Reproduzir dígitos:

(Resposta 3)

                                    Resposta 3:
{
    "caller_name": NAME
}

Reproduzir o número (de acordo com as regras numéricas complexas):

(Resposta 4)

                                    Resposta 4:
{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

onde,

• language pode ter um dos seguintes valores: ru, ua, en, es, pl;

Se ivr_saydigits ou ivr_saynumber forem indicados, no próximo evento NOTIFY_IVR será adicionado o parâmetro: "ivr_saydigits": "COMPLETE" ou "ivr_saynumber": "COMPLETE"

Em cada uma das solicitações anteriores pode haver uma solicitação de entrada de dígitos da pessoa que chama:

(Resposta 5)

                                    Resposta 5:
{
    "ivr_play": "ID"
}

onde,

• timeout - tempo de espera para a entrada de dígitos em segundos;
• attempts - número de tentativas para a entrada de dígitos da pessoa que chama;
• maxdigits - número máximo de dígitos para a entrada;
• name - o nome que será retornado na resposta;
• default - ação se nenhum dígito for inserido (nota que para a reprodução da ação é necessário previamente reproduzir o arquivo com o comando ivr_play de acordo com o item 4 abaixo). Valores possíveis:
  • id do cenário de desvio (no formato 0-1, onde 0 é o menu de voz, 1 é o número do cenário);
  • menu da central telefónica virtual no formato 0-main, onde 0 é o id do menu;
  • extensão da central telefónica virtual (número de 3 dígitos);
  • hangup - terminar a chamada.

No próximo evento NOTIFY_IVR será indicado o parâmetro adicional:

(Resposta 6)

                                    Resposta 6:
{
    "ivr_saypopular": 1,
    "language": "en"
}

onde,

• name - nome indicado na resposta anterior;
• digits - dígitos inseridos pela pessoa que chama;
• default_behaviour - indicado se o usuário não pressionar nenhum botão e o comportamento padrão for acionado;

Transferir a chamada:

(Resposta 7)

                                    Resposta 7:
{
    "ivr_saydigits": "12",
    "language": "en"
}

onde,

• redirect - id do cenário de desvio (no formato 0-1, onde 0 é o número do menu de voz, 1 é o número do cenário); ou no formato 1 onde q é o cenário (número do menu de voz é 0 neste caso); ou menu da central telefónica virtual 0-main, onde 0 é o id do menu; ou extensão da central telefónica virtual (número de 3 dígitos); ou "blacklist" - neste caso a chamada será rejeitada com o tom de ocupado;
• return_timeout - Valores em segundos. Possíveis valores:
  • 0, a chamada não será devolvida ao menu;
  • >= 3 - duração da chamada antes de ser devolvida ao menu;
• rewrite_forward_number - desvio para o número de telefone. Parâmetro opcional, disponível apenas para uso conjunto com o parâmetro redirect. Necessário para a alteração em tempo real do número de desvio indicado nas configurações da extensão da central.

Finalizar a chamada:

(Resposta 8)

                                    Resposta 8:
{
    "ivr_saynumber": "123",
    "language": "en"
}

Em cada resposta pode ser indicado adicionalmente:

Estabelecer um nome para o número de entrada:

(Resposta 9)

                                    Resposta 9:
{
    "wait_dtmf": {
        "name": NAME,
        "digits": DIGITS,
        "default_behaviour": "1"
    }
}

onde,

• caller_name - nome do número.

Lista de frases populares:

• Bom dia
• Desvio de chamadas
• Chamada da web
• Bem-vindos
• Mensagem de teste
• Permaneça na linha
• Ligou fora do horário de expediente
• Todos os nossos operadores estão ocupados. O primeiro operador disponível atenderá.
• Insira o número de extensão do assinante
• Insira o número de extensão do operador
• Insira o número de extensão
• Por favor, permaneça à espera
• Insira o número de extensão ou espere para ser atendido por um operador
• Por favor, deixe a sua mensagem
• Deixe a sua mensagem após o sinal
• Por favor, ligue novamente durante o horário de expediente
• Obrigado por nos contactar
• Obrigado pela sua chamada
• Aguarde para ser atendido por um operador
• A sua chamada é muito importante para nós
• A chamada está a ser gravada
• No momento não estamos no escritório
• Retornaremos a sua chamada assim que possível.
• Estamos de folga.
• Olá!

início da chamada de entrada para a extensão da central telefónica virtual

Parâmetros que são enviados para o link de notificação

• event – evento (NOTIFY_INTERNAL)
• call_start – duração do inicio da chamada;
• pbx_call_id – id da chamada;
• caller_id – número do chamador;
• called_did – número para o qual a chamada é realizada;
• internal – (opcional) extensão.
• transfer_from – (opcional) o iniciador da transferência, extensão.
• transfer_type – (opcional) tipo de transferência.

Criar uma assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

chamada de retorno para um número interno ou externo

Parâmetros que se enviam ao link para a notificação:

• event – evento (NOTIFY_ANSWER)
• caller_id – número do chamador;
• destination – número para o qual se realiza a chamada;
• call_start – hora do início da chamada;
• pbx_call_id – ID da chamada;
• internal – (opcional) extensão.

Criar uma assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

fim da chamada recebida na extensão da central telefónica virtual

Parâmetros que se enviam para o link para a notificação:

• event – evento (NOTIFY_END)
• call_start – hora do início da chamada;
• pbx_call_id – id da chamada;
• caller_id – número do chamador;
• called_did – número para o qual a chamada é realizada;
• internal – (opcional) extensão;
• duration – duração em segundos;
• disposition – estado da chamada:
  • 'answered' – conversação,
  • 'busy' – ocupado,
  • 'cancel' - cancelado,
  • 'no answer' - sem resposta,
  • 'failed' - não foi possível,
  • 'no money' - sem saldo, limite excedido,
  • 'unallocated number' - o número não existe,
  • 'no limit' - limite excedido,
  • 'no day limit' - limite diário excedido,
  • 'line limit' - limite de linhas excedido,
  • 'no money, no limit' - limite excedido;
• last_internal – extensão, último participante da chamada (após a transferência ou captura da chamada);
• status_code – código do estado da chamada Q.931;
• is_recorded – 1 - existe gravação da chamada, 0 - não existe gravação;
• call_id_with_rec – id da chamada com gravação (recomendamos carregar o arquivo da gravação não antes de 40 segundos, pois é necessário tempo para guardar o arquivo).

Criar uma assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

início de chamadas de saída a partir da central telefónica virtual

Parâmetros que se enviam para o link para a notificação:

• event – evento (NOTIFY_OUT_START)
• call_start – hora do início da chamada;
• pbx_call_id – id da chamada;
• destination – número para o qual a chamada é realizada;
• caller_id – número estabelecido na extensão da central telefónica virtual ou na regra de definição com base no destino. Se o número não estiver estabelecido, será transmitido 0;
• internal – (opcional) número de extensão.

Criar uma assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['internal'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

fim das chamadas efectuadas a partir da central telefónica virtual

Parâmetros que se enviam para o link para a notificação:

• event – evento (NOTIFY_OUT_END)
• call_start – hora do início da chamada;
• pbx_call_id – id da chamada;
• caller_id – número estabelecido na extensão da central telefónica virtual ou na regra de definição com base no destino. Se o número não estiver estabelecido, será transmitido 0;
• destination – número para o qual a chamada é realizada;
• internal – (opcional) extensão;
• duration – duração em segundos;
• disposition – estado da chamada:
  • 'answered' – conversação,
  • 'busy' – ocupado,
  • 'cancel' - cancelado,
  • 'no answer' - sem resposta,
  • 'failed' - não foi possível,
  • 'no money' - sem saldo, limite excedido,
  • 'unallocated number' - o número não existe,
  • 'no limit' - limite excedido,
  • 'no day limit' - limite diário excedido,
  • 'line limit' - limite de linhas excedido,
  • 'no money, no limit' - limite excedido;
• status_code – código do estado da chamada Q.931;
• is_recorded – 1 - existe gravação da chamada, 0 - não existe gravação;
• call_id_with_rec – id da chamada com gravação (recomendamos carregar o arquivo da gravação não antes de 40 segundos após a notificação, pois é necessário tempo para guardar o arquivo).

Criar uma assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['internal'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

a gravação da chamada está pronta para ser descarregada

Parâmetros que se enviam para o link para a notificação:

• event – evento (NOTIFY_RECORD)
• call_id_with_rec – id único da chamada com gravação da conversa;
• pbx_call_id – ID permanente da chamada externa à central telefónica virtual (não muda ao passar por cenários, menu de voz, transferência, etc., é mostrado em estatísticas e notificações).

Criar uma assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET));

resposta do autor da chamada à ação atribuída

Parâmetros que se enviam para o link de notificações:

• event – evento (NOTIFY_IVR)
• call_start – hora de início da chamada;
• pbx_call_id – id da chamada;
• caller_id – número do chamador;
• called_did – número para o qual a chamada foi realizada.

Redação da assinatura de verificação para a notificação de chamadas recebidas, exemplo em PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

As possíveis respostas enviadas são semelhantes às respostas das solicitações NOTIFY_START.

relatório sobre a verificação dos números

Parâmetros enviados para o link de notificações:

• event – evento (NUMBER_LOOKUP)
• success – indicador de sucesso da validação;
• description – descrição do estado de conclusão da validação;
• result – dados do relatório;
  • number – número verificado;
  • mcc – prefixo móvel do país;
  • mnc – prefixo do operador móvel;
  • ported – indicador de transferência para outro operador;
  • roaming – indicador de estar em roaming;
  • error – estado do erro;
  • errorDescription – descrição do erro;
  • mccName – nome do país;
  • mncName – nome do operador;

Redação da assinatura de verificação:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

informações sobre chamadas para números conectados no rastreamento de chamadas

Enviado uma vez a cada 8 minutos se houver novas chamadas.

Parâmetros que se enviam para o link de notificação:

• event – evento (CALL_TRACKING)
• result - área
  • tracker - ID do tracker (pode ser encontrado na página onde o código é inserido);
  • start - hora de início da chamada;
  • duration - duração da chamada em segundos;
  • caller_id - número do chamador;
  • caller_did - número para o qual a chamada foi realizada;
  • country - (opcional) país de onde a chamada é realizada;
  • ga_id - (opcional, se no ajuste estiver indicado Id Google Analytics) id do visitante no Google Analytics;
  • url - endereço da página de onde a chamada foi realizada;
  • utm_source, utm_medium, utm_campaign, utm_term, utm_content - (opcional, se ao visitar o site foram indicadas as tags utm) tags utm através das quais o usuário chegou ao site pela última vez;
  • first_utm - (opcional, se na primeira visita ao site foram indicadas tags utm diferentes das indicadas na última visita) matriz com as tags utm mencionadas acima através das quais o usuário visitou o site pela primeira vez;
  • pbx_call_id – id da chamada (exceto as gratuitas);

Redação da assinatura de verificação:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

informações sobre SMS recebidos

Parâmetros que se enviam para o link de notificação:

• event – evento (SMS)
• result – área;
  • caller_id – número do remetente;
  • caller_did – número do destinatário;
  • text – texto da mensagem.

Redação da assinatura de verificação:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

resultado do reconhecimento de voz

Parâmetros a enviar para a ligação de notificação:

• event – evento (SPEECH_RECOGNITION)
• lang – idioma;
• call_id – id único de chamada, este id está indicado no nome do ficheiro com a gravação da chamada;
• pbx_call_id – ID de chamador externo permanente para a central telefónica virtual;
• result:
  • words - conjunto:
    • result - conjunto de palavras (conjunto):
      • s - hora de início da palavra
      • e - hora do fim da palavra
      • w - palavra
    • channel - número do canal
  • phrases - conjunto:
    • result - frase
    • channel - número do canal

                                    <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>

Para aumentar a segurança, recomendamos permitir o acesso ao teu link apenas a partir do endereço IP 185.45.152.42.

Além disso, caso tenhas solicitado a palavra-passe de acesso à API, em cada solicitação ao teu link, receberás um cabeçalho adicional "Signature", pelo qual também podes verificar a integridade, bem como a autenticidade dos dados.

Podes ver um exemplo de script no nosso repositório no GitHub.