Documentação da API do HubSoft!¶
Bem-vindo à documentação da API do HubSoft. Para utilizar a API é necessário que você tenha em mãos as seguintes informações: Endereço do Servidor, Client Secret, Client Id, Username e Password. Com esses dados em mãos, será possível fazer autenticação via oAuth2, para utilizar a API
Introdução¶
HubSoft é um sistema voltado para empresas de telecomunicação. A ideia de liberar a API do sistema, torna todos os processos de integração / comunicação mais dinâmicos, tornando as rotinas das empresas mais simples e ágeis.
Com intuito de sempre inovar, a API do HubSoft foi construída em cima das tecnologias mais recentes do mercado. A troca de mensagens com a API é feita através do HTTP (Hypertext Transfer Protocol) utilizando o estilo arquitetural REST (Representation State Transfer).
Exemplos:
https://example.com/produto/1234
Ao fazer uma chamada na rota acima utilizando o método GET, estaremos fazendo a consulta do produto de código 1234. Porém ao fazer a chamada na mesma rota, utilizando o método DELETE, estaremos enviando a instrução para que a API faça a remoção do produto 1234.
Dessa forma, todas as funções do CRUD estarão dipsoníveis pela API, através dos métodos:
- GET (Consultar)
- POST (Adicionar)
- PUT (Editar)
- DELETE (Apagar)
Autenticação da API¶
Necessário
Para autenticar na API, será necessário possuir os seguintes dados em mãos:
- client_id
- client_secret
- username
- password
- host
Para fazer a autenticação na API é necessário fazer uma requisição POST na rota:
https://endereco_do_servidor/oauth/token
Deverá ser enviado na requisição um JSON, com as seguintes informações:
{
"grant_type":"password",
"client_id":"3",
"client_secret":"ONe7Ns48Y30tB",
"username":"teste@teste.com",
"password":"1234"
}
O exemplo acima, possui alguns prarâmetros, que serão explicados abaixo:
- grant_type: Sempre deverá conter o valor «password»
- client_id: Será o client_id que a empresa e/ou equipe do HubSoft lhe enviar
- client_secret: Será o client_secret que a empresa e/ou equipe do HubSoft lhe enviar
- username: Será o nome de usuário do sistema (Sempre será um endereço de e-mail)
- password: Senha do usuário
O resultado da requisição da rota /oauth/token, será igual ao exemplo abaixo:
{
access_token:"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
expires_in:2592000
refresh_token:"def502007d459fb49e6b09071f127a0163714607233687eac066
token_type:"Bearer"
}
Nesse momento, você já possui todos os dados necessário para iniciar as chamadas na rota da API. Em todas as rotas da API, será necessário enviar o TOKEN que foi recebido na rota /oauth/token. O TOKEN que deve ser enviado, é formado pelo token_type + access_token, no caso do exemplo acima o token ficaria da seguinte forma:
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O
Exemplo de chamada em uma rota, enviando os dados do Token:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/teste -k
Aviso
IMPORTANTE: O token irá expirar conforme o tempo retornado no parametro expires_in.
Observação: O valor 2592000 é equivalente a 30 dias. Sugerimos que armazenem o token e reutilizem o mesmo, conforme for necessário. Será necessário gerar um novo token sempre que o mesmo expirar.
Observação 2: Caso o token ainda não tenha terminado o seu prazo de validade, porém a API retornar o código de status HTTP 401, significa que é necessário gerar um novo token, pois o mesmo pode ter sido cancelado / expirado manualmente através de algum usuário administrador do sistema (por exemplo, durante atualizações o sistema poderá invalidar todos os TOKENS, fazendo com que uma nova autenticação seja necessária)
Aviso
IMPORTANTE: Veja que o token foi enviado no HEADER da requisição HTTP. Conforme o exemplo acima, podemos observar que o token é enviado sempre no header Authorization. Caso o Token não esteja presente no header Authorization a API irá responder com o código HTTP 401 (Unauthorized), não permitindo a utilização da API.
Atendimento¶
Necessário
Para fazer requisições nos dados de atendimento, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de atendimentos, devem ser feitos na rota:
/api/v1/integracao/atendimento
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/atendimento
Abaixo estão todas as funções disponíveis do atendimento
Consulta (Todos os Atendimentos - Com Paginação)¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação).
As requisições de atendimentos, devem ser feitos na rota:
/api/v1/integracao/atendimento/paginado/{quantidade}?page={numero_pagina}
O parâmetro quantidade indica quantos itens serão retornados por página. E o parâmetro numero_pagina indica qual pagina será consultada na requisição
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/atendimento/paginado/10?page=1
POST
No método POST, irá consultar os dados dos atendimentos e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| data_inicio | Data de Cadastro Inicial | Sim |
| data_fim | Data de Cadastro Final | Sim |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| data_inicio | Valor no formato DateTime (YYYY-MM-DD) | Nenhum |
| data_fim | Valor no formato DateTime (YYYY-MM-DD) Obs: Maior ou igual data_inicio | Nenhum |
Exemplo de requisição POST na rota de atendimentos:
curl --request POST \
--url 'http://endereco_servidor/api/v1/integracao/atendimento/paginado/5?page=1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O \
--header 'Content-Type: application/json' \
--data '{
"data_inicio":"2021-04-10",
"data_fim":"2021-04-15"
}'
Retorno da requisição POST:
{
"status": "success",
"msg": "Dados consultados com sucesso",
"atendimentos": {
"current_page": 2,
"data": [
{
"id_atendimento": 2364,
"protocolo": "202104151321184",
"id_cliente_servico": 11883,
"id_tipo_atendimento": 132,
"id_usuario_abertura": 1129,
"id_usuario_fechamento": null,
"descricao_abertura": "ir no cliente com urgência",
"descricao_fechamento": null,
"data_cadastro": "2021-04-15 13:24:14",
"data_fechamento": null,
"ip_cadastro": "177.22.5.2",
"id_usuario_responsavel": null,
"id_setor_responsavel": null,
"destino": "usuario",
"status_fechamento": null,
"id_motivo_fechamento_atendimento": null,
"id_atendimento_status": 22,
"nome_contato": "JULIO CESAR ANANIAS",
"telefone_contato": "37988469145",
"email_contato": "naotem@naotem.com.br",
"rascunho": false,
"deleted_at": null,
"id_origem_contato": null,
"avaliacao": null,
"comentario_avaliacao": null,
"push_notification_enviado": false,
"ordem_servico_count": 1,
"anexos_count": 1,
"ingressado": false,
"data_cadastro_br": "15\/04\/2021 13:24",
"data_cadastro_timestamp": 1618503854000,
"data_fechamento_br": null,
"data_fechamento_timestamp": null,
"minutos_em_aberto": 5945,
"tempo_restante": "-98h 5min",
"percentual_tempo_restante": 0,
"percentual_color_class": "white-fg md-red-bg",
"status": {
"id_atendimento_status": 22,
"prefixo": "pendente",
"descricao": "Pendente",
"cor": "md-purple-900-bg",
"abrir_ordem_servico": true,
"display": "Pendente (Abertura de OS)"
},
"tipo_atendimento": {
"id_tipo_atendimento": 132,
"descricao": "FINANCEIRO"
},
"cliente_servico": {
"id_cliente_servico": 11883,
"id_cliente": 11357,
"id_servico": 1208,
"endereco_numero_completo": "RUA PEDRO F DE OLIVEIRA, 55, CH BARRETOS - BARRETOS, NOVA SERRANA\/MG | CEP: 35519-000",
"cliente": {
"id_cliente": 11357,
"ativo": true,
"codigo_cliente": 577,
"nome_razaosocial": "JULIO CESAR ANANIAS",
"display": "(577) JULIO CESAR ANANIAS"
}
},
"usuarios_responsaveis": []
},
{
"id_atendimento": 2362,
"protocolo": "202104150938230",
"id_cliente_servico": 15871,
"id_tipo_atendimento": 126,
"id_usuario_abertura": 1131,
"id_usuario_fechamento": null,
"descricao_abertura": "INSTALAR PONTO NOVO",
"descricao_fechamento": null,
"data_cadastro": "2021-04-15 09:38:23",
"data_fechamento": null,
"ip_cadastro": null,
"id_usuario_responsavel": null,
"id_setor_responsavel": null,
"destino": "usuario",
"status_fechamento": null,
"id_motivo_fechamento_atendimento": null,
"id_atendimento_status": 22,
"nome_contato": "GLEIDSON PEREIRA TORRES",
"telefone_contato": "83996555702",
"email_contato": "gleidson@alsol.com.br",
"rascunho": false,
"deleted_at": null,
"id_origem_contato": 2,
"avaliacao": null,
"comentario_avaliacao": null,
"push_notification_enviado": false,
"ordem_servico_count": 0,
"anexos_count": 0,
"ingressado": false,
"data_cadastro_br": "15\/04\/2021 09:38",
"data_cadastro_timestamp": 1618490303000,
"data_fechamento_br": null,
"data_fechamento_timestamp": null,
"minutos_em_aberto": 6171,
"tempo_restante": "-101h 51min",
"percentual_tempo_restante": 0,
"percentual_color_class": "white-fg md-red-bg",
"status": {
"id_atendimento_status": 22,
"prefixo": "pendente",
"descricao": "Pendente",
"cor": "md-purple-900-bg",
"abrir_ordem_servico": true,
"display": "Pendente (Abertura de OS)"
},
"tipo_atendimento": {
"id_tipo_atendimento": 126,
"descricao": "ATIVAÇÃO FIBRA ÓPTICA"
},
"cliente_servico": {
"id_cliente_servico": 15871,
"id_cliente": 24532,
"id_servico": 2610,
"endereco_numero_completo": "RUA ALZIRA PEREIRA DE MELO, 181, CASA VERMELHA(VIZINHO A MERCEARIA DA SAMARA) - JARDIM PLANALTO, CATOLÉ DO ROCHA\/PB | CEP: 58884-000",
"cliente": {
"id_cliente": 24532,
"ativo": true,
"codigo_cliente": 1679,
"nome_razaosocial": "GLEIDSON PEREIRA TORRES",
"display": "(1679) GLEIDSON PEREIRA TORRES"
}
},
"usuarios_responsaveis": [
{
"id": 1131,
"name": "Gleidson Torres",
"id_imagem_upload": null,
"pivot": {
"id_atendimento": 2362,
"id_usuario": 1131
},
"imagem": null
}
]
}
],
"first_page_url": "http:\/\/localhost:8000\/api\/v1\/integracao\/atendimento\/paginado\/2?page=1",
"from": 3,
"last_page": 5,
"last_page_url": "http:\/\/localhost:8000\/api\/v1\/integracao\/atendimento\/paginado\/2?page=5",
"next_page_url": "http:\/\/localhost:8000\/api\/v1\/integracao\/atendimento\/paginado\/2?page=3",
"path": "http:\/\/localhost:8000\/api\/v1\/integracao\/atendimento\/paginado\/2",
"per_page": 2,
"prev_page_url": "http:\/\/localhost:8000\/api\/v1\/integracao\/atendimento\/paginado\/2?page=1",
"to": 4,
"total": 10
},
"cliente": null
}
Novo Atendimento¶
Necessário
Para fazer requisições nos dados de atendimento, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de atendimento, devem ser feitos na rota:
/api/v1/integracao/atendimento
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/atendimento
POST
No método POST, será possível consultar os atendimentos em aberto/fechados dos clientes e obter o retorno no formato JSON como resposta. Os segintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_cliente_servico | Identificador do serviço do cliente | Sim |
| id_tipo_atendimento | Identificador do tipo de atendimento | Não |
| descricao | Descrição detalhada do atendimento | Sim |
| nome | Nome do solicitante | Sim |
| telefone | Telefone do solicitante | Sim |
| Email do solicitante | Não | |
| abrir_os | Indica se deve abrir Ordem de Serviço ou não | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_cliente_servico | Número Inteiro | Nenhum |
| id_tipo_atendimento | Número Inteiro | Nenhum |
| descricao | Campo Livre (Qualquer valor é aceito) | Nenhum |
| nome | Campo Livre (Qualquer valor é aceito) | Nenhum |
| telefone | Telefone no formato (DDNNNNNNNNN). | Nenhum |
| Caso enviado deve ser no formato e-mail (EX: user@dominio.com) | Nenhum | |
| abrir_os | Caso enviado, deve conter um valor boolean (true | false) | false |
Observação: Se o paramêtro id_tipo_atendimento não for enviado, o atendimento será aberto com o tipo padrão SAC.
Exemplo de requisição POST na rota de crição de novo atendimento:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/atendimento -d '{"id_cliente_servico":"11000", "descricao":"Abertura de atendimento de teste", "nome":"Nome do Usuário Solicitante", "telefone":"37999112233", "email":"teste@teste.com.br"}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_cliente_servico":"11000",
"descricao":"Abertura de atendimento de teste",
"nome":"Nome do Usuário Solicitante",
"telefone":"37999112233",
"email":"teste@teste.com.br",
"abrir_os":true
}
Retorno da requisição GET:
{
"status": "success",
"msg": "Atendimento aberto com sucesso. Anote o protocolo: 201811161058216. Foi aberto também uma ordem de serviço e encaminhada ao sertor responsável",
"atendimento": {
"id_atendimento": 300,
"protocolo": "201811161058216",
"descricao_abertura": "Estou sem acesso a internet desde segunda-feira. | ATENDIMENTO ABERTO VIA API",
"descricao_fechamento": null,
"tipo_atendimento": "SAC",
"usuario_abertura": "IP Telecom",
"usuario_responsavel": "IP Telecom",
"usuario_fechamento": null,
"data_cadastro": "16/11/2018",
"data_fechamento": null,
"setor_responsavel": null,
"status_fechamento": null,
"motivo_fechamento": null,
"status": "Aguardando Análise",
"cliente": {
"codigo_cliente": 1204,
"nome_razaosocial": "BIANCA COUTO",
"cpf_cnpj": "86214941081"
},
"ordens_servico": [
{
"id_ordem_servico": 340,
"numero_ordem_servico": "320",
"data_cadastro": "16/11/2018 10:58:21",
"tipo": "ABERTURA VIA API",
"data_inicio_programado": "16/11/2018 11:58:21",
"data_termino_programado": "16/11/2018 12:58:21",
"data_inicio_executado": null,
"data_termino_executado": null,
"descricao_abertura": "Estou sem acesso a internet desde segunda-feira. | ATENDIMENTO ABERTO VIA API",
"descricao_servico": "Estou sem acesso a internet desde segunda-feira. | ATENDIMENTO ABERTO VIA API",
"descricao_fechamento": null,
"usuario_abertura": "IP Telecom",
"usuario_fechamento": null,
"status": "aguardando_agendamento",
"status_fechamento": null,
"cliente": {
"codigo_cliente": 1204,
"nome_razaosocial": "BIANCA COUTO",
"cpf_cnpj": "86214941081"
},
"servico": {
"numero_plano": 9,
"nome": "NEXT-NV_1MBPS",
"valor": 69.9,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado"
}
}
]
}
}
Nota
OBSERVAÇÃO: O JSON de resposta da requisição acima, contém dados de ordem de serviço, pois na requisição o atributo (abrir_os) foi enviado como true. Sendo assim, o setor técnico do provedor de internet, vai receber essa ordem de serviço para ser executada em campo pelo técnico responsável.
Editar Atendimento¶
Necessário
Para fazer requisições nos dados de atendimento, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de atendimento, devem ser feitos na rota:
/api/v1/integracao/atendimento
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/atendimento/{id_atendimento}
PUT
No método PUT, será possível editar e fechar os atendimentos em abertos dos clientes e obter o retorno no formato JSON como resposta. Lembre de enviar o ID do atendimento como um parametro na URL, conforme o exemplo acima. Os segintes parâmetros podem/devem estar presentes no corpo do requisição:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| descricao | Descrição de abertura do atendimento (Opcional) | Não |
| fechar_atendimento | Indica se deve ser fechado os atendimento e suas ordens de serviço | Sim |
| parametros | Objeto JSON que poderá conter qualquer informação da integração | Sim |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| descricao | Texto | Nenhum |
| fechar_atendimento | Boolean ( Verdadeiro ou Falso ) | false |
| parametros | Array Associativo, JSON | Nenhum |
Exemplo de requisição PUT na rota de edição do atendimento:
curl -X PUT
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/atendimento/1 -d '{"parametros": { "url_ligacao": "https://www.meusite.com.br/ligacao/3", "empresa": "NeWave", "xpto": 123456 }, "fechar_atendimento": true }' -k
Veja que os paramêtros enviados na requisição PUT devem obedecer a estrutura no formato JSON:
{
"parametros": {
"url_ligacao": "https://www.meusite.com.br/ligacao/3",
"empresa": "NeWave",
"xpto": 123456
},
"fechar_atendimento": true
}
Retorno da requisição PUT:
{
"status": "success",
"msg": "Atendimento atualizado com sucesso",
"atendimento": {
"id_atendimento": 1114,
"protocolo": "202003051452007",
"id_cliente_servico": 13677,
"id_tipo_atendimento": 44,
"id_usuario_abertura": 56,
"id_usuario_fechamento": 1,
"descricao_abertura": "INSTALAÇÃO NOVA",
"descricao_fechamento": "Fechamento automático.",
"data_cadastro": "2020-03-05 14:52:00",
"data_fechamento": "2020-03-11 09:56:10",
"ip_cadastro": null,
"id_usuario_responsavel": 22,
"id_setor_responsavel": null,
"destino": "usuario",
"status_fechamento": "concluido",
"id_motivo_fechamento_atendimento": 5,
"id_atendimento_status": 24,
"resultado_diagnostico": null,
"nome_contato": "TESTE APRESENT",
"telefone_contato": "3734151100",
"email_contato": null,
"rascunho": false,
"deleted_at": null,
"id_origem_contato": null,
"avaliacao": null,
"comentario_avaliacao": null,
"push_notification_enviado": false,
"data_cadastro_br": "05\/03\/2020 14:52",
"data_cadastro_timestamp": 1583430720000,
"data_fechamento_br": "11\/03\/2020 09:56",
"data_fechamento_timestamp": 1583931370000,
"minutos_em_aberto": 8344,
"tempo_restante": "-138h 4min",
"percentual_tempo_restante": 0,
"percentual_color_class": "white-fg md-red-bg"
}
}
Cidade¶
Necessário
Para fazer requisições nos dados de endereços, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de endereçø, devem ser feitos na rota:
/api/v1/integracao/cidade
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cidade
Abaixo estão todas as funções disponíveis das rotas de endereço
All (Todas as Cidades)¶
Necessário
Para fazer requisições nos dados da API, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de REDE, devem ser feitos na rota:
/api/v1/integracao/configuracao/cidade
O endereço completo da requisição, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/configuracao/cidade
GET
No método GET, será possível consultar as cidades e seus bairros que estão cadastrados no sistema:
Exemplo de requisição GET na rota de Cidades:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/endereco/cidade -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso.",
"cidades": [
{
"id_cidade": 1393,
"nome": "Araújos",
"uf": "MG",
"ibge": "3103900",
"bairros": [
{
"nome": "ANTONIA DE LURDES"
},
{
"nome": "BEIRA RIO"
},
{
"nome": "BELA VISTA"
},
{
"nome": "CENTRO"
},
{
"nome": "CHIQUINHO PERCILIA"
},
{
"nome": "CIDADE NOVA"
},
{
"nome": "CIDADE NOVO"
},
{
"nome": "DOM CABRAL"
},
{
"nome": "ESTEVES"
},
{
"nome": "ESTIVA"
},
{
"nome": "FREDERICO OZANAN"
},
{
"nome": "GERALDO FIRMINO"
},
{
"nome": "JOAO ALONSO"
},
{
"nome": "JUCA FIRMINO"
},
{
"nome": "OLAVO DA AZ"
},
{
"nome": "OLAVO DA PAZ"
},
{
"nome": "RESIDENCIAL OLAVO ALVES DA PAZ"
},
{
"nome": "SANTO AGOSTINHO"
},
{
"nome": "SANTO ANTÔNIO"
},
{
"nome": "SOLAR"
}
]
},
{
"id_cidade": 1406,
"nome": "Bambuí",
"uf": "MG",
"ibge": "3105103",
"bairros": [
{
"nome": "CENTRO"
},
{
"nome": "JARDIM AMERICA"
}
]
},
{
"id_cidade": 1416,
"nome": "Belo Horizonte",
"uf": "MG",
"ibge": "3106200",
"bairros": [
{
"nome": "LOURDES"
},
{
"nome": "OURO PRETO"
},
{
"nome": "PALMEIRAS"
}
]
}
]
}
Nota
OBSERVAÇÃO: Apenas as cidades e bairros que possuem clientes ativos, serão retornadas na requisição da API, uma vez que o sistema conta com o cadastro atualizado de todas as cidades do Brasil.
Clientes¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente
Abaixo estão todas as funções disponíveis do cliente
All (Todos os Clientes)¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação). OBS: Essa rota irá retornar todos os dados de clientes, caso nenhum parâmetro seja enviado. Utilize com cautela.
Aviso
IMPORTANTE: Por se tratar de uma requisição que poderá trazer uma quantidade muito grande dados, o sistema irá armazenar o resultado da requisição em um Cache. Portanto, em chamadas consecutivas em curtos intervalos de tempo dessa rota, o sistema irá retornar o mesmo resultado. Recomendamos o uso dessa API poucas vezes ao dia (EX: 1 vez de madrugada e outra na parte da tarde por exemplo). Chamadas consecutivas nessa API pode parar seu sistema.
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente/all
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/all
GET
No método GET, irá consultar os dados dos clientes e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| data_inicio | Data de Cadastro Inicial | Não |
| data_fim | Data de Cadastro Final | Não |
| cancelado | Retornar serviços cancelados | Não |
| ultima_conexao | Informa se deseja trazer os dados da última conexão | Não |
| codigo_pacote | Retorna apenas os clientes que contém pacotes com o código especificado | Não |
| relacoes | Carrega apenas os relacionamentos especificados | Não |
| limit | Limite de resultados | Não |
| offset | Deslocamento em relação ao limite de dados | Não |
| order_by | Campo que será utilizado para ordenação | Não |
| order_type | Tipo de Ordenação | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| data_inicio | Valor no formato DateTime (YYYY-MM-DD) | Nenhum |
| data_fim | Valor no formato DateTime (YYYY-MM-DD) Obs: Maior ou igual data_inicio | Nenhum |
| cancelado | sim,nao | nao |
| ultima_conexao | sim,nao | nao |
| codigo_pacote | Valor no formato string | Nenhum |
| relacoes | endereco_instalacao,endereco_cadastral,endereco_cobranca,endereco_fiscal,pacotes,interface,interface_roteamento,equipamento_conexao,equipamento_roteamento,grupos,porta_atendimento,senhas,status_conexao | Nenhum |
| limit | Número Inteiro maior que 0 | Nenhum |
| offset | Número Inteiro maior que 0 | Nenhum |
| order_by | data_cadastro,data_fechamento | data_cadastro |
| order_type | asc,desc | asc |
Exemplo de requisição GET na rota de cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/all -k
Retorno da requisição GET:
{
"status":"success",
"msg":"Dados consultados com sucesso",
"clientes":[
{
"id_cliente":11201,
"codigo_cliente":421,
"nome_razaosocial":"GUILHERME SILVA",
"nome_fantasia":null,
"tipo_pessoa":"pf",
"cpf_cnpj":"10682083681",
"telefone_primario":"37988242968",
"telefone_secundario":"37988242968",
"telefone_terciario":"",
"email_principal":"guilherme@silva.com.br",
"email_secundario":null,
"rg":"MG16999888",
"rg_emissao":null,
"inscricao_municipal":null,
"inscricao_estadual":null,
"data_cadastro":"2017-08-05 00:00:00",
"data_nascmento":"1969-12-31 04:00:00",
"servicos":[
{
"id_cliente_servico":11201,
"id_servico":100,
"numero_plano":1,
"nome":"4M",
"valor":119.9,
"status":"Serviço Habilitado",
"status_prefixo":"servico_habilitado",
"tecnologia":"WIRELESS",
"login":"guilhermesilva1068",
"senha":"123",
"ipv4":"10.99.2.203",
"ipv6":null,
"interface":{
"nome":"PON5",
"tipo":"gpon",
"called_sid":null
},
"interface_roteamento":{
"nome":"ether8",
"tipo":"ethernet",
"called_sid":null
},
"equipamento_conexao":{
"nome":"OLT XPTO",
"ipv4":"192.168.2.100",
"ipv6":null
},
"equipamento_roteamento":{
"nome":"CONCENTRADOR XPTO",
"ipv4":"172.17.24.98",
"ipv6":null
},
"pacotes":[
{
"id_pacote": 1,
"codigo":"meu_codigo_personalizado_1",
"descricao": "IP FIXO",
"valor": "20",
"observacoes": "IP FIXO 189.79.21.21",
"data_cadastro": "2019-11-21 16:43:56"
},
{
"id_pacote": 2,
"codigo":"meu_codigo_personalizado_2",
"descricao": "TV",
"valor": "20",
"observacoes": "ASSINATURA DE TV",
"data_cadastro": "2019-11-20 16:43:56"
}
],
"senhas": [
{
"id_cliente_servico_senha": 6,
"descricao": "Teste",
"usuario": "xpto123",
"senha": "abc123"
}
],
"endereco_cadastral":{
"completo":"RUA DONA MARIA DAS DORES, 541 - NOSSA SENHORA DAS GRACAS, DIVINóPOLIS/MG - IGREJA",
"logradouro":"RUA",
"endereco":"DONA MARIA DAS DORES",
"numero":"541",
"complemento":"IGREJA",
"bairro":"NOSSA SENHORA DAS GRACAS",
"cep":"35501-048",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_instalacao":{
"completo":"RUA MINAS GERAIS, 1793 - IPIRANGA, DIVINÓPOLIS/MG",
"logradouro":"RUA",
"endereco":"MINAS GERAIS",
"numero":"1793",
"complemento":"",
"bairro":"IPIRANGA",
"cep":"35502-026",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": -20.086592,
"longitude": -45.290962
}
},
"endereco_fiscal":{
"completo":"RUA GOIAS, 86 - PORTO VELHO, DIVINÓPOLIS/MG - APTO 101",
"logradouro":"RUA",
"endereco":"GOIAS",
"numero":"86",
"complemento":"APTO 101",
"bairro":"PORTO VELHO",
"cep":"35500-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_cobranca":{
"completo":"RUA SEBASTIAO PARDINI, 58 - CENTRO, DIVINÓPOLIS/MG - 202",
"logradouro":"RUA",
"endereco":"SEBASTIAO PARDINI",
"numero":"58",
"complemento":"202",
"bairro":"CENTRO",
"cep":"35500-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": null,
"longitude": null
}
}
}
]
},
{
"id_cliente":11202,
"codigo_cliente":422,
"nome_razaosocial":"GUILHERME COSTA",
"nome_fantasia":null,
"tipo_pessoa":"pf",
"cpf_cnpj":"05333614622",
"telefone_primario":"37999450812",
"telefone_secundario":"37999452812",
"telefone_terciario":"",
"email_principal":null,
"email_secundario":null,
"rg":"MG11298180",
"rg_emissao":null,
"inscricao_municipal":null,
"inscricao_estadual":null,
"data_cadastro":"2017-04-26 00:00:00",
"data_nascmento":"1969-12-31 00:00:00",
"servicos":[
{
"id_cliente_servico":11302,
"id_servico":1023,
"numero_plano":2,
"nome":"24M",
"valor":119.9,
"status":"Serviço Habilitado",
"status_prefixo":"servico_habilitado",
"tecnologia":"FIBRA",
"login":"guilhermesouza0533",
"senha":"123",
"ipv4":"10.99.1.118",
"ipv6":null,
"interface":{
"nome":"PON5",
"tipo":"gpon",
"called_sid":null
},
"interface_roteamento":{
"nome":"ether8",
"tipo":"ethernet",
"called_sid":null
},
"equipamento_conexao":{
"nome":"OLT XPTO",
"ipv4":"192.168.2.100",
"ipv6":null
},
"equipamento_roteamento":{
"nome":"CONCENTRADOR XPTO",
"ipv4":"172.17.24.98",
"ipv6":null
},
"pacotes":[],
"senhas": [],
"endereco_cadastral":{
"completo":"RUA GERALDO RODRIGUES DA COSTA, 5 - CENTRO, SANTO ANTôNIO DO MONTE/MG",
"logradouro":"RUA",
"endereco":"GERALDO RODRIGUES DA COSTA",
"numero":"5",
"complemento":"",
"bairro":"CENTRO",
"cep":"35560000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Santo Antônio do Monte",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_instalacao":{
"completo":"RUA JOÃO J FERNANDES, 900 - BARRETOS, NOVA SERRANA/MG - AREA RURAL",
"logradouro":"RUA",
"endereco":"JOÃO J FERNANDES",
"numero":"900",
"complemento":"AREA RURAL",
"bairro":"BARRETOS",
"cep":"35519-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Nova Serrana",
"coordenadas": {
"latitude": -19.8562717,
"longitude": -45.0105913
}
},
"endereco_fiscal":{
"completo":"RUA RITA DOS SANTOS MESQUITA, 233 - SANTO AGOSTINHO, PERDIGãO/MG",
"logradouro":"RUA",
"endereco":"RITA DOS SANTOS MESQUITA",
"numero":"233",
"complemento":"",
"bairro":"SANTO AGOSTINHO",
"cep":"35545-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Perdigão",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_cobranca":{
"completo":"RUA DOIS, 221 - BARRETINHOS, NOVA SERRANA/MG - AREA RURAL",
"logradouro":"RUA",
"endereco":"DOIS",
"numero":"221",
"complemento":"AREA RURAL",
"bairro":"BARRETINHOS",
"cep":"35519-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Nova Serrana",
"coordenadas": {
"latitude": null,
"longitude": null
}
}
}
]
}
]
}
Exemplo de requisição GET na rota de cliente, carregando apenas algumas relações:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/all?relacoes=pacotes,senhas -k
Retorno da requisição GET:
{
"status":"success",
"msg":"Dados consultados com sucesso",
"clientes":[
{
"id_cliente":11201,
"codigo_cliente":421,
"nome_razaosocial":"GUILHERME SILVA",
"nome_fantasia":null,
"tipo_pessoa":"pf",
"cpf_cnpj":"10682083681",
"telefone_primario":"37988242968",
"telefone_secundario":"37988242968",
"telefone_terciario":"",
"email_principal":"guilherme@silva.com.br",
"email_secundario":null,
"rg":"MG16999888",
"rg_emissao":null,
"inscricao_municipal":null,
"inscricao_estadual":null,
"data_cadastro":"2017-08-05 00:00:00",
"data_nascmento":"1969-12-31 04:00:00",
"servicos":[
{
"id_cliente_servico":11201,
"id_servico":100,
"numero_plano":1,
"nome":"4M",
"valor":119.9,
"status":"Serviço Habilitado",
"status_prefixo":"servico_habilitado",
"tecnologia":"WIRELESS",
"login":"guilhermesilva1068",
"senha":"123",
"ipv4":"10.99.2.203",
"ipv6":null,
"pacotes":[
{
"id_pacote": 1,
"codigo":"meu_codigo_personalizado_1",
"descricao": "IP FIXO",
"valor": "20",
"observacoes": "IP FIXO 189.79.21.21",
"data_cadastro": "2019-11-21 16:43:56"
},
{
"id_pacote": 2,
"codigo":"meu_codigo_personalizado_2",
"descricao": "TV",
"valor": "20",
"observacoes": "ASSINATURA DE TV",
"data_cadastro": "2019-11-20 16:43:56"
}
],
"senhas": [
{
"id_cliente_servico_senha": 6,
"descricao": "Teste",
"usuario": "xpto123",
"senha": "abc123"
}
]
}
]
}
]
}
Atendimento¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/atendimento
GET
No método GET, será possível consultar os atendimentos em aberto/fechados dos clientes e obter o retorno no formato JSON como resposta. Os segintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| busca | Tipo de busca que deseja fazer no cliente | Sim |
| termo_busca | Termo utilizado para fazer a busca | Sim |
| limit | Limite de resultados | Não |
| apenas_pendente | Informa de deseja trazer apenas os atendimentos pendentes (abertos) | Não |
| order_by | Campo que será utilizado para ordenação | Não |
| order_type | Tipo de Ordenação | Não |
| data_inicio | Data de Início (Utiliza a data de cadastro como base) | Não |
| data_fim | Data de Fim (Utiliza a data de cadastro como base) | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| busca | codigo_cliente, cpf_cnpj, id_cliente_servico, protocolo | Nenhum |
| termo_busca | Campo livre (Qualquer valor será aceito) | Nenhum |
| limit | Valor mínimo 1, Valor máximo 50. | 20 |
| apenas_pendente | sim,nao | sim |
| order_by | data_cadastro,data_fechamento | data_cadastro |
| order_type | asc,desc | asc |
| data_inicio | Campo no formato DateTime (YYYY-MM-DD) | Nenhum |
| data_fim | Campo no formato DateTime (YYYY-MM-DD) | Nenhum |
Exemplo de requisição GET na rota do cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/atendimento?busca=codigo_cliente&termo_busca=1099&limit=2 -k
Retorno da requisição GET:
{
"status": "suscess",
"msg": "Dados consultados com sucesso",
"atendimentos": [
{
"id_atendimento": 110,
"protocolo": "201806191505251",
"descricao_abertura": "VERIFICAR CONEXÃO",
"descricao_fechamento": null,
"tipo_atendimento": "TÉCNICO - QUEDAS DE CONEXÃO",
"usuario_abertura": "Bianca Couto",
"usuario_responsavel": "Bianca Couto",
"usuario_fechamento": null,
"data_cadastro": "19/06/2018",
"data_fechamento": null,
"setor_responsavel": null,
"status_fechamento": null,
"motivo_fechamento": null,
"status": "Pendente",
"cliente": {
"codigo_cliente": 1204,
"nome_razaosocial": "BIANCA COUTO",
"cpf_cnpj": "86214941081"
},
"servico": {
"id_cliente_servico":"123",
"numero_plano": 0,
"nome": "5MB-WIRELLES-TESTE",
"valor": 199.9,
"status": "Cancelado",
"status_prefixo": "cancelado"
},
"ordens_servico": [
{
"id_ordem_servico": 131,
"numero_ordem_servico": "125",
"data_cadastro": "19/06/2018 15:05:25",
"tipo": "SUPORTE",
"data_inicio_programado": "19/06/2018 14:02:00",
"data_termino_programado": "19/06/2018 15:02:00",
"data_inicio_executado": "19/06/2018 14:02:00",
"data_termino_executado": "19/06/2018 15:02:00",
"descricao_abertura": "VERIFICAR CONEXÃO",
"descricao_servico": "VERIFICAR CONEXÃO",
"descricao_fechamento": "asdfasdfadsf",
"usuario_abertura": "Bianca Couto",
"usuario_fechamento": "Bianca Couto",
"status": "finalizado",
"status_fechamento": "concluido",
"cliente": {
"codigo_cliente": 1204,
"nome_razaosocial": "BIANCA COUTO",
"cpf_cnpj": "86214941081"
},
"servico": {
"id_cliente_servico":"123",
"numero_plano": 0,
"nome": "5MB-WIRELLES-TESTE",
"valor": 199.9,
"status": "Cancelado",
"status_prefixo": "cancelado"
}
}
]
},
{
"id_atendimento": 285,
"protocolo": "201811061724214",
"descricao_abertura": "Abertura de atendimento através da API | ATENDIMENTO ABERTO VIA CENTRAL DO ASSINANTE",
"descricao_fechamento": null,
"tipo_atendimento": "SAC",
"usuario_abertura": "Master",
"usuario_responsavel": "Master",
"usuario_fechamento": null,
"data_cadastro": "06/11/2018",
"data_fechamento": null,
"setor_responsavel": null,
"status_fechamento": null,
"motivo_fechamento": null,
"status": "Aguardando Análise",
"cliente": {
"codigo_cliente": 1204,
"nome_razaosocial": "BIANCA COUTO",
"cpf_cnpj": "86214941081"
},
"ordens_servico": []
},
{
"id_atendimento": 300,
"protocolo": "201811161058216",
"descricao_abertura": "Estou sem acesso a internet desde segunda-feira. | ATENDIMENTO ABERTO VIA API",
"descricao_fechamento": null,
"tipo_atendimento": "SAC",
"usuario_abertura": "IP Telecom",
"usuario_responsavel": "IP Telecom",
"usuario_fechamento": null,
"data_cadastro": "16/11/2018",
"data_fechamento": null,
"setor_responsavel": null,
"status_fechamento": null,
"motivo_fechamento": null,
"status": "Aguardando Análise",
"cliente": {
"codigo_cliente": 1204,
"nome_razaosocial": "BIANCA COUTO",
"cpf_cnpj": "86214941081"
},
"servico": {
"id_cliente_servico":"12345",
"numero_plano": 9,
"nome": "NEXT-NV_1MBPS",
"valor": 69.9,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado"
},
"ordens_servico": [
{
"id_ordem_servico": 340,
"numero_ordem_servico": "320",
"data_cadastro": "16/11/2018 10:58:21",
"tipo": "ABERTURA VIA API",
"data_inicio_programado": "16/11/2018 11:58:21",
"data_termino_programado": "16/11/2018 12:58:21",
"data_inicio_executado": null,
"data_termino_executado": null,
"descricao_abertura": "Estou sem acesso a internet desde segunda-feira. | ATENDIMENTO ABERTO VIA API",
"descricao_servico": "Estou sem acesso a internet desde segunda-feira. | ATENDIMENTO ABERTO VIA API",
"descricao_fechamento": null,
"usuario_abertura": "IP Telecom",
"usuario_fechamento": null,
"status": "aguardando_agendamento",
"status_fechamento": null,
"cliente": {
"codigo_cliente": 1204,
"nome_razaosocial": "BIANCA COUTO",
"cpf_cnpj": "86214941081"
},
"servico": {
"id_cliente_servico":"12345",
"numero_plano": 9,
"nome": "NEXT-NV_1MBPS",
"valor": 69.9,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado"
}
}
]
}
]
}
Autenticação¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/autenticacao
POST
No método POST, será possível realizar a autenticação do cliente, com seu usuário e senha. Essa autenticação respeita os mesmos dados que o cliente utiliza para conectar na Central do Assinante WEB ou APP. Os segintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| usuario | Usuário de Autenticação da Central | Sim |
| senha | Senha de Autenticação da Central | Sim |
Exemplo de requisição POST na rota do cliente:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/autenticacao -d '{"usuario":"12312312344", "senha":"!M1nhAS3nhA&"}' -k
Exemlo do JSON da requisição POST:
{
"usuario":"12312312344",
"senha":"!M1nhAS3nhA&"
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Usuário autenticado com sucesso",
"cliente": {
"id_cliente": 23285,
"codigo_cliente": 1382,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"nome_fantasia": null,
"cpf_cnpj": "09141806654",
"data_nascimento": "1994-03-11",
"telefone_primario": "37911112222",
"telefone_secundario": "3734151100",
"telefone_terciario": "11988887777",
"email_principal": "naotem@naotem.com.br",
"email_secundario": "naotem@naotem.com.br"
}
}
Consulta¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente
GET
No método GET, irá consultar os dados dos clientes e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| busca | Tipo de busca que deseja fazer no cliente | Sim |
| termo_busca | Termo utilizado para fazer a busca | Sim |
| limit | Limite de resultados | Não |
| cancelado | Informa se deseja trazer os serviços cancelados ou não | Não |
| ultima_conexao | Informa se deseja trazer os dados da última conexão | Não |
| incluir_contrato | Informa se deseja incluir os contratos do serviço | Não |
| order_by | Campo que será utilizado para ordenação | Não |
| order_type | Tipo de Ordenação | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| busca | nome_razaosocial, nome_fantasia, cpf_cnpj, codigo_cliente, telefone, login_radius, ipv4, mac | Nenhum |
| termo_busca | Campo livre (Qualquer valor será aceito) | Nenhum |
| limit | Valor mínimo 1, Valor Máximo 100. | 5 |
| cancelado | sim,nao | nao |
| ultima_conexao | sim,nao | nao |
| incluir_contrato | sim,nao | nao |
| order_by | data_cadastro,data_fechamento | data_cadastro |
| order_type | asc,desc | asc |
Exemplo de requisição GET na rota de cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente?busca=nome_razaosocial&termo_busca=guilherme&limit=2&cancelado=nao&order_by=codigo_cliente&order_type=asc -k
Retorno da requisição GET:
{
"status":"success",
"msg":"Dados consultados com sucesso",
"clientes":[
{
"id_cliente":11201,
"codigo_cliente":421,
"nome_razaosocial":"GUILHERME SILVA",
"nome_fantasia":null,
"tipo_pessoa":"pf",
"cpf_cnpj":"10682083681",
"telefone_primario":"37988242968",
"telefone_secundario":"37988242968",
"telefone_terciario":"",
"email_principal":"guilherme@silva.com.br",
"email_secundario":null,
"rg":"MG16999888",
"rg_emissao":null,
"inscricao_municipal":null,
"inscricao_estadual":null,
"data_cadastro":"2017-08-05 00:00:00",
"data_nascmento":"1969-12-31 04:00:00",
"alerta":true,
"alerta_mensagens":[
"Existe um rompimento de fibra no bairro Centro, na cidade Divinópolis que está afetando esse cliente",
"A equipe técnica já está a caminho para resolver o rompimento de fibra"
],
"servicos":[
{
"id_cliente_servico":11201,
"numero_plano":1,
"nome":"4M",
"valor":119.9,
"status":"Serviço Habilitado",
"status_prefixo":"servico_habilitado",
"tecnologia":"WIRELESS",
"login":"guilhermesilva1068",
"senha":"123",
"ipv4":"10.99.2.203",
"ipv6":null,
"ultima_conexao": {
"conectado": true,
"ultima_conexao_datetime": "2019-12-15 18:22:24-03",
"ultima_desconexao_datetime": null,
"ultima_conexao": "15/12/2019 18:22:24",
"ultima_desconexao": null,
"ultimo_ipv4": "189.90.210.100",
"ultimo_nas_ip": "10.28.33.20",
"status_txt": "CONECTADO HÁ 0 MES(ES), 0 DIA(S), 22 HORA(S) e 53 MINUTO(S) - 189.90.210.100(10.28.50.20)",
"status_txt_resumido": "CONECTADO HÁ 0 MES(ES), 0 DIA(S), 22 HORA(S) e 53 MINUTO(S)"
}
"interface":{
"nome":"PON5",
"tipo":"gpon",
"called_sid":null
},
"interface_roteamento":{
"nome":"ether8",
"tipo":"ethernet",
"called_sid":null
},
"equipamento_conexao":{
"nome":"OLT XPTO",
"ipv4":"192.168.2.100",
"ipv6":null
},
"equipamento_roteamento":{
"nome":"CONCENTRADOR XPTO",
"ipv4":"172.17.24.98",
"ipv6":null
},
"pacotes":[
{
"id_pacote": 1,
"descricao": "IP FIXO",
"valor": "20",
"observacoes": "IP FIXO 189.79.21.21",
"data_cadastro": "2019-11-21 16:43:56"
},
{
"id_pacote": 2,
"descricao": "TV",
"valor": "20",
"observacoes": "ASSINATURA DE TV",
"data_cadastro": "2019-11-20 16:43:56"
}
],
"senhas": [
{
"id_cliente_servico_senha": 6,
"descricao": "Teste",
"usuario": "xpto123",
"senha": "abc123"
}
],
"endereco_cadastral":{
"completo":"RUA DONA MARIA DAS DORES, 541 - NOSSA SENHORA DAS GRACAS, DIVINóPOLIS/MG - IGREJA",
"logradouro":"RUA",
"endereco":"DONA MARIA DAS DORES",
"numero":"541",
"complemento":"IGREJA",
"bairro":"NOSSA SENHORA DAS GRACAS",
"cep":"35501-048",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_instalacao":{
"completo":"RUA MINAS GERAIS, 1793 - IPIRANGA, DIVINóPOLIS/MG",
"logradouro":"RUA",
"endereco":"MINAS GERAIS",
"numero":"1793",
"complemento":"",
"bairro":"IPIRANGA",
"cep":"35502-026",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": -19.8562717,
"longitude": -45.0105913
}
},
"endereco_fiscal":{
"completo":"RUA GOIAS, 86 - PORTO VELHO, DIVINóPOLIS/MG - APTO 101",
"logradouro":"RUA",
"endereco":"GOIAS",
"numero":"86",
"complemento":"APTO 101",
"bairro":"PORTO VELHO",
"cep":"35500-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_cobranca":{
"completo":"RUA SEBASTIAO PARDINI, 58 - CENTRO, DIVINóPOLIS/MG - 202",
"logradouro":"RUA",
"endereco":"SEBASTIAO PARDINI",
"numero":"58",
"complemento":"202",
"bairro":"CENTRO",
"cep":"35500-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Divinópolis",
"coordenadas": {
"latitude": null,
"longitude": null
}
}
}
]
},
{
"id_cliente":11202,
"codigo_cliente":422,
"nome_razaosocial":"GUILHERME COSTA",
"nome_fantasia":null,
"tipo_pessoa":"pf",
"cpf_cnpj":"05333614622",
"telefone_primario":"37999450812",
"telefone_secundario":"37999452812",
"telefone_terciario":"",
"email_principal":null,
"email_secundario":null,
"rg":"MG11298180",
"rg_emissao":null,
"inscricao_municipal":null,
"inscricao_estadual":null,
"data_cadastro":"2017-04-26 00:00:00",
"data_nascmento":"1969-12-31 00:00:00",
"alerta":false,
"alerta_mensagens":[],
"servicos":[
{
"id_cliente_servico":11302,
"numero_plano":2,
"nome":"24M",
"valor":119.9,
"status":"Serviço Habilitado",
"status_prefixo":"servico_habilitado",
"tecnologia":"FIBRA",
"login":"guilhermesouza0533",
"senha":"123",
"ipv4":"10.99.1.118",
"ipv6":null,
"ultima_conexao": [],
"porta_atendimento": {
"numero": 7,
"equipamento": "A2R3C2"
},
"interface":{
"nome":"PON5",
"tipo":"gpon",
"called_sid":null
},
"interface_roteamento":{
"nome":"ether8",
"tipo":"ethernet",
"called_sid":null
},
"equipamento_conexao":{
"nome":"OLT XPTO",
"ipv4":"192.168.2.100",
"ipv6":null
},
"equipamento_roteamento":{
"nome":"CONCENTRADOR XPTO",
"ipv4":"172.17.24.98",
"ipv6":null
},
"pacotes":[],
"senhas":[],
"endereco_cadastral":{
"completo":"RUA GERALDO RODRIGUES DA COSTA, 5 - CENTRO, SANTO ANTôNIO DO MONTE/MG",
"logradouro":"RUA",
"endereco":"GERALDO RODRIGUES DA COSTA",
"numero":"5",
"complemento":"",
"bairro":"CENTRO",
"cep":"35560000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Santo Antônio do Monte",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_instalacao":{
"completo":"RUA JOÃO J FERNANDES, 900 - BARRETOS, NOVA SERRANA/MG - AREA RURAL",
"logradouro":"RUA",
"endereco":"JOÃO J FERNANDES",
"numero":"900",
"complemento":"AREA RURAL",
"bairro":"BARRETOS",
"cep":"35519-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Nova Serrana",
"coordenadas": {
"latitude": -19.8562717,
"longitude": -45.0105913
}
},
"endereco_fiscal":{
"completo":"RUA RITA DOS SANTOS MESQUITA, 233 - SANTO AGOSTINHO, PERDIGãO/MG",
"logradouro":"RUA",
"endereco":"RITA DOS SANTOS MESQUITA",
"numero":"233",
"complemento":"",
"bairro":"SANTO AGOSTINHO",
"cep":"35545-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Perdigão",
"coordenadas": {
"latitude": null,
"longitude": null
}
},
"endereco_cobranca":{
"completo":"RUA DOIS, 221 - BARRETINHOS, NOVA SERRANA/MG - AREA RURAL",
"logradouro":"RUA",
"endereco":"DOIS",
"numero":"221",
"complemento":"AREA RURAL",
"bairro":"BARRETINHOS",
"cep":"35519-000",
"estado":"MG",
"uf":"MINAS GERAIS",
"cidade":"Nova Serrana",
"coordenadas": {
"latitude": null,
"longitude": null
}
}
}
]
}
]
}
No exemplo acima, foi feito uma requisição utilizando os seguintes parâmetros:
- busca: nome_razaosocial
- limit: 2 (Preciso de apenas 2 resultados)
- cancelado: nao (Quero apenas planos ativos)
- order_by: codigo_cliente
- order_type: asc (Do maior para o menor)
Aviso
IMPORTANTE: Para trazer os dados da última autenticação, é necessário enviar o parâmetro ultima_conexao=sim. A última conexão utiliza como base o extrato de conexão do RADIUS, por isso, caso existam problemas na rede do provedor, essa informação poderá não ser 100% confiável, uma vez, que ela depende que o concentrador do provedor, informe ao servidor RADIUS o estado atual da conexão do cliente.
Aviso
IMPORTANTE 2: Para que o HubSoft consiga retornar os dados de coordenadas do endereço, é importante que o provedor tenha configurado em seus sistema, as credenciais de integração com o Google Maps API. O HubSoft irá verificar apenas os endereços de instalação, para fazer a atualização de coordenadas.
Aviso
IMPORTANTE 3: O provedor poderá cadastrar os alertas, que serão retornados aqui na API, pelos atributos alerta e alerta_mensagens. Esses alertas, podem ser utilizados pelo software que está consumindo a API, para enviar uma mensagem automática em um BOT para o cliente, ou soltar um áudio customizado no PBX, quando o cliente ligar, ou ainda exibir o cliente de uma cor diferente no mapa. As possibilidades são muitas e vão depender exclusivamente da criatividade do integrador. A equipe do HubSoft estará sempre a disposição para ajudar os desenvolvedores em suas integrações conosco :)
Configuração de dados de Autenticação¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/configurar_autenticacao
POST
No método POST, será possível efetuar a configuração de alguns parametros de autenticação do serviço.
Atributos da Requisição
No método GET, irá consultar os dados dos clientes e retornar um JSON como resposta. Na consulta de Equipamentos é possível obter a lista de Interfaces e os respectivos IDs.
Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_cliente_servico | Identificador único do serviço do cliente | Sim |
| id_interface_conexao | Interface de conexão com a qual o plano deverá ser vinculado | Não |
| phy_addr | MAC/Serial da ONU ou equipamento equivalente do cliente, que forneça acesso em camada 2 | Não |
| password | Senha de autenticação do cliente | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_cliente_servico | Deve conter um número inteiro maior que 0 | Nenhum |
| id_interface_conexao | Deve conter um número inteiro maior que 0 | Nenhum |
| phy_addr | Deve conter uma sequencia de letras e caracteres, sem espaço | Nenhum |
| password | Deve conter no minimo tres caracteres | Nenhum |
Exemplo de requisição POST na rota do desbloqueio em confiança:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/cliente/configurar_autenticacao -d '{"id_cliente_servico":"11000", "password":"NewPasswd123"}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_cliente_servico":"11000",
"password":"NewPasswd123",
"id_interface_conexao":"931"
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Parametros de autenticacao modificados com sucesso!"
}
Desbloqueio em Confiança¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/desbloqueio_confianca
POST
No método POST, será possível efetuar o desbloqueio em confiança, pela quantidade de dias desejados.
Aviso
IMPORTANTE: O sistema vai fazer a validação da regra configurada pelo painel do administrador. Por exemplo, se a regra configurada pelo painel, estiver definido que o máximo de dias para desbloqueio for menor ou igual a 3 dias e a requisição da API, possuir um valor maior que 3 (no atributo dias_desbloqueio), o desbloqueio não será efetuado, e uma mensagem de erro será retornada, avisando que o valor informado para os dias de desbloqueio não é permitido, pois ultrapassa a configuração pré-estabelecida.
Atributos da Requisição
No método GET, irá consultar os dados dos clientes e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_cliente_servico | Identificador único do serviço do cliente | Sim |
| dias_desbloqueio | Quantidade de dias, a partir da data atual que o cliente ficará desbloqueado em confiança | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_cliente_servico | Deve conter um número inteiro maior que 0 | Nenhum |
| dias_desbloqueio | Deve conter um número inteiro maior que 0. Se não for preenchido o valor 1 será atributo, ou seja, será desbloqueado até o próximo dia | Nenhum |
Exemplo de requisição POST na rota do desbloqueio em confiança:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/cliente/desbloqueio_confianca -d '{"id_cliente_servico":"11000", "dias_desbloqueio":"1"}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_cliente_servico":"11000",
"dias_desbloqueio":"1"
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Desbloqueio em confiança realizado com sucesso até a data 26/11/2018"
}
Desconexão do Cliente¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/solicitar_desconexao/<id_cliente_servico>
GET
No método GET, será possível efetuar a desconexão da conexão do cliente.
Aviso
IMPORTANTE: A desconexão apenas será realizada se a porta INCOMING estiver habilitada no equipamento de conexão (Concentrador). É necessário estar configurado no HubSoft em Rede > Equipamentos de Conexão e também é importante que o servidor RADIUS possua comunicação com o equipamento de conexão (Concentrador) no momento da solicitação. Todos esses fatores devem trabalhar em conjunto, para que o sistema consiga executar a operação com sucesso.
Atributos da Requisição
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_cliente_servico | Identificador único do serviço do cliente | Sim |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_cliente_servico | Deve conter um número inteiro maior que 0 | Nenhum |
Exemplo de requisição GET na rota do desbloqueio em confiança:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/solicitar_desconexao/11000
Retorno da requisição GET em caso de sucesso:
{
"status": "success",
"msg": "A desconexão foi bem sucedida para o login hubsoft!",
"login": "hubsoft"
}
Retorno da requisição GET em caso de erro:
{
"status": "error",
"msg": "A desconexão não foi bem sucedida para o login hubsoft!",
"errors": []
}
Extrato Conexão¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/extrato_conexao
GET
No método GET, será possível consultar os extratos de conexão de um determinaod login e obter o retorno no formato JSON como resposta. Os segintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| busca | Tipo de busca que deseja fazer no cliente | Sim |
| termo_busca | Termo utilizado para fazer a busca | Sim |
| limit | Limite de resultados | Não |
| data_inicio | Data de Início (Utiliza a data de vencimento como base) | Não |
| data_fim | Data de Fim (Utiliza a data de vencimento como base) | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| busca | login,ipv4,ipv6_wan,ipv6_lan | Nenhum |
| termo_busca | Campo livre | Nehum |
| limit | Valor mínimo 1, Valor máximo 50 | 20 |
| data_inicio | Campo no formato DateTime (YYYY-MM-DD). | Data atual menos 30 dias |
| data_fim | Campo no formato DateTime (YYYY-MM-DD). | Data atual |
Exemplo de requisição GET na rota do cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/extrato_conexao?busca=login&termo_busca=antoniomas&limit=2 -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso",
"registros": [
{
"acctstarttime": "2017-09-27 18:14:08-03",
"acctstarttimebr": "27/09/2017 18:14:08",
"acctstoptime": null,
"acctstoptimebr": null,
"calledstationid": "service2",
"callingstationid": "58:10:8C:4B:FF:AA",
"download_megabytes": 4594.95,
"upload_megabytes": 156.12,
"framedipaddress": "10.99.1.152",
"nasipaddress": "172.17.22.132",
"nasportid": "ether3",
"nasporttype": "Ethernet",
"username": "antoniomas",
"servico": {
"numero_plano": 49,
"nome": "100GB-DE-TESTE-",
"valor": 100,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado"
},
"cliente": {
"codigo_cliente": 1161,
"nome_razaosocial": "ANTONIO MODESTO",
"cpf_cnpj": "09350012345"
}
}
],
"estatisticas": {
"total_conexoes": 1,
"download_total": 4594.95,
"upload_total": 156.12,
"trafego_total": 4751.07,
"media_download": 0.23,
"media_upload": 0.01
}
}
Financeiro¶
Necessário
Para fazer requisições nos dados de financeiro dos clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/financeiro
GET
No método GET, será possível consultar as faturas em aberto/liquidadas dos clientes e obter o retorno no formato JSON como resposta. Os segintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| busca | Tipo de busca que deseja fazer no cliente | Sim |
| termo_busca | Termo utilizado para fazer a busca | Sim |
| limit | Limite de resultados | Não |
| apenas_pendente | Informa de deseja trazer apenas as faturas pendentes | Não |
| order_by | Campo que será utilizado para ordenação | Não |
| order_type | Tipo da Ordenação | Não |
| data_inicio | Data de Início (Utiliza a data de vencimento como base) | Não |
| data_fim | Data de Fim (Utiliza a data de vencimento como base) | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| busca | cpf_cnpj, codigo_cliente, id_cliente_servico | Nenhum |
| termo_busca | Campo livre | Sim |
| limit | Valor mínimo 1, Valor máximo 50. | 20 |
| apenas_pendente | sim,nao. | sim |
| order_by | data_vencimento,data_pagamento,data_cadastro,valor. | data_vencimento |
| order_type | asc,desc. | asc |
| data_inicio | Campo no formato DateTime (YYYY-MM-DD) | Nenhum |
| data_fim | Campo no formato DateTime (YYYY-MM-DD) | Nenhum |
| tipo_data | data_vencimento, data_pagamento, data_cadastro | data_vencimento |
Nota
INFORMAÇÃO: O atributo «tipo_data» somente será validado, caso seja informado o atributo data_inicio e/ou data_fim, pois o filtro o tipo de data selecionado, será aplicado em cima da data inicial e/ou data final.
Exemplo de requisição GET na rota do cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/financeiro?busca=codigo_cliente&termo_busca=1099&limit=2 -k
Retorno da requisição GET:
{
"status": "suscess",
"msg": "Dados consultados com sucesso",
"faturas": [
{
"id_fatura": 36397,
"nosso_numero": "272064",
"nosso_numero_dv": null,
"linha_digitavel": null,
"codigo_barras": null,
"link": null,
"agencia_codigo_beneficiario": null,
"beneficiario": null,
"numero_documento": null,
"especie": null,
"especie_dinheiro": "R$",
"aceite": null,
"local_pagamento": null,
"carteira": null,
"tipo_cobranca": "debito_conta_corrente",
"valor": 54.95,
"data_vencimento": "10/10/2017",
"data_cadastro": "10/10/2017",
"data_pagamento": "31/07/2017",
"data_documento": null,
"data_processamento": null,
"pix_copia_cola":"00020101026216880014BR.GOV.BCB.PIX2566qrcodes-pix.gerencianet.com.br/v2/9a5944a87b1a47da12345581735e74165204000053039865802BR5914GERENCIANET SA6010OURO PRETO62070503***6301122B",
"detalhamento": [
{
"descricao": "(+) Serviço de Comunicação e Multimídia (26/09/2017) até (09/10/2017) - 13 dias (proporcional) | R$ 21.62",
"valor": 21.62
},
{
"descricao": "(+) Taxa de Instalação (1/3) | R$ 33.33",
"valor": 33.33
}
],
"cliente": {
"codigo_cliente": 1162,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"cpf_cnpj": "41107296617",
"servico": {
"id_cliente_servico": 22703,
"numero_plano": 26,
"nome": "500MB",
"valor": 54.95,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado",
"endereco_cadastral": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
},
"endereco_instalacao": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
},
"endereco_fiscal": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
},
"endereco_cobranca": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
}
}
}
},
{
"id_fatura": 36403,
"nosso_numero": "272100",
"nosso_numero_dv": "0272100-0",
"linha_digitavel": "75691.31662 01006.726101 27210.000017 7 73380000001000",
"codigo_barras": "75697733800000010001316601006726102721000001",
"link": "https://endereco_do_servidor/pdf/fatura/TXpZME1ETT0=",
"agencia_codigo_beneficiario": "3166 / 67261",
"beneficiario": "PROVEDOR DE INTERNET LTDA / CNPJ: 22.385.367/0001-03",
"numero_documento": 36403,
"especie": "DS",
"especie_dinheiro": "R$",
"aceite": "N",
"local_pagamento": "PAGÁVEL EM QUALQUER BANCO ATÉ O VENCIMENTO",
"carteira": "1",
"tipo_cobranca": "boleto_bancario",
"valor": 10,
"data_vencimento": "09/11/2017",
"data_cadastro": "10/10/2017",
"data_pagamento": "25/06/2018",
"data_documento": "06/04/2020",
"data_processamento": "06/04/2020",
"pix_copia_cola":null,
"detalhamento": [
{
"descricao": "Cobrança adicional",
"valor": 10
}
],
"cliente": {
"codigo_cliente": 1162,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"cpf_cnpj": "41107296617",
"servico": {
"id_cliente_servico": 22703,
"numero_plano": 26,
"nome": "500MB",
"valor": 54.95,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado",
"endereco_cadastral": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
},
"endereco_instalacao": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
},
"endereco_fiscal": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
},
"endereco_cobranca": {
"completo": "PRAÇA GETULIO VARGAS, 100, SALA 411 - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000",
"endereco": "PRAÇA GETULIO VARGAS",
"numero": "100",
"complemento": "SALA 411",
"referencia": null,
"bairro": "CENTRO",
"cep": "35560000",
"estado": "MG",
"uf": "MINAS GERAIS",
"cidade": "SANTO ANTÔNIO DO MONTE",
"coordenadas": {
"latitude": -20.086726,
"longitude": -45.290536
}
}
}
}
},
{
"id_fatura": 43653,
"nosso_numero": "274554",
"nosso_numero_dv": "0274554-2",
"linha_digitavel": "75691.31662 01006.726101 27455.420011 8 82170000001232",
"codigo_barras": "75698821700000012321316601006726102745542001",
"link": "http://endereco_do_servidor/pdf/fatura/TkRNMk5UTT0=",
"agencia_codigo_beneficiario": "3166 / 67261",
"beneficiario": "PROVEDOR DE INTERNET LTDA / CNPJ: 22.385.367/0001-03",
"numero_documento": 43653,
"especie": "DS",
"especie_dinheiro": "R$",
"aceite": "N",
"local_pagamento": "PAGÁVEL EM QUALQUER BANCO ATÉ O VENCIMENTO",
"carteira": "1",
"tipo_cobranca": "boleto_bancario",
"valor": 10,
"data_vencimento": "10/07/2018",
"data_cadastro": "10/10/2017",
"data_pagamento": null,
"data_documento": "06/04/2020",
"data_processamento": "06/04/2020",
"pix_copia_cola":"00020101026216880014BR.GOV.BCB.PIX2566qrcodes-pix.gerencianet.com.br/v2/9a5944a87b1a47da12345581735e74165204000053039865802BR5914GERENCIANET SA6010OURO PRETO62070503***6301122B",
"detalhamento": [
{
"descricao": "COBRANÇA DE TESTE VENCIDA",
"valor": 10
}
],
"cliente": {
"codigo_cliente": 1162,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"cpf_cnpj": "41107296617"
}
}
]
}
Financeiro > Envio por Email¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/financeiro/enviar_email
POST
No método POST, será possível fazer o disparo da fatura do cliente por e-mail. Podem ser passados emails adicionais, além dos que já estão cadastrados no sistema.
Aviso
IMPORTANTE: O sistema vai fazer a validação dos dados de e-mail e verificar se a API possui um servidor de e-mail válido configurado. Caso todas as regras sejam atendidas, o disparo do e-mail será efetuado instantaneamente, ou seja, é enviado em tempo real. Por esse motivo, o tempo de resposta da API, irá variar de acordo com a quantidade de e-mails que está na requisição para ser disparado.
Aviso
IMPORTANTE 2: O(s) servidor(es) de e-mails configurados no HubSoft possuem configuração de timeout entre um disparo e outro, dessa forma evita-se que o servidor seja adicionado em BlackLists de SPAM. Por esse motivo, a chamada da API, poderá ter um tempo de resposta diferente do comum.
Atributos da Requisição
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_fatura | Identificador único da fatura do cliente | Sim |
| email_adicional | Outros e-mails adicionais, podem ser enviados na requisição. | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_fatura | Deve conter um número inteiro maior que 0 | Nenhum |
| email_adicional | Deve conter um array de strings (emails) | Nenhum |
Exemplo de requisição POST na rota do envio de e-mail:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/cliente/financeiro/enviar_email -d '{"id_fatura":"11000", "email_adicional":["email1@email.com","email2@email.com"]}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_fatura":"11000",
"email_adicional":[
"email1@email.com",
"email2@email.com"
]
}
Retorno da requisição POST:
{
"status": "success",
"msg": "As faturas foram adicionadas para serem disparadas por e-mail. Por se tratar de um processo de envio massivo, o sistema fará o agendamento do disparo. Dentro de alguns minutos o cliente irá receber os e-mails com as faturas. OBS: Para cada fatura selecionada será enviado um e-mail",
"job": {
"tries": 1,
"timeout": 172800,
"memory": 2048,
"faturas": [
{
"id_fatura": 50949
}
],
"emails": [
{
"id_contato": null,
"id_cliente": 12025,
"email": "macielrsf@gmail.com",
"nome": "MACIEL RODRIGUES",
"name": "MACIEL RODRIGUES",
"permite_enviar_email": true,
"origem": "cadastro_cliente"
},
{
"id_contato": null,
"id_cliente": 12025,
"email": "macielrsf@gmail.com",
"nome": "MACIEL RODRIGUES",
"name": "MACIEL RODRIGUES",
"permite_enviar_email": true,
"origem": "cadastro_cliente"
},
{
"id_contato": 12035,
"id_cliente": 12025,
"email": "macielrsf@gmail.com",
"nome": "MACIEL RODRIGUES",
"name": "MACIEL RODRIGUES",
"permite_enviar_email": "sim",
"origem": "contato"
}
],
"connection": null,
"queue": "hubsoft-prioritario",
"delay": {
"date": "2019-10-07 13:39:48.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
}
Nota
OBSERVAÇÃO: Perceba que foram enviados 2 e-mails adicionais, porém o sistema fez um disparo de 3 emails. Isso aconteceu, pois o cliente já possuia 1 endereço de e-mail em seu cadastro. No momento do disparo, o sistema enviou para os e-mails já cadastrados no sistema e também para os telefones adicionais passados na requisição POST
Financeiro > Envio por SMS¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/financeiro/enviar_sms
POST
No método POST, será possível fazer o disparo da fatura do cliente por SMS. Podem ser passados números de telefones adicionais, além dos que já estão cadastrados no sistema.
Aviso
IMPORTANTE: O disparo do SMS é efetuado para a Plataforma de SMS. Caso o HubSoft consiga entregar o SMS para plataforma, o resultado da requisição será uma resposta de SUCESSO, mesmo que a plataforma não efetue o disparo, para o HubSoft a tarefa foi efetuada com sucesso.
Atributos da Requisição
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_fatura | Identificador único da fatura do cliente | Sim |
| telefone_adicional | Outros telefones adicionais, podem ser enviados na requisição. | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_fatura | Deve conter um número inteiro maior que 0 | Nenhum |
| telefone_adicional | Deve conter um array de strings com os telefones no formato DDNNNNNNNN ou DDNNNNNNNNN | Nenhum |
Exemplo de requisição POST na rota do envio de e-mail:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/cliente/financeiro/enviar_sms -d '{"id_fatura":"11000", "telefone_adicional":["11988887777","1188887776"]}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_fatura":"11000",
"email_adicional":[
"11988887777",
"1188887776"
]
}
Retorno da requisição POST:
{
"status": "success",
"msg": "As faturas foram adicionadas para serem disparadas por SMS. Por se tratar de um processo de envio massivo, o sistema fará o agendamento do disparo. Dentro de alguns minutos o cliente irá receber as mensgens SMS com os dados das faturas. OBS: Para cada fatura selecionada será enviado um SMS",
"job": {
"tries": 1,
"timeout": 172800,
"memory": 2048,
"faturas": [
{
"id_fatura": 50949
}
],
"telefones": [
{
"id_contato": null,
"id_cliente": 12025,
"telefone": "37999931412",
"nome": "MACIEL RODRIGUES",
"permite_enviar_sms": true,
"origem": "cadastro_cliente"
}
],
"connection": null,
"queue": "teste",
"delay": {
"date": "2019-10-07 13:20:51.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
}
Nota
OBSERVAÇÃO: Perceba que foram enviados 2 telefones adicionais, porém o sistema fez um disparo de 3 SMS. Isso aconteceu, pois o cliente já possuia 1 número de telefone celular válido em seu cadastro. No momento do disparo, o sistema enviou para os telefones já cadastrados no sistema e também para os telefones adicionais passados na requisição POST
Financeiro > Envio por Push Notification¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/financeiro/enviar_push
POST
No método POST, será possível fazer o disparo da fatura do cliente por push notification. .. warning:
IMPORTANTE: O cliente só receberá o push notification, caso ele possua o aplicativo do cliente instalado e esteja autenticado com o CPF/CNPJ.
Atributos da Requisição
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_fatura | Identificador único da fatura do cliente | Sim |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_fatura | Deve conter um número inteiro maior que 0 | Nenhum |
Exemplo de requisição POST na rota do envio de push notification:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/cliente/financeiro/enviar_push -d '{"id_fatura":"11000"}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_fatura":"11000"
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Fatura enviada com sucesso via push notification"
}
Fiscal > Nota Fiscal¶
Necessário
Para fazer requisições nos dados de nota fiscal dos clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/nota_fiscal
GET
No método GET, será possível consultar as notas fiscais e obter o retorno no formato JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| busca | Tipo de busca que deseja fazer no cliente | Sim |
| termo_busca | Termo utilizado para fazer a busca | Sim |
| data_inicio | Data de Início (Utiliza a data de emissão da nota como base) | Não |
| data_fim | Data de Fim (Utiliza a data de emissão da nota como base) | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| busca | id_cliente | Nenhum |
| termo_busca | Campo livre | Sim |
| data_inicio | Campo no formato DateTime (YYYY-MM-DD) | Nenhum |
| data_fim | Campo no formato DateTime (YYYY-MM-DD) | Nenhum |
Aviso
A API vai retornar somente notas que já foram processadas e enviadas aos respectivos orgãos responsavéis, sendo assim será retornado somente as notas com os seguintes status: NFe: efetivada / NFSe: autorizado / Nota Fiscal Telecom 21/22: normal
Nota
Para os parâmetros data_inicio e data_fim não pode ser informado um intervalo de datas maior que 60 dias.
Exemplo de requisição GET na rota do cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/nota_fiscal?busca=id_cliente&termo_busca=999&data_inicio=2021-01-01&data_fim=2022-02-23 -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados carregados com sucesso",
"cliente": {
"id_cliente": 23285,
"codigo_cliente": 1382,
"nome_razaosocial": "HUBSOFT BRASIL"
},
"notas_fiscais": [
{
"id_nota_fiscal": 3064,
"id_tipo_documento_fiscal": 1,
"numero_nota": 427,
"serie_nota": "U",
"cfop": "5307",
"identificacao": "XYWNrpBhW5D8p2yuvAoL",
"valor": "5",
"data_cadastro_br": "25/02/2022 09:07",
"data_emissao_br": "25/02/2022",
"data_cancelamento_br": null,
"cancelado": false,
"tipo_documento_fiscal": {
"id_tipo_documento_fiscal": 1,
"descricao": "Nota Fiscal de Serviço de Comunicação",
"codigo": "21",
"ativo": true,
"display": "21 - Nota Fiscal de Serviço de Comunicação"
}
}
],
"nfes": [
{
"id_nfe": 351,
"modelo": "55",
"serie": "1",
"numero_nf": 60,
"chave": "NFe16922351872769307419",
"recibo": "16922351872769307419",
"autorizacao": null,
"status": "efetivada",
"status_mensagem": "Autorizado o uso da NF-e",
"data_cadastro": "2021-12-09 17:31:39",
"protocolo_autorizacao": "16922351872769307419",
"cancelado": false,
"data_cadastro_br": "09/12/2021 17:31:39",
"data_cadastro_timestamp": 1639081899000,
"data_emissao_br": "25/02/2022 09:07:06",
"data_emissao_timestamp": 1645790826000,
"data_contigencia_br": null,
"data_contigencia_timestamp": null,
"data_saida_br": null,
"data_saida_timestamp": null,
"nfe_emitente": {
"id_nfe_emitente": 343,
"id_nfe": 351,
"nome_razaosocial": "TELECOM E HARDWARE LTDA",
"nome_fantasia": "TESTE NFE",
"inscricao_estadual": "0010735429999",
"inscricao_municipal": null,
"cpf_cnpj": "09613622999999",
"tipo_pessoa": "pj",
"end_logradouro": "PRAÇA GETULIO VARGAS",
"end_numero": "77",
"end_complemento": null,
"end_bairro": "CENTRO",
"end_cep": "35560000"
}
}
],
"nfses": [
{
"id_nfse": 106,
"id_externo": "61279626fbce65722f734bf899999",
"hash": "ae71a618-f673-4359-ac4d-6LuLjmXmLuu9G4KGOdXd",
"numero": "14890",
"serie": "LAL",
"lote_rps": "290008",
"valor": "25",
"data_cadastro": "2021-08-26 10:22:51",
"tipo_emissao": "manual",
"link_pdf": "",
"link_xml": "",
"status": "autorizado",
"status_mensagem": "RPS Autorizada com sucesso",
"informacao_complementar": "INFORMAÇÃO COMPLEMENTAR DA NFSE",
"data_cadastro_br": "26/08/2021 10:22",
"data_cadastro_timestamp": 1629984171000,
"data_cancelamento_br": null,
"data_cancelamento_timestamp": null
}
]
}
Fiscal > Nota Fiscal > Envio por Email¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/nota_fiscal/enviar_email
POST
No método POST, será possível fazer o disparo da nota fiscal do cliente por e-mail. Podem ser passados emails adicionais, além dos que já estão cadastrados no sistema.
Aviso
IMPORTANTE: O sistema vai fazer a validação dos dados de e-mail e verificar se a API possui um servidor de e-mail válido configurado. Caso todas as regras sejam atendidas, o disparo do e-mail será efetuado instantaneamente, ou seja, é enviado em tempo real. Por esse motivo, o tempo de resposta da API, irá variar de acordo com a quantidade de e-mails que está na requisição para ser disparado.
Aviso
IMPORTANTE 2: O(s) servidor(es) de e-mails configurados no HubSoft possuem configuração de timeout entre um disparo e outro, dessa forma evita-se que o servidor seja adicionado em BlackLists de SPAM. Por esse motivo, a chamada da API, poderá ter um tempo de resposta diferente do comum.
Atributos da Requisição
Os atributos podem conter os seguintes valores:
Exemplo de requisição POST na rota do envio de e-mail:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/cliente/nota_fiscal/enviar_email -d '{"id_nota_fiscal":"123","tipo_documento":"nfe", "email_adicional":["email1@email.com"]}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_nota_fiscal":"123",
"tipo_documento":"nfe",
"email_adicional":[
"email1@email.com"
]
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Um total de 2/3 email(s) foram enviados com sucesso",
"emails_enviados": [
{
"id_cliente": 23285,
"id_usuario": 1,
"id_usuario_envio": 915,
"host": "smtp.mailtrap.io",
"email_origem": "b860cbd1ea1dca",
"email_destino": "naotem@naotem.com.br",
"tipo_envio": "manual",
"tipo_documento": "nota_fiscal_produto",
"data_envio": "2022-02-25 09:59:46",
"enviado": true,
"mensagem_erro": null,
"id_email_enviado": 1416,
"data_envio_br": "25/02/2022 09:59",
"data_envio_timestamp": 1645793986000
},
{
"id_cliente": 23285,
"id_usuario": 1,
"id_usuario_envio": 915,
"host": "smtp.mailtrap.io",
"email_origem": "b860cbd1ea1dca",
"email_destino": "guilherme@hubsoft.com.br",
"tipo_envio": "manual",
"tipo_documento": "nota_fiscal_produto",
"data_envio": "2022-02-25 10:00:30",
"enviado": true,
"mensagem_erro": null,
"id_email_enviado": 1417,
"data_envio_br": "25/02/2022 10:00",
"data_envio_timestamp": 1645794030000
}
]
}
Ordem de Serviço¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente/ordem_servico
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/ordem_servico
GET
No método GET, será possível consultar as ordens de serviço de um determinado cliente e obter o retorno no formato JSON como resposta. Os segintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| busca | Tipo de busca que deseja fazer no cliente | Sim |
| termo_busca | Termo utilizado para fazer a busca (Campo Livre) | Não |
| limit | Limite de resultados | Não |
| status | Informa o status que deseja trazer como retorno | Não |
| order_by | Campo que será utilizado para ordenação | Não |
| order_type | Tipo da Ordenação | Não |
| data_inicio | Data de Início dos resultados | Não |
| data_fim | Data de Fim dos resultados | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| busca | codigo_cliente, cpf_cnpj, id_cliente_servico, numero_ordem_servico | Nenhum |
| termo_busca | Campo livre | Nenhum |
| limit | Valor mínimo 1, Valor máximo 50. | 20 |
| status | pendente,aguardando_agendamento,finalizado | Todos |
| order_by | data_cadastro,data_inicio_programado | data_cadastro |
| order_type | asc,desc | desc |
| data_inicio | Campo no formato DateTime (YYYY-MM-DD). Será aplicado o filtro em cima da data de cadastro | Não |
| data_fim | Campo no formato DateTime (YYYY-MM-DD). Será aplicado o filtro em cima da data de cadastro | Não |
Exemplo de requisição GET na rota do cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/cliente/ordem_servico?busca=codigo_cliente&termo_busca=1188&limit=2 -k
Retorno da requisição GET:
{
"status": "suscess",
"msg": "Dados consultados com sucesso",
"ordens_servico": [
{
"id_ordem_servico": 78,
"numero_ordem_servico": "74",
"data_cadastro": "12/04/2018 15:26:28",
"tipo": "SUPORTE",
"data_inicio_programado": "02/05/2018 10:00:00",
"data_termino_programado": "16/04/2018 12:00:00",
"data_inicio_executado": null,
"data_termino_executado": null,
"descricao_abertura": "cliente reclama de conexão lenta",
"descricao_servico": "CLIENTE TESTE TESTE",
"descricao_fechamento": null,
"usuario_abertura": "Master",
"usuario_fechamento": null,
"status": "aguardando_agendamento",
"status_fechamento": null,
"atendimento": {
"protocolo": "201804121526287",
"id_atendimento": 60,
"tipo_atendimento": "TÉCNICO - CONEXÃO LENTA",
"usuario_abertura": "Master",
"usuario_responsavel": "Guilherme Couto",
"usuario_fechamento": null,
"data_cadastro": "12/04/2018",
"data_fechamento": null,
"setor_responsavel": null,
"status_fechamento": null,
"motivo_fechamento": null
},
"cliente": {
"codigo_cliente": 1188,
"nome_razaosocial": "GUILHERME DA COSTA COUTO - TESTE",
"cpf_cnpj": "26788493090"
},
"servico": {
"numero_plano": 0,
"nome": "100GB-DE-TESTE-",
"valor": 100,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado"
}
},
{
"id_ordem_servico": 102,
"numero_ordem_servico": "96",
"data_cadastro": "19/05/2018 10:17:03",
"tipo": "INSTALAÇÃO",
"data_inicio_programado": "19/05/2018 08:00:00",
"data_termino_programado": "19/05/2018 09:00:00",
"data_inicio_executado": "19/05/2018 11:54:59",
"data_termino_executado": "19/05/2018 11:56:50",
"descricao_abertura": "TESTE TESTE TESTE",
"descricao_servico": "teste teste teste",
"descricao_fechamento": "RT Este de fechamento",
"usuario_abertura": "Master",
"usuario_fechamento": "Master",
"status": "finalizado",
"status_fechamento": "concluido",
"atendimento": {
"protocolo": "201805191017039",
"id_atendimento": 79,
"tipo_atendimento": "TÉCNICO - CONEXÃO LENTA",
"usuario_abertura": "Master",
"usuario_responsavel": "Guilherme Couto",
"usuario_fechamento": null,
"data_cadastro": "19/05/2018",
"data_fechamento": null,
"setor_responsavel": null,
"status_fechamento": null,
"motivo_fechamento": null
},
"cliente": {
"codigo_cliente": 1188,
"nome_razaosocial": "GUILHERME DA COSTA COUTO - TESTE",
"cpf_cnpj": "26788493090"
},
"servico": {
"numero_plano": 6,
"nome": "100GB-DE-TESTE-",
"valor": 100,
"status": "Serviço Habilitado",
"status_prefixo": "servico_habilitado"
}
},
{
"id_ordem_servico": 208,
"numero_ordem_servico": "191",
"data_cadastro": "14/08/2018 16:22:25",
"tipo": "INSTALAÇÃO",
"data_inicio_programado": "14/08/2018 15:00:00",
"data_termino_programado": "14/08/2018 16:00:00",
"data_inicio_executado": null,
"data_termino_executado": null,
"descricao_abertura": "inatalacção",
"descricao_servico": "inatalacção",
"descricao_fechamento": null,
"usuario_abertura": "Suporte",
"usuario_fechamento": null,
"status": "aguardando_agendamento",
"status_fechamento": null,
"atendimento": null,
"cliente": {
"codigo_cliente": 1188,
"nome_razaosocial": "GUILHERME DA COSTA COUTO - TESTE",
"cpf_cnpj": "26788493090"
},
"servico": {
"numero_plano": 7,
"nome": "5MB-WIRELESS",
"valor": 300,
"status": "Aguardando Migração",
"status_prefixo": "aguardando_migracao"
}
},
{
"id_ordem_servico": 209,
"numero_ordem_servico": "192",
"data_cadastro": "14/08/2018 16:24:12",
"tipo": "INSTALAÇÃO",
"data_inicio_programado": "14/08/2018 15:00:00",
"data_termino_programado": "14/08/2018 16:00:00",
"data_inicio_executado": null,
"data_termino_executado": null,
"descricao_abertura": "dsgsdgsdgsd",
"descricao_servico": "dsgsdgsdgsd",
"descricao_fechamento": null,
"usuario_abertura": "Suporte",
"usuario_fechamento": null,
"status": "aguardando_agendamento",
"status_fechamento": null,
"atendimento": null,
"cliente": {
"codigo_cliente": 1188,
"nome_razaosocial": "GUILHERME DA COSTA COUTO - TESTE",
"cpf_cnpj": "26788493090"
},
"servico": {
"numero_plano": 8,
"nome": "5MB-WIRELESS",
"valor": 300,
"status": "Aguardando Migração",
"status_prefixo": "aguardando_migracao"
}
}
]
}
Resetar MAC do Cliente¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/cliente
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/cliente/reset_mac_addr
POST
No método POST, será possível efetuar o desbloqueio em confiança, pela quantidade de dias desejados.
Aviso
IMPORTANTE: O sistema irá validar se o serviço informado possui dados de autenticação. Caso o serviço selecionado não possua, uma mensagem de erro será retornada, impedindo que a solicitação seja executada.
Atributos da Requisição
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_cliente_servico | Identificador único do serviço do cliente | Sim |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_cliente_servico | Deve conter um número inteiro maior que 0 | Nenhum |
Exemplo de requisição POST na rota do desbloqueio em confiança:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/cliente/reset_mac_addr -d '{"id_cliente_servico":"11000"}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_cliente_servico":"11000"
}
Retorno da requisição POST:
{
"status": "success",
"msg": ""Endereço MAC resetado com sucesso!"
}
Financeiro¶
Necessário
Para fazer requisições nos dados de clientes, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/financeiro
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/financeiro
Abaixo estão todas as funções disponíveis do financeiro
Consulta¶
Necessário
Para fazer requisições nos dados de financeiro, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de financeiro, devem ser feitos na rota:
/api/v1/integracao/financeiro
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/financeiro
GET
No método GET, irá consultar os dados financeiros (contas a receber) e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| busca | Tipo de busca que deseja fazer no cliente | Não |
| termo_busca | Termo utilizado para fazer a busca | Não |
| tipo_data | Tipo de data que será utilizada | Não |
| tipo_resultado | Tipo de resultado que será devolvido na resposta | Não |
| data_inicio | Data de início da filtragem de dados | Não |
| data_fim | Data final da filtragem de dados | Não |
| order_by | Campo que será utilizado para ordenação | Não |
| order_type | Tipo de Ordenação | Não |
| limit | Limite de resultados | Não |
| apenas_quitado | Indica o status desejado das faturas | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| busca | id_cliente, codigo_cliente, cpf_cnpj, id_cliente_servico | Nenhum |
| termo_busca | Campo livre (Qualquer valor será aceito) | Nenhum |
| tipo_data | data_vencimento, data_pagamento, data_cadastro | data_vencimento |
| tipo_resultado | simplificado, detalhado | simplificado |
| data_inicio | Campo no formato DateTime (YYYY-MM-DD) | Não |
| data_fim | Campo no formato DateTime (YYYY-MM-DD) | Não |
| order_by | data_vencimento, data_pagamento, data_cadastro, valor | Não |
| order_type | asc, desc | Não |
| limit | Valor número maior que 0 (zero) | Não |
| apenas_quitado | Indica o status desejado das faturas | Não |
Exemplo de requisição GET na rota de cliente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/financeiro -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso.",
"faturas": [
{
"id_fatura": 62636,
"nosso_numero": "1900247",
"data_vencimento": "2020-04-05",
"data_vencimento_br": "05/04/2020",
"data_pagamento": null,
"data_pagamento_br": null,
"data_cadastro": "2020-01-01 12:52:12",
"data_cadastro_br": "01/01/2020",
"valor": "119.9",
"valor_pago": null,
"cliente": {
"id_cliente": 11943,
"codigo_cliente": 1162,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"nome_fantasia": null,
"tipo_pessoa": "pf",
"cpf_cnpj": "41107296617",
"data_nascimento": "1994-03-10",
"data_nascimento_br": "10/03/1994",
"telefone_primario": "37999091234",
"telefone_secundario": "373415100",
"telefone_terciario": null,
"email_principal": "email@cliente.com.b4",
"email_secundario": null,
"data_cadastro": "2017-09-26 13:20:33",
"data_cadastro_br": "26/09/2017 13:20",
"ativo": true
}
},
{
"id_fatura": 62634,
"nosso_numero": "1900245",
"data_vencimento": "2020-04-05",
"data_vencimento_br": "05/04/2020",
"data_pagamento": null,
"data_pagamento_br": null,
"data_cadastro": "2020-01-01 12:52:12",
"data_cadastro_br": "01/01/2020",
"valor": "115.9",
"valor_pago": null,
"cliente": {
"id_cliente": 11943,
"codigo_cliente": 1162,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"nome_fantasia": null,
"tipo_pessoa": "pf",
"cpf_cnpj": "41107296617",
"data_nascimento": "1994-03-10",
"data_nascimento_br": "10/03/1994",
"telefone_primario": "37999091234",
"telefone_secundario": "373415100",
"telefone_terciario": null,
"email_principal": "email@cliente.com.b4",
"email_secundario": null,
"data_cadastro": "2017-09-26 13:20:33",
"data_cadastro_br": "26/09/2017 13:20",
"ativo": true
}
},
{
"id_fatura": 62625,
"nosso_numero": "1900242",
"data_vencimento": "2020-04-05",
"data_vencimento_br": "05/04/2020",
"data_pagamento": null,
"data_pagamento_br": null,
"data_cadastro": "2020-01-01 12:52:12",
"data_cadastro_br": "01/01/2020",
"valor": "169.9",
"valor_pago": null,
"cliente": {
"id_cliente": 11943,
"codigo_cliente": 1162,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"nome_fantasia": null,
"tipo_pessoa": "pf",
"cpf_cnpj": "41107296617",
"data_nascimento": "1994-03-10",
"data_nascimento_br": "10/03/1994",
"telefone_primario": "37999091234",
"telefone_secundario": "373415100",
"telefone_terciario": null,
"email_principal": "email@cliente.com.b4",
"email_secundario": null,
"data_cadastro": "2017-09-26 13:20:33",
"data_cadastro_br": "26/09/2017 13:20",
"ativo": true
}
},
{
"id_fatura": 62628,
"nosso_numero": "212",
"data_vencimento": "2020-04-05",
"data_vencimento_br": "05/04/2020",
"data_pagamento": null,
"data_pagamento_br": null,
"data_cadastro": "2020-01-01 12:52:12",
"data_cadastro_br": "01/01/2020",
"valor": "40.3",
"valor_pago": null,
"cliente": {
"id_cliente": 11943,
"codigo_cliente": 1162,
"nome_razaosocial": "GUILHERME DA COSTA COUTO",
"nome_fantasia": null,
"tipo_pessoa": "pf",
"cpf_cnpj": "41107296617",
"data_nascimento": "1994-03-10",
"data_nascimento_br": "10/03/1994",
"telefone_primario": "37999091234",
"telefone_secundario": "373415100",
"telefone_terciario": null,
"email_principal": "email@cliente.com.b4",
"email_secundario": null,
"data_cadastro": "2017-09-26 13:20:33",
"data_cadastro_br": "26/09/2017 13:20",
"ativo": true
}
}
]
}
No exemplo acima, nenhum parâmetro foi preenchido, sendo assim, o sistema assumiu a data de início como 10 dias anteriores da data atual e a data final como o dia em questão que a requisição está sendo executada. Por exemplo, se essa requisição fosse executada no dia 20/12/2020, então a data de início seria em 10/12/2020 e a data final em 20/12/2020. O sistema só iria traze as faturas que vencem nesse intervalo.
A URL abaixo, está simulando uma consulta, onde o integrador deseja trazer apenas as faturas quitadadas do dia 05/03/2020 ate 10/03/2020, ordenando por data de pagamento de forma decrescente:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/financeiro?data_inicio=2020-03-05&data_fim=2020-03-10&apenas_quitado=sim&tipo_data=data_pagamento&order_by=data_pagamento&order_type=desc
Veja que os atributos foram preenchidos da seguinte forma:
- data_inicio = 2020-03-05 (05/03/2020)
- data_fim = 2020-03-10 (10/03/2020)
- apenas_quitado = sim (Apenas quitado)
- tipo_data = data_pagamento
- order_by = data_pagamento
- order_type = desc (Do maior para o menor)
Aviso
IMPORTANTE: Caso o atributo busca e termo_busca não sejam utilizados, a API irá limitar o intervalo entre a data_inicio e data_fim para no máximo 30 dias. Por exemplo, se o integrador requisitar a data de início 2020-01-01, data fim 2020-12-31 e não utilizar um termo de busca, a quantidade de dados retornado pode ter um volume muito grande, portanto, para esse cenário, será limitado em 30 dias de intervalo entre as datas
Evento de Faturamento¶
Necessário
Para fazer requisições nos dados de financeiro, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de financeiro, devem ser feitos na rota:
/api/v1/integracao/financeiro
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/financeiro/evento_faturamento
POST
No método POST, será possível fazer o cadastro de evento de faturamento. Pode ser cadastrado um evento de Acréscimo ou Desconto, permitindo também parcelamento.
Aviso
IMPORTANTE: É necessário informar o id_cliente_servico e o id_tipo_servico, ambos retornados nas rotas Clientes > Consulta e Tipo de Serviço > All respectivamente
Aviso
IMPORTANTE 2: Ao enviar a o parâmetro parcelado como true, os parâmetros numero_total_parcelas, mes_primeira_parcela e ano_primeira_parcela tornam-se obrigatórios
Aviso
IMPORTANTE 3: Ao enviar a o parâmetro parcelado como false, o parâmetro proximo_faturamento torna-se obrigatório. Caso ele seja enviado como false, os parâmetros mes_processar e ano_processar também deverão ser enviados
Atributos da Requisição
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_cliente_servico | Identificador único do serviço do cliente | Sim |
| id_tipo_servico | Identificador único do tipo de serviço | Sim |
| tipo | Textual (aceita os valores acrescimo e desconto). | Sim |
| descricao | Descrição textual para o evento. | Sim |
| valor | Campo númerico (aceita valor decimal separado por ponto. Ex.: 10.2). | Sim |
| parcelado | Boolean para identificar se o evento é parcelado ou não | Sim |
| numero_total_parcelas | Valor maior que 0 para identificar o total de parcelas | Sim (Se parcelado = true) |
| mes_primeira_parcela | Valor inteiro que representa o mês do ano (Dezembro = 12). Utilizado para verificar o mês da primeira parcela | Sim (Se parcelado = true) |
| ano_primeira_parcela | Valor inteiro que representa o ano. Utilizado para verificar o ano da primeira parcela | Sim (Se parcelado = true) |
| proximo_faturamento | Boolean para identificar se o evento será lançado no próximo faturamento | Sim (Se parcelado = false) |
| mes_processar | Valor inteiro que representa o mês do ano (Dezembro = 12). Utilizado para verificar o mês de processamento do faturamento | Sim (Se proximo_faturamento = false) |
| ano_processar | Valor inteiro que representa o ano. Utilizado para verificar o ano de processamento do faturamento | Sim (Se proximo_faturamento = false) |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_cliente_servico | Deve conter um número inteiro maior que 0 | Nenhum |
| id_tipo_servico | Deve conter um número inteiro maior que 0 | Nenhum |
| tipo | Textual | Nenhum |
| descricao | Textual | Nenhum |
| valor | Número Inteiro/Decimal | Nenhum |
| parcelado | Boolean | Nenhum |
| numero_total_parcelas | Número Inteiro | Nenhum |
| mes_primeira_parcela | Número Inteiro (maior que 0 e menor que 13) | Nenhum |
| ano_primeira_parcela | Número Inteiro | Nenhum |
| proximo_faturamento | Boolean | Nenhum |
| mes_processar | Número Inteiro (maior que 0 e menor que 13) | Nenhum |
| ano_processar | Número Inteiro | Nenhum |
Exemplo de requisição POST na rota do envio de e-mail:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
--header "Content-Type: application/json"
https://endereco_servidor/api/v1/integracao/financeiro/evento_faturamento -d '{"id_cliente_servico":"13579", "id_tipo_servico":"2", "descricao": "ADICIONAL", "parcelado": false, "proximo_faturamento": true, "tipo": "acrescimo", "valor": 10.3}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_cliente_servico": 13579,
"id_tipo_servico": 2,
"descricao": "ADICIONAL",
"parcelado": false,
"proximo_faturamento": true,
"tipo": "acrescimo",
"valor": 10.3
}
Retorno da requisição POST:
{
"status": "success",
"msg": "1 Evento(s) de Farturamento de acréscimo cadastrados com sucesso. VALOR TOTAL: R$ 10.30",
"eventos_faturamento": [
{
"id_evento_faturamento": 1575
}
]
}
Nota
OBSERVAÇÃO: Perceba que foi retornado um array contendo o ID do Evento de Faturamento. Esse retorno é caracterizado pelo fato do evento poder ser parcelado, caso ele tenha 3 parcelas, por exemplo, será retornado um array com 3 itens. Como no exemplo demonstrado acima foi cadastrado um evento sem parcelamento, o array com uma posição foi retornado
Ordem de Serviço¶
Necessário
Para fazer requisições nos dados de ordem de serviço, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de ordem de serviço, devem ser feitos na rota:
/api/v1/integracao/ordem_servico
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/ordem_servico
Abaixo estão todas as funções disponíveis da ordem de serviço
Agendar¶
Necessário
Para fazer requisições nos dados de ordem de serviço, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
A requisição de agendamento da ordem de serviço, deve ser feita na rota:
/api/v1/integracao/ordem_servico/agendar
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/ordem_servico/agendar
Endpoint (Rota)
Neste endpoint, será possível agendar uma O.S. que esteja aguardando agendamento, obtendo o retorno no formato JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_ordem_servico | Identificador da ordem de serviço | Sim |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_ordem_servico | Número Inteiro | Nenhum |
Exemplo de requisição POST na rota de agendamento da ordem de serviço:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/ordem_servico/agendar -d '{"id_ordem_servico":"11000"}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_ordem_servico":"11000"
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Agendamento salvo com sucesso",
"ordem_servico": {
"id_ordem_servico": 1493,
"numero": "1262",
"tipo": "INSTALAÇÃO FIBRA - VALORES OBRIGATÓRIOS: R$ 280.00",
"data_inicio_programado": "2020-11-23 08:00:00",
"data_termino_programado": "2020-11-23 09:30:00",
"data_inicio_executado": null,
"data_termino_executado": null,
"data_cadastro": "2020-11-18 13:35:31",
"descricao_abertura": "TESTE",
"descricao_servico": "TESTE",
"descricao_fechamento": null,
"status": "Pendente",
"tecnicos": [
{
"id": 1,
"name": "Master",
"pivot": {
"id_ordem_servico": 1493,
"id_usuario": 1
}
}
],
"disponibilidade": "Manhã, Tarde",
"cliente": "(1395) GUILHERME COUTO",
"servico": "(1) PLANO 5 MBPS RAP10 E FIXO EM DOBRO",
"endereco_instalacao": "PRAÇA GETÚLIO VARGAS, 77, SALA 411(SHOPPING WORK) - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000"
}
}
Consultar¶
Necessário
Para fazer requisições nos dados de ordem de serviço, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
A requisição de consulta da ordem de serviço, deve ser feita na rota:
/api/v1/integracao/ordem_servico/consultar
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/ordem_servico/agendar
Endpoint (Rota)
Neste endpoint, será possível consultar ordens de serviço, obtendo o retorno no formato JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| consulta | Parametro que será utilizado para encontrar uma O.S. pelo seu número ou nome do cliente | Sim |
| data_inicio | Data inicial de referência para consulta de ordens de serviço em um intervalo | Sim |
| data_fim | Data final de referência para consulta de ordens de serviço em um intervalo | Sim |
| tipo_data | O tipo de data poderá ser: data_cadastro, data_inicio_programado, data_inicio_executado, data_termino_programado, data_termino_executado | Não |
| order_by | A ordenação poderá ser: data_cadastro, data_inicio_programado, data_inicio_executado, data_termino_programado, data_termino_executado | Não |
| order_by_key | A ordenação poderá ser: crescente (ASC) ou decrescenter (DESC) | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_ordem_servico | Número Inteiro | Nenhum |
| consulta | Texto ou número inteiro | Nenhum |
| data_inicio | Formato timestamp (2020-01-01 00:00:00) | Nenhum |
| data_fim | Formato timestamp (2020-01-01 00:00:00) | Nenhum |
| tipo_data | Texto | data_inicio_programado |
| order_by | Texto | data_inicio_programado |
| order_by_key | Texto | desc |
Exemplo de requisição POST na rota de consulta da ordem de serviço:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/ordem_servico/consultar -d
'{
"consulta": "Guilherme",
"data_inicio": "2020-11-01 00:00:00",
"data_fim": "2020-11-20 23:59:59",
"tipo_data": "data_inicio_programado",
"order_by_key": "asc",
"order_by": "data_inicio_programado"
}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"consulta": "Guilherme",
"data_inicio": "2020-11-01 00:00:00",
"data_fim": "2020-11-20 23:59:59",
"tipo_data": "data_inicio_programado",
"order_by_key": "asc",
"order_by": "data_inicio_programado"
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Dados consultados com sucesso",
"ordens_servico": [
{
"id_ordem_servico": 1493,
"numero": "1262",
"tipo": "INSTALAÇÃO FIBRA - VALORES OBRIGATÓRIOS: R$ 280.00",
"data_inicio_programado": "2020-11-18 08:00:00",
"data_termino_programado": "2020-11-18 09:00:00",
"data_inicio_executado": null,
"data_termino_executado": null,
"data_cadastro": "2020-11-18 13:35:31",
"descricao_abertura": "TESTE",
"descricao_servico": "TESTE",
"descricao_fechamento": null,
"status": "Aguardando Agendamento",
"tecnicos": [
{
"id": 4,
"name": "Guilherme Couto",
"pivot": {
"id_ordem_servico": 1493,
"id_usuario": 4
}
}
],
"disponibilidade": "Manhã, Tarde",
"cliente": "(1395) GUILHERME COUTO",
"servico": "(1) PLANO 5 MBPS RAP10 E FIXO EM DOBRO",
"endereco_instalacao": "PRAÇA GETÚLIO VARGAS, 77, SALA 411(SHOPPING WORK) - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000"
}
]
}
Reagendar¶
Necessário
Para fazer requisições nos dados de ordem de serviço, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
A requisição de reagendamento da ordem de serviço, deve ser feita na rota:
/api/v1/integracao/ordem_servico/reagendar
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/ordem_servico/reagendar
Endpoint (Rota)
Neste endpoint, será possível reagendar a ordem de serviço, obtendo o retorno no formato JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_ordem_servico | Identificador da ordem de serviço | Sim |
| data_inicio_programado | Data inicial programada para iniciar a execução da ordem de serviço | Sim |
| hora_inicio_programado | Hora inicial programada para iniciar a execução da ordem de serviço | Sim |
| data_termino_programado | Data final programada para finalizar a execução da ordem de serviço | Sim |
| hora_termino_programado | Hora final programada para finalizar a execução da ordem de serviço | Sim |
| id_usuario_antigo | Identificador do usuário (técnico) responsável pela ordem de serviço | Sim, se o id_usuario_novo for especificado |
| id_usuario_novo | Identificador do usuário (técnico) responsável pela ordem de serviço | Sim, se o id_usuario_antigo for especificado |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_ordem_servico | Número Inteiro | Nenhum |
| data_inicio_programado | Timestamp (2020-01-01) | Nenhum |
| hora_inicio_programado | Texto (12:00:00) | Nenhum |
| data_termino_programado | Texto (2020-01-01) | Nenhum |
| hora_termino_programado | Texto (13:00:00) | Nenhum |
| id_usuario_antigo | Número Inteiro | Nenhum |
| id_usuario_novo | Número Inteiro | Nenhum |
Exemplo de requisição POST na rota de consulta da ordem de serviço:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/ordem_servico/reagendar -d
'{
"id_ordem_servico": "1493",
"data_inicio_programado": "2020-11-23",
"hora_inicio_programado": "08:00:00",
"data_termino_programado": "2020-11-23",
"hora_termino_programado": "09:30:00",
"id_usuario_antigo": 4,
"id_usuario_novo": 1
}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_ordem_servico": "1493",
"data_inicio_programado": "2020-11-23",
"hora_inicio_programado": "08:00:00",
"data_termino_programado": "2020-11-23",
"hora_termino_programado": "09:30:00",
"id_usuario_antigo": 4,
"id_usuario_novo": 1
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Reagendamento salvo com sucesso",
"ordem_servico": {
"id_ordem_servico": 1493,
"numero": "1262",
"tipo": "INSTALAÇÃO FIBRA - VALORES OBRIGATÓRIOS: R$ 280.00",
"data_inicio_programado": "2020-11-23 08:00",
"data_termino_programado": "2020-11-23 09:30",
"data_inicio_executado": null,
"data_termino_executado": null,
"data_cadastro": "2020-11-18 13:35:31",
"descricao_abertura": "TESTE",
"descricao_servico": "TESTE",
"descricao_fechamento": null,
"status": "Pendente",
"tecnicos": [
{
"id": 1,
"name": "Master",
"pivot": {
"id_ordem_servico": 1493,
"id_usuario": 1
}
}
],
"disponibilidade": "Manhã, Tarde",
"cliente": "(1395) GUILHERME COUTO",
"servico": "(1) PLANO 5 MBPS RAP10 E FIXO EM DOBRO",
"endereco_instalacao": "PRAÇA GETÚLIO VARGAS, 77, SALA 411(SHOPPING WORK) - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000"
}
}
Remover Agendamento¶
Necessário
Para fazer requisições nos dados de ordem de serviço, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
A requisição de remoção de agendamento da ordem de serviço, deve ser feita na rota:
/api/v1/integracao/ordem_servico/remove_agendamento
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/ordem_servico/remove_agendamento
Endpoint (Rota)
Neste endpoint, será possível remover o agendamento da ordem de serviço, obtendo o retorno no formato JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| id_ordem_servico | Identificador da ordem de serviço | Sim |
| id_motivo_remocao_agendamento | Identificador do motivo de remoção de agendamento | Sim |
| observacao | Textual (Mínimo de 10 caracteres) | Sim |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| id_ordem_servico | Número Inteiro | Nenhum |
| id_motivo_remocao_agendamento | Número Inteiro | Nenhum |
| observacao | Texto | Nenhum |
Exemplo de requisição POST na rota de consulta da ordem de serviço:
curl -X POST
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/ordem_servico/reagendar -d
'{
"id_ordem_servico": "1493",
"id_motivo_remocao_agendamento": "8",
"observacao": "Cliente pediu para ir no dia seguinte."
}' -k
Veja que os paramêtros enviados na requisição POST devem obedecer a estrutura no formato JSON:
{
"id_ordem_servico": "1493",
"id_motivo_remocao_agendamento": "8",
"observacao": "Cliente pediu para ir no dia seguinte."
}
Retorno da requisição POST:
{
"status": "success",
"msg": "Remoção do agendamento feito com sucesso",
"ordem_servico": {
"id_ordem_servico": 1493,
"numero": "1262",
"tipo": "INSTALAÇÃO FIBRA - VALORES OBRIGATÓRIOS: R$ 280.00",
"data_inicio_programado": "2020-11-23 08:00:00",
"data_termino_programado": "2020-11-23 09:30:00",
"data_inicio_executado": null,
"data_termino_executado": null,
"data_cadastro": "2020-11-18 13:35:31",
"descricao_abertura": "TESTE",
"descricao_servico": "TESTE",
"descricao_fechamento": null,
"status": "Aguardando Agendamento",
"tecnicos": [
{
"id": 1,
"name": "Master",
"pivot": {
"id_ordem_servico": 1493,
"id_usuario": 1
}
}
],
"disponibilidade": "Manhã, Tarde",
"cliente": "(1395) GUILHERME COUTO",
"servico": "(1) PLANO 5 MBPS RAP10 E FIXO EM DOBRO",
"endereco_instalacao": "PRAÇA GETÚLIO VARGAS, 77, SALA 411(SHOPPING WORK) - CENTRO, SANTO ANTÔNIO DO MONTE\/MG | CEP: 35560-000"
}
}
PBX¶
Necessário
Para fazer requisições nas rotas de notificação de ligação do PBX, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de notificação de ligação, devem ser feitos na rota:
/api/v1/integracao/pbx/ligacao/notificar
As requisições de cancelamento de ligação (notificar ligação perdida), devem ser feitos na rota:
/api/v1/integracao/pbx/ligacao/cancelar
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/pbx/ligacao/notificar
https://endereco_do_servidor/api/v1/integracao/pbx/ligacao/cancelar
POST
No método POST, de ambas as rotas poderão ser realizadas as notificações e cancelamento de ligações.
Aviso
IMPORTANTE: Ao realizar a requisição na rota de «notificação», o sistema irá automaticamente abrir uma janela pro usuário de destino, com os dados da chamada: ramal, identificador interno, telefone de origem da ligação. Caso algum cliente tenha sido identificado, será possível abrir o atendimento e já fornecer o protocolo ao cliente, caso contrário terá a opção de consultar um cliente na base. Ao relizar a requisição na rota de «cancelamento» da ligação, a janela de ligação será fechada automaticamente caso ela ainda esteja aberta.
Atributos da Requisição de ambas as rotas
| Atributo | Descrição | Obrigatório |
|---|---|---|
| ramal | Número de ramal correspondente ao usuário | (Obrigatório caso o identificador_interno não seja informado) |
| identificador_interno | ID Interno correspondente ao usuário | (Obrigatório caso o ramal não seja informado) |
| codigo_cliente | Código único do cliente | Não |
| id_cliente | Identificador (chave primária) do cliente | Não |
| telefone | Telefone da ligação externa do PBX | Não |
| ligacao_params | Objeto JSON para serem informados parametros da ligação | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| ramal | Deve ser um valor numérico | Nenhum |
| identificador_interno | Deve ser um valor alfanumérico | Nenhum |
| codigo_cliente | Deve ser um valor númerico e existir na base de dados | Nenhum |
| id_cliente | Deve ser um valor númerico e existir na base de dados | Nenhum |
| telefone | Deve ser um valor númerico | Nenhum |
| ligacao_params | Deve ser um objeto no formato JSON | Nenhum |
Exemplo de requisição POST na rota de notificação de ligação:
curl -X POST https://endereco_servidor/api/v1/integracao/pbx/ligacao/notificar
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjNjN2VjYTY1"
-H "content-type: application/json"
-d '{"ramal": 111, "telefone": 37999912222, "ligacao_params": {"origem": "PBX", "atendente": "João"}}'
Exemplo de requisição POST na rota de cancelamento da ligação:
curl -X POST https://endereco_servidor/api/v1/integracao/pbx/ligacao/cancelar
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjNjN2VjYTY1"
-H "content-type: application/json"
-d '{"ramal": 111, "telefone": 37999912222}'
Retorno da requisição POST notificação de ligação:
{
"status": "success",
"msg": "Ligação notificada com sucesso"
}
Retorno da requisição POST cancelamento de ligação:
{
"status": "success",
"msg": "Ligação cancelada com sucesso"
}
CRM¶
Necessário
Para fazer requisições nos dados de CRM, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação). OBS: Essa rota irá retornar todos os dados de CRM.
As requisições de clientes, devem ser feitos na rota:
/api/v1/integracao/crm/all
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/crm/all
GET
No método GET, irá consultar os dados dos CRM e retornar um JSON como resposta. Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso",
"crms": [
{
"id_crm": 1,
"nome": "CRM - VENDAS"
},
{
"id_crm": 201,
"nome": "TESTE INTEGRACAO API"
}
]
}
Prospectos¶
Necessário
Para fazer requisições nos dados de prospectos, é necessário que você já possua o TOKEN, adquirido na etapa (Autenticação)
Abaixo estão todas as funções disponíveis para o prospecto
All (Todos os Prospectos)¶
Necessário
Para fazer requisições nos dados de prospectos, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação). OBS: Essa rota irá retornar todos os dados de prospectos, caso nenhum parâmetro seja enviado. Utilize com cautela.
As requisições de prospectos, devem ser feitos na rota:
/api/v1/integracao/prospecto/all
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/prospecto/all
GET
No método GET, irá consultar os dados de prospectos e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
| Atributo | Descrição | Obrigatório |
|---|---|---|
| convertido | Retornar prospectos convertidos | Não |
Os atributos podem conter os seguintes valores:
| Atributo | Descrição | Valor Default |
|---|---|---|
| convertido | sim,nao | nao |
Exemplo de requisição GET na rota de prospectos:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/prospecto/all?convertido=sim -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso",
"prospectos": [
{
"id_prospecto": 3,
"nome_razaosocial": "FULANO DE TAL",
"cpf_cnpj": "54691185097",
"email": null,
"telefone": null,
"observacao": null,
"id_cliente": 23360,
"id_endereco_numero": 34934,
"created_at": "2020-02-20 08:52:44",
"updated_at": "2020-02-20 17:53:45",
"tipo_pessoa": "pf",
"id_usuario": 1,
"origem": "web",
"rg": null,
"telefone_secundario": null,
"data_nascimento": null,
"id_vendedor": null,
"id_vencimento": null,
"nome_pai": null,
"nome_mae": null,
"estado_civil": null,
"genero": null,
"nacionalidade": "brasileiro",
"profissao": null,
"created_at_br": "20/02/2020"
}
}
Serviços / Planos Disponíveis¶
Necessário
Para fazer requisições nos dados de serviços / planos disponíveis para prospecto, é necessário que você já possua o TOKEN, adquirido na etapa (Autenticação)
As requisições devem ser feitos na rota:
/api/v1/integracao/prospecto/create?cep=<numero_cep>
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/prospecto/create?cep=35560000
Nota
NOTA: As informações disponíveis na rota em questão são necessárias para a criação de um novo prospecto. Será preciso informar o objeto jSON do serviço / plano, selecionado na interface pelo usuário. Para mais informações, consulte o tópico abaixo.
Cadastrar Prospecto¶
Necessário
Para fazer requisições de cadastro de prospectos, é necessário que você já possua o TOKEN, adquirido na etapa (Autenticação)
As requisições devem ser feitos na rota:
/api/v1/integracao/prospecto
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/prospecto
Rota e corpo (payload) da requisição¶
A rota em questão é do tipo POST e o corpo da requisição deve ter o formato abaixo:
{ "cep": "35560000", "servico": { "id_servico": 1, "valor": 100 }, "cpf_cnpj": "68346567000158", "telefone": "3732818000", "nome_razaosocial": "Empresa XPTO LTDA", "tipo_pessoa": "pj", "bairro": "Centro", "endereco": "Praça Getúlio Vargas", "numero": 77 }
Obrigatoriedade dos campos:
| Campo | Descrição | Obrigatório |
|---|---|---|
| cep | CEP referente ao endereço de instalação | Sim |
| servico.id_servico | Identificador único do serviço / plano de contratação | Sim |
| servico.valor | Valor em reais (R$) do serviço / plano ofertado | Sim |
| nome_razaosocial | Nome ou Razão Social do contratante | Sim |
| cpf_cnpj | CPF ou CNPJ do contratante | Não |
| telefone | Telefone principal do contratante | Sim |
| email principal do contratante | Não | |
| observacao | Campo livre para observações do contratante | Não |
| tipo_pessoa | Informar «pj» para pessoa jurídica ou «pf» para pessoa física | Sim |
| bairro | Bairro referente ao endereço de instalação | Sim |
| endereco | Endereço referente ao local de instalação | Sim |
| numero | Número referente ao endereço de instalação | Sim |
| id_crm | ID referente ao CRM que será vinculado o prospecto | Nao |
- Tipo de valores aceitos pelos campos:
| Campo | Tipo |
|---|---|
| cep | Numérico |
| servico.id_servico | Numérico |
| servico.valor | Numérico |
| nome_razaosocial | Texto |
| cpf_cnpj | Numérico |
| telefone | Numérico |
| Texto | |
| observacao | Texto |
| tipo_pessoa | Texto |
| bairro | Texto |
| endereco | Texto |
| numero | Numérico |
| id_crm | Numérico |
Respostas da requisição¶
As seguintes respostas podem ser obtidas de acordo com o que for informado na rota em questão:
Casos de erro
Em casos de um CPF ou CNPJ já tiver sido cadastrado, a seguinte resposta será obtida:
{ "status": "error", "msg": "O CPF/CNPJ já foi cadastrado antes no prospecto EMPRESA XPTO LTDA" }
Observação ao vincular Prospecto a um CRM
- Caso seja informado o atributo id_crm, o prospecto será vinculado a lista PROSPECTOS-API por padrão.
Casos de sucesso
Um prospecto que atende todos os requisitos, será cadastrado e a seguinte resposta será obtida:
{ "status": "success", "msg": "Prospecto adicionado com sucesso", "prospecto": { "nome_razaosocial": "EMPRESA XPTO LTDA", "telefone": "3732818000", "email": null, "observacao": null, "id_endereco_numero": 33320, "tipo_pessoa": "pj", "cpf_cnpj": "41483316000169", "id_usuario": 1, "origem": "API", "updated_at": "2020-07-28 10:27:56", "created_at": "2020-07-28 10:27:56", "id_prospecto": 100, "created_at_br": "28\/07\/2020", "prospecto_servico": { "id_prospecto_servico": 99, "id_prospecto": 100, "id_servico": 1, "valor": "100" } } }
Rota e parâmetros da requisição¶
A rota em questão é do tipo GET e possui 1 único parâmetro obrigatório que deve ser informado junto a URL, o «cep». O parâmetro deve ser informado no formato de query string, da seguinte forma: ?cep=<numero_cep>. O <numero_cep>, deve ser substituído pelo valor equivalente ao CEP a ser informado para busca de serviços / planos disponíveis.
Respostas da requisição¶
As seguintes respostas podem ser obtidas de acordo com o que for informado na rota em questão:
Casos de erro
Omissão do parâmetro ?cep=<numero_cep> na rota, resultará na resposta:
{ "status": "error", "msg": "CEP não informado." }
Informando um CEP inválido na rota, resultará na resposta:
{ "status": "error", "msg": "Nenhuma cidade foi encontrada com esse CEP." }
Casos de sucesso
Informando um CEP válido na rota, todos os planos / serviços que estiverem associados a uma unidade de negócio referente ao CEP e que estejam habilitados para prospecto, serão retornados com a seguinte resposta:
{ "status": "success", "msg": "Dados consultados com sucesso", "servicos": [ { "id_servico": 1330, "descricao": "COMBO 10 MB EM DOBRO FIXO E 3 CAMERAS RAP10", "valor": 254.9, "nome_radius": "HUBSOFT-SERVICE-1330", "display": "COMBO 10 MB EM DOBRO FIXO E 3 CAMERAS RAP10 - (R$ 254.90) (INATIVO)", "velocidade_download": 20480, "velocidade_upload": 4096 }, { "id_servico": 1308, "descricao": "PLANO 10 MBPS + IP FIXO", "valor": 129.9, "nome_radius": "HUBSOFT-SERVICE-1308", "display": "PLANO 10 MBPS + IP FIXO - (R$ 129.90) (INATIVO)", "velocidade_download": 10240, "velocidade_upload": 2048 }, { "id_servico": 1318, "descricao": "PLANO 10 MBPS RAP10 E FIXO EM DOBRO", "valor": 129.9, "nome_radius": "HUBSOFT-SERVICE-1318", "display": "PLANO 10 MBPS RAP10 E FIXO EM DOBRO - (R$ 129.90) (INATIVO)", "velocidade_download": 20480, "velocidade_upload": 4096 }, { "id_servico": 1319, "descricao": "PLANO 25 MBPS RAP10 E FIXO EM DOBRO", "valor": 169.9, "nome_radius": "HUBSOFT-SERVICE-1319", "display": "PLANO 25 MBPS RAP10 E FIXO EM DOBRO - (R$ 169.90) (INATIVO)", "velocidade_download": 51200, "velocidade_upload": 10240 } ] }
Informando um CEP válido e que não esteja associado a uma unidade de negócio, será retornado todos serviços / planos habilitados para prospecto:
{ "status": "success", "msg": "Dados consultados com sucesso", "servicos": [ { "id_servico": 1303, "descricao": "100-FIBRA-CLONE-TEST", "valor": 100, "nome_radius": "HUBSOFT-SERVICE-1303", "display": "100-FIBRA-CLONE-TEST - (R$ 100.00) (INATIVO)", "velocidade_download": 150000, "velocidade_upload": 35000 }, { "id_servico": 1292, "descricao": "100GB-FIBRA-CLONADO", "valor": 100, "nome_radius": "HUBSOFT-SERVICE-1292", "display": "100GB-FIBRA-CLONADO - (R$ 100.00) (INATIVO)", "velocidade_download": 150000, "velocidade_upload": 35000 }, { "id_servico": 1417, "descricao": "100GB-FIBRA-CLONE-imprimir-carne", "valor": 80, "nome_radius": "HUBSOFT-SERVICE-1417", "display": "100GB-FIBRA-CLONE-imprimir-carne - (R$ 80.00) (INATIVO)", "velocidade_download": 150000, "velocidade_upload": 35000 }, { "id_servico": 1410, "descricao": "100GB-FIBRA-XPTO", "valor": 80, "nome_radius": "HUBSOFT-SERVICE-1410", "display": "100GB-FIBRA-XPTO - (R$ 80.00) (INATIVO)", "velocidade_download": 150000, "velocidade_upload": 35000 }, { "id_servico": 1394, "descricao": "100MB + HBO", "valor": 100, "nome_radius": "HUBSOFT-SERVICE-1394", "display": "100MB + HBO - (R$ 100.00) (INATIVO)", "velocidade_download": 150000, "velocidade_upload": 35000 }, { "id_servico": 1384, "descricao": "100MB-FIBRA + PACOTE", "valor": 100, "nome_radius": "HUBSOFT-SERVICE-1384", "display": "100MB-FIBRA + PACOTE - (R$ 100.00) (INATIVO)", "velocidade_download": 150000, "velocidade_upload": 35000 }, { "id_servico": 1402, "descricao": "200 GB", "valor": 80, "nome_radius": "HUBSOFT-SERVICE-1402", "display": "200 GB - (R$ 80.00) (INATIVO)", "velocidade_download": 150000, "velocidade_upload": 35000 }, { "id_servico": 1272, "descricao": "20MB-TESTE1", "valor": 100, "nome_radius": "HUBSOFT-SERVICE-1272", "display": "20MB-TESTE1 - (R$ 100.00) (INATIVO)", "velocidade_download": 20000, "velocidade_upload": 10000 }, { "id_servico": 1260, "descricao": "2MB_WIRELESS", "valor": 59.9, "nome_radius": "HUBSOFT-SERVICE-1260", "display": "2MB_WIRELESS - (R$ 59.90) (INATIVO)", "velocidade_download": 2000, "velocidade_upload": 800 }, { "id_servico": 1275, "descricao": "30 MB FIBRA PLUS", "valor": 49.9, "nome_radius": "HUBSOFT-SERVICE-1275", "display": "30 MB FIBRA PLUS - (R$ 49.90) (INATIVO)", "velocidade_download": 2000, "velocidade_upload": 640 }, { "id_servico": 1301, "descricao": "5MB CONECTA 2", "valor": 89.9, "nome_radius": "HUBSOFT-SERVICE-1301", "display": "5MB CONECTA 2 - (R$ 89.90) (INATIVO)", "velocidade_download": 5192, "velocidade_upload": 5192 }, { "id_servico": 1, "descricao": "5MB-WIRELESS", "valor": 300, "nome_radius": "HUBSOFT-SERVICE-1", "display": "5MB-WIRELESS - (R$ 300.00) (INATIVO)", "velocidade_download": 7000, "velocidade_upload": 2000 }, { "id_servico": 1251, "descricao": "AOM - CNPJ - 02MB", "valor": 69.9, "nome_radius": "HUBSOFT-SERVICE-1251", "display": "AOM - CNPJ - 02MB - (R$ 69.90) (INATIVO)", "velocidade_download": 2048, "velocidade_upload": 1024 }, { "id_servico": 1330, "descricao": "COMBO 10 MB EM DOBRO FIXO E 3 CAMERAS RAP10", "valor": 254.9, "nome_radius": "HUBSOFT-SERVICE-1330", "display": "COMBO 10 MB EM DOBRO FIXO E 3 CAMERAS RAP10 - (R$ 254.90) (INATIVO)", "velocidade_download": 20480, "velocidade_upload": 4096 }, { "id_servico": 1324, "descricao": "COMBO 50 MB FIXO E 1 CAMERA RAP10", "valor": 274.9, "nome_radius": "HUBSOFT-SERVICE-1324", "display": "COMBO 50 MB FIXO E 1 CAMERA RAP10 - (R$ 274.90) (INATIVO)", "velocidade_download": 51200, "velocidade_upload": 10240 }, { "id_servico": 1308, "descricao": "PLANO 10 MBPS + IP FIXO", "valor": 129.9, "nome_radius": "HUBSOFT-SERVICE-1308", "display": "PLANO 10 MBPS + IP FIXO - (R$ 129.90) (INATIVO)", "velocidade_download": 10240, "velocidade_upload": 2048 }, { "id_servico": 1318, "descricao": "PLANO 10 MBPS RAP10 E FIXO EM DOBRO", "valor": 129.9, "nome_radius": "HUBSOFT-SERVICE-1318", "display": "PLANO 10 MBPS RAP10 E FIXO EM DOBRO - (R$ 129.90) (INATIVO)", "velocidade_download": 20480, "velocidade_upload": 4096 }, { "id_servico": 1319, "descricao": "PLANO 25 MBPS RAP10 E FIXO EM DOBRO", "valor": 169.9, "nome_radius": "HUBSOFT-SERVICE-1319", "display": "PLANO 25 MBPS RAP10 E FIXO EM DOBRO - (R$ 169.90) (INATIVO)", "velocidade_download": 51200, "velocidade_upload": 10240 } ] }
Buscar Prospectos¶
Necessário
Para fazer requisições de busca de prospectos, é necessário que você já possua o TOKEN, adquirido na etapa (Autenticação)
As requisições devem ser feitos na rota:
/api/v1/integracao/prospecto?busca=<valor_busca>
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/prospecto?busca=xpto
Rota e parâmetros da requisição¶
A rota em questão é do tipo GET e é necessário informar o parâmetro busca no formato query string.
Nota
A busca irá funcionar apenas para o campo Nome ou Razão Social no banco de dados do HubSoft.
Respostas da requisição¶
As seguintes respostas podem ser obtidas de acordo com o que for informado na rota em questão:
Casos de erro
Caso o parâmetro de busca seja omitido, a seguinte resposta será obtida:
{ "status": "error", "msg": "O campo busca é obrigatória" }
Casos de sucesso
Caso o a busca encontre algum registro, a seguinte resposta será obtida:
{ "status": "success", "msg": "Dados consultados com sucesso", "prospectos": [ { "id_prospecto": 100, "nome_razaosocial": "EMPRESA XPTO LTDA", "cpf_cnpj": "41483316000169", "email": null, "telefone": "3732818000", "observacao": null, "id_cliente": null, "id_endereco_numero": 33320, "created_at": "2020-07-28 10:27:56", "updated_at": "2020-07-28 10:27:56", "tipo_pessoa": "pj", "id_usuario": 1, "origem": "API", "created_at_br": "28\/07\/2020" } ] }
Rede¶
Necessário
Para fazer requisições nos dados de REDE, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições das rotas de REDE, devem ser feitos na rota:
/api/v1/integracao/rede
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/rede
Abaixo estão todas as funções disponíveis das rotas de Rede
Equipamento¶
Necessário
Para fazer requisições nos dados da API, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de REDE, devem ser feitos na rota:
/api/v1/integracao/rede
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/rede/equipamento
GET
No método GET, será possível consultar os equipamentos que estão cadastrados no sistema:
Exemplo de requisição GET na rota de equipamentos:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/rede/equipamento -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso.",
"equipamentos": [
{
"id_equipamento": 1374,
"nome": "ACCEL-SDT-01",
"ipv4": "10.20.1.80",
"ipv6": null,
"autentica_radius": true,
"modelo": "SERVERU L800",
"tipo": "ROTEADOR",
"fabricante": "SERVERU",
"interfaces": [
{
"id_interface_conexao": 419,
"nome": "VLAN100",
"descricao": "VLAN100",
"tipo": "vlan",
"interface_conexao_roteamento": {
"id_interface_conexao": 419,
"nome": "VLAN100",
"descricao": "VLAN100",
"tipo": "vlan",
"equipamento_conexao": {
"id_equipamento": 1374,
"nome": "ACCEL-SDT-01",
"ipv4": "10.20.1.80",
"ipv6": null
}
}
},
{
"id_interface_conexao": 420,
"nome": "bridge0",
"descricao": "bridge0",
"tipo": "bridge",
"interface_conexao_roteamento": {
"id_interface_conexao": 420,
"nome": "bridge0",
"descricao": "bridge0",
"tipo": "bridge",
"equipamento_conexao": {
"id_equipamento": 1374,
"nome": "ACCEL-SDT-01",
"ipv4": "10.20.1.80",
"ipv6": null
}
}
},
{
"id_interface_conexao": 66,
"nome": "ether1",
"descricao": "",
"tipo": "ethernet",
"interface_conexao_roteamento": {
"id_interface_conexao": 66,
"nome": "ether1",
"descricao": "",
"tipo": "ethernet",
"equipamento_conexao": {
"id_equipamento": 1374,
"nome": "ACCEL-SDT-01",
"ipv4": "10.20.1.80",
"ipv6": null
}
}
},
{
"id_interface_conexao": 386,
"nome": "ether2",
"descricao": null,
"tipo": "ethernet",
"interface_conexao_roteamento": {
"id_interface_conexao": 386,
"nome": "ether2",
"descricao": null,
"tipo": "ethernet",
"equipamento_conexao": {
"id_equipamento": 1374,
"nome": "ACCEL-SDT-01",
"ipv4": "10.20.1.80",
"ipv6": null
}
}
}
]
},
{
"id_equipamento": 1477,
"nome": "AP MIKROTIK",
"ipv4": "10.101.102.103",
"ipv6": null,
"autentica_radius": true,
"modelo": "RB600",
"tipo": "ACCESS POINT",
"fabricante": "MIKROTIK",
"interfaces": [
{
"id_interface_conexao": 571,
"nome": "Wireless01",
"descricao": null,
"tipo": "wireless",
"interface_conexao_roteamento": {
"id_interface_conexao": 419,
"nome": "VLAN100",
"descricao": "VLAN100",
"tipo": "vlan",
"equipamento_conexao": {
"id_equipamento": 1374,
"nome": "ACCEL-SDT-01",
"ipv4": "10.20.1.80",
"ipv6": null
}
}
},
{
"id_interface_conexao": 862,
"nome": "vlan 10",
"descricao": null,
"tipo": "vlan",
"interface_conexao_roteamento": {
"id_interface_conexao": 862,
"nome": "vlan 10",
"descricao": null,
"tipo": "vlan",
"equipamento_conexao": {
"id_equipamento": 1477,
"nome": "AP MIKROTIK",
"ipv4": "10.101.102.103",
"ipv6": null
}
}
}
]
}
]
}
Pop¶
Necessário
Para fazer requisições nos dados da API, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de REDE, devem ser feitos na rota:
/api/v1/integracao/rede
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/rede/pop
GET
No método GET, será possível consultar os POPs e seus equipamentos de conexão que estão cadastrados no sistema:
Exemplo de requisição GET na rota de POP:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/rede/pop -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso.",
"pops": [
{
"id_pop": 51,
"nome": "NOVO POP",
"equipamentos": [
{
"id_equipamento": 1402,
"nome": "NOVO EQUIP CADASTRADO",
"ipv4": "192.168.100.254",
"ipv6": null,
"modelo": "DELL 5524",
"fabricante": "DELL"
}
]
},
{
"id_pop": 53,
"nome": "POP EXEMPLO WIKI",
"equipamentos": [
{
"id_equipamento": 1400,
"nome": "EXEMPLO WIKI",
"ipv4": "10.10.10.100",
"ipv6": null,
"modelo": "RB433AH",
"fabricante": "MIKROTIK"
}
]
},
{
"id_pop": 48,
"nome": "POP TESTE",
"equipamentos": [
{
"id_equipamento": 1413,
"nome": "HUAWEI-NICNET",
"ipv4": "45.4.33.194",
"ipv6": null,
"modelo": "NE20E-S2F",
"fabricante": "HUAWEI"
},
{
"id_equipamento": 1410,
"nome": "OLT BDCOM",
"ipv4": "177.52.48.7",
"ipv6": null,
"modelo": "GP3600-08",
"fabricante": "BDCOM"
},
{
"id_equipamento": 1406,
"nome": "JUNIPER-MX104",
"ipv4": "10.20.1.114",
"ipv6": null,
"modelo": "MX104",
"fabricante": "JUNIPER"
}
]
},
{
"id_pop": 52,
"nome": "POP EXEMPLO",
"equipamentos": []
}
]
}
Nota
OBSERVAÇÃO: Um POP pode conter 0 ou mais equipamentos de conexão associados, de acordo com as configurações estabelecidas no sistema.
Zona de Atendimento¶
Necessário
Para fazer requisições nos dados da API, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de REDE, devem ser feitos na rota:
/api/v1/integracao/rede
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/rede/zona_atendimento
GET
No método GET, será possível consultar as Zonas de Atendimento que estão cadastradas no sistema:
Exemplo de requisição GET na rota de Zonas de Atendimento:
curl -X GET
--header "Accept:application/json"
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O"
https://endereco_servidor/api/v1/integracao/rede/zona_atendimento -k
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso.",
"zonas_atendimento": [
{
"id_zona_atendimento": 12,
"nome": "FIBRA - PIUMHI - A1R3",
"descricao": "ATENDIMENTO FIBRA AREA 1 ROTA 3 EM PIUMHI - TESTE",
"interfaces": [
{
"id_interface_conexao": 355,
"nome": "A1R3_INTELBRAS",
"descricao": null,
"tipo": "gpon",
"equipamento_conexao": {
"nome": "PIU_CHASSI_INTELBRAS_ESCRIT?RIO_02",
"ipv4": "10.37.1.249",
"ipv6": null,
"modelo": "8820G",
"fabricante": "INTELBRAS"
}
}
]
},
{
"id_zona_atendimento": 13,
"nome": "WIRELESS RAUL",
"descricao": "REDE WIRELESS PERTO DO AP RAUL",
"interfaces": [
{
"id_interface_conexao": 51,
"nome": "ath0",
"descricao": null,
"tipo": "wireless",
"equipamento_conexao": {
"nome": "AP_RAUL",
"ipv4": "10.20.72.12",
"ipv6": null,
"modelo": "BULLET2",
"fabricante": "UBIQUITI"
}
}
]
},
{
"id_zona_atendimento": 10,
"nome": "SDT - FIBRA - AREA 9",
"descricao": "AREA 9 DE FIBRA EM SAMONTE",
"interfaces": [
{
"id_interface_conexao": 327,
"nome": "SDT_A9R3_A9R4",
"descricao": null,
"tipo": "epon",
"equipamento_conexao": {
"nome": "FIBERHOME-SDT",
"ipv4": "10.20.14.34",
"ipv6": null,
"modelo": "AN5516-06",
"fabricante": "FIBERHOME"
}
},
{
"id_interface_conexao": 330,
"nome": "Teste Panhaque",
"descricao": null,
"tipo": "epon",
"equipamento_conexao": {
"nome": "FIBERHOME-SDT",
"ipv4": "10.20.14.34",
"ipv6": null,
"modelo": "AN5516-06",
"fabricante": "FIBERHOME"
}
}
]
},
{
"id_zona_atendimento": 14,
"nome": "PIUMHI - FIBRA -A4",
"descricao": "AREA 04 DE FIBRA EM PIUMHI",
"interfaces": [
{
"id_interface_conexao": 353,
"nome": "PIU_A4R1_A4R2",
"descricao": null,
"tipo": "gpon",
"equipamento_conexao": {
"nome": "PIU_CHASSI_INTELBRAS_ARMARIO_RENATO",
"ipv4": "10.37.8.3",
"ipv6": null,
"modelo": "8820G",
"fabricante": "INTELBRAS"
}
}
]
}
]
}
Nota
OBSERVAÇÃO: Uma zona de atendimento poderá conter 0 ou mais interfaces de conexão configuradas. O ideal de se utilizar essa rota da API, é que todas as Interfaces de Conexões, estejam associadas com as Zonas de Atendimento de forma correta. Verifique com o gestor da Rede do provedor, para verificar se todos os cadastros estão corretos.
Tipos de Atendimento¶
Necessário
Para fazer requisições nos dados de tipos de atendimento, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de tipos de atendimento, devem ser feitos na rota:
/api/v1/integracao/configuracao/tipo_atendimento
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/configuracao/tipo_atendimento
Abaixo estão todas as funções disponíveis do cliente
All (Todos os Tipos de Atendimento)¶
Necessário
Para fazer requisições nos dados de tipos de atendimento, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação). OBS: Essa rota irá retornar todos os dados de tipos de atendimento.
As requisições de tipos de atendimento, devem ser feitos na rota:
/api/v1/integracao/configuracao/tipo_atendimento
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/configuracao/tipo_atendimento
GET
No método GET, irá consultar os dados dos tipos de atendimento e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
Exemplo de requisição GET na rota de cliente:
curl --request GET \
--url http://endereco_do_servidor:8000/api/v1/integracao/tipo_atendimento \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O' \
--header 'Content-Type: application/json'
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso",
"tipos_atendimento": [
{
"id_tipo_atendimento": 109,
"descricao": "SEM ACESSO A INTERNET"
},
{
"id_tipo_atendimento": 111,
"descricao": "OSCILAÇÃO\/QUEDAS DE CONEXÃO"
}
],
"encrypted": false
}
Tipos de Serviço¶
Necessário
Para fazer requisições nos dados de tipos de serviço, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação)
As requisições de tipos de serviço, devem ser feitos na rota:
/api/v1/integracao/configuracao/tipo_servico
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/configuracao/tipo_servico
Abaixo estão todas as funções disponíveis do cliente
All (Todos os Tipos de Serviço)¶
Necessário
Para fazer requisições nos dados de tipos de serviço, é necessário que você já possua o TOKEN, conseguido na etapa (Autenticação). OBS: Essa rota irá retornar todos os dados de tipos de serviço.
As requisições de tipos de serviço, devem ser feitos na rota:
/api/v1/integracao/configuracao/tipo_servico
O endereço completo, ficará da seguinte forma:
https://endereco_do_servidor/api/v1/integracao/configuracao/tipo_servico
GET
No método GET, irá consultar os dados dos tipos de serviço e retornar um JSON como resposta. Os seguintes parâmetros podem/devem ser utilizados:
Exemplo de requisição GET na rota de cliente:
curl --request GET \
--url http://endereco_do_servidor:8000/api/v1/integracao/tipo_servico \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0MTM2O' \
--header 'Content-Type: application/json'
Retorno da requisição GET:
{
"status": "success",
"msg": "Dados consultados com sucesso",
"tipos_servico": [
{
"id_tipo_servico": 3,
"descricao": "Taxa de Instalação",
"bloquear": true,
"display": "Taxa de Instalação"
},
{
"id_tipo_servico": 4,
"descricao": "Ordem de Serviço",
"bloquear": true,
"display": "Ordem de Serviço"
}
],
"encrypted": false
}
Exemplos¶
Necessário
Alguns exemplos básicos foram desenvolvidos para facilitar a visualização de uso da API do HubSoft
Abaixo estão listados exemplos em algumas linguagens de programação
JavaScript¶
Nota
OBSERVAÇÃO: O código abaixo é apenas um exemplo para facilitar o desenvolvimento. Em ambiente de produção, o ideal é que faça a separação das funções e se possível faça o desenvolvimento com orientação a objetos (caso a sua linguagem de programação assim permita).
Exemplo de código em JavaScript:
var url = "https://api.dev.hubsoft.com.br/oauth/token";
var data = {
"grant_type":"password",
"client_id":"3",
"client_secret":"ONe7Ns48Y30tBMzneW",
"username":"api@hubsoft.com.br",
"password":"api123api"
};
$.ajax({
type: "POST",
url: url,
data: data,
success: success,
error: error
});
function success(response){
var alerta = 'SUCESSO ---- TOKEN TYPE: ' + response.token_type + ' | ACCESS TOKEN: ' + response.access_token;
alert(alerta);
}
function error(){
alert('error');
}
PHP¶
Nota
OBSERVAÇÃO: O código abaixo é apenas um exemplo para facilitar o desenvolvimento. Em ambiente de produção, o ideal é que faça a separação das funções e se possível faça o desenvolvimento com orientação a objetos (caso a sua linguagem de programação assim permita).
Exemplo de Código em PHP:
/**
* O código abaixo é apenas um exemplo para facilitar o desenvolvimento
* Em ambiente de produção, o ideal é que faça a separação das funções
* e se possível faça o desenvolvimento com orientação a objetos.
*/
function requisicao($url, $method, $body = [], $token = null){
$req = curl_init($url);
$header = array();
$header[] = 'Accept: application/json';
$header[] = 'Content-Type: application/json';
if(!is_null($token)){
$header[] = 'Authorization: ' . $token;
}
curl_setopt($req, CURLOPT_HTTPHEADER, $header);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
if($method == "POST"){
curl_setopt($req, CURLOPT_POST, true );
curl_setopt($req, CURLOPT_POSTFIELDS, http_build_query($body));
}
$respCode = curl_getinfo($req, CURLINFO_HTTP_CODE);
$resp = json_decode(curl_exec($req), true);
curl_close($req);
return $resp;
}
$clientId = "3";
$clientSecret = "ONe7Ns48Y30tBMzneWAwL6hWuh4ze09Jf7qcMsO9";
$username = "api@hubsoft.com.br";
$password = "api123api";
$url = "https://api.dev.hubsoft.com.br";
$urlOauth = $url . "/oauth/token";
$urlCliente = $url . "/api/v1/integracao/cliente?busca=cpf_cnpj&termo_busca=09141806654";
//Body da requisição do oauth
$requestBody = [
"client_id"=>$clientId,
"client_secret"=>$clientSecret,
"username"=>$username,
"password"=>$password,
"grant_type"=>"password"
];
//Faz autorização do oauth
$reqOauth = requisicao($urlOauth, 'POST', $requestBody);
//Armazena os dados pra montar o token (Authorization)
$tokenType = $reqOauth['token_type'];
$accessToken = $reqOauth['access_token'];
//Monta o token Authorization
$authorizationToken = $tokenType . " " . $accessToken;
//Faz requisição do cliente
$reqCliente = requisicao($urlCliente, 'GET', [], $authorizationToken);
//Exibe o resultado da requisição
var_dump($reqCliente);
Dúvidas sobre API do HubSoft!¶
Caso existam dúvidas sobre a utilização da API do HubSoft, estamos à disposição através do e-mail suporte@hubsoft.com.br