API multi-tenant pra workflow / atendimento (ticket) via header api-key.
Mesmas regras de autenticação e tenant da pasta CRM — diferença é o
domínio: aqui você cria, movimenta e consulta tickets; o CRM gerencia os
dados de cliente/empresa que esses tickets representam.Conceitos rápidos#
Estrutura#
Workspace ──┬── Workflow ──┬── Phase (fase) ──┬── Ticket
│ │ ├── Ticket
│ └── Phase └── ...
└── Workflow
Workspace: agrupador de workflows (ex.: "Suporte ao cliente", "Financeiro")
Workflow: fluxo de atendimento (ex.: "Reclamações", "Dúvidas")
Phase: estágio dentro do workflow (statusId: 1=em andamento, 2=insucesso, 3=sucesso). Flag finisher=true indica fase terminal.
Ticket: o atendimento em si — tem id_phase (fase atual), customer (vinculado ao CRM), mensagens, SLA, etc.
Estado do ticket#
super_status: "Em andamento" | "Finalizado com sucesso" | "Finalizado com insucesso"
phase + id_phase: estado atual no workflow
customer: cliente CRM vinculado (ou null)
business: negociação vinculada (ou null)
responsibles[]: operadores designados
protocols: protocolos de atendimento ligados ao ticket
Endpoints centrais#
Estruturais (subpasta Workspaces & Workflows)#
| Rota | Pra que serve |
|---|
GET /api/v2/workspace/ | Listar workspaces + workflows acessíveis ao usuário da api-key. |
GET /api/v2/workflow-v2/workflows/{workflowId}/phases | Listar fases de um workflow. |
GET /api/v2/workflow-v2/workflow/{workflowId}/tickets/all-data | Listar tickets por fase (paginado). |
Ações de ticket (subpasta Tickets)#
| Rota | Pra que serve |
|---|
POST /api/v2/ticket | Criar ticket (com crm opcional pra vincular cliente existente). |
POST /api/v2/ticket/custom | Criar ticket + auto-vincular customer (via contact_search ou criar customer novo). |
POST /api/v2/ticket/finish | Movimentar entre fases / finalizar (se a fase de destino tem finisher=true). |
GET /api/v2/ticket/info/{id} | Detalhe completo (mensagens, SLA, customer, business, eligible_phases, protocols…). |
PUT /api/v2/workflow-v2/{ticketId} | Atualizar name / description. |
PUT /api/v2/ticket/link_customer | Vincular cliente CRM a um ticket existente. |
POST /api/v2/ticket/message | Adicionar nota (is_note: true) ou mensagem. |
Status (statusId na fase)#
| id | Significado | Quando entra |
|---|
| 1 | Em andamento | ticket entrou na fase mas ainda não finalizou |
| 2 | Finalizado com insucesso | fase finisher de insucesso |
| 3 | Finalizado com sucesso | fase finisher de sucesso |
Canais (canal_contato em crm.contact)#
| id | Canal |
|---|
| 2 | WhatsApp |
| 3 | SMS |
| 4 | E-mail |
| 6 | Telefone |
| 9 | Telegram |
| 12 | RCS |
Erros comuns#
| HTTP | Causa típica |
|---|
| 400 | Payload inválido, id_phase inexistente, crm.contact parcialmente preenchido |
| 401 | api-key ausente / inválida |
| 404 | Ticket / workflow / phase inexistente |
| 500 | Bug interno — abrir ticket no time de plataforma |
Modificado em 2026-11-04 02:31:07
