CRM — Overview - Khal Docs

API multi-tenant pra ler/escrever dados do CRM (empresa, cliente, negócios,
tabelas customizadas) via header api-key. Todos os endpoints abaixo respondem
no host do tenant (https://api-<tenant>.atendimento.khal.ai) — a api-key
já carrega o contexto multi-tenant.

Quickstart em 60 segundos

Configure api-key no Environment do Apidog (variável api-key).

Liste empresas pra pegar IDs:

Pegue um id da resposta e use nos demais endpoints (relacionamentos, vínculo com ticket).

Conceitos rápidos

Tenant (multi-empresa)

Cada cliente da Khal roda em um host próprio: https://api-<tenant>.atendimento.khal.ai.
A api-key está atrelada ao tenant — não precisa trocar de tenant; resolve sozinho.

Scopes

O CRM separa as tabelas por scope:

Scope	Tabelas	O que é
`customer`	`cliente`, `avaliacao`	Pessoa que consome / é atendida.
`contact`	`contato`	Canais do cliente (phone, email, WhatsApp, …).
`business`	`negociacao`	Oportunidade/deal vinculada a 1 cliente.
`company`	`empresa`, `empresas_relacionadas`, + tabelas customizadas (`financeiro`, `contrato`, …)	Empresa B2B (CNPJ). `cliente.id_empresa` é a FK que liga cliente → empresa.
`catalog`	(custom por tenant)	Catálogos auxiliares (listas de opções).

Autenticação

Todas as rotas exigem o header api-key:

api-key: <SEU_TOKEN>

Sem header → 401. A api-key resolve tenant + permissões automaticamente.
No Apidog, defina a variável api-key no Environment e os exemplos {{api-key}}
são preenchidos automaticamente em todos os endpoints.

Endpoints centrais

Genérico (qualquer tabela do CRM)

Rota	Pra que serve
`POST /api/v2/crm/data/filter`	Listar/filtrar (qualquer tabela).
`POST /api/v2/crm/data/set`	Criar (`method:"post"`) ou atualizar (`method:"patch"`).
`POST /api/v2/crm/data/delete`	Hard-delete (bloqueado para tabela company — use soft-delete).

Específicos de Empresa (subpasta Empresas Relacionadas)

Rota	Pra que serve
`GET /api/v2/empresa-relacionadas/types`	Tipos válidos pra `tipo_de_relacionamento`.
`GET /api/v2/empresa-relacionadas/by-empresa/{id}?onlyActive=true`	Listar relacionamentos (ambas direções).
`POST /api/v2/empresa-relacionadas`	Criar vínculo direcional empresa→empresa.
`PATCH /api/v2/empresa-relacionadas/{id}/type`	Alterar tipo.
`PATCH /api/v2/empresa-relacionadas/{id}/inactivate`	Inativar (reversível).
`DELETE /api/v2/empresa-relacionadas/{id}`	Hard-delete (irreversível).

Ticket ↔ Empresa (subpasta Ticket ↔ Empresa)

Rota	Pra que serve
`GET /api/v2/ticket/{id}/empresas`	Empresas elegíveis pro vínculo (cliente direto + relacionadas).
`PUT /api/v2/ticket/{id}/empresa`	Vincular/trocar a empresa do ticket.
`GET /api/v2/ticket/info/{id}`	Detalhe do ticket (customer + empresa + business).

Formato das respostas

Não é uniforme — preste atenção em qual estilo o endpoint usa:

Endpoints	Formato	Exemplo
`/crm/data/filter`, `/crm/data/set`	Array nu (sem envelope)	`[{...}, {...}]`
Todos os outros (`/empresa-relacionadas/`, `/ticket/`, `/data/delete`)	Envelope `{ok, data}`	`{"ok":true,"data":[...]}`
Erros 4xx/5xx	`{"error":"..."}` (mscrm direto) ou `{"ok":false,"message":"..."}` (envelope)	varia

Cada endpoint mostra o formato real no exemplo de resposta — sempre confira lá.

Operadores de filtro (em `/crm/data/filter` e `/crm/data/set patch`)

Operador	Significado	Tipo de `value`
`=`	igual	string / number / boolean
`!=` ou `<>`	diferente	string / number / boolean
`>` `<` `>=` `<=`	comparação numérica/data	number / date
`in`	está na lista	array

Comparação exata (não há LIKE/fuzzy). Pra busca textual livre, use o endpoint de search dedicado (fora desta API).

Tipos de `value`

string: aspas obrigatórias ("texto").

CNPJ / CPF no banco é sem formatação — use "11111111000111", não "11.111.111/0001-11".

number: sem aspas (12, 12.5).

boolean: true / false (sem aspas — "true" quebra).

date: ISO-8601 ("2026-01-01T00:00:00Z").

array: usado só com in ([1,2,3]).

Paginação

Objeto aninhado (não plano): {"page": {"page": 0, "limit": 100}} — page começa em 0, não 1. Default 100/página, máximo 1000.

Soft-delete e auditoria (escopo `company`)

Tabelas do scope company (incl. tabelas customizadas, ex: financeiro/contrato):

Hard-delete via /data/delete é bloqueado (400). Pra "remover", use data/set patch:

Inativar (reversível, some dos seletores): {"payload": {"ativo": false}}.

Soft-delete (destrutivo, auditável): {"payload": {"ativo": false, "deleted_at": "<ISO-8601>"}}.

Reads filtram deleted_at IS NULL automaticamente — registros soft-deletados somem do data/filter.

Toda mutação grava trilha em crm_data_audit (interno, sem endpoint público de leitura).

Fluxo típico: vincular uma empresa nova a um ticket

POST /api/v2/crm/data/set method:"post" table:"empresa" — cria a empresa, anota o id.

(opcional) POST /api/v2/empresa-relacionadas — vincula essa empresa a outra existente.

GET /api/v2/ticket/{id}/empresas — confirma que a empresa nova apareceu na lista de elegíveis.

PUT /api/v2/ticket/{id}/empresa {"id_empresa_crm": <id>} — vincula ao ticket. Se já havia outra empresa, o vínculo anterior é inativado.

GET /api/v2/ticket/info/{id} — valida que data.empresa agora reflete a empresa nova.

Erros comuns

HTTP	Causa típica	Resposta típica
400	Payload inválido (campo errado, operator desconhecido, `patch` sem `filter`, hard-delete em tabela company)	`{"error":"..."}`
401	Header `api-key` ausente ou inválido	`{"tokenError":"..."}`
404	Recurso inexistente (relacionamento, ticket)	`{"ok":false,"message":"..."}`
422	Invariante violado (self-relation, duplicata, empresa inativa em vínculo)	`{"ok":false,"message":"..."}`
500	Bug interno — abrir ticket no time de plataforma com o `correlation_id` da resposta	varia

CRM — Overview

Quickstart em 60 segundos#

Conceitos rápidos#

Tenant (multi-empresa)#

Scopes#

Autenticação#

Endpoints centrais#

Genérico (qualquer tabela do CRM)#

Específicos de Empresa (subpasta Empresas Relacionadas)#

Ticket ↔ Empresa (subpasta Ticket ↔ Empresa)#

Formato das respostas#

Operadores de filtro (em /crm/data/filter e /crm/data/set patch)#

Tipos de value#

Paginação#

Soft-delete e auditoria (escopo company)#

Fluxo típico: vincular uma empresa nova a um ticket#

Erros comuns#