Documentação da API

Integre o Devskin CRM com seus sistemas usando nossa API REST poderosa e fácil de usar.

50+
Endpoints
7
Eventos Webhook
99.9%
Uptime
<100ms
Resposta Média
Configure sua API Key para testar os endpoints:
💡 Dica: Obtenha sua API Key no painel admin → API Keys. Clique no botão "Usar API Key" para ativar em todos os testes.

Autenticação

Todas as requisições à API devem incluir uma API Key válida no header Authorization.

Como obter sua API Key:
Acesse o painel admin → API Keys → Criar nova chave 
curl -X GET "https://crm-api.devskin.com/v1/leads" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Escopos de Permissão

Escopo Descrição
leads:read Ler informações de leads
leads:write Criar e atualizar leads
leads:delete Deletar leads
messages:read Ler mensagens
messages:write Enviar mensagens
pipeline:read Ler pipeline
pipeline:write Mover leads no pipeline
campaigns:read Ler campanhas
campaigns:write Criar e gerenciar campanhas

Rate Limits

A API tem limite de 1000 requisições por hora por API Key.

⚠️ Atenção:
Requisições que excederem o limite retornarão status HTTP 429 (Too Many Requests)

Headers de Rate Limit

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

API de Leads

GET /v1/leads

Lista todos os leads com paginação

Parâmetros

Parâmetro Tipo Obrigatório Descrição
page integer Opcional Número da página (padrão: 1)
limit integer Opcional Items por página (padrão: 20, máx: 100)
status string Opcional Filtrar por status 
curl -X GET "https://crm-api.devskin.com/v1/leads?page=1&limit=10" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

Resposta de Exemplo

{
  "data": [
    {
      "id": "lead_123",
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "+5511999999999",
      "status": "NEW",
      "score": 85,
      "createdAt": "2025-01-07T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}
GET /v1/leads/search

Busca leads por email, telefone ou nome

Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição
email string Opcional Email do lead para buscar
phone string Opcional Telefone do lead (com ou sem formatação)
name string Opcional Nome do lead (busca parcial)
⚠️ Importante: Forneça pelo menos um dos parâmetros (email, phone ou name) para realizar a busca. 
curl -X GET "https://crm-api.devskin.com/v1/leads/search?phone=%2B5511999999999" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

💡 Preencha pelo menos um campo para buscar

Resposta de Exemplo

{
  "success": true,
  "data": {
    "id": "lead_123",
    "name": "João Silva",
    "email": "[email protected]",
    "phone": "+5511999999999",
    "company": "Empresa XYZ",
    "status": "NEW",
    "score": 85,
    "tags": ["vip", "high-priority"],
    "createdAt": "2025-01-07T10:00:00Z",
    "updatedAt": "2025-01-07T15:30:00Z"
  }
}
POST /v1/leads

Cria um novo lead

Corpo da Requisição

Campo Tipo Obrigatório Descrição
name string Obrigatório Nome completo do lead
email string Opcional Email do lead
phone string Opcional Telefone do lead 
curl -X POST "https://crm-api.devskin.com/v1/leads" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Santos",
    "email": "[email protected]",
    "phone": "+5511888888888"
  }'

📝 Parâmetros do Teste

PATCH /v1/leads/:id

Atualiza um lead existente

curl -X PATCH "https://crm-api.devskin.com/v1/leads/lead_123" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Santos Silva",
    "status": "CONTACTED"
  }'

📝 Parâmetros do Teste

DELETE /v1/leads/:id

Deleta um lead

curl -X DELETE "https://crm-api.devskin.com/v1/leads/lead_123" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

API de Mensagens

POST /v1/messages

Envia uma mensagem para um lead

Corpo da Requisição

Campo Tipo Obrigatório Descrição
leadId string Obrigatório ID do lead
channel string Obrigatório Canal (whatsapp, email, telegram, instagram)
message string Condicional Conteúdo da mensagem (obrigatório se não usar template)
templateName string Opcional Nome do template WhatsApp Cloud API (substitui message)
templateLanguage string Opcional Idioma do template (ex: pt_BR, en_US). Padrão: pt_BR
templateComponents array Opcional Componentes do template com variáveis substituídas
WhatsApp Cloud API: Após 24h sem resposta do contato, é obrigatório usar templates aprovados pela Meta. Use templateName ao invés de message nesse caso. 
curl -X POST "https://crm-api.devskin.com/v1/messages" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "lead_123",
    "channel": "whatsapp",
    "message": "Olá! Como posso ajudar?"
  }'

📝 Parâmetros do Teste

📞 API de Telefonia

Inicie ligações automaticamente via API. O bot de voz atenderá e conversará com o lead utilizando inteligência artificial.

Requisitos:
Para usar a API de telefonia, você precisa ter um número de telefone configurado e créditos de telefonia disponíveis na sua conta.
POST /v1/telephony/calls/outbound

Inicia uma ligação de saída para um número de telefone

Parâmetros

Parâmetro Tipo Obrigatório Descrição
phoneNumberId string Sim ID do número de telefone de origem (seu número)
toNumber string Sim Número de destino no formato E.164 (ex: +5511999999999)
leadId string Não ID do lead para vincular a ligação (opcional) 
curl -X POST "https://crm-api.devskin.com/v1/telephony/calls/outbound" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: your_project_id" \
  -d '{
    "phoneNumberId": "phn_abc123",
    "toNumber": "+5511999999999",
    "leadId": "lead_xyz789"
  }'

Resposta

{
  "success": true,
  "data": {
    "callId": "call_abc123xyz",
    "callSid": "CA1234567890abcdef",
    "conversationId": "conv_abc123",
    "from": "+5511888888888",
    "to": "+5511999999999",
    "status": "RINGING",
    "leadId": "lead_xyz789"
  },
  "message": "Call initiated successfully"
}

Status da Ligação

Status Descrição
RINGINGLigação em andamento, tocando
IN_PROGRESSLigação atendida, em progresso
COMPLETEDLigação finalizada com sucesso
BUSYNúmero ocupado
NO_ANSWERNão atendeu
FAILEDFalha na ligação
VOICEMAILCaixa postal detectada

Testar Endpoint

GET /v1/telephony/calls

Lista o histórico de ligações

Parâmetros Query

Parâmetro Tipo Obrigatório Descrição
limit number Não Quantidade de registros (padrão: 50)
offset number Não Offset para paginação
status string Não Filtrar por status (COMPLETED, FAILED, etc)
startDate string Não Data inicial (YYYY-MM-DD)
endDate string Não Data final (YYYY-MM-DD) 
curl -X GET "https://crm-api.devskin.com/v1/telephony/calls?limit=20&status=COMPLETED" \
  -H "Authorization: Bearer dsk_your_api_key_here"
GET /v1/telephony/calls/{callId}

Obtém os detalhes de uma ligação específica

curl -X GET "https://crm-api.devskin.com/v1/telephony/calls/call_abc123" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Resposta

{
  "id": "call_abc123xyz",
  "direction": "OUTBOUND",
  "fromNumber": "+5511888888888",
  "toNumber": "+5511999999999",
  "status": "COMPLETED",
  "duration": 145,
  "costBRL": 0.85,
  "recordingUrl": "https://...",
  "transcription": "Olá, tudo bem? ...",
  "leadId": "lead_xyz789",
  "lead": {
    "id": "lead_xyz789",
    "name": "João Silva",
    "phone": "+5511999999999"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "answeredAt": "2024-01-15T10:30:05Z",
  "endedAt": "2024-01-15T10:32:30Z"
}

📝 Parâmetros do Teste

GET /v1/telephony/numbers

Lista seus números de telefone configurados

curl -X GET "https://crm-api.devskin.com/v1/telephony/numbers" \
  -H "Authorization: Bearer dsk_your_api_key_here"
GET /v1/telephony/credits

Consulta o saldo de créditos de telefonia

curl -X GET "https://crm-api.devskin.com/v1/telephony/credits" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Resposta

{
  "hasAccess": true,
  "creditsCents": 15000,
  "creditsBRL": 150.00,
  "creditsFormatted": "R$ 150,00",
  "usage": {
    "minutesThisMonth": 45,
    "callsThisMonth": 12,
    "costThisMonth": 38.50,
    "costThisMonthFormatted": "R$ 38,50"
  },
  "planName": "Pro"
}

API de Pipeline

GET /v1/pipeline/stages

Lista todos os estágios do pipeline

curl -X GET "https://crm-api.devskin.com/v1/pipeline/stages" \
  -H "Authorization: Bearer dsk_your_api_key_here"
POST /v1/pipeline/move

Move um lead para outro estágio

curl -X POST "https://crm-api.devskin.com/v1/pipeline/move" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "lead_123",
    "stageId": "stage_456"
  }'

📝 Parâmetros do Teste

API de Campanhas

GET /v1/campaigns

Lista todas as campanhas

curl -X GET "https://crm-api.devskin.com/v1/campaigns" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

GET /v1/campaigns/:id/stats

Obtém estatísticas de uma campanha

curl -X GET "https://crm-api.devskin.com/v1/campaigns/campaign_123/stats" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

API de Tags

GET /v1/tags

Lista todas as tags do projeto

curl -X GET "https://crm-api.devskin.com/v1/tags" \
  -H "Authorization: Bearer dsk_your_api_key_here"
POST /v1/leads/:id/tags

Adiciona tags a um lead

curl -X POST "https://crm-api.devskin.com/v1/leads/lead_123/tags" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["vip", "high-priority"]
  }'

📝 Parâmetros do Teste

DELETE /v1/leads/:id/tags/:tagId

Remove uma tag de um lead

curl -X DELETE "https://crm-api.devskin.com/v1/leads/lead_123/tags/tag_456" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

Tickets

Gerencie tickets de suporte, categorias e acompanhe SLA.

GET /v1/tickets

Lista todos os tickets do projeto

Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição
status string Opcional OPEN, IN_PROGRESS, WAITING_CUSTOMER, WAITING_INTERNAL, RESOLVED, CLOSED
priority string Opcional LOW, MEDIUM, HIGH, URGENT
categoryId string Opcional Filtrar por categoria
page integer Opcional Número da página (padrão: 1)
limit integer Opcional Items por página (padrão: 20) 
curl -X GET "https://crm-api.devskin.com/v1/tickets?status=OPEN&limit=10" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

Resposta de Exemplo

{
  "tickets": [
    {
      "id": "ticket_123",
      "number": 1,
      "subject": "Problema com login",
      "description": "Não consigo acessar minha conta",
      "status": "OPEN",
      "priority": "HIGH",
      "contactName": "João Silva",
      "contactEmail": "[email protected]",
      "createdAt": "2025-01-07T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}
GET /v1/tickets/:id

Busca um ticket específico pelo ID

curl -X GET "https://crm-api.devskin.com/v1/tickets/ticket_123" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

POST /v1/tickets

Cria um novo ticket de suporte

Body (JSON)

Parâmetro Tipo Obrigatório Descrição
subject string Obrigatório Assunto do ticket
description string Obrigatório Descrição detalhada
priority string Opcional LOW, MEDIUM (padrão), HIGH, URGENT
categoryId string Opcional ID da categoria
contactName string Opcional Nome do contato
contactEmail string Opcional Email do contato
contactPhone string Opcional Telefone do contato
leadId string Opcional ID do lead vinculado 
curl -X POST "https://crm-api.devskin.com/v1/tickets" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Problema com login",
    "description": "Não consigo acessar minha conta desde ontem",
    "priority": "HIGH",
    "contactName": "João Silva",
    "contactEmail": "[email protected]"
  }'

📝 Parâmetros do Teste

PUT /v1/tickets/:id

Atualiza um ticket existente

curl -X PUT "https://crm-api.devskin.com/v1/tickets/ticket_123" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_PROGRESS",
    "priority": "URGENT"
  }'

📝 Parâmetros do Teste

POST /v1/tickets/:id/resolve

Marca o ticket como resolvido

curl -X POST "https://crm-api.devskin.com/v1/tickets/ticket_123/resolve" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

POST /v1/tickets/:id/reopen

Reabre um ticket resolvido ou fechado

curl -X POST "https://crm-api.devskin.com/v1/tickets/ticket_123/reopen" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

POST /v1/tickets/:id/close

Fecha o ticket definitivamente

curl -X POST "https://crm-api.devskin.com/v1/tickets/ticket_123/close" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

GET /v1/tickets/:id/comments

Lista os comentários de um ticket

curl -X GET "https://crm-api.devskin.com/v1/tickets/ticket_123/comments" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

POST /v1/tickets/:id/comments

Adiciona um comentário ao ticket

Body (JSON)

Parâmetro Tipo Obrigatório Descrição
content string Obrigatório Conteúdo do comentário
isInternal boolean Opcional Se true, comentário interno (não visível para cliente) 
curl -X POST "https://crm-api.devskin.com/v1/tickets/ticket_123/comments" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Comentário de teste via API",
    "isInternal": false
  }'

📝 Parâmetros do Teste

GET /v1/tickets/categories

Lista as categorias de tickets

curl -X GET "https://crm-api.devskin.com/v1/tickets/categories" \
  -H "Authorization: Bearer dsk_your_api_key_here"
POST /v1/tickets/categories

Cria uma nova categoria

Body (JSON)

Parâmetro Tipo Obrigatório Descrição
name string Obrigatório Nome da categoria
color string Opcional Cor em hex (ex: #3B82F6)
icon string Opcional Emoji ou nome do ícone
slaFirstResponse integer Opcional SLA primeira resposta em horas
slaResolution integer Opcional SLA resolução em horas 
curl -X POST "https://crm-api.devskin.com/v1/tickets/categories" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Suporte Técnico",
    "color": "#3B82F6",
    "slaFirstResponse": 4,
    "slaResolution": 24
  }'

📝 Parâmetros do Teste

GET /v1/tickets/metrics

Retorna métricas de tickets (total, por status, SLA violados)

curl -X GET "https://crm-api.devskin.com/v1/tickets/metrics" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Resposta de Exemplo

{
  "total": 150,
  "open": 25,
  "inProgress": 30,
  "waitingCustomer": 10,
  "waitingInternal": 5,
  "resolved": 60,
  "closed": 20,
  "slaBreached": 3
}
DELETE /v1/tickets/:id

Exclui um ticket permanentemente

curl -X DELETE "https://crm-api.devskin.com/v1/tickets/ticket_123" \
  -H "Authorization: Bearer dsk_your_api_key_here"

⚠️ Zona de Perigo

POST /v1/tickets/:id/assign

Atribui o ticket a um usuário

Body (JSON)

Parâmetro Tipo Obrigatório Descrição
userId string Obrigatório ID do usuário para atribuir 
curl -X POST "https://crm-api.devskin.com/v1/tickets/ticket_123/assign" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_456"
  }'

📝 Parâmetros do Teste

GET /v1/tickets/:id/activities

Lista o histórico de atividades de um ticket

curl -X GET "https://crm-api.devskin.com/v1/tickets/ticket_123/activities" \
  -H "Authorization: Bearer dsk_your_api_key_here"

📝 Parâmetros do Teste

Resposta de Exemplo

[
  {
    "id": "act_123",
    "type": "STATUS_CHANGED",
    "description": "alterou o status",
    "oldValue": "OPEN",
    "newValue": "IN_PROGRESS",
    "user": {
      "id": "user_456",
      "name": "João Silva"
    },
    "createdAt": "2025-01-07T14:30:00Z"
  }
]

🎯 Etapas do Kanban (Stages)

Configure as etapas do Kanban para organizar seus tickets visualmente.

GET /v1/tickets/stages

Lista todas as etapas do Kanban de tickets

curl -X GET "https://crm-api.devskin.com/v1/tickets/stages" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Resposta de Exemplo

[
  {
    "id": "stage_123",
    "name": "Novos",
    "status": "OPEN",
    "color": "#3B82F6",
    "icon": "circle",
    "order": 1,
    "isDefault": true
  },
  {
    "id": "stage_456",
    "name": "Em Análise",
    "status": "IN_PROGRESS",
    "color": "#F59E0B",
    "icon": "clock",
    "order": 2,
    "isDefault": false
  },
  {
    "id": "stage_789",
    "name": "Resolvidos",
    "status": "RESOLVED",
    "color": "#10B981",
    "icon": "check-circle",
    "order": 3,
    "isDefault": false
  }
]
POST /v1/tickets/stages

Cria uma nova etapa no Kanban

Body (JSON)

Parâmetro Tipo Obrigatório Descrição
name string Obrigatório Nome da etapa
status string Obrigatório OPEN, IN_PROGRESS, WAITING_CUSTOMER, WAITING_INTERNAL, RESOLVED, CLOSED
color string Opcional Cor em hex (ex: #3B82F6)
icon string Opcional Nome do ícone (circle, clock, check-circle, etc.) 
curl -X POST "https://crm-api.devskin.com/v1/tickets/stages" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aguardando Aprovação",
    "status": "WAITING_INTERNAL",
    "color": "#8B5CF6",
    "icon": "pause"
  }'

📝 Parâmetros do Teste

PUT /v1/tickets/stages/:id

Atualiza uma etapa existente

curl -X PUT "https://crm-api.devskin.com/v1/tickets/stages/stage_123" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Em Revisão",
    "color": "#EC4899"
  }'

📝 Parâmetros do Teste

DELETE /v1/tickets/stages/:id

Exclui uma etapa (tickets serão movidos para etapa padrão)

curl -X DELETE "https://crm-api.devskin.com/v1/tickets/stages/stage_123" \
  -H "Authorization: Bearer dsk_your_api_key_here"

⚠️ Zona de Perigo

PUT /v1/tickets/stages/reorder

Reordena as etapas do Kanban

Body (JSON)

Parâmetro Tipo Obrigatório Descrição
stageIds array Obrigatório Array de IDs das etapas na nova ordem 
curl -X PUT "https://crm-api.devskin.com/v1/tickets/stages/reorder" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "stageIds": ["stage_456", "stage_123", "stage_789"]
  }'

📝 Parâmetros do Teste

📁 Gerenciamento de Categorias

PUT /v1/tickets/categories/:id

Atualiza uma categoria existente

curl -X PUT "https://crm-api.devskin.com/v1/tickets/categories/cat_123" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Suporte Premium",
    "slaFirstResponse": 2,
    "slaResolution": 24
  }'

📝 Parâmetros do Teste

DELETE /v1/tickets/categories/:id

Exclui uma categoria (tickets serão movidos para "sem categoria")

curl -X DELETE "https://crm-api.devskin.com/v1/tickets/categories/cat_123" \
  -H "Authorization: Bearer dsk_your_api_key_here"

⚠️ Zona de Perigo

API de Mensagens Agendadas

Agende mensagens para serem enviadas automaticamente em uma data/hora específica via WhatsApp, Email ou Ligação.

POST /v1/scheduled-messages

Criar uma nova mensagem agendada

Corpo da Requisição

Campo Tipo Obrigatório Descrição
channel string Obrigatório Canal: WHATSAPP, EMAIL ou CALL
content string Obrigatório Conteúdo da mensagem (não obrigatório para templates)
scheduledFor string Obrigatório Data/hora no formato ISO: 2025-01-15T14:30:00
leadId string Opcional ID do lead (extrai telefone/email automaticamente)
toPhone string Opcional Número de telefone destino
toEmail string Opcional Email destino (para canal EMAIL)
subject string Opcional Assunto (obrigatório para canal EMAIL)
templateName string Opcional Nome do template WhatsApp (Cloud API)
templateLanguage string Opcional Idioma do template (ex: pt_BR)
templateComponents array Opcional Componentes do template com variáveis preenchidas
timezone string Opcional Timezone (padrão: America/Sao_Paulo) 
# Mensagem simples
curl -X POST "https://crm-api.devskin.com/v1/scheduled-messages" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "WHATSAPP",
    "content": "Olá {{name}}, lembrando da nossa reunião amanhã às 10h!",
    "scheduledFor": "2025-01-15T09:00:00",
    "leadId": "lead_abc123"
  }'

# Com template WhatsApp Cloud API
curl -X POST "https://crm-api.devskin.com/v1/scheduled-messages" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "WHATSAPP",
    "scheduledFor": "2025-01-15T09:00:00",
    "leadId": "lead_abc123",
    "templateName": "follow_up",
    "templateLanguage": "pt_BR",
    "templateComponents": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" },
          { "type": "text", "text": "Empresa XYZ" }
        ]
      }
    ]
  }'

Resposta de Exemplo

{
  "id": "sm_abc123",
  "channel": "WHATSAPP",
  "content": "Olá João, lembrando da nossa reunião amanhã às 10h!",
  "scheduledFor": "2025-01-15T09:00:00.000Z",
  "status": "PENDING",
  "toPhone": "+5511999999999",
  "toName": "João Silva",
  "createdAt": "2025-01-14T15:30:00.000Z"
}

📝 Parâmetros do Teste

GET /v1/scheduled-messages

Listar mensagens agendadas

Parâmetros

Parâmetro Tipo Obrigatório Descrição
status string Opcional Filtrar por status: PENDING, SENT, FAILED, CANCELLED
channel string Opcional Filtrar por canal: WHATSAPP, EMAIL, CALL
leadId string Opcional Filtrar por lead específico 
curl -X GET "https://crm-api.devskin.com/v1/scheduled-messages?status=PENDING" \
  -H "Authorization: Bearer dsk_your_api_key_here"
DELETE /v1/scheduled-messages/{id}

Cancelar mensagem agendada (apenas PENDING)

curl -X DELETE "https://crm-api.devskin.com/v1/scheduled-messages/sm_abc123" \
  -H "Authorization: Bearer dsk_your_api_key_here"

⚠️ Zona de Perigo

API de Templates WhatsApp

Gerencie templates de mensagem do WhatsApp Cloud API. Templates são necessários para iniciar conversas após 24h sem resposta do contato.

💡 Regra das 24h:
O WhatsApp Cloud API exige que mensagens enviadas após 24h sem resposta do contato utilizem templates aprovados pela Meta. Mensagens de texto livre só podem ser enviadas dentro da janela de 24h após a última mensagem recebida do contato.
GET /v1/whatsapp/cloud/templates

Listar templates do WhatsApp Cloud API

Parâmetros

Parâmetro Tipo Obrigatório Descrição
status string Opcional Filtrar por status: APPROVED, PENDING, REJECTED 
curl -X GET "https://crm-api.devskin.com/v1/whatsapp/cloud/templates?status=APPROVED" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Resposta de Exemplo

{
  "templates": [
    {
      "id": "tpl_abc123",
      "name": "follow_up",
      "language": "pt_BR",
      "status": "APPROVED",
      "category": "MARKETING",
      "components": [
        {
          "type": "BODY",
          "text": "Olá {{1}}, tudo bem? Gostaria de conversar sobre {{2}}."
        }
      ]
    }
  ]
}
POST /v1/whatsapp/cloud/templates

Criar novo template (envia para aprovação da Meta)

Corpo da Requisição

Campo Tipo Obrigatório Descrição
name string Obrigatório Nome único (lowercase, underscores, sem espaços)
category string Obrigatório MARKETING, UTILITY ou AUTHENTICATION
language string Obrigatório Código do idioma (pt_BR, en_US, etc.)
body string Obrigatório Texto do corpo (use {{1}}, {{2}} para variáveis)
header string Opcional Texto do cabeçalho
footer string Opcional Texto do rodapé 
curl -X POST "https://crm-api.devskin.com/v1/whatsapp/cloud/templates" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "follow_up_call",
    "category": "UTILITY",
    "language": "pt_BR",
    "body": "Olá {{1}}, tudo bem? Notamos que você se interessou por {{2}}. Podemos agendar uma conversa para esclarecer suas dúvidas?"
  }'
⚠️ Atenção:
Templates enviados passam por revisão da Meta e podem levar de algumas horas a alguns dias para serem aprovados. Use a API de listagem para verificar o status.

📝 Parâmetros do Teste

DELETE /v1/whatsapp/cloud/templates/{name}

Deletar template

curl -X DELETE "https://crm-api.devskin.com/v1/whatsapp/cloud/templates/follow_up" \
  -H "Authorization: Bearer dsk_your_api_key_here"

⚠️ Zona de Perigo

POST /v1/timeline/whatsapp

Enviar mensagem de template para um lead

Corpo da Requisição

Campo Tipo Obrigatório Descrição
leadId string Obrigatório ID do lead
templateName string Obrigatório Nome do template aprovado
templateLanguage string Obrigatório Idioma do template (pt_BR)
templateComponents array Opcional Valores das variáveis do template 
curl -X POST "https://crm-api.devskin.com/v1/timeline/whatsapp" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "lead_abc123",
    "templateName": "follow_up",
    "templateLanguage": "pt_BR",
    "templateComponents": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" },
          { "type": "text", "text": "nosso produto XYZ" }
        ]
      }
    ]
  }'

Resposta de Exemplo

{
  "success": true,
  "messageId": "wamid.HBgLNTUxMTk5OTk5OTkVAgASGCA2N...",
  "template": "follow_up",
  "status": "sent"
}

📝 Parâmetros do Teste

Variáveis de Template

Templates do WhatsApp Cloud API usam variáveis no formato {{1}}, {{2}}, etc. Ao enviar uma mensagem, você deve fornecer os valores na ordem correta através do templateComponents.

Mapeamento de Variáveis Sugerido

Variável Uso Comum Campo do Lead
{{1}} Nome do contato lead.name ou lead.firstName
{{2}} Empresa lead.company
{{3}} Produto/Serviço Texto customizado
{{4}} Data/Hora Data formatada
💡 Dica:
Na interface do CRM, o mapeamento de variáveis é feito automaticamente através de um seletor visual que conecta as variáveis do template aos campos do lead.

API de Campos Personalizados

Configure campos personalizados para leads e oportunidades através do painel admin. Use a API para consultar as configurações e incluir valores nos seus leads/oportunidades.

Configuração:
Os campos personalizados são configurados no painel admin → Campos Personalizados. Esta API permite consultar as configurações e usar os campos na criação/atualização de leads e oportunidades.
GET /v1/admin/custom-fields

Lista todas as configurações de campos personalizados

Parâmetros

Parâmetro Tipo Obrigatório Descrição
entityType string Opcional Filtrar por tipo: LEAD, OPPORTUNITY, ou BOTH 
curl -X GET "https://crm-api.devskin.com/v1/admin/custom-fields?entityType=LEAD" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Resposta de Exemplo

{
  "fields": [
    {
      "id": "cf_123",
      "name": "CNPJ",
      "key": "CNPJ",
      "type": "TEXT",
      "entityType": "BOTH",
      "required": true,
      "defaultValue": null,
      "description": "CNPJ da empresa",
      "showInQuote": true,
      "order": 1
    },
    {
      "id": "cf_124",
      "name": "Contrato",
      "key": "CONTRATO",
      "type": "FILE",
      "entityType": "OPPORTUNITY",
      "required": false,
      "defaultValue": null,
      "description": "Arquivo do contrato assinado",
      "showInQuote": false,
      "order": 2
    }
  ]
}

Tipos de Campo Suportados

Tipo Descrição Exemplo de Valor
TEXT Texto curto (até 255 caracteres) "12.345.678/0001-90"
TEXTAREA Texto longo (múltiplas linhas) "Observações detalhadas..."
NUMBER Número inteiro ou decimal 1500.50
DATE Data no formato ISO "2025-01-15"
SELECT Seleção de opções predefinidas "Opção A"
FILE Arquivo (PDF, imagem, etc.) {"url": "...", "name": "contrato.pdf"}
POST /v1/leads

Criar lead com campos personalizados

curl -X POST "https://crm-api.devskin.com/v1/leads" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "[email protected]",
    "phone": "+5511999999999",
    "company": "Empresa XYZ",
    "customFields": {
      "CNPJ": "12.345.678/0001-90",
      "NUMERO_FUNCIONARIOS": 50,
      "DATA_FUNDACAO": "2020-05-15",
      "SETOR": "Tecnologia"
    }
  }'

Resposta de Exemplo

{
  "id": "lead_abc123",
  "name": "João Silva",
  "email": "[email protected]",
  "phone": "+5511999999999",
  "company": "Empresa XYZ",
  "customFields": {
    "CNPJ": "12.345.678/0001-90",
    "NUMERO_FUNCIONARIOS": 50,
    "DATA_FUNDACAO": "2020-05-15",
    "SETOR": "Tecnologia"
  },
  "createdAt": "2025-01-15T10:30:00Z"
}

📝 Parâmetros do Teste

POST /v1/opportunities

Criar oportunidade com campos personalizados

curl -X POST "https://crm-api.devskin.com/v1/opportunities" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Proposta Comercial - Empresa XYZ",
    "leadId": "lead_abc123",
    "value": 50000,
    "customFields": {
      "PRAZO_ENTREGA": "30 dias",
      "CONDICAO_PAGAMENTO": "30/60/90",
      "GARANTIA": "12 meses"
    }
  }'

📝 Parâmetros do Teste

POST /v1/attachments/custom-field

Upload de arquivo para campo personalizado do tipo FILE

Corpo da Requisição (multipart/form-data)

Campo Tipo Obrigatório Descrição
file file Obrigatório Arquivo a ser enviado (máx 10MB)
fieldKey string Obrigatório Chave do campo personalizado
entityType string Opcional Tipo de entidade (LEAD ou OPPORTUNITY) 
curl -X POST "https://crm-api.devskin.com/v1/attachments/custom-field" \
  -H "Authorization: Bearer dsk_your_api_key_here" \
  -F "file=@/path/to/contrato.pdf" \
  -F "fieldKey=CONTRATO" \
  -F "entityType=OPPORTUNITY"

Resposta de Exemplo

{
  "url": "https://s3.amazonaws.com/.../contrato-123456.pdf",
  "name": "contrato.pdf",
  "size": 245678,
  "mimeType": "application/pdf"
}
💡 Dica:
Após o upload, use a resposta como valor do campo personalizado ao criar/atualizar o lead ou oportunidade. Armazene o objeto JSON completo no campo.
GET /v1/admin/custom-fields/defaults

Obtém os valores padrão configurados para campos personalizados

Parâmetros

Parâmetro Tipo Obrigatório Descrição
entityType string Opcional Filtrar por tipo: LEAD ou OPPORTUNITY 
curl -X GET "https://crm-api.devskin.com/v1/admin/custom-fields/defaults?entityType=LEAD" \
  -H "Authorization: Bearer dsk_your_api_key_here"

Resposta de Exemplo

{
  "defaults": {
    "PRAZO_PAGAMENTO": "30 dias",
    "GARANTIA": "12 meses",
    "FRETE": "FOB"
  }
}

Webhooks

Webhooks permitem que você receba notificações em tempo real quando eventos ocorrem no sistema.

Como Configurar:
Acesse o painel admin → Webhooks → Criar novo webhook e selecione os eventos que deseja receber.

Eventos Disponíveis

lead.created
Disparado quando um novo lead é criado
lead.updated
Disparado quando um lead é atualizado
lead.moved
Disparado quando um lead é movido para outro estágio
message.sent
Disparado quando uma mensagem é enviada para um lead
message.received
Disparado quando uma mensagem é recebida de um lead
campaign.completed
Disparado quando uma campanha é concluída

🎫 Eventos de Tickets

ticket.created
Disparado quando um novo ticket é criado
ticket.updated
Disparado quando um ticket é atualizado (status, prioridade, categoria, etc.)
ticket.assigned
Disparado quando um ticket é atribuído a um agente
ticket.resolved
Disparado quando um ticket é marcado como resolvido
ticket.reopened
Disparado quando um ticket fechado/resolvido é reaberto
ticket.closed
Disparado quando um ticket é fechado definitivamente

📞 Eventos de Ligações

call.initiated
Disparado quando uma ligação é iniciada (entrada ou saída)
call.answered
Disparado quando uma ligação é atendida
call.completed
Disparado quando uma ligação é finalizada com sucesso
call.failed
Disparado quando uma ligação falha (ocupado, não atendeu, erro)
call.voicemail
Disparado quando uma ligação cai na caixa postal

Segurança dos Webhooks

Todos os webhooks são assinados com HMAC-SHA256 para garantir autenticidade.

Validando Assinatura

const crypto = require('crypto');

function validateWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === expectedSignature;
}

// Uso
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-devskin-signature'];
  const secret = 'your_webhook_secret';

  if (!validateWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Processar webhook
  console.log('Evento:', req.body.event);
  console.log('Dados:', req.body.data);

  res.status(200).send('OK');
});

Lógica de Retry

Se seu endpoint retornar um erro (status 4xx ou 5xx), tentaremos reenviar automaticamente:

  • 1ª tentativa: imediata
  • 2ª tentativa: após 1 minuto
  • 3ª tentativa: após 5 minutos