# 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
clientId string | null Presente em registros de objetos que não são contatos. Id do contato vinculado ao registro (o mesmo clientId do relatório de interações). null se não houver vínculo
responsibles array Usuários responsáveis pelo registro (o responsável pelo card no pipeline), na ordem em que estão no card. Cada item tem id (string) e name (string | null). Lista vazia se o registro não tiver responsável. name vem null se o usuário estiver desativado ou tiver sido removido, ou se o nome não puder ser consultado no momento; o id sempre vem
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) -
clientId string (24 hex) Não Retorna apenas os registros vinculados a esse contato. Sempre combinado com o escopo de acesso do próprio token -

# 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,
        "clientId": "507f1f77bcf86cd799439013",
        "responsibles": [
          { "id": "507f1f77bcf86cd799439021", "name": "Ana Souza" }
        ],
        "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,
    "responsibles": [
      { "id": "507f1f77bcf86cd799439021", "name": "Ana Souza" }
    ],
    "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
  • Aceita mais de um valor: repita o parâmetro fieldValue e o registro é retornado se o campo contiver qualquer um deles

# 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
  • Contar, em uma única chamada, os registros de várias etapas de um funil

# Vários valores em uma chamada

Para buscar registros em mais de um valor do mesmo campo, repita fieldValue. O registro é retornado se o campo contiver qualquer um dos valores, e pagination.total conta todos os registros encontrados, sem somar chamadas separadas. O segundo exemplo desta seção mostra a chamada.

# 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 | array Sim Valor para buscar no campo (suporta regex/contains, sem considerar maiúsculas/minúsculas). Repita o parâmetro para buscar mais de um valor (até 20); valores repetidos são ignorados
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,
        "responsibles": [
          { "id": "507f1f77bcf86cd799439021", "name": "Ana Souza" }
        ],
        "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'
curl -X GET 'https://sdm.smarttalks.ai/v1/objects/507f1f77bcf86cd799439011/records/by-field-and-date?fieldLabel=Etapa&fieldValue=Em%20negocia%C3%A7%C3%A3o&fieldValue=Follow-up&fieldValue=Venda%20realizada&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'

# Exemplo 6: Da conversa ao card

Descubra em qual etapa do funil (card) está o contato de uma conversa. O fluxo usa o relatório de interações e os registros do CRM.

Passo 1. Busque as interações. Cada item traz clientId (o contato) e, em evidences[], entityId (objeto do CRM) e itemIds (cards ligados):

curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?startDate=2025-11-01&endDate=2025-11-30' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

Passo 2. Se a evidência tiver itemIds, busque o card e leia o campo de etapa (por exemplo, Etapa):

curl -X GET 'https://sdm.smarttalks.ai/v1/objects/{entityId}/records/{itemId}' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

Passo 3. Sem itemIds, liste os cards do objeto de funil filtrando pelo clientId da interação:

curl -X GET 'https://sdm.smarttalks.ai/v1/objects/{pipelineObjectId}/records?clientId={clientId}' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

Para listar apenas os cards em uma etapa, filtre pelo nome do campo:

curl -G 'https://sdm.smarttalks.ai/v1/objects/{pipelineObjectId}/records' \
  --data-urlencode 'filters={"Etapa":"Venda Realizada"}' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Observações

  • A etapa retornada é a atual do card, não a etapa na data da conversa.
  • O intervalo de datas do relatório de interações considera a data de criação da conversa. O intervalo de by-field-and-date considera a data de criação do card. Por isso, as contagens das duas APIs não são esperadas como iguais.

# 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