S4ilor · API Reference

Documentação da API

REST API v1 — documentação completa de endpoints, parâmetros e exemplos.

Usuários

Consulta de usuários do workspace. Somente leitura via API.

GET

/users

Lista todos os usuários do workspace (membros ativos + convites pendentes), com contagem de chats abertos.

Permissãoread

Query Parameters

search

stringBusca por nome ou prefixo do e-mail. Case-insensitive.

order

stringOrdenação. Aceito: "name". Padrão: "name".

direction

string"asc" ou "desc". Padrão: "asc".

status

stringFiltrar por role: "$team_admin", "operational", "viewer", "pending".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/users" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Maria Silva",
      "email": "maria@empresa.com",
      "avatar": "https://cdn.example.com/avatar.jpg",
      "role": "operational",
      "openChatsCount": 12
    }
  ]
}

Respostas

200 OK

Lista retornada.

400 Bad Request

Parâmetros inválidos.

401 Unauthorized

Token inválido.

500 Internal Server Error

Erro interno.

GET

/users/{userId}

Retorna os detalhes de um usuário específico.

Permissãoread

Path Parameters

userId

stringID do usuário (ObjectId).

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/users/:userId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Maria Silva",
    "email": "maria@empresa.com",
    "avatar": "https://cdn.example.com/avatar.jpg",
    "role": "operational",
    "openChatsCount": 12
  }
}

Respostas

200 OK

Usuário retornado.

400 Bad Request

userId ausente.

404 Not Found

Usuário não encontrado.

500 Internal Server Error

Erro interno.

Roles possíveis: "$team_admin" (admin), "operational" (operador), "viewer" (visualizador), "pending" (convite pendente). Pendentes têm o e-mail como name.

Clientes

Gerenciamento de clientes (contatos) do workspace.

GET

/clients

Lista clientes com busca, paginação e ordenação.

Permissãoread

Query Parameters

search

stringBusca por nome ou telefone.

page

stringPágina (>=1). Padrão: 1.

order

string"name", "createdAt" ou "updatedAt". Padrão: "createdAt".

direction

string"asc" ou "desc". Padrão: "desc".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/clients" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "João da Silva",
      "phone": "5511999998888",
      "cpf": "12345678901",
      "observations": "Cliente VIP",
      "fixed": false,
      "extraData": { "plano": "gold", "idade": 30, "ativo": true },
      "createdAt": "2025-01-01T12:00:00.000Z",
      "updatedAt": "2025-06-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 5,
    "totalCount": 98,
    "hasNextPage": true,
    "hasPrevPage": false,
    "order": "createdAt",
    "direction": "desc",
    "perPage": 20,
    "hasMore": true
  }
}

Respostas

200 OK

Lista retornada.

400 Bad Request

Parâmetros inválidos.

500 Internal Server Error

Erro interno.

POST

/clients

Cria um novo cliente. Opcionalmente, cria também uma conversa na conexão do token.

Permissãoread_write

Body (JSON)

name

stringNome do cliente.

phone

stringTelefone (10-15 dígitos, apenas números).

cpf

stringCPF (11 dígitos). Vazio ou omitido se não aplicável.

observations

stringObservações (máx. 500 caracteres). Quando informado, cria a conversa automaticamente.

extraData

objectDados extras do cliente (objeto chave-valor). Quando informado, cria a conversa automaticamente.

fixed

booleanSe o cliente é fixo.

tagIds

ObjectId[]Tags a aplicar na conversa (mescladas com as tags padrão da conexão). Quando informado, cria a conversa automaticamente.

departmentId

ObjectId | nullDepartamento da conversa. Sobrescreve o padrão da conexão se informado. Quando informado, cria a conversa automaticamente.

operatorIds

string[]Operadores a atribuir à conversa (mesclados com os operadores padrão da conexão). Quando informado, cria a conversa automaticamente.

Exemplo de Body

{
  "name": "João da Silva",
  "phone": "5511999998888",
  "cpf": "12345678901",
  "observations": "Cliente VIP",
  "extraData": { "plano": "gold", "idade": 30, "ativo": true },
  "tagIds": ["507f1f77bcf86cd799439033"],
  "departmentId": "507f1f77bcf86cd799439044",
  "operatorIds": ["operator_id_1"]
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/clients" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "João da Silva",
  "phone": "5511999998888",
  "cpf": "12345678901",
  "observations": "Cliente VIP",
  "extraData": { "plano": "gold", "idade": 30, "ativo": true },
  "tagIds": ["507f1f77bcf86cd799439033"],
  "departmentId": "507f1f77bcf86cd799439044",
  "operatorIds": ["operator_id_1"]
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "João da Silva",
    "phone": "5511999998888",
    "cpf": "12345678901",
    "observations": "Cliente VIP",
    "extraData": { "plano": "gold", "idade": 30, "ativo": true },
    "fixed": false,
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z",
    "chatId": "507f1f77bcf86cd799439055"
  }
}

Respostas

201 Created

Cliente criado. chatId presente na resposta se a conversa foi criada.

400 Bad Request

Dados inválidos.

409 Conflict

Telefone ou CPF já cadastrado em outro cliente.

500 Internal Server Error

Erro interno.

GET

/clients/{clientId}

Retorna um cliente específico.

Permissãoread

Path Parameters

clientId

ObjectIdID do cliente.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/clients/:clientId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "externalId": "5511999998888@s.whatsapp.net",
    "name": "João da Silva",
    "phone": "5511999998888",
    "profilePicturePath": "https://cdn.example.com/profile.jpg",
    "cpf": "12345678901",
    "observations": "Cliente VIP",
    "fixed": false,
    "extraData": { "plano": "gold", "idade": 30, "ativo": true },
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z"
  }
}

Respostas

200 OK

Cliente retornado.

400 Bad Request

ID inválido.

404 Not Found

Cliente não encontrado.

500 Internal Server Error

Erro interno.

PATCH

/clients/{clientId}

Atualiza campos de um cliente. Opcionalmente, cria ou reabre uma conversa na conexão do token. Envie apenas os campos a alterar.

Permissãoread_write

Path Parameters

clientId

ObjectIdID do cliente.

Body (JSON)

name

stringNovo nome.

phone

stringNovo telefone (10-15 dígitos).

cpf

stringNovo CPF (11 dígitos).

observations

stringNovas observações (máx. 500).

fixed

booleanFixo ou não.

extraData

objectDados extras do cliente (objeto chave-valor). Quando informado, cria ou reabre a conversa automaticamente.

extraDataMode

"merge" | "replace"Como aplicar extraData: "replace" (padrão) substitui todo o objeto; "merge" mescla as chaves enviadas com as existentes (chaves não enviadas são mantidas).

tagIds

ObjectId[]Tags a aplicar na conversa (mescladas com as tags padrão da conexão). Quando informado, cria ou reabre a conversa automaticamente.

departmentId

ObjectId | nullDepartamento da conversa. Sobrescreve o padrão da conexão se informado. Quando informado, cria ou reabre a conversa automaticamente.

operatorIds

string[]Operadores a atribuir à conversa (mesclados com os operadores padrão da conexão). Quando informado, cria ou reabre a conversa automaticamente.

Exemplo de Body

{
  "name": "João da Silva Atualizado",
  "observations": "Cliente VIP - Prioridade alta",
  "extraData": { "plano": "gold", "idade": 30, "ativo": true },
  "extraDataMode": "merge",
  "tagIds": ["507f1f77bcf86cd799439033"],
  "operatorIds": ["operator_id_1"]
}

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/clients/:clientId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "João da Silva Atualizado",
  "observations": "Cliente VIP - Prioridade alta",
  "extraData": { "plano": "gold", "idade": 30, "ativo": true },
  "extraDataMode": "merge",
  "tagIds": ["507f1f77bcf86cd799439033"],
  "operatorIds": ["operator_id_1"]
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "externalId": "5511999998888@s.whatsapp.net",
    "name": "João da Silva Atualizado",
    "phone": "5511999998888",
    "profilePicturePath": "https://cdn.example.com/profile.jpg",
    "cpf": "12345678901",
    "observations": "Cliente VIP - Prioridade alta",
    "fixed": false,
    "extraData": { "plano": "gold", "idade": 30, "ativo": true },
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-06-15T10:30:00.000Z",
    "chatId": "507f1f77bcf86cd799439055"
  }
}

Respostas

200 OK

Cliente atualizado. chatId presente na resposta se a conversa foi criada/reaberta.

400 Bad Request

Dados inválidos ou nenhum campo enviado.

404 Not Found

Cliente não encontrado.

409 Conflict

Telefone já em uso por outro cliente.

500 Internal Server Error

Erro interno.

DELETE

/clients/{clientId}

Remove um cliente.

Permissãoread_write

Path Parameters

clientId

ObjectIdID do cliente.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/clients/:clientId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "externalId": "5511999998888@s.whatsapp.net",
    "name": "João da Silva",
    "phone": "5511999998888",
    "profilePicturePath": "https://cdn.example.com/profile.jpg",
    "cpf": "12345678901",
    "observations": "Cliente VIP",
    "fixed": false,
    "extraData": { "plano": "gold", "idade": 30, "ativo": true },
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z"
  }
}

Respostas

200 OK

Cliente removido.

400 Bad Request

ID inválido.

404 Not Found

Cliente não encontrado.

500 Internal Server Error

Erro interno.

Tags

Gerenciamento de tags do workspace.

GET

/tags

Lista tags com busca, paginação e ordenação.

Permissãoread

Query Parameters

search

stringBusca por nome.

page

stringPágina (>=1). Padrão: 1.

order

string"name" ou "updatedAt". Padrão: "name".

direction

string"asc" ou "desc". Padrão: "asc".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/tags" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "name": "Urgente",
      "color": "#FF0000",
      "icon": "AlertTriangle",
      "description": "Atendimentos prioritários"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 2,
    "totalCount": 12,
    "hasNextPage": true,
    "hasPrevPage": false,
    "order": "name",
    "direction": "asc",
    "perPage": 20,
    "hasMore": true
  }
}

Respostas

200 OK

Lista retornada com paginação.

400 Bad Request

Parâmetros inválidos.

500 Internal Server Error

Erro interno.

POST

/tags

Cria uma nova tag.

Permissãoread_write

Body (JSON)

name

stringNome da tag.

color

stringCor hexadecimal (ex: "#FF0000").

icon

stringÍcone. Padrão: "Tag".

description

stringDescrição da tag.

Exemplo de Body

{
  "name": "Urgente",
  "color": "#FF0000",
  "icon": "AlertTriangle",
  "description": "Atendimentos prioritários"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/tags" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Urgente",
  "color": "#FF0000",
  "icon": "AlertTriangle",
  "description": "Atendimentos prioritários"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439012",
    "name": "Urgente",
    "color": "#FF0000",
    "icon": "AlertTriangle",
    "description": "Atendimentos prioritários"
  }
}

Respostas

201 Created

Tag criada.

400 Bad Request

Dados inválidos ou nome/cor ausente.

500 Internal Server Error

Erro interno.

GET

/tags/{tagId}

Retorna uma tag específica.

Permissãoread

Path Parameters

tagId

ObjectIdID da tag.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/tags/:tagId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439012",
    "name": "Urgente",
    "color": "#FF0000",
    "icon": "AlertTriangle",
    "description": "Atendimentos prioritários"
  }
}

Respostas

200 OK

Tag retornada.

400 Bad Request

ID inválido.

404 Not Found

Tag não encontrada.

500 Internal Server Error

Erro interno.

PATCH

/tags/{tagId}

Atualiza campos de uma tag. Envie apenas os campos a alterar.

Permissãoread_write

Path Parameters

tagId

ObjectIdID da tag.

Body (JSON)

name

stringNovo nome (não vazio).

color

stringNova cor hex.

icon

stringNovo ícone.

description

stringNova descrição.

Exemplo de Body

{
  "name": "Urgente Atualizado",
  "color": "#FF4500"
}

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/tags/:tagId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Urgente Atualizado",
  "color": "#FF4500"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439012",
    "name": "Urgente Atualizado",
    "color": "#FF4500",
    "icon": "AlertTriangle",
    "description": "Atendimentos prioritários"
  }
}

Respostas

200 OK

Tag atualizada.

400 Bad Request

Dados inválidos ou nenhum campo.

404 Not Found

Tag não encontrada.

500 Internal Server Error

Erro interno.

DELETE

/tags/{tagId}

Remove uma tag.

Permissãoread_write

Path Parameters

tagId

ObjectIdID da tag.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/tags/:tagId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439012",
    "name": "Urgente",
    "color": "#FF0000",
    "icon": "AlertTriangle",
    "description": "Atendimentos prioritários"
  }
}

Respostas

200 OK

Tag removida.

400 Bad Request

ID inválido.

404 Not Found

Tag não encontrada.

500 Internal Server Error

Erro interno.

Departamentos

Gerenciamento de departamentos (setores) do workspace.

GET

/departments

Lista departamentos com busca, paginação e ordenação.

Permissãoread

Query Parameters

search

stringBusca por nome.

page

stringPágina (>=1). Padrão: 1.

order

string"name" ou "updatedAt". Padrão: "name".

direction

string"asc" ou "desc". Padrão: "asc".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/departments" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "name": "Suporte",
      "color": "#3B82F6",
      "description": "Equipe de suporte técnico"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 1,
    "totalCount": 1,
    "hasNextPage": false,
    "hasPrevPage": false,
    "order": "name",
    "direction": "asc",
    "perPage": 20,
    "hasMore": false
  }
}

Respostas

200 OK

Lista retornada com paginação.

400 Bad Request

Parâmetros inválidos.

500 Internal Server Error

Erro interno.

POST

/departments

Cria um novo departamento.

Permissãoread_write

Body (JSON)

name

stringNome do departamento.

color

stringCor hexadecimal (ex: "#3B82F6").

description

stringDescrição.

operatorIds

string[]IDs dos operadores.

userPermissions

object[]Permissões por usuário.

operatorPool

string[]Pool de operadores.

Exemplo de Body

{
  "name": "Suporte",
  "color": "#3B82F6",
  "description": "Equipe de suporte técnico",
  "operatorIds": ["userId1", "userId2"]
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/departments" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Suporte",
  "color": "#3B82F6",
  "description": "Equipe de suporte técnico",
  "operatorIds": ["userId1", "userId2"]
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439013",
    "name": "Suporte",
    "color": "#3B82F6",
    "description": "Equipe de suporte técnico"
  }
}

Respostas

201 Created

Departamento criado.

400 Bad Request

Dados inválidos ou nome/cor ausente.

500 Internal Server Error

Erro interno.

GET

/departments/{departmentId}

Retorna um departamento específico.

Permissãoread

Path Parameters

departmentId

ObjectIdID do departamento.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/departments/:departmentId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439013",
    "name": "Suporte",
    "color": "#3B82F6",
    "description": "Equipe de suporte técnico"
  }
}

Respostas

200 OK

Departamento retornado.

400 Bad Request

ID inválido.

404 Not Found

Departamento não encontrado.

500 Internal Server Error

Erro interno.

PATCH

/departments/{departmentId}

Atualiza campos de um departamento.

Permissãoread_write

Path Parameters

departmentId

ObjectIdID do departamento.

Body (JSON)

name

stringNovo nome (não vazio).

color

stringNova cor hex.

description

stringNova descrição.

operatorIds

string[]Novos IDs de operadores.

userPermissions

object[]Novas permissões.

operatorPool

string[]Novo pool de operadores.

Exemplo de Body

{
  "name": "Suporte Atualizado",
  "operatorIds": ["userId1", "userId2", "userId3"]
}

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/departments/:departmentId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Suporte Atualizado",
  "operatorIds": ["userId1", "userId2", "userId3"]
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439013",
    "name": "Suporte Atualizado",
    "color": "#3B82F6",
    "description": "Equipe de suporte técnico",
    "operatorIds": ["userId1", "userId2", "userId3"]
  }
}

Respostas

200 OK

Departamento atualizado.

400 Bad Request

Dados inválidos ou nenhum campo.

404 Not Found

Departamento não encontrado.

500 Internal Server Error

Erro interno.

DELETE

/departments/{departmentId}

Remove um departamento.

Permissãoread_write

Path Parameters

departmentId

ObjectIdID do departamento.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/departments/:departmentId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439013",
    "name": "Suporte",
    "color": "#3B82F6",
    "description": "Equipe de suporte técnico"
  }
}

Respostas

200 OK

Departamento removido.

400 Bad Request

ID inválido.

404 Not Found

Departamento não encontrado (ou erro na remoção).

500 Internal Server Error

Erro interno.

Atalhos

Gerenciamento de atalhos de mensagem do workspace. Atalhos criados via API são sempre globais (disponíveis para todos os operadores).

GET

/shortcuts

Lista atalhos com busca, paginação e ordenação.

Permissãoread

Query Parameters

search

stringBusca por título ou chave.

page

stringPágina (>=1). Padrão: 1.

order

string"title", "key" ou "updatedAt". Padrão: "title".

direction

string"asc" ou "desc". Padrão: "asc".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/shortcuts" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439020",
      "title": "Saudação",
      "key": "/saudacao",
      "message": "Olá! Como posso ajudar você hoje?",
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 3,
    "totalCount": 58,
    "hasNextPage": true,
    "hasPrevPage": false,
    "order": "title",
    "direction": "asc",
    "perPage": 20,
    "hasMore": true
  }
}

Respostas

200 OK

Lista retornada com paginação.

400 Bad Request

Parâmetros inválidos.

500 Internal Server Error

Erro interno.

POST

/shortcuts

Cria um novo atalho global (disponível para todos os operadores).

Permissãoread_write

Body (JSON)

title

stringTítulo do atalho.

key

stringChave de ativação do atalho (ex: /saudacao).

message

stringMensagem do atalho (máx. 4000 caracteres).

Exemplo de Body

{
  "title": "Saudação",
  "key": "/saudacao",
  "message": "Olá! Como posso ajudar você hoje?"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/shortcuts" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Saudação",
  "key": "/saudacao",
  "message": "Olá! Como posso ajudar você hoje?"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "title": "Saudação",
    "key": "/saudacao",
    "message": "Olá! Como posso ajudar você hoje?",
    "createdAt": "2025-06-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z"
  }
}

Respostas

201 Created

Atalho criado.

400 Bad Request

Dados inválidos ou campos obrigatórios ausentes.

500 Internal Server Error

Erro interno.

Atalhos criados via API não possuem operatorId e são sempre globais ( Sempre visiveis para todos os operadores ).

GET

/shortcuts/{shortcutId}

Retorna um atalho específico.

Permissãoread

Path Parameters

shortcutId

ObjectIdID do atalho.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/shortcuts/:shortcutId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "title": "Saudação",
    "key": "/saudacao",
    "message": "Olá! Como posso ajudar você hoje?",
    "createdAt": "2025-06-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z"
  }
}

Respostas

200 OK

Atalho retornado.

400 Bad Request

ID inválido.

404 Not Found

Atalho não encontrado.

500 Internal Server Error

Erro interno.

PATCH

/shortcuts/{shortcutId}

Atualiza campos de um atalho. Envie apenas os campos a alterar.

Permissãoread_write

Path Parameters

shortcutId

ObjectIdID do atalho.

Body (JSON)

title

stringNovo título (não vazio).

key

stringNova chave (não vazia).

message

stringNova mensagem (máx. 4000 caracteres).

docPaths

object[]Novos anexos. Cada item: { "path": "url", "type": "image"|"video"|"file" }.

Exemplo de Body

{
  "title": "Saudação Atualizada",
  "message": "Olá! Bem-vindo ao nosso atendimento. Como posso ajudar?"
}

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/shortcuts/:shortcutId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Saudação Atualizada",
  "message": "Olá! Bem-vindo ao nosso atendimento. Como posso ajudar?"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "title": "Saudação Atualizada",
    "key": "/saudacao",
    "message": "Olá! Bem-vindo ao nosso atendimento. Como posso ajudar?",
    "createdAt": "2025-06-01T12:00:00.000Z",
    "updatedAt": "2025-06-15T10:30:00.000Z"
  }
}

Respostas

200 OK

Atalho atualizado.

400 Bad Request

Dados inválidos ou nenhum campo.

404 Not Found

Atalho não encontrado.

500 Internal Server Error

Erro interno.

DELETE

/shortcuts/{shortcutId}

Remove um atalho.

Permissãoread_write

Path Parameters

shortcutId

ObjectIdID do atalho.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/shortcuts/:shortcutId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "title": "Saudação",
    "key": "/saudacao",
    "message": "Olá! Como posso ajudar você hoje?",
    "createdAt": "2025-06-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z"
  }
}

Respostas

200 OK

Atalho removido.

400 Bad Request

ID inválido.

404 Not Found

Atalho não encontrado.

500 Internal Server Error

Erro interno.

Robôs

Gerenciamento de robôs (assistentes IA) do workspace.

GET

/robots

Lista robôs com busca, paginação e ordenação.

Permissãoread

Query Parameters

search

stringBusca por nome.

page

stringPágina (>=1). Padrão: 1.

order

string"name" ou "updatedAt". Padrão: "name".

direction

string"asc" ou "desc". Padrão: "asc".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/robots" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439030",
      "name": "Assistente de Vendas",
      "description": "Robô para atendimento de vendas",
      "color": "#10B981",
      "model": "gpt-5-mini",
      "canTag": true,
      "canDepartment": false,
      "canSearchWeb": false,
      "canClose": false,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "updatedAt": "2025-06-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 1,
    "totalCount": 3,
    "hasNextPage": false,
    "hasPrevPage": false,
    "order": "name",
    "direction": "asc",
    "perPage": 20,
    "hasMore": false
  }
}

Respostas

200 OK

Lista retornada com paginação.

400 Bad Request

Parâmetros inválidos.

500 Internal Server Error

Erro interno.

POST

/robots

Cria um novo robô.

Permissãoread_write

Body (JSON)

name

stringNome do robô.

color

stringCor hexadecimal (ex: "#10B981").

description

stringDescrição do robô.

basePrompt

stringPrompt base para o modelo de IA.

notes

stringNotas internas sobre o robô.

security

stringInstruções de segurança para o modelo.

messageDelay

stringDelay entre mensagens em segundos (máx 30). Ex: "2s" ou "2".

model

stringModelo de IA. Valores: "gpt-5.2", "gpt-5", "gpt-5-mini", "gpt-5-nano". Padrão: "gpt-5-mini".

canTag

booleanPode gerenciar tags. Padrão: false.

canDepartment

booleanPode gerenciar departamentos. Padrão: false.

canSearchWeb

booleanPode pesquisar na web. Padrão: false.

canClose

booleanPode fechar conversas. Padrão: false.

Exemplo de Body

{
  "name": "Assistente de Vendas",
  "color": "#10B981",
  "description": "Robô para atendimento de vendas",
  "basePrompt": "Você é um assistente de vendas...",
  "model": "gpt-5-mini",
  "canTag": true
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/robots" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Assistente de Vendas",
  "color": "#10B981",
  "description": "Robô para atendimento de vendas",
  "basePrompt": "Você é um assistente de vendas...",
  "model": "gpt-5-mini",
  "canTag": true
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439030",
    "name": "Assistente de Vendas",
    "color": "#10B981",
    "description": "Robô para atendimento de vendas",
    "model": "gpt-5-mini",
    "canTag": true,
    "canDepartment": false,
    "canSearchWeb": false,
    "canClose": false
  }
}

Respostas

201 Created

Robô criado.

400 Bad Request

Dados inválidos ou nome/cor ausente.

500 Internal Server Error

Erro interno.

GET

/robots/{robotId}

Retorna um robô específico.

Permissãoread

Path Parameters

robotId

ObjectIdID do robô.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/robots/:robotId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439030",
    "name": "Assistente de Vendas",
    "description": "Robô para atendimento de vendas",
    "color": "#10B981",
    "basePrompt": "Você é um assistente de vendas...",
    "notes": "",
    "security": "",
    "messageDelay": "",
    "model": "gpt-5-mini",
    "canTag": true,
    "canDepartment": false,
    "canSearchWeb": false,
    "canClose": false,
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z"
  }
}

Respostas

200 OK

Robô retornado.

400 Bad Request

ID inválido.

404 Not Found

Robô não encontrado.

500 Internal Server Error

Erro interno.

PATCH

/robots/{robotId}

Atualiza campos de um robô. Envie apenas os campos a alterar.

Permissãoread_write

Path Parameters

robotId

ObjectIdID do robô.

Body (JSON)

name

stringNovo nome (não vazio).

color

stringNova cor hex.

description

stringNova descrição.

basePrompt

stringNovo prompt base.

notes

stringNovas notas.

security

stringNovas instruções de segurança.

messageDelay

stringNovo delay em segundos (máx 30). Ex: "2s" ou "2".

model

stringNovo modelo de IA. Valores: "gpt-5.2", "gpt-5", "gpt-5-mini", "gpt-5-nano".

canTag

booleanPode gerenciar tags.

canDepartment

booleanPode gerenciar departamentos.

canSearchWeb

booleanPode pesquisar na web.

canClose

booleanPode fechar conversas.

Exemplo de Body

{
  "name": "Assistente de Vendas Atualizado",
  "model": "gpt-5",
  "canSearchWeb": true
}

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/robots/:robotId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Assistente de Vendas Atualizado",
  "model": "gpt-5",
  "canSearchWeb": true
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439030",
    "name": "Assistente de Vendas Atualizado",
    "description": "Robô para atendimento de vendas",
    "color": "#10B981",
    "model": "gpt-5",
    "canTag": true,
    "canDepartment": false,
    "canSearchWeb": true,
    "canClose": false
  }
}

Respostas

200 OK

Robô atualizado.

400 Bad Request

Dados inválidos ou nenhum campo.

404 Not Found

Robô não encontrado.

500 Internal Server Error

Erro interno.

DELETE

/robots/{robotId}

Remove um robô. Conexões e controles de automação vinculados são atualizados.

Permissãoread_write

Path Parameters

robotId

ObjectIdID do robô.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/robots/:robotId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439030",
    "name": "Assistente de Vendas",
    "description": "Robô para atendimento de vendas",
    "color": "#10B981",
    "model": "gpt-5-mini",
    "canTag": true,
    "canDepartment": false,
    "canSearchWeb": false,
    "canClose": false
  }
}

Respostas

200 OK

Robô removido.

400 Bad Request

ID inválido.

404 Not Found

Robô não encontrado.

500 Internal Server Error

Erro interno.

Ao remover um robô, referências em conexões (startingRobot) e controles de automação (responsibleBotId) são automaticamente limpas.

Conexão

Configurações da conexão vinculada ao token. O token identifica automaticamente a conexão.

GET

/connection

Retorna as configurações da conexão vinculada ao token.

Permissãoread

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/connection" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011" ( ObjectId ),
    "name": "WhatsApp Principal",
    "icon": "MessageCircle",
    "color": "#25D366",
    "type": "whatsapp_meta_cloud",
    "status": "connected",
    "active": true,
    "namePrefix": false,
    "security": true,
    "startingOperators": [],
    "startingTags": [],
    "startingDepartment": null,
    "startingRobot": null,
    "removeOperators": true,
    "removeTags": true,
    "removeDepartment": true,
    "removeRobot": true,
    "addOperatorOnStart": false,
    "summarizeCompletedSessions": false,
    "sendCSAT": false,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-06-01T00:00:00.000Z"
  }
}

Respostas

200 OK

Configurações retornadas.

500 Internal Server Error

Erro interno.

PATCH

/connection

Atualiza configurações da conexão.

Permissãoread_write

Body (JSON)

name

stringNome da conexão. Não pode conter "/" ou "\".

icon

stringÍcone.

color

stringCor hex (#RRGGBB, 6 dígitos).

namePrefix

booleanExibir prefixo do nome.

security

booleanSegurança ativada.

startingOperators

string[]Operadores iniciais.

startingTags

string[]Tags iniciais.

startingDepartment

string|nullDepartamento inicial.

startingRobot

string|nullRobô/URA inicial.

removeOperators

booleanRemover operadores ao fechar.

removeTags

booleanRemover tags ao fechar.

removeDepartment

booleanRemover departamento ao fechar.

removeRobot

booleanRemover robô ao fechar.

addOperatorOnStart

booleanAdicionar operador ao iniciar.

summarizeCompletedSessions

booleanResumir sessões ao completar.

sendCSAT

booleanEnviar pesquisa de satisfação (CSAT).

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/connection" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json"

Respostas

200 OK

Conexão atualizada.

400 Bad Request

Dados inválidos ou nenhum campo.

404 Not Found

Conexão não encontrada.

500 Internal Server Error

Erro interno.

DELETE

/connection

Remove a conexão permanentemente.

Permissãoread_write

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/connection" \
  -H "Authorization: Bearer <seu-token>"

Respostas

200 OK

Conexão removida.

400 Bad Request

Erro na remoção.

500 Internal Server Error

Erro interno.

Atenção: esta operação é irreversível. Todos os dados vinculados à conexão serão removidos.

PATCH

/connection/toggle

Alterna o estado ativo/inativo da conexão.

Permissãoread_write

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/connection/toggle" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json"

Resposta de Sucesso

{
  "success": true,
  "data": { "active": false }
}

Respostas

200 OK

Status alternado.

400 Bad Request

Erro ao alternar.

500 Internal Server Error

Erro interno.

POST

/connection/sync-templates

Sincroniza templates da conexão com o provedor externo. Disponível apenas para tipos de conexão que suportam templates.

Permissãoread_write

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/connection/sync-templates" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json"

Resposta de Sucesso

{
  "success": true,
  "message": "Templates sincronizados com sucesso"
}

Respostas

200 OK

Templates sincronizados.

400 Bad Request

Tipo de conexão não suporta templates.

500 Internal Server Error

Erro interno.

Conversas

Gerenciamento de conversas da conexão.

GET

/chats

Lista chats da conexão com paginação, filtro por status e busca.

Permissãoread

Query Parameters

page

stringPágina (>=1). Padrão: 1.

limit

stringItens por página (1-100). Padrão: 20.

status

string"open" ou "closed".

search

stringBusca por nome ou telefone do cliente.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/chats" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439014" ( ObjectId ),
      "client": { "_id": "507f1f77bcf86cd799439011" ( ObjectId ), "name": "João", "phone": "5511999998888" },
      "externalChatId": "5511999998888@s.whatsapp.net",
      "status": "open",
      "tagIds": ["tagId1"],
      "operatorIds": ["userId1"],
      "departmentId": "deptId1",
      "lastMessage": {
        "_id": "507f1f77bcf86cd799439015",
        "content": "Olá, preciso de ajuda",
        "type": "text",
        "timestamp": "2025-06-01T14:29:00.000Z",
        "operatorId": null,
        "status": "received",
        "createdAt": "2025-06-01T14:29:00.000Z"
      },
      "unreadCount": 3,
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 3,
    "totalCount": 42,
    "hasNextPage": true,
    "hasPrevPage": false,
    "order": "updatedAt",
    "direction": "desc",
    "perPage": 20,
    "hasMore": true
  }
}

Respostas

200 OK

Lista retornada.

500 Internal Server Error

Erro interno.

POST

/chats

Cria um novo chat ou reabre um chat fechado para um cliente. Aplica configurações base da conexão (operadores, tags, departamento iniciais).

Permissãoread_write

Body (JSON)

clientId

ObjectIdID do cliente.

Exemplo de Body

{
  "clientId": "507f1f77bcf86cd799439011"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/chats" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "clientId": "507f1f77bcf86cd799439011"
}'

Resposta de Sucesso

{
  "success": true,
  "data": { "chatId": "507f1f77bcf86cd799439014" ( ObjectId ), "isNew": true }
}

Respostas

201 Created

Chat criado (novo).

200 OK

Chat reaberto (já existia fechado) ou já estava aberto.

400 Bad Request

clientId inválido.

404 Not Found

Cliente não encontrado.

500 Internal Server Error

Erro interno.

GET

/chats/{chatId}

Retorna os detalhes completos de um chat.

Permissãoread

Path Parameters

chatId

ObjectIdID do chat.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/chats/:chatId" \
  -H "Authorization: Bearer <seu-token>"

Respostas

200 OK

Chat retornado.

400 Bad Request

ID inválido.

404 Not Found

Chat não encontrado.

500 Internal Server Error

Erro interno.

PATCH

/chats/{chatId}

Atualiza propriedades de um chat: status, tags, operadores, departamento ou nome do cliente. Mudanças de status disparam fluxos/URAs e aplicam regras da conexão.

Permissãoread_write

Path Parameters

chatId

ObjectIdID do chat.

Body (JSON)

status

string"open" ou "closed". Alterna o status do chat.

tagIds

string[]Array de IDs de tags (substitui as atuais).

operatorIds

string[]Array de IDs de operadores (substitui os atuais).

operatorId

stringID do operador responsável pela atualização (usado para rastreio/auditoria da ação).

departmentId

string|nullID do departamento (ou null para remover).

client

object{ "name": "Novo Nome" } — altera o nome do cliente no chat.

Exemplo de Body

{
  "status": "closed",
  "tagIds": ["tagId1", "tagId2"],
  "operatorIds": ["userId1"],
  "operatorId": "userId1",
  "departmentId": "deptId1"
}

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/chats/:chatId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "closed",
  "tagIds": ["tagId1", "tagId2"],
  "operatorIds": ["userId1"],
  "operatorId": "userId1",
  "departmentId": "deptId1"
}'

Respostas

200 OK

Chat atualizado.

400 Bad Request

Dados inválidos.

404 Not Found

Chat não encontrado.

500 Internal Server Error

Erro interno.

Alterar status para 'closed' marca mensagens como lidas, remove operadores/tags/departamento conforme configurações da conexão e dispara flows/URAs vinculados.

Mensagens

Leitura e envio de mensagens dentro de um chat.

GET

/chats/{chatId}/messages

Lista mensagens de um chat com paginação e filtros de data.

Permissãoread

Path Parameters

chatId

ObjectIdID do chat.

Query Parameters

page

stringPágina (>=1). Padrão: 1.

limit

stringItens por página (1-100). Padrão: 50.

before

string (ISO 8601)Retorna mensagens anteriores a esta data.

after

string (ISO 8601)Retorna mensagens posteriores a esta data.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/chats/:chatId/messages" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439012" ( ObjectId ),
      "content": "Olá, preciso de ajuda",
      "type": "text",
      "category": "incoming",
      "timestamp": "2025-06-01T14:30:00.000Z",
      "operatorId": null,
      "operator": null,
      "read": null,
      "status": "received",
      "metadata": null,
      "externalMessageId": "wamid.xxx",
      "staredBy": ["userId1"],
      "moderation": null,
      "createdAt": "2025-06-01T14:30:00.000Z",
      "updatedAt": "2025-06-01T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 3,
    "totalCount": 127,
    "hasNextPage": true,
    "hasPrevPage": false,
    "order": "timestamp",
    "direction": "desc",
    "perPage": 50,
    "hasMore": true
  }
}

Respostas

200 OK

Mensagens retornadas.

400 Bad Request

chatId inválido.

404 Not Found

Chat não encontrado.

500 Internal Server Error

Erro interno.

Mensagens são ordenadas por timestamp descendente (mais recentes primeiro). Os filtros before/after aceitam datas ISO 8601.

POST

/chats/{chatId}/messages

Envia uma mensagem para o chat. O comportamento varia conforme o campo type:

Permissão: read_write

Path Parameters

chatId

ObjectIdID do chat.

Opção 1 — Mensagem de texto / mídia

Quando type é qualquer valor exceto "template". O envio é processado de forma assíncrona via fila.

Body (JSON)

content

string | objectTexto da mensagem, ou objeto { "path": "url", "originalPath": "originalUrl" } para mídia.

type

string"text", "image", "file", "audio", "video", "reply", "document", "contact", "interactive". Padrão: "text".

metadata

anyMetadados adicionais (ex: reply context).

tempId

stringID temporário para rastreamento client-side.

operatorId

ObjectIdID do operador que está enviando a mensagem. Quando fornecido, a mensagem aparece como enviada por esse operador no chat.

Exemplo de Body (texto/mídia)

{
  "content": "Olá! Como posso ajudar?",
  "type": "text",
  "tempId": "temp-123",
  "operatorId": "507f1f77bcf86cd799439011"
}

Resposta de Sucesso (texto/mídia)

{
  "success": true,
  "data": { "tempId": "temp-123" }
}

Opção 2 — Mensagem de template

Quando type é "template". Enviada diretamente à API do Meta (síncrono). Disponível apenas para conexões whatsapp_meta_cloud.

Body (JSON)

type

"template"Deve ser exatamente "template".

templateId

ObjectIdID do template cadastrado.

variables

objectVariáveis do template.

tempId

stringID temporário para rastreamento.

Exemplo de Body (template)

{
  "type": "template",
  "templateId": "507f1f77bcf86cd799439099",
  "variables": { "1": "João" },
  "tempId": "temp-456"
}

Resposta de Sucesso (template)

{
  "success": true,
  "data": {
    "messageId": "wamid.xxx",
    "status": "sent",
    "tempId": "temp-456"
  }
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/chats/:chatId/messages" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Respostas

200 OK

Mensagem enfileirada (texto/mídia) ou template enviado.

400 Bad Request

Dados inválidos ou conexão não é WhatsApp Meta Cloud (template).

404 Not Found

Chat ou template não encontrado.

500 Internal Server Error

Erro interno.

O campo type determina o fluxo: qualquer valor diferente de "template" segue o envio assíncrono via fila; "template" envia diretamente à API Meta (síncrono) e retorna status 'sent' ou 'failed'.

POST

/chats/{chatId}/read

Marca todas as mensagens não lidas de um chat como lidas. Zera o contador de não lidas, registra um log de auditoria e emite o evento readUpdate no canal list:{workspaceId} em tempo real.

Permissãoread_write

Path Parameters

chatId

ObjectIdID do chat.

Body (JSON)

operatorId

stringID do operador que está marcando as mensagens como lidas. Nome e avatar são buscados automaticamente.

Exemplo de Body

{
  "operatorId": "userId1"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/chats/:chatId/read" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "operatorId": "userId1"
}'

Respostas

200 OK

Mensagens marcadas como lidas.

400 Bad Request

chatId inválido ou dados ausentes.

404 Not Found

Chat não encontrado.

500 Internal Server Error

Erro interno.

Apenas mensagens com read: null são atualizadas. O evento readUpdate é emitido no canal list:{workspaceId} com unreadCount: 0.

POST

/messages/{messageId}/star

Alterna o estado de destaque de uma mensagem para um operador: se já estiver destacada, remove; caso contrário, adiciona.

Permissãoread_write

Path Parameters

messageId

ObjectIdID da mensagem.

Body (JSON)

operatorId

stringID do operador que está aplicando/removendo o destaque.

Exemplo de Body

{
  "operatorId": "userId1"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/messages/:messageId/star" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "operatorId": "userId1"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "staredBy": ["userId1"]
  }
}

Respostas

200 OK

Destaque alternado com sucesso.

400 Bad Request

messageId inválido ou operatorId ausente.

404 Not Found

Mensagem não encontrada.

500 Internal Server Error

Erro interno.

O endpoint é idempotente por operador: chamadas repetidas alternam entre destacar e remover destaque no array staredBy.

Envio Direto

Rota simplificada para enviar mensagens diretamente pelo número do destinatário. O cliente é criado automaticamente se não existir, e o chat é aberto (ou reaberto) conforme necessário.

POST

/messages

Envia uma mensagem para um número de telefone. Se o cliente não existir no workspace, ele é criado automaticamente. Se não houver um chat aberto para este número na conexão, um novo chat é aberto. O comportamento da mensagem varia conforme o campo type (igual ao endpoint POST /chats/{chatId}/messages).

Permissão: read_write

Opção 1 — Mensagem de texto / mídia

Body (JSON)

phone

stringNúmero de telefone (10-15 dígitos, apenas números).

name

stringNome do cliente. Usado apenas se o cliente for criado. Se omitido, usa o número como nome.

content

string | objectTexto da mensagem, ou objeto { "path": "url", "originalPath": "originalUrl" } para mídia.

type

string"text", "image", "file", "audio", "video", "reply", "document", "contact", "interactive". Padrão: "text".

metadata

anyMetadados adicionais.

tempId

stringID temporário para rastreamento client-side.

Exemplo de Body (texto/mídia)

{
  "phone": "5511999998888",
  "name": "João da Silva",
  "content": "Olá! Como posso ajudar?",
  "type": "text"
}

Resposta de Sucesso (texto/mídia)

{
  "success": true,
  "data": {
    "clientId": "507f1f77bcf86cd799439011",
    "chatId": "507f1f77bcf86cd799439014",
    "clientCreated": true,
    "chatOpened": true,
    "tempId": null
  }
}

Opção 2 — Mensagem de template

Disponível apenas para conexões whatsapp_meta_cloud. Enviada diretamente à API do Meta (síncrono).

Body (JSON)

phone

stringNúmero de telefone (10-15 dígitos, apenas números).

name

stringNome do cliente (se for criado).

type

"template"Deve ser exatamente "template".

templateId

ObjectIdID do template cadastrado.

variables

objectVariáveis do template.

tempId

stringID temporário para rastreamento.

Exemplo de Body (template)

{
  "phone": "5511999998888",
  "name": "João da Silva",
  "type": "template",
  "templateId": "507f1f77bcf86cd799439099",
  "variables": { "1": "João" }
}

Resposta de Sucesso (template)

{
  "success": true,
  "data": {
    "clientId": "507f1f77bcf86cd799439011",
    "chatId": "507f1f77bcf86cd799439014",
    "clientCreated": false,
    "chatOpened": false,
    "messageId": "507f1f77bcf86cd799439015",
    "status": "sent",
    "tempId": null
  }
}

Respostas

200 OK

Mensagem enfileirada (texto/mídia) ou template enviado.

400 Bad Request

Dados inválidos ou conexão não suporta templates.

404 Not Found

Template não encontrado.

500 Internal Server Error

Erro interno.

Se o cliente não existir, é criado com o nome fornecido (ou o número como nome). O chat é aberto ou reaberto automaticamente, aplicando as configurações base da conexão (operadores, tags, departamento).

Follow-ups

Mensagens agendadas (status: queued) enviadas automaticamente ao cliente quando ele responder no chat.

POST

/ephemeral

Cria um follow-up no chat. A mensagem fica em fila e será enviada ao cliente quando ele responder.

Permissãoread_write

Body (JSON)

chatId

ObjectIdID do chat onde o follow-up será criado.

operatorId

ObjectIdID do operador que está criando o follow-up.

content

stringTexto do follow-up.

Exemplo de Body

{
  "chatId": "507f1f77bcf86cd799439014",
  "operatorId": "507f1f77bcf86cd799439011",
  "content": "Ligar amanhã para confirmar pedido"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/ephemeral" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "507f1f77bcf86cd799439014",
  "operatorId": "507f1f77bcf86cd799439011",
  "content": "Ligar amanhã para confirmar pedido"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "chatId": "507f1f77bcf86cd799439014",
    "operatorId": "507f1f77bcf86cd799439011",
    "content": "Ligar amanhã para confirmar pedido",
    "type": "text",
    "status": "queued",
    "_bubbleType": "ephemeral",
    "createdAt": "2025-06-01T14:30:00.000Z"
  }
}

Respostas

201 Created

Follow-up criado.

400 Bad Request

Dados inválidos ou chatId/operatorId ausente.

404 Not Found

Chat não encontrado.

500 Internal Server Error

Erro interno.

O follow-up emite o evento newEphemeral no canal chat:{chatId} em tempo real.

DELETE

/ephemeral/{ephemeralId}

Remove um follow-up agendado. Só é possível remover follow-ups com status queued (ainda não enviados).

Permissãoread_write

Path Parameters

ephemeralId

ObjectIdID do follow-up a remover.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/ephemeral/:ephemeralId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{ "success": true }

Respostas

200 OK

Follow-up removido.

400 Bad Request

ID inválido ou follow-up não está com status queued.

404 Not Found

Follow-up não encontrado.

500 Internal Server Error

Erro interno.

Só é possível remover follow-ups que ainda não foram enviados (status: queued). Emite o evento ephemeralDeleted no canal chat:{chatId} ao remover.

Notas

Registros internos em um chat — texto livre ou anexo — visíveis apenas para operadores. Não são enviadas ao cliente.

POST

/notes

Cria uma nota em um chat. É obrigatório enviar ao menos content ou attachment.

Permissãoread_write

Body (JSON)

chatId

ObjectIdID do chat onde a nota será criada.

operatorId

ObjectIdID do operador que está criando a nota.

content

stringTexto da nota. Obrigatório se attachment não for enviado.

attachment

objectAnexo da nota. Obrigatório se content não for enviado. Ver estrutura abaixo.

attachment.path

stringCaminho do arquivo no storage.

attachment.name

stringNome original do arquivo.

attachment.size

numberTamanho em bytes.

attachment.mimeType

stringTipo MIME (ex: "image/jpeg").

attachment.type

stringTipo de mídia (ex: "image", "file").

Exemplo de Body

{
  "chatId": "507f1f77bcf86cd799439014",
  "operatorId": "507f1f77bcf86cd799439011",
  "content": "Cliente confirmou endereço de entrega"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/notes" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "507f1f77bcf86cd799439014",
  "operatorId": "507f1f77bcf86cd799439011",
  "content": "Cliente confirmou endereço de entrega"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439030",
    "chatId": "507f1f77bcf86cd799439014",
    "operatorId": "507f1f77bcf86cd799439011",
    "content": "Cliente confirmou endereço de entrega",
    "_bubbleType": "note",
    "createdAt": "2025-06-01T14:30:00.000Z"
  }
}

Respostas

201 Created

Nota criada.

400 Bad Request

Dados inválidos ou nem content nem attachment enviados.

404 Not Found

Chat não encontrado.

500 Internal Server Error

Erro interno.

Ao criar uma nota, o campo lastMessage do chat é atualizado para exibir o preview na listagem. Se a nota tiver anexo, a resposta retorna uma URL assinada temporária (6h) no campo attachment.path.

Notificações

Agendamento de notificações para operadores em um horário específico, associadas a um chat.

POST

/notifications

Agenda uma notificação para um operador. A notificação é enviada na data e hora informadas.

Permissãoread_write

Body (JSON)

title

stringTítulo da notificação (máx. 100 caracteres).

message

stringCorpo da notificação (máx. 500 caracteres).

chatId

ObjectIdID do chat associado à notificação.

operatorId

ObjectIdID do operador que receberá a notificação.

datetime

string (ISO 8601)Data e hora de envio da notificação (ex: 2025-06-10T14:30:00.000Z).

Exemplo de Body

{
  "title": "Retorno com cliente",
  "message": "Ligar para João para confirmar proposta",
  "chatId": "507f1f77bcf86cd799439014",
  "operatorId": "507f1f77bcf86cd799439011",
  "datetime": "2025-06-10T14:30:00.000Z"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/notifications" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Retorno com cliente",
  "message": "Ligar para João para confirmar proposta",
  "chatId": "507f1f77bcf86cd799439014",
  "operatorId": "507f1f77bcf86cd799439011",
  "datetime": "2025-06-10T14:30:00.000Z"
}'

Resposta de Sucesso

{
  "success": true,
  "message": "Notificação agendada com sucesso"
}

Respostas

201 Created

Notificação agendada.

400 Bad Request

Dados inválidos, campo ausente ou data inválida.

404 Not Found

Chat não encontrado.

500 Internal Server Error

Erro interno.

Atualizações de Cliente

Endpoint para notificar o S4ilor sobre eventos de entrega ou mudança de dados de um cliente via adaptador WhatsApp.

POST

/{connectionId}/clientUpdate

Processa um evento de atualização de cliente: falha de entrega de mensagem ou mudança de número de telefone.

Permissãoread_write

Path Parameters

connectionId

ObjectIdID da conexão (deve corresponder ao token usado).

Body (JSON)

event

string"failed" — falha de entrega de mensagem. "client_phone_changed" — mudança de número do cliente.

externalMessageId

stringID externo da mensagem (obrigatório quando event = "failed").

errorCode

numberCódigo de erro da plataforma (ex: 131047 = janela de conversa expirada). Usado com event = "failed".

timestamp

stringTimestamp da falha. Usado com event = "failed".

recipientId

stringID do destinatário na plataforma. Usado com event = "failed".

oldId

stringNúmero antigo do cliente (obrigatório quando event = "client_phone_changed").

newId

stringNovo número do cliente (obrigatório quando event = "client_phone_changed").

Exemplo de Body

// event: failed
{
  "event": "failed",
  "externalMessageId": "wamid.xxx",
  "errorCode": 131047,
  "timestamp": "2025-06-01T14:30:00.000Z",
  "recipientId": "5511999998888@s.whatsapp.net"
}

// event: client_phone_changed
{
  "event": "client_phone_changed",
  "oldId": "5511999998888@s.whatsapp.net",
  "newId": "5511999990000@s.whatsapp.net"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/:connectionId/clientUpdate" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Resposta de Sucesso

{ "success": true }

Respostas

200 OK

Evento processado.

400 Bad Request

Campo event ausente ou campos obrigatórios faltando para o evento.

404 Not Found

Mensagem não encontrada (event: failed).

500 Internal Server Error

Erro interno.

Quando errorCode = 131047 (janela de conversa expirada), o chat é marcado com windowExpired: true e o campo é incluído no evento em tempo real. O token utilizado deve pertencer à mesma conexão informada na URL.

Atendimentos

Consulta do histórico de atendimentos encerrados. Resultados são escopados à conexão do token.

GET

/attendances

Lista atendimentos encerrados da conexão com filtros, paginação e ordenação.

Permissãoread

Query Parameters

page

stringPágina (≥1). Padrão: 1.

order

string"date" (data de encerramento) ou "messageCount". Padrão: "date".

direction

string"asc" ou "desc". Padrão: "desc".

startDate

stringData de início no fuso de Brasília (YYYY-MM-DD). Ex: 2025-06-01.

endDate

stringData de fim no fuso de Brasília (YYYY-MM-DD). Ex: 2025-06-30.

operatorId

stringFiltra pelo operador que encerrou o atendimento (ID do usuário).

departmentId

ObjectIdFiltra atendimentos que passaram pelo departamento informado.

tagId

ObjectIdFiltra atendimentos que possuem a tag informada.

uraId

ObjectIdFiltra atendimentos que passaram pela URA informada.

search

stringBusca por nome ou telefone do cliente. Case-insensitive.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/attendances" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439020",
      "chatId": "507f1f77bcf86cd799439021",
      "closedAt": "2025-06-01T21:30:00.000Z",
      "sessionStart": "2025-06-01T20:00:00.000Z",
      "sessionDurationMs": 5400000,
      "closedBy": {
        "operatorId": "507f1f77bcf86cd799439011",
        "operator": { "name": "Maria Silva" }
      },
      "client": {
        "_id": "507f1f77bcf86cd799439015",
        "name": "João Costa",
        "phone": "5511999998888"
      },
      "connection": {
        "_id": "507f1f77bcf86cd799439030",
        "name": "WhatsApp Principal",
        "type": "whatsapp_baileys"
      },
      "sessionOperators": [
        { "operatorId": "507f1f77bcf86cd799439011", "operator": { "name": "Maria Silva" } }
      ],
      "tags": [{ "_id": "...", "name": "Urgente", "color": "#FF0000", "icon": "AlertTriangle" }],
      "departments": [{ "_id": "...", "name": "Suporte", "color": "#0000FF" }],
      "uras": [{ "uraId": "...", "uraName": "Triagem" }],
      "messageCount": 24,
      "tagsAdded": 2,
      "tagsRemoved": 0,
      "departmentsAdded": 1,
      "departmentsRemoved": 0
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 5,
    "totalCount": 87,
    "perPage": 20,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Respostas

200 OK

Lista retornada.

400 Bad Request

Parâmetros inválidos.

401 Unauthorized

Token inválido.

500 Internal Server Error

Erro interno.

O connectionId é extraído automaticamente do token — não é um parâmetro de query. Atendimentos sem conexão válida são omitidos.

GET

/attendances/{attendanceId}

Retorna os detalhes completos de um atendimento encerrado: mensagens, logs de eventos, operadores participantes, tags, departamentos e execuções de URA.

Permissãoread

Path Parameters

attendanceId

ObjectIdID do atendimento (log de closed_chat).

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/attendances/:attendanceId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "attendance": {
      "_id": "507f1f77bcf86cd799439020",
      "chatId": "507f1f77bcf86cd799439021",
      "sessionStart": "2025-06-01T20:00:00.000Z",
      "closedAt": "2025-06-01T21:30:00.000Z",
      "sessionDurationMs": 5400000,
      "closedBy": { "operatorId": "...", "operator": { "name": "Maria Silva" } },
      "client": { "_id": "...", "name": "João Costa", "phone": "5511999998888", "profilePicturePath": null },
      "briefing": null
    },
    "connection": { "_id": "...", "name": "WhatsApp Principal", "type": "whatsapp_baileys" },
    "tags": [{ "_id": "...", "name": "Urgente", "color": "#FF0000", "icon": "AlertTriangle" }],
    "departments": [{ "_id": "...", "name": "Suporte", "color": "#0000FF" }],
    "participants": [
      { "operatorId": "507f1f77bcf86cd799439011", "operator": { "name": "Maria Silva" } }
    ],
    "uraExecutions": [
      {
        "_id": "...",
        "uraId": "...",
        "uraName": "Triagem",
        "status": "completed",
        "executionTime": 12000,
        "nodesExecuted": 5,
        "startedAt": "2025-06-01T20:00:05.000Z",
        "completedAt": "2025-06-01T20:00:17.000Z"
      }
    ],
    "logs": [
      { "_id": "...", "action": "operator_joined", "createdAt": "2025-06-01T20:01:00.000Z", "operator": { "name": "Maria Silva" } }
    ],
    "messages": [
      {
        "_id": "...",
        "operatorId": null,
        "content": "Olá, preciso de ajuda",
        "type": "text",
        "createdAt": "2025-06-01T20:00:30.000Z"
      }
    ]
  }
}

Respostas

200 OK

Atendimento retornado.

400 Bad Request

ID inválido.

401 Unauthorized

Token inválido.

404 Not Found

Atendimento não encontrado ou pertence a outra conexão.

500 Internal Server Error

Erro interno.

Logs read_new_messages são excluídos da resposta. Mensagens com mídia retornam URLs assinadas com validade de 6 horas no campo content (ou metadata.headerMediaUrl para cabeçalhos).

Bases Complexas

Coleções de objetos de schema livre para armazenar dados estruturados com filtragem e consulta dinâmica via operadores MongoDB. Cada objeto tem campo data flexível (qualquer JSON) e suporte a externalId para upserts idempotentes.

GET

/complexBases

Lista coleções do workspace com busca, paginação e ordenação.

Permissãoread

Query Parameters

listSearch

stringBusca por nome da coleção.

page

stringPágina (>=1). Padrão: 1.

perPage

stringItens por página (1–100). Padrão: 20.

order

string"name", "updatedAt", "createdAt" ou "objectCount". Padrão: "updatedAt".

direction

string"asc" ou "desc". Padrão: "desc".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/complexBases" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "items": [
      {
        "_id": "6a0b48612c18c5cc643b743c",
        "name": "Leads CRM",
        "description": "Contatos importados do CRM",
        "color": "#6366f1",
        "icon": "Database",
        "objectCount": 1240,
        "createdAt": "2025-01-15T10:00:00.000Z",
        "updatedAt": "2025-05-01T08:30:00.000Z"
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "totalCount": 1, "totalPages": 1 }
  }
}

Respostas

200 OK

Lista retornada.

401 Unauthorized

Token inválido.

500 Internal Server Error

Erro interno.

POST

/complexBases

Cria uma nova coleção no workspace.

Permissãoread_write

Body (JSON)

name

stringNome da coleção (único por workspace).

description

stringDescrição opcional.

color

stringCor em hex (ex: #6366f1).

icon

stringNome do ícone Lucide (ex: Database).

Exemplo de Body

{
  "name": "Leads CRM",
  "description": "Contatos importados do CRM",
  "color": "#6366f1",
  "icon": "Database"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/complexBases" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Leads CRM",
  "description": "Contatos importados do CRM",
  "color": "#6366f1",
  "icon": "Database"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "6a0b48612c18c5cc643b743c",
    "name": "Leads CRM",
    "description": "Contatos importados do CRM",
    "color": "#6366f1",
    "icon": "Database",
    "objectCount": 0,
    "createdAt": "2025-05-18T12:00:00.000Z",
    "updatedAt": "2025-05-18T12:00:00.000Z"
  }
}

Respostas

201 Created

Coleção criada.

400 Bad Request

Dados inválidos ou nome duplicado.

401 Unauthorized

Token inválido.

500 Internal Server Error

Erro interno.

GET

/complexBases/{baseId}

Retorna metadados da coleção junto com a primeira página de objetos.

Permissãoread

Path Parameters

baseId

ObjectIdID da coleção.

Query Parameters

page

stringPágina de objetos. Padrão: 1.

perPage

stringItens por página (1–100). Padrão: 20.

search

stringBusca textual nos campos de data.

order

string"createdAt", "updatedAt" ou "externalId". Padrão: "createdAt".

direction

string"asc" ou "desc". Padrão: "desc".

filters

stringFiltros MongoDB serializados como JSON (ex: {"data.status":{"$eq":"active"}}).

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/complexBases/:baseId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "base": {
      "_id": "6a0b48612c18c5cc643b743c",
      "name": "Leads CRM",
      "objectCount": 1240
    },
    "objects": {
      "items": [ { "_id": "...", "data": { "name": "João", "status": "active" }, "externalId": "lead-001", "createdAt": "..." } ],
      "pagination": { "page": 1, "perPage": 20, "totalCount": 1240, "totalPages": 62 }
    }
  }
}

Respostas

200 OK

Coleção e objetos retornados.

400 Bad Request

baseId inválido.

401 Unauthorized

Token inválido.

404 Not Found

Coleção não encontrada.

500 Internal Server Error

Erro interno.

PATCH

/complexBases/{baseId}

Atualiza metadados da coleção (nome, descrição, cor, ícone).

Permissãoread_write

Path Parameters

baseId

ObjectIdID da coleção.

Body (JSON)

name

stringNovo nome (único por workspace).

description

stringNova descrição.

color

stringNova cor em hex.

icon

stringNovo ícone Lucide.

Exemplo de Body

{ "name": "Leads CRM v2", "color": "#10b981" }

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/complexBases/:baseId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Resposta de Sucesso

{ "success": true, "data": { "_id": "...", "name": "Leads CRM v2", "color": "#10b981" } }

Respostas

200 OK

Coleção atualizada.

400 Bad Request

Dados inválidos.

401 Unauthorized

Token inválido.

404 Not Found

Coleção não encontrada.

500 Internal Server Error

Erro interno.

DELETE

/complexBases/{baseId}

Remove a coleção e todos os seus objetos em cascata. Irreversível.

Permissãoread_write

Path Parameters

baseId

ObjectIdID da coleção.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/complexBases/:baseId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{ "success": true }

Respostas

200 OK

Coleção e objetos removidos.

401 Unauthorized

Token inválido.

404 Not Found

Coleção não encontrada.

500 Internal Server Error

Erro interno.

Esta operação deleta permanentemente a coleção e todos os objetos associados. Não pode ser desfeita.

GET

/complexBases/{baseId}/objects

Lista objetos da coleção com paginação, busca textual e filtros MongoDB.

Permissãoread

Path Parameters

baseId

ObjectIdID da coleção.

Query Parameters

page

stringPágina (>=1). Padrão: 1.

perPage

stringItens por página (1–100). Padrão: 20.

search

stringBusca textual em todos os campos de data.

order

string"createdAt", "updatedAt" ou "externalId". Padrão: "createdAt".

direction

string"asc" ou "desc". Padrão: "desc".

filters

stringJSON com filtros MongoDB sobre campos data (ex: {"data.status":{"$eq":"active"}}).

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/complexBases/:baseId/objects" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "items": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "externalId": "lead-001",
        "data": { "name": "João Silva", "status": "active", "score": 95 },
        "createdBy": "api",
        "createdAt": "2025-05-01T10:00:00.000Z",
        "updatedAt": "2025-05-10T08:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "totalCount": 1240, "totalPages": 62 }
  }
}

Respostas

200 OK

Lista retornada.

400 Bad Request

Parâmetros ou filtros inválidos.

401 Unauthorized

Token inválido.

404 Not Found

Coleção não encontrada.

500 Internal Server Error

Erro interno.

POST

/complexBases/{baseId}/objects

Cria um objeto na coleção. O campo data aceita qualquer JSON (máx. 100 KB, profundidade máx. 10).

Permissãoread_write

Path Parameters

baseId

ObjectIdID da coleção.

Body (JSON)

data

objectPayload livre (qualquer JSON). Chaves não podem começar com $ ou conter ponto.

externalId

stringIdentificador externo único por coleção (máx. 256 chars). Usado para upserts idempotentes.

Exemplo de Body

{
  "externalId": "lead-001",
  "data": {
    "name": "João Silva",
    "status": "active",
    "score": 95,
    "tags": ["enterprise", "priority"],
    "meta": { "source": "hubspot", "importedAt": "2025-05-01" }
  }
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/complexBases/:baseId/objects" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "lead-001",
  "data": {
    "name": "João Silva",
    "status": "active",
    "score": 95,
    "tags": ["enterprise", "priority"],
    "meta": { "source": "hubspot", "importedAt": "2025-05-01" }
  }
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "complexBaseId": "6a0b48612c18c5cc643b743c",
    "externalId": "lead-001",
    "data": { "name": "João Silva", "status": "active", "score": 95 },
    "createdBy": "api",
    "createdAt": "2025-05-18T12:00:00.000Z",
    "updatedAt": "2025-05-18T12:00:00.000Z"
  }
}

Respostas

201 Created

Objeto criado.

400 Bad Request

data inválido ou payload excede limite.

401 Unauthorized

Token inválido.

404 Not Found

Coleção não encontrada.

409 Conflict

externalId já existe nesta coleção.

500 Internal Server Error

Erro interno.

Para criar ou atualizar pelo externalId de forma idempotente, use PUT /complexBases/{baseId}/objects/byExternalId/{externalId}.

GET

/complexBases/{baseId}/objects/{objectId}

Retorna um objeto pelo seu _id.

Permissãoread

Path Parameters

baseId

ObjectIdID da coleção.

objectId

ObjectIdID do objeto.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/complexBases/:baseId/objects/:objectId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "externalId": "lead-001",
    "data": { "name": "João Silva", "status": "active" },
    "createdBy": "api",
    "createdAt": "2025-05-18T12:00:00.000Z",
    "updatedAt": "2025-05-18T12:00:00.000Z"
  }
}

Respostas

200 OK

Objeto retornado.

400 Bad Request

ID inválido.

401 Unauthorized

Token inválido.

404 Not Found

Objeto não encontrado.

500 Internal Server Error

Erro interno.

PATCH

/complexBases/{baseId}/objects/{objectId}

Atualiza data e/ou externalId de um objeto pelo seu _id.

Permissãoread_write

Path Parameters

baseId

ObjectIdID da coleção.

objectId

ObjectIdID do objeto.

Body (JSON)

data

objectNovo payload (substitui integralmente o campo data).

externalId

stringNovo externalId (deve ser único na coleção). Envie null para remover.

Exemplo de Body

{
  "data": { "name": "João Silva", "status": "inactive", "score": 80 }
}

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/complexBases/:baseId/objects/:objectId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "data": { "name": "João Silva", "status": "inactive", "score": 80 }
}'

Resposta de Sucesso

{ "success": true, "data": { "_id": "...", "data": { "name": "João Silva", "status": "inactive" }, "updatedAt": "..." } }

Respostas

200 OK

Objeto atualizado.

400 Bad Request

Payload inválido.

401 Unauthorized

Token inválido.

404 Not Found

Objeto não encontrado.

409 Conflict

externalId já em uso.

500 Internal Server Error

Erro interno.

O PATCH substitui o campo data integralmente — não faz merge parcial.

DELETE

/complexBases/{baseId}/objects/{objectId}

Remove um objeto pelo seu _id.

Permissãoread_write

Path Parameters

baseId

ObjectIdID da coleção.

objectId

ObjectIdID do objeto.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/complexBases/:baseId/objects/:objectId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{ "success": true }

Respostas

200 OK

Objeto removido.

401 Unauthorized

Token inválido.

404 Not Found

Objeto não encontrado.

500 Internal Server Error

Erro interno.

POST

/complexBases/{baseId}/objects/query

Consulta avançada com filtros MongoDB, ordenação, paginação e skip. Retorna dados e total de resultados.

Permissãoread

Path Parameters

baseId

ObjectIdID da coleção.

Body (JSON)

filter

objectFiltro MongoDB sobre campos data.*. Operadores permitidos: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or, $not.

sort

objectOrdenação: { campo: 1 } (asc) ou { campo: -1 } (desc). Máx. 5 campos.

limit

numberMáximo de resultados (1–200). Padrão: 50.

skip

numberDocumentos a pular (para paginação manual). Padrão: 0.

Exemplo de Body

{
  "filter": {
    "$and": [
      { "data.status": { "$eq": "active" } },
      { "data.score": { "$gte": 80 } }
    ]
  },
  "sort": { "data.score": -1 },
  "limit": 20,
  "skip": 0
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/complexBases/:baseId/objects/query" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "$and": [
      { "data.status": { "$eq": "active" } },
      { "data.score": { "$gte": 80 } }
    ]
  },
  "sort": { "data.score": -1 },
  "limit": 20,
  "skip": 0
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "items": [
      { "_id": "...", "data": { "name": "João", "status": "active", "score": 95 }, "externalId": "lead-001" }
    ],
    "total": 48,
    "limit": 20,
    "skip": 0
  }
}

Respostas

200 OK

Resultados retornados.

400 Bad Request

Filtro inválido ou operador não permitido.

401 Unauthorized

Token inválido.

404 Not Found

Coleção não encontrada.

500 Internal Server Error

Erro interno.

Operadores de lógica ($and, $or, $not) podem ser aninhados até 8 níveis. Regex aceita máx. 200 chars e padrões de backtracking catastrófico são rejeitados. Arrays em $in/$nin aceitam máx. 200 itens.

GET

/complexBases/{baseId}/objects/byExternalId/{externalId}

Retorna um objeto pelo externalId fornecido pelo sistema externo.

Permissãoread

Path Parameters

baseId

ObjectIdID da coleção.

externalId

stringIdentificador externo do objeto.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/complexBases/:baseId/objects/byExternalId/:externalId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "externalId": "lead-001",
    "data": { "name": "João Silva", "status": "active" },
    "createdAt": "2025-05-01T10:00:00.000Z"
  }
}

Respostas

200 OK

Objeto retornado.

401 Unauthorized

Token inválido.

404 Not Found

Objeto não encontrado para este externalId.

500 Internal Server Error

Erro interno.

PUT

/complexBases/{baseId}/objects/byExternalId/{externalId}

Cria ou atualiza (upsert) um objeto pelo externalId. Idempotente: chamar múltiplas vezes com o mesmo externalId apenas atualiza o objeto existente.

Permissãoread_write

Path Parameters

baseId

ObjectIdID da coleção.

externalId

stringIdentificador externo (único por coleção).

Body (JSON)

data

objectPayload do objeto (substitui integralmente em atualizações).

Exemplo de Body

{
  "data": {
    "name": "João Silva",
    "status": "active",
    "score": 95,
    "updatedFrom": "webhook"
  }
}

Exemplo de Requisição

curl -X PUT "https://s4ilor.com/api/v1/complexBases/:baseId/objects/byExternalId/:externalId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": "João Silva",
    "status": "active",
    "score": 95,
    "updatedFrom": "webhook"
  }
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "externalId": "lead-001",
    "data": { "name": "João Silva", "status": "active", "score": 95 },
    "createdBy": "api",
    "createdAt": "2025-05-01T10:00:00.000Z",
    "updatedAt": "2025-05-18T12:00:00.000Z"
  },
  "created": false
}

Respostas

200 OK

Objeto criado (created: true) ou atualizado (created: false).

400 Bad Request

Payload inválido.

401 Unauthorized

Token inválido.

404 Not Found

Coleção não encontrada.

500 Internal Server Error

Erro interno.

O campo "created" na resposta indica se o objeto foi criado (true) ou atualizado (false). Use este endpoint para sincronização incremental de dados externos.

DELETE

/complexBases/{baseId}/objects/byExternalId/{externalId}

Remove um objeto pelo seu externalId.

Permissãoread_write

Path Parameters

baseId

ObjectIdID da coleção.

externalId

stringIdentificador externo do objeto.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/complexBases/:baseId/objects/byExternalId/:externalId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{ "success": true }

Respostas

200 OK

Objeto removido.

401 Unauthorized

Token inválido.

404 Not Found

Objeto não encontrado para este externalId.

500 Internal Server Error

Erro interno.

Bases de Conhecimento

Gerenciamento de bases de conhecimento e seus itens. Suporta busca semântica vetorial.

GET

/knowledgeBases

Lista bases de conhecimento com busca, paginação e ordenação.

Permissãoread

Query Parameters

search

stringBusca por nome.

page

stringPágina (≥1). Padrão: 1.

order

string"name" ou "createdAt". Padrão: "createdAt".

direction

string"asc" ou "desc". Padrão: "desc".

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/knowledgeBases" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439060",
      "name": "FAQ Produto",
      "description": "Perguntas frequentes sobre o produto",
      "createdAt": "2025-01-01T12:00:00.000Z",
      "updatedAt": "2025-06-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 1,
    "totalCount": 3,
    "hasNextPage": false,
    "hasPrevPage": false,
    "perPage": 20
  }
}

Respostas

200 OK

Lista retornada.

400 Bad Request

Parâmetros inválidos.

401 Unauthorized

Token inválido.

500 Internal Server Error

Erro interno.

POST

/knowledgeBases

Cria uma nova base de conhecimento.

Permissãoread_write

Body (JSON)

name

stringNome da base (máx. 100 caracteres).

description

stringDescrição da base (máx. 500 caracteres).

Exemplo de Body

{
  "name": "FAQ Produto",
  "description": "Perguntas frequentes sobre o produto"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/knowledgeBases" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "FAQ Produto",
  "description": "Perguntas frequentes sobre o produto"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "name": "FAQ Produto",
    "description": "Perguntas frequentes sobre o produto",
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-01-01T12:00:00.000Z"
  }
}

Respostas

201 Created

Base criada.

400 Bad Request

Dados inválidos.

401 Unauthorized

Token inválido.

500 Internal Server Error

Erro interno.

GET

/knowledgeBases/{knowledgeBaseId}

Retorna uma base com a primeira página de conhecimentos.

Permissãoread

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "name": "FAQ Produto",
    "description": "Perguntas frequentes sobre o produto",
    "knowledges": [
      {
        "_id": "507f1f77bcf86cd799439061",
        "title": "Como resetar senha?",
        "content": "Acesse Configurações > Segurança > Redefinir senha.",
        "status": "active",
        "createdAt": "2025-01-02T10:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "totalPages": 2, "totalCount": 25, "perPage": 20, "hasNextPage": true }
  }
}

Respostas

200 OK

Base retornada com conhecimentos.

400 Bad Request

ID inválido.

404 Not Found

Base não encontrada.

500 Internal Server Error

Erro interno.

PATCH

/knowledgeBases/{knowledgeBaseId}

Atualiza campos de uma base de conhecimento.

Permissãoread_write

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

Body (JSON)

name

stringNovo nome.

description

stringNova descrição.

Exemplo de Body

{ "name": "FAQ Produto v2" }

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "name": "FAQ Produto v2",
    "description": "Perguntas frequentes sobre o produto",
    "updatedAt": "2025-06-15T10:00:00.000Z"
  }
}

Respostas

200 OK

Base atualizada.

400 Bad Request

Dados inválidos ou nenhum campo enviado.

404 Not Found

Base não encontrada.

500 Internal Server Error

Erro interno.

DELETE

/knowledgeBases/{knowledgeBaseId}

Remove uma base e todos os seus conhecimentos.

Permissãoread_write

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{ "success": true }

Respostas

200 OK

Base e conhecimentos removidos.

404 Not Found

Base não encontrada.

500 Internal Server Error

Erro interno.

GET

/knowledgeBases/{knowledgeBaseId}/knowledges

Lista conhecimentos da base com busca, paginação e filtro de status.

Permissãoread

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

Query Parameters

search

stringBusca por título ou conteúdo.

page

stringPágina (≥1). Padrão: 1.

status

string"active" ou "inactive". Omitir retorna todos.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId/knowledges" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439061",
      "title": "Como resetar senha?",
      "content": "Acesse Configurações > Segurança > Redefinir senha.",
      "status": "active",
      "createdAt": "2025-01-02T10:00:00.000Z",
      "updatedAt": "2025-01-02T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "totalPages": 2, "totalCount": 25, "perPage": 20, "hasNextPage": true }
}

Respostas

200 OK

Lista retornada.

400 Bad Request

Parâmetros inválidos.

404 Not Found

Base não encontrada.

500 Internal Server Error

Erro interno.

POST

/knowledgeBases/{knowledgeBaseId}/knowledges

Cria um conhecimento na base.

Permissãoread_write

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

Body (JSON)

title

stringTítulo do conhecimento (máx. 200 caracteres).

content

stringConteúdo do conhecimento.

status

string"active" (padrão) ou "inactive".

Exemplo de Body

{
  "title": "Como resetar senha?",
  "content": "Acesse Configurações > Segurança > Redefinir senha.",
  "status": "active"
}

Exemplo de Requisição

curl -X POST "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId/knowledges" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Como resetar senha?",
  "content": "Acesse Configurações > Segurança > Redefinir senha.",
  "status": "active"
}'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439061",
    "title": "Como resetar senha?",
    "content": "Acesse Configurações > Segurança > Redefinir senha.",
    "status": "active",
    "createdAt": "2025-01-02T10:00:00.000Z",
    "updatedAt": "2025-01-02T10:00:00.000Z"
  }
}

Respostas

201 Created

Conhecimento criado.

400 Bad Request

Dados inválidos.

404 Not Found

Base não encontrada.

500 Internal Server Error

Erro interno.

GET

/knowledgeBases/{knowledgeBaseId}/knowledges/{knowledgeId}

Retorna um conhecimento específico.

Permissãoread

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

knowledgeId

ObjectIdID do conhecimento.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId/knowledges/:knowledgeId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439061",
    "title": "Como resetar senha?",
    "content": "Acesse Configurações > Segurança > Redefinir senha.",
    "status": "active",
    "createdAt": "2025-01-02T10:00:00.000Z",
    "updatedAt": "2025-01-02T10:00:00.000Z"
  }
}

Respostas

200 OK

Conhecimento retornado.

404 Not Found

Base ou conhecimento não encontrado.

500 Internal Server Error

Erro interno.

PATCH

/knowledgeBases/{knowledgeBaseId}/knowledges/{knowledgeId}

Atualiza campos de um conhecimento.

Permissãoread_write

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

knowledgeId

ObjectIdID do conhecimento.

Body (JSON)

title

stringNovo título.

content

stringNovo conteúdo.

status

string"active" ou "inactive".

Exemplo de Body

{ "status": "inactive" }

Exemplo de Requisição

curl -X PATCH "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId/knowledges/:knowledgeId" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Resposta de Sucesso

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439061",
    "title": "Como resetar senha?",
    "content": "Acesse Configurações > Segurança > Redefinir senha.",
    "status": "inactive",
    "updatedAt": "2025-06-15T10:00:00.000Z"
  }
}

Respostas

200 OK

Conhecimento atualizado.

400 Bad Request

Nenhum campo enviado.

404 Not Found

Base ou conhecimento não encontrado.

500 Internal Server Error

Erro interno.

DELETE

/knowledgeBases/{knowledgeBaseId}/knowledges/{knowledgeId}

Remove um conhecimento.

Permissãoread_write

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

knowledgeId

ObjectIdID do conhecimento.

Exemplo de Requisição

curl -X DELETE "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId/knowledges/:knowledgeId" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{ "success": true }

Respostas

200 OK

Conhecimento removido.

404 Not Found

Base ou conhecimento não encontrado.

500 Internal Server Error

Erro interno.

GET

/knowledgeBases/{knowledgeBaseId}/knowledges/search

Busca semântica (vetorial) por conhecimentos na base.

Permissãoread

Path Parameters

knowledgeBaseId

ObjectIdID da base de conhecimento.

Query Parameters

q

stringTexto da busca semântica.

limit

stringMáximo de resultados (1–20). Padrão: 5.

Exemplo de Requisição

curl -X GET "https://s4ilor.com/api/v1/knowledgeBases/:knowledgeBaseId/knowledges/search" \
  -H "Authorization: Bearer <seu-token>"

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439061",
      "title": "Como resetar senha?",
      "content": "Acesse Configurações > Segurança > Redefinir senha.",
      "status": "active",
      "score": 0.92
    }
  ]
}

Respostas

200 OK

Resultados semânticos retornados.

400 Bad Request

Parâmetro q ausente ou limit inválido.

404 Not Found

Base não encontrada.

500 Internal Server Error

Erro interno.

A busca usa embeddings vetoriais. Apenas conhecimentos com status active são indexados. Resultados ordenados por similaridade (score 0–1).

S4ilor API v1 — Documentação Completa

Buscar

Documentação da API

Path Parameters

Body (JSON)

Body (JSON)

Respostas

Body (JSON)

Body (JSON)

Respostas