Documentação da API

Integre seu site ou aplicação com o CRM SERGEST

Quick Start

Comece a integrar em menos de 5 minutos. Você só precisa de três coisas:
1
Gere suas credenciais
Acesse a área de desenvolvedor e gere seu Client ID e Secret
2
Registre sua aplicação
Crie uma aplicação com um nome único para identificar suas requisições
3
Faça sua primeira requisição
Use os exemplos abaixo para criar seu primeiro contato

1. Endpoints da API

Criar Contato
POST
https://crm.softsergest.com/api/crm/contacts/:clientId
Criar Ticket
POST
https://crm.softsergest.com/api/crm/tickets/:clientId
Enviar Email
POST
https://crm.softsergest.com/api/crm/emails/:clientId
Enviar Mensagem WhatsApp
POST
https://crm.softsergest.com/api/crm/whatsapp/:clientId

2. Headers Obrigatórios

Content-TypeObrigatório
Deve ser exatamente: application/json⚠️ Sem este header, o body não será parseado corretamente
x-api-keyObrigatório
Seu Secret (API Key) gerado na área de desenvolvedor
application_nameObrigatório
Nome exato da aplicação registrada (case-sensitive)

3. Campos do Body - Contatos

⚠️ Erro comum:Não envie o JSON como string. O body deve ser um objeto JSON direto.
❌ ERRADO: body: JSON.stringify(data)
✅ CORRETO: body: data (objeto direto)

3.1. Campos do Body - Tickets

⚠️ Erro comum:Não envie o JSON como string. O body deve ser um objeto JSON direto.
❌ ERRADO: body: JSON.stringify(data)
✅ CORRETO: body: data (objeto direto)

3.3. Campos do Body - WhatsApp

Tipos de Mensagem:
Tipo: "texto"
  • Envia uma mensagem de texto simples
  • Campo mensagem é obrigatório
  • Campo codigo não é usado
Tipo: "otp"
  • Envia um código OTP com botão interativo
  • Campo codigo é obrigatório (4-8 dígitos)
  • Campo mensagem é opcional (padrão usado se não fornecido)

3.2. Campos do Body - Emails

4. Resposta de Sucesso

Status: 201 Created
{
  "success": true,
  "message": "Contato criado com sucesso",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "nome": "João Silva",
    "email": "joao@example.com",
    "telefone": "+244923456789",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

5. Códigos de Erro e Troubleshooting

401Não autorizado
Client ID, API Key ou Application Name inválidos. Verifique suas credenciais.• Verifique se o Client ID está correto na URL
• Confirme que o x-api-key corresponde ao Secret gerado
• O application_name deve ser exatamente igual ao nome registrado (case-sensitive)
400Dados inválidos / Bad Request
Erro comum: "property '..." should not exist" ou "email must be an email"Soluções:
  • Certifique-se de enviar Content-Type: application/json no header
  • O body deve ser um objeto JSON, não uma string JSON
  • Com Fetch: use JSON.stringify(data) no body
  • Com Axios: envie o objeto diretamente (Axios faz JSON.stringify automaticamente)
  • Verifique se o email é válido (formato correto)
  • Para tickets: assunto e descricao são obrigatórios
404Client ID não encontrado
O Client ID fornecido na URL não existe ou não está ativo. Verifique na área de desenvolvedor.
💡 Dicas para evitar erros:
  • Sempre inclua o header Content-Type: application/json
  • Use ferramentas como Postman ou Insomnia para testar antes de integrar
  • Verifique os logs do servidor para mensagens de erro mais detalhadas
  • Teste com o exemplo mínimo primeiro (apenas email para contatos)

Exemplos de Código

JavaScript (Fetch)
// Exemplo usando Fetch API - Criar Contato
// ⚠️ IMPORTANTE: Sempre envie Content-Type: application/json
const createContact = async (contactData) => {
  const response = await fetch('https://crm.softsergest.com/api/crm/contacts/seu_client_id_aqui', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json', // ⚠️ OBRIGATÓRIO
      'x-api-key': 'SEU_SECRET_AQUI',
      'application_name': 'NomeDaSuaAplicacao'
    },
    body: JSON.stringify(contactData) // JSON.stringify é necessário aqui
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Erro ao criar contato');
  }

  const result = await response.json();
  return result;
};

// Uso - Criar Contato
createContact({
  email: 'joao@example.com',  // Obrigatório
  nome: 'João Silva',         // Opcional
  telefone: '+244923456789',  // Opcional
  empresa: 'Empresa XYZ',     // Opcional
  observacoes: 'Interessado em nossos serviços'  // Opcional
}).then(data => {
}).catch(error => {
});

// Exemplo - Criar Ticket
// ⚠️ IMPORTANTE: Sempre envie Content-Type: application/json
const createTicket = async (ticketData) => {
  const response = await fetch('https://crm.softsergest.com/api/crm/tickets/seu_client_id_aqui', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json', // ⚠️ OBRIGATÓRIO
      'x-api-key': 'SEU_SECRET_AQUI',
      'application_name': 'NomeDaSuaAplicacao'
    },
    body: JSON.stringify(ticketData) // JSON.stringify é necessário aqui
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Erro ao criar ticket');
  }

  const result = await response.json();
  return result;
};

// Uso - Criar Ticket
createTicket({
  email: 'cliente@example.com',  // Obrigatório se clienteId não for fornecido
  nome: 'Nome do Cliente',        // Obrigatório se clienteId não for fornecido
  assunto: 'Problema com conexão', // Obrigatório
  descricao: 'Estou tendo problemas...', // Obrigatório
  prioridade: 2  // Opcional: 1-Alta, 2-Média, 3-Baixa
}).then(data => {
}).catch(error => {
});

// Exemplo - Enviar Email
const sendEmail = async (emailData) => {
  const response = await fetch('https://crm.softsergest.com/api/crm/emails/seu_client_id_aqui', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json', // ⚠️ OBRIGATÓRIO
      'x-api-key': 'SEU_SECRET_AQUI',
      'application_name': 'NomeDaSuaAplicacao'
    },
    body: JSON.stringify(emailData) // JSON.stringify é necessário aqui
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Erro ao enviar email');
  }

  const result = await response.json();
  return result;
};

// Uso - Enviar Email
sendEmail({
  to: 'destinatario@example.com',  // Obrigatório
  subject: 'Assunto do Email',      // Obrigatório
  html: '<html><body><h1>Olá!</h1><p>Este é um email de teste.</p></body></html>', // Obrigatório
  cc: ['copia@example.com'],        // Opcional
  bcc: ['oculto@example.com']      // Opcional
}).then(data => {
}).catch(error => {
});