# API CRM SmartTalks

A API CRM do SmartTalks fornece endpoints abrangentes para gerenciar entidades CRM (Objetos) e seus registros relacionados (Itens). A API usa autenticação baseada em JWT através do header Authorization.

# Autenticação

Todos os endpoints requerem um header Authorization com um token JWT:

Authorization: Bearer <seu-token-jwt>

# Visão Geral

A API CRM foi projetada para:

  • Leitura de Dados: Operações de leitura (GET) para contatos e objetos personalizados
  • Busca e Filtragem Avançada: Capacidades de busca e filtragem robustas
  • Paginação: Suporte para todos os endpoints de listagem
  • Transformação de Dados: Transformação abrangente e mapeamento de campos
  • Recuperação de Tags: Acesso a tags e metadados de contatos

# URLs Base

Ambiente URL
Produção https://sdm.smarttalks.ai/v1
Desenvolvimento http://localhost:3002/v1

# Tipos de Dados Suportados

O CRM suporta os seguintes tipos de campo:

Tipo ID Descrição
TEXT 1 Campo de texto simples
NUMBER 2 Campo numérico
DATE/SCHEDULE_DATE 3, 41 Data ou data/hora agendada
BOOLEAN 5 Verdadeiro/Falso
OBJECT_ID_MULTIPLE 6 Múltiplas referências a objetos
OBJECT_ID 7 Referência a um objeto
ARRAY 8 Matriz de valores
MASK 9 Campo com máscara de formato
EMAIL 10 Endereço de email
PHONE 11 Número de telefone
NAME 13 Nome (com validação especial)
SELECT 19 Seleção única
SELECT_MULTIPLE 20 Múltiplas seleções
CURRENCY 27 Valor monetário
URL 33 URL
TAGS 38 Etiquetas/Tags

# Modelos de Dados

# Contato

Registro de contato com dados transformados.

Campo Tipo Descrição
id string (UUID) Identificador único do contato
createdAt string (ISO 8601) Timestamp de criação
updatedAt string (ISO 8601) Timestamp da última atualização
favorite boolean Se o contato é marcado como favorito
bookmark boolean Se o contato é marcado com bookmark
Campos adicionais * Campos personalizados definidos no CRM

# Registro (Record)

Registro genérico de um objeto personalizado com dados transformados.

Campo Tipo Descrição
id string (UUID) Identificador único do registro
createdAt string (ISO 8601) Timestamp de criação
updatedAt string (ISO 8601) Timestamp da última atualização
favorite boolean Se o registro é marcado como favorito
bookmark boolean Se o registro é marcado com bookmark
Campos adicionais * Campos personalizados definidos no objeto

# Entidade (Entity)

Definição de entidade (Objeto/Modelo) no CRM.

Campo Tipo Descrição
id string (UUID) Identificador único da entidade
type integer Identificador do tipo de entidade
title string Título legível da entidade
description string Descrição detalhada da entidade
folder string Pasta/categoria para organizar entidades
isSystem boolean Se esta é uma entidade do sistema
showUnits boolean Se deve mostrar unidades para esta entidade
showClient boolean Se deve mostrar informações do cliente
permissions object Configurações de permissão (read, write)
createdAt string (ISO 8601) Timestamp de criação
updatedAt string (ISO 8601) Timestamp da última atualização

# Paginação

Informações de paginação para respostas de listagem.

Campo Tipo Descrição
page integer Número da página atual (começando em 1)
limit integer Número de itens por página
total integer Número total de itens
totalPages integer Número total de páginas

# Endpoints de Contatos

# Listar Contatos

Recupere uma lista paginada de todos os contatos com filtragem, busca e ordenação opcionais.

GET https://sdm.smarttalks.ai/v1/contacts

# Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição Padrão
page integer Não Número da página (começando em 1) 1
limit integer Não Número de itens por página (máx 100) 10
search string Não Busca em campos de texto -
sortBy string Não Campo para ordenar createdAt
sortOrder string Não Direção de ordenação: asc ou desc desc
filters object Não Filtrar por valores de campos específicos (JSON) -

# Comportamento de Busca

  • Busca em campos baseados em texto (TEXT, EMAIL, NAME)
  • Correspondência sem considerar maiúsculas/minúsculas
  • Correspondência parcial de string suportada

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "data": [
      {
        "id": "507f1f77bcf86cd799439011",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "favorite": false,
        "bookmark": false,
        "Name": "John Doe",
        "Email": "john@example.com",
        "Phone": "1234567890",
        "Status": "Active"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 42,
      "totalPages": 5
    }
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/contacts?page=1&limit=10&sortOrder=desc' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Obter Contato por ID

Recupere um único contato por seu identificador único.

GET https://sdm.smarttalks.ai/v1/contacts/{id}

# Parâmetros de Caminho

Parâmetro Tipo Obrigatório Descrição
id string (UUID) Sim Identificador único do contato

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "id": "507f1f77bcf86cd799439011",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "favorite": false,
    "bookmark": false,
    "Name": "John Doe",
    "Email": "john@example.com",
    "Phone": "1234567890",
    "Status": "Active"
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/contacts/507f1f77bcf86cd799439011' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Obter Tags do Contato

Recupere todas as tags associadas a um contato específico.

GET https://sdm.smarttalks.ai/v1/contacts/{id}/tags

# Resolução de Tags

  • Tags são buscadas da API de Autenticação
  • Rótulos de tags são recuperados com base em IDs armazenados no contato
  • Se uma tag não puder ser resolvida, retorna como "Unknown Tag"

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "_id": "507f1f77bcf86cd799439011",
    "tags": [
      {
        "_id": "507f1f77bcf86cd799439012",
        "label": "VIP"
      },
      {
        "_id": "507f1f77bcf86cd799439013",
        "label": "Partner"
      }
    ]
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/contacts/507f1f77bcf86cd799439011/tags' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Endpoints de Objetos

# Listar Objetos

Recupere uma lista paginada de todos os objetos/entidades personalizados no CRM.

GET https://sdm.smarttalks.ai/v1/objects

# Objetos vs Entidades

  • Objetos são as definições de entidade CRM (schemas)
  • Cada objeto pode ter múltiplos registros (items)
  • Objetos definem os campos e estrutura para registros

# Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição Padrão
page integer Não Número da página (começando em 1) 1
limit integer Não Número de itens por página (máx 100) 10
search string Não Busca em título, descrição e campos de pasta -
sortBy string Não Campo para ordenar createdAt
sortOrder string Não Direção de ordenação: asc ou desc desc
type integer Não Filtrar por identificador de tipo de entidade -

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "data": [
      {
        "id": "507f1f77bcf86cd799439011",
        "type": 1,
        "title": "Contacts",
        "description": "List of all contacts",
        "folder": "CRM",
        "isSystem": false,
        "showUnits": false,
        "showClient": false,
        "permissions": {
          "read": [],
          "write": []
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 5,
      "totalPages": 1
    }
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/objects?page=1&limit=10' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Listar Registros de um Objeto

Recupere uma lista paginada de todos os registros (items) de um objeto/entidade específico.

GET https://sdm.smarttalks.ai/v1/objects/{objectId}/records

# Transformação de Dados

  • Valores de campo são transformados automaticamente com base no tipo de campo
  • IDs de campo são convertidos para rótulos de campo
  • Campos SELECT são convertidos de valores de opção para rótulos

# Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição Padrão
objectId string (UUID) Sim Identificador do objeto -
page integer Não Número da página (começando em 1) 1
limit integer Não Número de itens por página (máx 100) 10
search string Não Busca em campos de texto -
sortBy string Não Campo para ordenar createdAt
sortOrder string Não Direção de ordenação: asc ou desc desc
filters object Não Filtrar por valores de campos específicos (JSON) -

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "data": [
      {
        "id": "507f1f77bcf86cd799439011",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "favorite": false,
        "bookmark": false,
        "status": "active",
        "total": 150.50
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 42,
      "totalPages": 5
    }
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/objects/507f1f77bcf86cd799439011/records?page=1&limit=10' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Obter um Registro de um Objeto

Recupere um único registro (item) de um objeto/entidade específico por seu ID.

GET https://sdm.smarttalks.ai/v1/objects/{objectId}/records/{recordId}

# Parâmetros de Caminho

Parâmetro Tipo Obrigatório Descrição
objectId string (UUID) Sim Identificador do objeto
recordId string (UUID) Sim Identificador do registro

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "id": "507f1f77bcf86cd799439011",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "favorite": false,
    "bookmark": false,
    "status": "active",
    "total": 150.50
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/objects/507f1f77bcf86cd799439011/records/507f1f77bcf86cd799439012' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Obter Registros por Campo e Intervalo de Data

Recupere registros de um objeto filtrados por um valor de campo específico e um intervalo de data.

GET https://sdm.smarttalks.ai/v1/objects/{objectId}/records/by-field-and-date

# Filtragem de Campo

  • Suporta correspondência regex/contains sem considerar maiúsculas/minúsculas
  • Correspondência em registros onde o valor do campo especificado contém a string de busca

# Filtragem de Data

  • Usa o timestamp createdAt do registro
  • Filtra registros criados entre as datas de início e fim especificadas (inclusive)

# Casos de Uso

  • Encontrar carrinhos de compra abandonados criados em um período específico
  • Identificar pedidos incompletos com status específicos em um intervalo de datas
  • Gerar relatórios BI para métricas de negócios em um período

# Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição
objectId string (UUID) Sim Identificador do objeto
fieldLabel string Sim Rótulo legível do campo para filtrar
fieldValue string Sim Valor para buscar no campo (suporta regex/contains, sem considerar maiúsculas/minúsculas)
startDate string (ISO 8601) Sim Data/hora de início do intervalo (ex: 2025-11-01T00:00:00Z)
endDate string (ISO 8601) Sim Data/hora de fim do intervalo (ex: 2025-11-30T23:59:59Z)
page integer Não Número da página (começando em 1)
limit integer Não Número de itens por página (máx 100)
sortBy string Não Campo para ordenar
sortOrder string Não Direção de ordenação: asc ou desc

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "data": [
      {
        "id": "507f1f77bcf86cd799439011",
        "createdAt": "2025-11-06T14:30:00Z",
        "updatedAt": "2025-11-06T14:30:00Z",
        "favorite": false,
        "bookmark": false,
        "status": "abandoned",
        "total": 150.50,
        "lastActivity": "2025-11-06T14:15:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 42,
      "totalPages": 5
    }
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/objects/507f1f77bcf86cd799439011/records/by-field-and-date?fieldLabel=status&fieldValue=abandoned&startDate=2025-11-01T00:00:00Z&endDate=2025-11-30T23:59:59Z' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Tratamento de Erros

# Códigos de Status HTTP

Status Descrição
200 Sucesso - Solicitação concluída com sucesso
201 Criado - Recurso criado com sucesso
204 Sem Conteúdo - Sucesso, mas sem corpo na resposta
400 Requisição Inválida - Parâmetros inválidos ou solicitação malformada
401 Não Autorizado - Token de autenticação ausente ou inválido
404 Não Encontrado - Recurso não encontrado
409 Conflito - Violação de restrição de unicidade ou valor duplicado
500 Erro Interno do Servidor - Erro no servidor

# Formato de Resposta de Erro

# Erro de Validação

{
  "status": "validation_error",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "number",
      "path": ["fields", "Email"],
      "message": "Expected string, received number"
    }
  ]
}

# Erro de Aplicação

{
  "status": "application_error",
  "error": "Contact not found",
  "code": "NOT_FOUND",
  "params": {}
}

# Erro de Conflito (Uniqueness)

{
  "status": "application_error",
  "error": "Duplicate value for primary field: Email",
  "code": "UNIQUENESS_ERROR",
  "params": {
    "fieldLabel": "Email"
  }
}

# Erro de Servidor Interno

{
  "status": "internal_server_error",
  "message": "Internal Server Error"
}

# Exemplos de Uso Comuns

# Exemplo 1: Buscar Contatos por Status

Recupere contatos com um status específico:

curl -X GET 'https://sdm.smarttalks.ai/v1/contacts?filters={"Status":"Active"}&limit=20' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exemplo 2: Buscar Contatos com Ordenação

Recupere os contatos mais recentes:

curl -X GET 'https://sdm.smarttalks.ai/v1/contacts?sortBy=createdAt&sortOrder=desc&limit=10' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exemplo 3: Criar Contato com Unidades

Crie um novo contato e atribua unidades:

curl -X POST 'https://sdm.smarttalks.ai/v1/contacts' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": {
      "Name": "Jane Smith",
      "Email": "jane@example.com",
      "Phone": "9876543210",
      "Status": "Prospect"
    },
    "units": ["507f1f77bcf86cd799439011"]
  }'

# Exemplo 4: Encontrar Carrinhos Abandonados

Recupere registros de carrinhos abandonados em um período específico:

curl -X GET 'https://sdm.smarttalks.ai/v1/objects/507f1f77bcf86cd799439011/records/by-field-and-date?fieldLabel=status&fieldValue=abandoned&startDate=2025-11-01T00:00:00Z&endDate=2025-11-30T23:59:59Z&sortOrder=desc' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exemplo 5: Listar Todos os Objetos Personalizados

Obtenha uma lista de todos os objetos personalizados no CRM:

curl -X GET 'https://sdm.smarttalks.ai/v1/objects?page=1&limit=20' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Filtragem e Busca

# Filtros Disponíveis

Todos os endpoints de listagem suportam filtragem com o parâmetro filters:

  • Forneça como objeto JSON com rótulos de campo e valores
  • Suporta correspondência exata
  • Correspondência sem considerar maiúsculas/minúsculas para campos de texto

# Busca por Texto

Use o parâmetro search para busca de texto:

  • Busca em campos baseados em texto
  • Correspondência parcial de string
  • Sem considerar maiúsculas/minúsculas

# Ordenação

Use os parâmetros sortBy e sortOrder:

  • sortBy: Campo para ordenar (padrão: createdAt)
  • sortOrder: asc (crescente) ou desc (decrescente) - padrão: desc

# Paginação

Use os parâmetros page e limit:

  • page: Número da página começando em 1 (padrão: 1)
  • limit: Número de itens por página, máximo 100 (padrão: 10)

# Suporte

Para suporte e dúvidas sobre a API CRM:

  • Email: support@smarttalks.ai
  • Documentação: Consulte este guia para detalhes dos endpoints e exemplos
Last Updated: 11/10/2025, 5:12:27 PM