OmniCRM API

Todas as funções dentro do OmniCRM são acessíveis via API - Não há funcionalidade que esteja disponível apenas na interface do usuário.

Isso permite que você integre o OmniCRM com outros sistemas ou automatize tarefas.

A API é uma API RESTful e está protegida usando múltiplos métodos de autenticação, incluindo tokens JWT, chaves de API e lista de permissões de IP.

A documentação da API é documentada usando Swagger, uma ferramenta que permite fácil leitura, compreensão e teste da funcionalidade da API.

A documentação da API está disponível no seguinte URL:

<https://yourcrm/crm/docs/>

Métodos de Autenticação

O OmniCRM suporta três métodos de autenticação, cada um projetado para casos de uso diferentes:

1. Tokens JWT Bearer - Para sessões de usuários interativas (UI Web, aplicativos móveis)
2. Chaves de API - Para integrações servidor-a-servidor e scripts de automação
3. Lista de Permissões de IP - Para sistemas internos confiáveis (servidores de provisionamento, ferramentas de monitoramento)

Autenticação com Token JWT Bearer

Este é o método de autenticação principal para sessões de usuários. Os usuários fazem login com e-mail e senha, recebem um token JWT e o utilizam para solicitações subsequentes.

Casos de Uso:

• Autenticação na UI Web
• Autenticação em aplicativos móveis
• Acesso programático de curta duração

Como se Autenticar:

Para fazer login, envie um corpo JSON com a seguinte estrutura para /crm/auth/login como uma solicitação POST:

{
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}

A API retornará um objeto JSON contendo um campo token, que é usado para autenticar todas as solicitações futuras. Além disso, a resposta inclui um refresh_token que pode ser usado para atualizar o token quando ele expirar, juntamente com as permissões e funções do usuário.

Você pode testar isso na página do Swagger selecionando o endpoint /auth/login, preenchendo seu Nome de Usuário e Senha, e clicando no botão Try it out.

Para autorizar a sessão, copie o valor do token e clique no botão "Authorize" no canto superior direito da página do Swagger. Cole o token no campo "Value", prefixado por Bearer e clique em "Authorize".

Agora, todas as solicitações subsequentes serão autenticadas com este token.

Autenticação com Chave de API

As chaves de API fornecem autenticação segura e de longa duração para integrações servidor-a-servidor e scripts de automação sem exigir senhas de usuário.

Casos de Uso:

• Sistemas de provisionamento automatizados
• Ferramentas de monitoramento e alerta
• Integração com sistemas externos
• Tarefas agendadas e jobs cron

Como Funcionam as Chaves de API:

As chaves de API são configuradas no arquivo crm_config.yaml e estão associadas a funções e permissões específicas. Cada chave de API é uma string aleatória segura (mínimo 32 caracteres) que autentica solicitações quando passada no cabeçalho X-API-KEY.

Configurando Chaves de API:

As chaves de API devem ser adicionadas ao crm_config.yaml por um administrador com acesso ao servidor:

api_keys:
  your-secure-api-key-here-minimum-32-chars:
    roles:
      - admin
    description: "Sistema de automação de provisionamento"
  another-api-key-for-monitoring-system:
    roles:
      - view_customer
      - view_service
    description: "Monitoramento e alerta"

Usando Chaves de API:

Inclua a chave de API no cabeçalho X-API-KEY de suas solicitações:

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: your-secure-api-key-here-minimum-32-chars"

Exemplo em Python:

import requests

crm_url = 'https://yourcrm.com'
api_key = 'your-secure-api-key-here-minimum-32-chars'

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": api_key
}

# Obter Clientes
response = requests.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)

Melhores Práticas:

• Gere chaves de API usando geradores aleatórios seguros (openssl rand -base64 48)
• Use chaves de API diferentes para sistemas diferentes
• Documente o propósito de cada chave de API no campo description
• Rotacione as chaves de API periodicamente
• Nunca comite chaves de API no controle de versão
• Atribua permissões mínimas necessárias a cada chave de API

Autenticação com Lista de Permissões de IP

A lista de permissões de IP permite que endereços IP específicos acessem a API sem autenticação. Isso é útil para sistemas internos confiáveis em redes privadas.

Casos de Uso:

• Servidores internos de provisionamento
• Sistemas de monitoramento de rede em VLANs de gerenciamento
• Playbooks do Ansible executando em infraestrutura controlada

Configurando a Lista de Permissões de IP:

Adicione endereços IP confiáveis ao crm_config.yaml:

ip_whitelist:
  - 192.168.1.100
  - 10.0.0.0/24
  - 172.16.50.10

Considerações de Segurança:

• Use a lista de permissões de IP apenas em redes privadas e seguras
• Nunca adicione endereços IP públicos à lista de permissões
• Use os intervalos de IP mais específicos possíveis
• Documente por que cada IP está na lista de permissões
• Audite regularmente os IPs na lista de permissões

Exemplos de Chamadas de API com Python

Aqui está um exemplo de como fazer login e recuperar uma lista de clientes usando autenticação com token JWT:

import requests

crm_url = 'https://yourcrm.com'
session = requests.Session()

print("Provisionando dados para o servidor: " + str(crm_url))

headers = {
    "Content-Type": "application/json"
}

# Obter Token de Autenticação
response = session.post(crm_url + '/crm/auth/login', json={
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}, headers=headers)

print(response.status_code)
print(response.json())
assert response.status_code == 200

headers['Authorization'] = 'Bearer ' + response.json()['token']
print("Autenticado no CRM com sucesso")

# Obter Clientes
response = session.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)