{ "openapi": "3.1.0", "info": { "title": "API do Fluxo Jurídico", "version": "1.0.0", "description": "API REST para integrar o Fluxo Jurídico ao seu site, ao seu CRM e a ferramentas como n8n, Make e Zapier.\n\n**Autenticação:** envie a chave do workspace no cabeçalho `Authorization: Bearer fj_live_…`. A chave é criada em Configurações › Empresa › Chaves de API e aparece uma única vez.\n\n**Isolamento:** a chave já identifica o workspace. Nenhum endpoint aceita o workspace no corpo da requisição, e registro de outro workspace responde como inexistente.\n\n**Erros:** sempre `{ \"error\": { \"code\", \"message\", \"request_id\" } }`, com mensagem em português. A lista completa está em `GET /errors`.", "contact": { "name": "Suporte Fluxo Jurídico", "url": "https://fluxojuridico.com.br/ajuda" } }, "servers": [ { "url": "https://api.fluxojuridico.com.br/functions/v1/public-api", "description": "Produção" } ], "tags": [ { "name": "Conta", "description": "Conferir a chave, o consumo e a lista de erros possíveis. Comece por aqui." }, { "name": "Contatos", "description": "O cadastro de pessoas: criar a partir do site, atualizar, marcar, mesclar duplicados e atender pedido de exclusão de dados." }, { "name": "Etiquetas", "description": "As marcações usadas para segmentar contatos." }, { "name": "Conversas", "description": "A linha do tempo com cada contato e o histórico de mensagens." }, { "name": "Mensagens", "description": "Enviar WhatsApp e consultar o que já foi trocado." }, { "name": "Atendimentos", "description": "O ciclo de trabalho: encerrar, transferir, priorizar, adiar e mover no funil." }, { "name": "Funis", "description": "Os quadros e etapas por onde os atendimentos caminham." }, { "name": "Filas", "description": "Os grupos de atendimento e a situação de cada um agora." }, { "name": "Canais", "description": "Os números e contas conectados. Nunca devolve credencial." }, { "name": "Templates", "description": "Os modelos aprovados pela Meta — o que permite falar fora da janela de 24 horas." }, { "name": "Campanhas", "description": "Acompanhar os disparos em massa e os números de entrega. Somente leitura." }, { "name": "Agenda", "description": "Consultar horários livres e marcar reuniões, com o evento criado na Google Agenda." }, { "name": "Robôs", "description": "Os robôs de atendimento e o controle de ligar/desligar por conversa." }, { "name": "Documentos", "description": "Contratos enviados para assinatura eletrônica e a situação de cada um." }, { "name": "Ligações", "description": "O registro de ligações, com duração e transcrição." }, { "name": "Base de conhecimento", "description": "O material que o robô consulta para responder — sincronizável com o site do escritório." }, { "name": "Biblioteca", "description": "Respostas rápidas e macros usadas pela equipe." }, { "name": "Webhooks", "description": "O caminho inverso: nós avisamos o seu sistema quando algo acontece aqui." }, { "name": "Relatórios", "description": "Os mesmos números da tela de Relatórios, para alimentar o seu painel." }, { "name": "Equipe", "description": "Quem faz parte do workspace, para atribuir atendimento e reunião." }, { "name": "Auditoria", "description": "Tudo o que foi feito no workspace, inclusive pela própria API." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Chave do workspace, no formato `fj_live_…`." } }, "schemas": { "Erro": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Código estável do erro. Use este valor no seu tratamento, não a mensagem." }, "message": { "type": "string", "description": "Explicação em português, própria para mostrar a uma pessoa." }, "details": { "description": "Informação extra sobre o que exatamente falhou. Presente quando ajuda." }, "request_id": { "type": "string", "description": "Identificador desta requisição. Informe ao suporte ao relatar um problema." } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ] }, "Paginacao": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Quantos itens por página." }, "offset": { "type": "integer", "description": "Quantos itens foram pulados." }, "total": { "type": [ "integer", "null" ], "description": "Total de itens que casam com o filtro." }, "has_more": { "type": "boolean", "description": "Se ainda há página seguinte." } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/conversations/{id}/bot/activate": { "post": { "tags": [ "Robôs" ], "summary": "Ligar o robô numa conversa", "description": "Coloca o robô para atender esta conversa a partir de agora. Exige atendimento ABERTO na conversa — o robô move etapa, transfere para fila e programa acompanhamento, e tudo isso se ancora no atendimento.\n\n**Permissão necessária:** `bots:write`", "operationId": "post_conversations__id__bot_activate", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da conversa.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "bot_id": "cc44dd55-ee66-4778-899a-bb0011223344", "session_id": "9f0e1d2c-3b4a-4596-8778-6a5b4c3d2e1f", "status": "active" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "422": { "description": "`BOT_NOT_CONFIGURED` — O robô não está configurado para operar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "BOT_NOT_CONFIGURED": { "summary": "BOT_NOT_CONFIGURED", "value": { "error": { "code": "BOT_NOT_CONFIGURED", "message": "O robô não está configurado para operar.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "format": "uuid", "description": "Robô a ligar. Veja os ids em GET /bots." } }, "required": [ "bot_id" ], "additionalProperties": false }, "example": { "bot_id": "cc44dd55-ee66-4778-899a-bb0011223344" } } } } } }, "/conversations/{id}/bot/deactivate": { "post": { "tags": [ "Robôs" ], "summary": "Desligar o robô numa conversa", "description": "O robô para de responder e a conversa fica com a equipe. É o que a tela faz quando um atendente assume.\n\n**Permissão necessária:** `bots:write`", "operationId": "post_conversations__id__bot_deactivate", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da conversa.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "deactivated": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Motivo registrado no histórico.", "example": "assumido_por_humano" } }, "additionalProperties": false }, "example": { "reason": "assumido_por_humano" } } } } } }, "/boards/{id}/stages": { "get": { "tags": [ "Funis" ], "summary": "Listar as etapas de um quadro", "description": "As colunas de um quadro, na ordem em que aparecem no kanban. O `id` de cada etapa é o que move um atendimento no funil.\n\n**Permissão necessária:** `pipelines:read`", "operationId": "get_boards__id__stages", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do quadro.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Qualificação", "color": "#64748B", "display_order": 0, "is_default": true, "created_at": "2026-06-01T10:00:00Z" } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/{id}/block": { "post": { "tags": [ "Contatos" ], "summary": "Bloquear contato", "description": "Contato bloqueado para de gerar conversa nova e não entra em campanha.\n\n**Permissão necessária:** `contacts:write`", "operationId": "post_contacts__id__block", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "is_blocked": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/{id}/conversations": { "get": { "tags": [ "Contatos" ], "summary": "Listar conversas de um contato", "description": "As conversas desse contato, uma por canal em que ele já falou. É por aqui que se chega ao `conversation_id` para ler o histórico ou responder.\n\n**Permissão necessária:** `conversations:read`", "operationId": "get_contacts__id__conversations", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "77c3…", "channel_id": "0a2b…", "inbox_status": "open", "last_message_at": "2026-07-25T09:41:00Z", "unread_count": 0 } ], "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/{id}/custom-fields": { "get": { "tags": [ "Contatos" ], "summary": "Ler os campos personalizados de um contato", "description": "Os valores dos campos extras que o escritório criou (número do processo, vara, matrícula…). A definição de cada campo está em GET /custom-fields.\n\n**Permissão necessária:** `contacts:read`", "operationId": "get_contacts__id__custom_fields", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "field_id": "c9a1…", "field_name": "Número do processo", "field_type": "text", "value": "0001234-56.2026.5.02.0011" } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Contatos" ], "summary": "Gravar campos personalizados de um contato", "description": "Grava um ou mais campos. O valor passa pela mesma validação da tela (tipo, obrigatoriedade e máscara), então valor fora do formato é recusado com o motivo exato.\n\n**Permissão necessária:** `contacts:write`", "operationId": "put_contacts__id__custom_fields", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "field_id": "c9a1…", "value": "0001234-56.2026.5.02.0011" } ] } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "description": "Lista de `{ field_id, value }`.", "example": [ { "field_id": "c9a1…", "value": "0001234-56.2026.5.02.0011" } ] } }, "required": [ "fields" ], "additionalProperties": false }, "example": { "fields": [ { "field_id": "c9a1…", "value": "0001234-56.2026.5.02.0011" } ] } } } } } }, "/contacts/{id}/media": { "get": { "tags": [ "Contatos" ], "summary": "Listar arquivos trocados com o contato", "description": "Imagens, áudios e documentos de todas as conversas dele. `url` é um link temporário, válido por 1 hora.\n\n**Permissão necessária:** `conversations:read`", "operationId": "get_contacts__id__media", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "message_id": "e4f1…", "message_type": "image", "direction": "inbound", "created_at": "2026-07-22T11:02:00Z", "url": "https://…/wa-media/…?token=…" } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/{id}/notes": { "get": { "tags": [ "Contatos" ], "summary": "Listar notas do contato", "description": "Notas internas datadas, visíveis só para a equipe. Não vão para o cliente.\n\n**Permissão necessária:** `contacts:read`", "operationId": "get_contacts__id__notes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantas por página (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantas pular.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "b1e0…", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "content": "Cliente pediu retorno após as 18h.", "author_id": null, "created_at": "2026-07-24T18:10:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Contatos" ], "summary": "Adicionar nota ao contato", "description": "Registra uma observação datada no contato, visível só para a equipe. Não é enviada ao cliente.\n\n**Permissão necessária:** `contacts:write`", "operationId": "post_contacts__id__notes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b1e0…", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "content": "Cliente pediu retorno após as 18h.", "created_at": "2026-07-24T18:10:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Texto da nota.", "example": "Cliente pediu retorno após as 18h." } }, "required": [ "content" ], "additionalProperties": false }, "example": { "content": "Cliente pediu retorno após as 18h." } } } } } }, "/contacts/{id}/tags": { "post": { "tags": [ "Contatos" ], "summary": "Marcar contato com etiquetas", "description": "Adiciona etiquetas sem remover as que já existem. Etiqueta que ainda não existe no workspace é criada.\n\n**Permissão necessária:** `tags:write`", "operationId": "post_contacts__id__tags", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "tags": [ "auxilio-acidente", "lead-quente" ] } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "description": "Lista de etiquetas.", "example": [ "lead-quente", "auxilio-acidente" ] } }, "required": [ "tags" ], "additionalProperties": false }, "example": { "tags": [ "lead-quente", "auxilio-acidente" ] } } } } } }, "/contacts/{id}/tags/{tag}": { "delete": { "tags": [ "Contatos" ], "summary": "Remover uma etiqueta do contato", "description": "Tira uma etiqueta desse contato. A etiqueta continua existindo no workspace para os outros contatos.\n\n**Permissão necessária:** `tags:write`", "operationId": "delete_contacts__id__tags__tag_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "tag", "in": "path", "required": true, "description": "Nome da etiqueta. Codifique caractere especial na URL.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "tags": [ "auxilio-acidente" ] } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/{id}/tickets": { "get": { "tags": [ "Contatos" ], "summary": "Histórico de atendimentos do contato", "description": "Todos os atendimentos que a pessoa já teve, abertos e encerrados, com a etapa do funil de cada um.\n\n**Permissão necessária:** `tickets:read`", "operationId": "get_contacts__id__tickets", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "aa10…", "ticket_number": 482, "opened_at": "2026-07-20T13:05:00Z", "closed_at": null, "queue_id": "5f1c…", "pipeline_stage_id": "9e2d…", "resolution_note": null } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/{id}/unblock": { "post": { "tags": [ "Contatos" ], "summary": "Desbloquear contato", "description": "Volta a permitir conversa e campanha com esse contato.\n\n**Permissão necessária:** `contacts:write`", "operationId": "post_contacts__id__unblock", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "is_blocked": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/lookup": { "get": { "tags": [ "Contatos" ], "summary": "Buscar contato por telefone", "description": "Atalho para descobrir se um telefone já é contato antes de criar. Tolera as duas formas do celular brasileiro (com e sem o 9º dígito), que é a causa mais comum de contato duplicado.\n\n**Permissão necessária:** `contacts:read`", "operationId": "get_contacts_lookup", "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "Telefone em qualquer formato.", "schema": { "type": "string" }, "example": "11987654321" } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "name": "Maria Souza", "first_name": "Maria", "last_name": "Souza", "email": "maria.souza@exemplo.com.br", "phone": "+5511987654321", "channel_type": "whatsapp", "tags": [ "lead-quente", "auxilio-acidente" ], "is_blocked": false, "city": "São Paulo", "state": "SP", "metadata": { "crm_id": "A-1099" }, "created_at": "2026-07-20T13:02:11.482Z", "updated_at": "2026-07-25T09:41:55.017Z" } } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts/merge": { "post": { "tags": [ "Contatos" ], "summary": "Mesclar dois contatos", "description": "Junta o contato `merge_id` dentro do `keep_id`: conversas, mensagens, atendimentos e etiquetas passam para o que fica. O mesclado deixa de aparecer nas listagens e passa a apontar para o que ficou.\n\n**Permissão necessária:** `contacts:write`", "operationId": "post_contacts_merge", "parameters": [], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "kept": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "merged": "8b7c22e1-4a90-41d3-b0aa-77e1c9f0a512", "moved": { "conversations": 2, "messages": 41 } } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keep_id": { "type": "string", "format": "uuid", "description": "Contato que permanece." }, "merge_id": { "type": "string", "format": "uuid", "description": "Contato que será absorvido." } }, "required": [ "keep_id", "merge_id" ], "additionalProperties": false }, "example": { "keep_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "merge_id": "8b7c22e1-4a90-41d3-b0aa-77e1c9f0a512" } } } } } }, "/conversations/{id}/messages": { "get": { "tags": [ "Conversas" ], "summary": "Listar mensagens de uma conversa", "description": "As mensagens em ordem cronológica inversa (a mais recente primeiro). Mensagem com arquivo vem com `media_url`, um link temporário válido por 1 hora. Notas internas e registros de atividade aparecem com `type: \"internal_note\"`; use `kind=regular` para trazer só o que o cliente viu.\n\n**Permissão necessária:** `conversations:read`", "operationId": "get_conversations__id__messages", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da conversa.", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "description": "`regular` traz só a conversa real; `activity` o registro de eventos (transferiu, encerrou); `system` os avisos automáticos.", "schema": { "type": "string", "enum": [ "regular", "activity", "system" ] } }, { "name": "direction", "in": "query", "required": false, "description": "Recebidas ou enviadas.", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "since", "in": "query", "required": false, "description": "Só as criadas depois desta data.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantas por página (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantas pular.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "e4f1a733-90c2-4b58-8d16-77aa0b9e5c34", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "direction": "outbound", "type": "text", "status": "sent", "text_body": "Bom dia, Maria! Recebemos os seus documentos.", "source": "api", "external_message_id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABEYEjc3QkI2NkM5RjhBMkE0RTUxAA==", "created_at": "2026-07-25T09:41:55.017Z", "media_url": null } ], "pagination": { "limit": 25, "offset": 0, "total": 41, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations/{id}/notes": { "post": { "tags": [ "Conversas" ], "summary": "Registrar nota interna na conversa", "description": "Aparece na linha do tempo para a equipe, com fundo destacado. **Nunca é enviada ao cliente.**\n\n**Permissão necessária:** `conversations:write`", "operationId": "post_conversations__id__notes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da conversa.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "d1c2…", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "type": "internal_note", "text_body": "Documentos conferidos, falta o comprovante de residência.", "created_at": "2026-07-25T10:02:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Texto da nota.", "example": "Documentos conferidos, falta o comprovante de residência." } }, "required": [ "content" ], "additionalProperties": false }, "example": { "content": "Documentos conferidos, falta o comprovante de residência." } } } } } }, "/kb/articles": { "get": { "tags": [ "Base de conhecimento" ], "summary": "Listar artigos da base de conhecimento", "description": "É o material que o robô consulta para responder. Artigo com `published: false` não é usado pelo robô.\n\n**Permissão necessária:** `kb:read`", "operationId": "get_kb_articles", "parameters": [ { "name": "category_id", "in": "query", "required": false, "description": "Filtra por categoria.", "schema": { "type": "string", "format": "uuid" } }, { "name": "published", "in": "query", "required": false, "description": "Só os publicados ou só os rascunhos.", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "required": false, "description": "Busca no título.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071", "category_id": "e0f1a2b3-c4d5-46e7-8f90-a1b2c3d4e5f6", "title": "Quem tem direito ao Auxílio-Acidente", "content": "O benefício é devido ao segurado que…", "published": true, "views": 34 } ], "pagination": { "limit": 25, "offset": 0, "total": 12, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Base de conhecimento" ], "summary": "Criar artigo", "description": "Serve para manter a base sincronizada com o site do escritório: o mesmo texto que está no site vira material do robô.\n\n**Permissão necessária:** `kb:write`", "operationId": "post_kb_articles", "parameters": [], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071", "title": "Quem tem direito ao Auxílio-Acidente", "published": true, "views": 0 } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Título do artigo.", "example": "Quem tem direito ao Auxílio-Acidente" }, "content": { "type": "string", "description": "Texto do artigo." }, "category_id": { "type": "string", "format": "uuid", "description": "Categoria a que pertence." }, "published": { "type": "boolean", "description": "Publicado (o robô consulta) ou rascunho.", "example": true } }, "required": [ "title" ], "additionalProperties": false }, "example": { "title": "Quem tem direito ao Auxílio-Acidente", "content": "O benefício é devido ao segurado que…", "published": true } } } } } }, "/kb/articles/{id}": { "get": { "tags": [ "Base de conhecimento" ], "summary": "Obter um artigo", "description": "O texto completo de um artigo da base de conhecimento — o mesmo material que o robô consulta para responder.\n\n**Permissão necessária:** `kb:read`", "operationId": "get_kb_articles__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do artigo.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071", "title": "Quem tem direito ao Auxílio-Acidente", "content": "O benefício é devido ao segurado que…", "published": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Base de conhecimento" ], "summary": "Editar artigo", "description": "Altera um artigo. Despublicar (`published: false`) tira o artigo do alcance do robô sem apagá-lo.\n\n**Permissão necessária:** `kb:write`", "operationId": "patch_kb_articles__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do artigo.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071", "title": "Quem tem direito ao Auxílio-Acidente", "published": true } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Novo título." }, "content": { "type": "string", "description": "Novo texto." }, "category_id": { "type": "string", "format": "uuid", "description": "Nova categoria." }, "published": { "type": "boolean", "description": "Publicar ou voltar para rascunho." } }, "additionalProperties": false }, "example": { "content": "Texto revisado em julho de 2026…" } } } } }, "delete": { "tags": [ "Base de conhecimento" ], "summary": "Excluir artigo", "description": "Apaga o artigo definitivamente. O robô deixa de considerá-lo na mesma hora.\n\n**Permissão necessária:** `kb:write`", "operationId": "delete_kb_articles__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do artigo.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Excluído. Sem corpo na resposta." }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/kb/categories": { "get": { "tags": [ "Base de conhecimento" ], "summary": "Listar categorias da base de conhecimento", "description": "As categorias que organizam a base de conhecimento. Cada robô pode ser configurado para consultar só algumas delas.\n\n**Permissão necessária:** `kb:read`", "operationId": "get_kb_categories", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "e0f1a2b3-c4d5-46e7-8f90-a1b2c3d4e5f6", "name": "Auxílio-Acidente", "description": null, "position": 0 } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Base de conhecimento" ], "summary": "Criar categoria", "description": "Cria uma categoria para agrupar artigos da base de conhecimento.\n\n**Permissão necessária:** `kb:write`", "operationId": "post_kb_categories", "parameters": [], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "e0f1a2b3-c4d5-46e7-8f90-a1b2c3d4e5f6", "name": "Auxílio-Acidente", "position": 0 } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`CONFLICT` — Já existe um registro com esses dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CONFLICT": { "summary": "CONFLICT", "value": { "error": { "code": "CONFLICT", "message": "Já existe um registro com esses dados.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da categoria.", "example": "Auxílio-Acidente" }, "description": { "type": "string", "description": "Do que trata." }, "position": { "type": "integer", "description": "Posição na lista." } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Auxílio-Acidente" } } } } } }, "/messages/search": { "get": { "tags": [ "Mensagens" ], "summary": "Buscar no texto das mensagens", "description": "Busca de texto completo em todas as conversas do workspace. Devolve o trecho e a conversa em que apareceu.\n\n**Permissão necessária:** `messages:read`", "operationId": "get_messages_search", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "O que procurar.", "schema": { "type": "string" }, "example": "comprovante de residência" }, { "name": "limit", "in": "query", "required": false, "description": "Quantos resultados (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantos pular.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "message_id": "e4f1a733-90c2-4b58-8d16-77aa0b9e5c34", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "text_body": "Enviei o comprovante de residência ontem", "direction": "inbound", "created_at": "2026-07-24T16:20:00Z", "rank": 0.61 } ], "pagination": { "limit": 25, "offset": 0, "total": null, "has_more": false } } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/queues/stats": { "get": { "tags": [ "Filas" ], "summary": "Situação das filas agora", "description": "Quantos atendimentos abertos, quantos ainda sem responsável e quantas pessoas atendem cada fila. É o número que alimenta um painel ao vivo.\n\n**Permissão necessária:** `queues:read`", "operationId": "get_queues_stats", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "queue_name": "Previdenciário", "open_count": 14, "waiting_count": 3, "agents_count": 4 } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/by-label": { "get": { "tags": [ "Relatórios" ], "summary": "Relatório por etiqueta", "description": "Quantos atendimentos cada etiqueta gerou no período, e quantos foram resolvidos. É como se mede o retorno de cada tese ou origem.\n\n**Permissão necessária:** `reports:read`", "operationId": "get_reports_by_label", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Início do período.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "Fim do período.", "schema": { "type": "string", "format": "date-time" } }, { "name": "queue_ids", "in": "query", "required": false, "description": "Filas, separadas por vírgula.", "schema": { "type": "string" } }, { "name": "channel_ids", "in": "query", "required": false, "description": "Canais, separados por vírgula.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "tag": "auxilio-acidente", "total": 142, "open": 21, "resolved": 121 } ] } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/first-contact": { "get": { "tags": [ "Relatórios" ], "summary": "Relatório de primeiro contato", "description": "Tempo até a primeira resposta, tempo de resolução e volume no período. São os mesmos números da tela de Relatórios — o cálculo é um só.\n\n**Permissão necessária:** `reports:read`", "operationId": "get_reports_first_contact", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Início do período.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-07-01T00:00:00Z" }, { "name": "to", "in": "query", "required": true, "description": "Fim do período.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-07-31T23:59:59Z" }, { "name": "queue_ids", "in": "query", "required": false, "description": "Filas, separadas por vírgula.", "schema": { "type": "string" } }, { "name": "channel_ids", "in": "query", "required": false, "description": "Canais, separados por vírgula.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "total_tickets": 312, "avg_first_response_seconds": 214, "median_first_response_seconds": 96, "avg_resolution_seconds": 15840, "resolved": 287 } } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/queue-status": { "get": { "tags": [ "Relatórios" ], "summary": "Relatório de situação por fila", "description": "Quantos atendimentos cada fila teve no período: abertos, resolvidos e quantos seguem sem responsável. É a foto da carga por equipe.\n\n**Permissão necessária:** `reports:read`", "operationId": "get_reports_queue_status", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Início do período.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "Fim do período.", "schema": { "type": "string", "format": "date-time" } }, { "name": "channel_ids", "in": "query", "required": false, "description": "Canais, separados por vírgula.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "queue_name": "Previdenciário", "open_count": 14, "resolved_count": 121, "unassigned_count": 3 } ] } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/time-in-stage": { "get": { "tags": [ "Relatórios" ], "summary": "Relatório de tempo em cada etapa do funil", "description": "Quanto tempo os atendimentos passam em cada etapa. É como se acha o gargalo do funil.\n\n**Permissão necessária:** `reports:read`", "operationId": "get_reports_time_in_stage", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Início do período.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "Fim do período.", "schema": { "type": "string", "format": "date-time" } }, { "name": "board_id", "in": "query", "required": true, "description": "Quadro do funil a analisar.", "schema": { "type": "string", "format": "uuid" } }, { "name": "channel_ids", "in": "query", "required": false, "description": "Canais, separados por vírgula.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "stage_name": "Qualificação", "stage_color": "#64748B", "display_order": 0, "avg_seconds": 7320, "p50_seconds": 4100, "ticket_count": 118 } ] } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/schedules/{id}/availability": { "get": { "tags": [ "Agenda" ], "summary": "Consultar horários livres", "description": "Os horários realmente disponíveis no período: a janela de trabalho da agenda, menos o que já está ocupado na Google Agenda de cada responsável, respeitando o intervalo entre compromissos e a antecedência mínima.\n\nCada horário já vem com o `member_user_id` de quem ficaria responsável — é esse valor que deve ser repassado em POST /appointments. **Um horário livre agora pode ser tomado em seguida:** se isso acontecer na hora de marcar, o sistema tenta outra pessoa da agenda automaticamente e só devolve `SLOT_UNAVAILABLE` quando ninguém estiver livre ali.\n\nResponsável sem Google Agenda conectada não aparece: sem ver o calendário dele, não há como afirmar que está livre.\n\n**Permissão necessária:** `agenda:read`", "operationId": "get_schedules__id__availability", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da agenda.", "schema": { "type": "string", "format": "uuid" } }, { "name": "date_from", "in": "query", "required": true, "description": "Primeiro dia do período, no formato AAAA-MM-DD.", "schema": { "type": "string" }, "example": "2026-07-28" }, { "name": "date_to", "in": "query", "required": true, "description": "Último dia do período, no formato AAAA-MM-DD.", "schema": { "type": "string" }, "example": "2026-08-01" }, { "name": "duration_minutes", "in": "query", "required": false, "description": "Duração diferente da padrão da agenda (1 a 480).", "schema": { "type": "integer" } }, { "name": "meeting_type", "in": "query", "required": false, "description": "Tipo de reunião, entre os oferecidos pela agenda: `whatsapp`, `google_meet` ou `presencial`.", "schema": { "type": "string" }, "example": "google_meet" }, { "name": "member_user_id", "in": "query", "required": false, "description": "Restringe a um responsável específico.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "timezone": "America/Sao_Paulo", "duration_minutes": 30, "slots": [ { "start": "2026-07-28T14:00:00.000Z", "end": "2026-07-28T14:30:00.000Z", "member_user_id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "meeting_type": "google_meet" }, { "start": "2026-07-28T14:45:00.000Z", "end": "2026-07-28T15:15:00.000Z", "member_user_id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "meeting_type": "google_meet" } ] } } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.\n\n`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } }, "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}/close": { "post": { "tags": [ "Atendimentos" ], "summary": "Encerrar atendimento", "description": "Encerrar duas vezes não é erro: a segunda chamada devolve o mesmo resultado sem alterar nada.\n\n**Permissão necessária:** `tickets:write`", "operationId": "post_tickets__id__close", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "normal", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": "2026-07-25T10:12:00Z", "opened_by": "inbound", "resolution_note": "Resolvido por telefone." } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolution_note": { "type": "string", "description": "Observação de encerramento, visível no histórico.", "example": "Resolvido por telefone." } }, "additionalProperties": false }, "example": { "resolution_note": "Resolvido por telefone." } } } } } }, "/tickets/{id}/priority": { "post": { "tags": [ "Atendimentos" ], "summary": "Mudar a prioridade do atendimento", "description": "Muda a urgência do atendimento. Atendimento urgente sobe na caixa de entrada da equipe.\n\n**Permissão necessária:** `tickets:write`", "operationId": "post_tickets__id__priority", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "high", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": null, "opened_by": "inbound", "resolution_note": null } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "description": "Nova prioridade.", "example": "high" } }, "required": [ "priority" ], "additionalProperties": false }, "example": { "priority": "high" } } } } } }, "/tickets/{id}/snooze": { "post": { "tags": [ "Atendimentos" ], "summary": "Adiar o atendimento", "description": "Some da caixa de entrada até a hora marcada e volta sozinho depois.\n\n**Permissão necessária:** `tickets:write`", "operationId": "post_tickets__id__snooze", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "normal", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": null, "opened_by": "inbound", "resolution_note": null, "snoozed_until": "2026-07-25T12:12:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minutes": { "type": "integer", "description": "Por quantos minutos adiar (1 a 129600, ou seja até 90 dias).", "example": 120 } }, "required": [ "minutes" ], "additionalProperties": false }, "example": { "minutes": 120 } } } } } }, "/tickets/{id}/stage": { "post": { "tags": [ "Atendimentos" ], "summary": "Mover o atendimento de etapa no funil", "description": "Move o cartão para outra etapa. O quadro é ajustado junto, então a etapa pode ser de qualquer funil do workspace.\n\n**Permissão necessária:** `tickets:write`", "operationId": "post_tickets__id__stage", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "normal", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": null, "opened_by": "inbound", "resolution_note": null } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pipeline_stage_id": { "type": "string", "format": "uuid", "description": "Etapa de destino. Veja os ids em GET /stages." } }, "required": [ "pipeline_stage_id" ], "additionalProperties": false }, "example": { "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61" } } } } } }, "/tickets/{id}/stage-history": { "get": { "tags": [ "Atendimentos" ], "summary": "Histórico de etapas do atendimento", "description": "Quando o cartão andou no funil e para onde. `actor` diz se foi pessoa ou automação (robô, regra ou a própria API).\n\n**Permissão necessária:** `tickets:read`", "operationId": "get_tickets__id__stage_history", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "changed_at": "2026-07-24T15:10:00Z", "from_stage": "Qualificação", "to_stage": "Proposta enviada", "actor": "automatico" }, { "changed_at": "2026-07-20T13:06:00Z", "from_stage": null, "to_stage": "Qualificação", "actor": "automatico" } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}/transfer": { "post": { "tags": [ "Atendimentos" ], "summary": "Transferir atendimento", "description": "Move para outra fila, para outra pessoa, ou os dois. Trocar de fila sem indicar responsável devolve o atendimento para a fila sem dono, que é o comportamento da tela. A pessoa indicada precisa ser membro da fila de destino.\n\n**Permissão necessária:** `tickets:write`", "operationId": "post_tickets__id__transfer", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "normal", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": null, "opened_by": "inbound", "resolution_note": null } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "queue_id": { "type": "string", "format": "uuid", "description": "Fila de destino. Veja os ids em GET /queues." }, "assigned_to": { "type": "string", "format": "uuid", "description": "Pessoa que passa a responder. Veja os ids em GET /users." }, "clear_queue": { "type": "boolean", "description": "Tira o atendimento de qualquer fila." }, "clear_assignee": { "type": "boolean", "description": "Deixa sem responsável." }, "note": { "type": "string", "description": "Motivo, registrado na linha do tempo.", "example": "Caso previdenciário — passando para a fila especializada." } }, "additionalProperties": false }, "example": { "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "note": "Caso previdenciário — passando para a fila especializada." } } } } } }, "/tickets/{id}/unsnooze": { "post": { "tags": [ "Atendimentos" ], "summary": "Trazer de volta um atendimento adiado", "description": "Cancela o adiamento e devolve o atendimento à caixa de entrada agora.\n\n**Permissão necessária:** `tickets:write`", "operationId": "post_tickets__id__unsnooze", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "normal", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": null, "opened_by": "inbound", "resolution_note": null, "snoozed_until": null } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Ver o histórico de entregas de um webhook", "description": "Serve para descobrir por que um aviso não chegou: mostra as tentativas, o erro de cada uma e quando a próxima será feita.\n\n**Permissão necessária:** `webhooks:read`", "operationId": "get_webhooks__id__deliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do webhook.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Situação da entrega.", "schema": { "type": "string" }, "example": "failed" } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "aa00bb11-cc22-4d33-8e44-f55566677788", "webhook_id": "1b2c3d4e-5f60-4718-a293-a4b5c6d7e8f9", "event_name": "message.created", "status": "delivered", "attempts": 1, "max_attempts": 5, "last_error": null, "created_at": "2026-07-25T09:41:56Z", "delivered_at": "2026-07-25T09:41:57Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 940, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "Listar os eventos que podem ser assinados", "description": "Todos os avisos que o Fluxo Jurídico sabe mandar, com **o corpo exato que cada um envia**. Use `payload_example` para escrever o seu receptor sem precisar provocar o evento primeiro.\n\n**Como conferir que o aviso veio de nós:** toda entrega leva os cabeçalhos `X-Fluxo-Event` (o nome do evento) e `X-Fluxo-Signature: sha256=…`, que é o HMAC-SHA256 do corpo BRUTO usando o `secret` do seu webhook. Calcule o mesmo HMAC do seu lado e compare — se não bater, descarte.\n\n**Reentrega:** falha de rede ou resposta 5xx/429 é retentada com espera progressiva; 4xx é considerado recusa definitiva e não repete. Responda 2xx rápido e processe depois — a espera é de 15 segundos.\n\n**Permissão:** qualquer chave válida.", "operationId": "get_webhooks_events", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "event": "ticket.stage_changed", "label": "Atendimento mudou de etapa no funil", "description": "O cartão andou no funil. É o evento para manter o seu CRM em sincronia com o kanban daqui.", "group": "Atendimentos", "payload_example": { "event": "ticket.stage_changed", "timestamp": "2026-07-25T10:05:00.123Z", "data": { "ticket_id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "stage_name": "Proposta enviada", "previous_stage_name": "Qualificação", "changed_at": "2026-07-25T10:05:00.000Z" } } } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/appointments": { "get": { "tags": [ "Agenda" ], "summary": "Listar agendamentos", "description": "Os compromissos marcados no workspace, com horário, responsável, contato e link da videochamada quando houver.\n\n**Permissão necessária:** `agenda:read`", "operationId": "get_appointments", "parameters": [ { "name": "schedule_id", "in": "query", "required": false, "description": "Filtra por agenda.", "schema": { "type": "string", "format": "uuid" } }, { "name": "contact_id", "in": "query", "required": false, "description": "Filtra por contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "member_user_id", "in": "query", "required": false, "description": "Filtra por responsável.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Situação do agendamento.", "schema": { "type": "string", "enum": [ "booked", "canceled", "rescheduled", "no_show" ] }, "example": "booked" }, { "name": "start_from", "in": "query", "required": false, "description": "Começa a partir desta data e hora.", "schema": { "type": "string", "format": "date-time" } }, { "name": "start_to", "in": "query", "required": false, "description": "Começa até esta data e hora.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantos por página (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantos pular.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819", "schedule_id": "7c8d9e0f-1a2b-43c4-95d6-e7f8a9b0c1d2", "member_user_id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "meeting_type": "google_meet", "meet_link": "https://meet.google.com/abc-defg-hij", "title": "Consulta inicial — Maria Souza", "start_at": "2026-07-28T14:00:00Z", "end_at": "2026-07-28T14:30:00Z", "status": "booked", "created_via": "api", "attendee_name": "Maria Souza", "attendee_email": "maria.souza@exemplo.com.br", "attendee_phone": "+5511987654321", "created_at": "2026-07-25T10:30:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 31, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Agenda" ], "summary": "Marcar um agendamento", "description": "Marca a reunião **e cria o evento na Google Agenda do responsável**, com link de videochamada quando o tipo for online. Pegue `start` e `member_user_id` de GET /schedules/{id}/availability.\n\nSe o horário tiver sido tomado entre a consulta e a marcação, o sistema tenta os outros responsáveis livres naquele mesmo horário antes de desistir — o cliente costuma manter o horário que escolheu. Só quando ninguém está livre é que vem `SLOT_UNAVAILABLE`.\n\n**O que você não precisa calcular:** o fim da reunião sai da duração da agenda, o tipo sai do primeiro que ela oferece e o título é montado com o nome da agenda e o do contato. Informe qualquer um deles para sobrescrever.\n\n**O responsável precisa ter a Google Agenda conectada** — sem enxergar o calendário dele não dá para afirmar que está livre, então a marcação é recusada em vez de arriscar reunião em cima de outra.\n\n**Permissão necessária:** `agenda:write`\n\nAceita o cabeçalho `Idempotency-Key`.", "operationId": "post_appointments", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Identificador único desta operação. Repetir a chamada com a mesma chave devolve a resposta original em vez de executar de novo.", "schema": { "type": "string", "maxLength": 128 }, "example": "pedido-4821" } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819", "schedule_id": "7c8d9e0f-1a2b-43c4-95d6-e7f8a9b0c1d2", "member_user_id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "meeting_type": "google_meet", "meet_link": "https://meet.google.com/abc-defg-hij", "title": "Consulta inicial — Maria Souza", "start_at": "2026-07-28T14:00:00Z", "end_at": "2026-07-28T14:30:00Z", "status": "booked", "created_via": "api", "attendee_name": "Maria Souza", "attendee_email": "maria.souza@exemplo.com.br", "attendee_phone": "+5511987654321", "created_at": "2026-07-25T10:30:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`SLOT_UNAVAILABLE` — O horário escolhido não está mais livre.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "SLOT_UNAVAILABLE": { "summary": "SLOT_UNAVAILABLE", "value": { "error": { "code": "SLOT_UNAVAILABLE", "message": "O horário escolhido não está mais livre.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule_id": { "type": "string", "format": "uuid", "description": "Agenda em que marcar." }, "start": { "type": "string", "format": "date-time", "description": "Início da reunião, em ISO-8601.", "example": "2026-07-28T14:00:00Z" }, "member_user_id": { "type": "string", "format": "uuid", "description": "Responsável, conforme veio na consulta de horários." }, "contact_id": { "type": "string", "format": "uuid", "description": "Contato do CRM a vincular. Recomendado — é o que junta a reunião ao histórico." }, "meeting_type": { "type": "string", "enum": [ "whatsapp", "google_meet", "presencial" ], "description": "Tipo de reunião. Precisa estar entre os `meeting_types` da agenda. `google_meet` gera o link da videochamada.", "example": "google_meet" }, "title": { "type": "string", "description": "Título do evento. Sem isso, é montado com o nome da agenda e o do contato." }, "end": { "type": "string", "format": "date-time", "description": "Fim da reunião. Sem isso, é calculado somando a duração da agenda ao início." }, "description": { "type": "string", "description": "Descrição do evento." }, "attendee_name": { "type": "string", "description": "Nome de quem vai participar." }, "attendee_email": { "type": "string", "description": "E-mail do participante — recebe o convite do Google." }, "attendee_phone": { "type": "string", "description": "Telefone do participante." } }, "required": [ "schedule_id", "start", "member_user_id" ], "additionalProperties": false }, "example": { "schedule_id": "7c8d9e0f-1a2b-43c4-95d6-e7f8a9b0c1d2", "start": "2026-07-28T14:00:00Z", "member_user_id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "meeting_type": "google_meet", "attendee_name": "Maria Souza", "attendee_email": "maria.souza@exemplo.com.br" } } } } } }, "/appointments/{id}": { "get": { "tags": [ "Agenda" ], "summary": "Obter um agendamento", "description": "Os dados completos de um compromisso, incluindo o link da reunião e os dados de quem vai participar.\n\n**Permissão necessária:** `agenda:read`", "operationId": "get_appointments__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do agendamento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819", "schedule_id": "7c8d9e0f-1a2b-43c4-95d6-e7f8a9b0c1d2", "member_user_id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "meeting_type": "google_meet", "meet_link": "https://meet.google.com/abc-defg-hij", "title": "Consulta inicial — Maria Souza", "start_at": "2026-07-28T14:00:00Z", "end_at": "2026-07-28T14:30:00Z", "status": "booked", "created_via": "api", "attendee_name": "Maria Souza", "attendee_email": "maria.souza@exemplo.com.br", "attendee_phone": "+5511987654321", "created_at": "2026-07-25T10:30:00Z" } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Agenda" ], "summary": "Cancelar um agendamento", "description": "Cancela a reunião e **remove o evento da Google Agenda do responsável**, liberando o horário para outra pessoa. Para remarcar, cancele e marque de novo: é o caminho que garante que o Google e o sistema fiquem iguais.\n\n**Permissão necessária:** `agenda:write`", "operationId": "delete_appointments__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do agendamento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819", "schedule_id": "7c8d9e0f-1a2b-43c4-95d6-e7f8a9b0c1d2", "member_user_id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "meeting_type": "google_meet", "meet_link": "https://meet.google.com/abc-defg-hij", "title": "Consulta inicial — Maria Souza", "start_at": "2026-07-28T14:00:00Z", "end_at": "2026-07-28T14:30:00Z", "status": "canceled", "created_via": "api", "attendee_name": "Maria Souza", "attendee_email": "maria.souza@exemplo.com.br", "attendee_phone": "+5511987654321", "created_at": "2026-07-25T10:30:00Z" } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/audit-logs": { "get": { "tags": [ "Auditoria" ], "summary": "Consultar o registro de auditoria", "description": "Tudo o que foi criado, alterado ou excluído no workspace, com quem fez e o que mudou. Ação feita pela API tem `actor_id` nulo e traz `via: \"api\"` no detalhe, com o nome da chave usada.\n\n**Permissão necessária:** `audit:read`", "operationId": "get_audit_logs", "parameters": [ { "name": "action", "in": "query", "required": false, "description": "Filtra pela ação.", "schema": { "type": "string" }, "example": "contact.updated" }, { "name": "entity", "in": "query", "required": false, "description": "Filtra pelo tipo de registro.", "schema": { "type": "string" }, "example": "contacts" }, { "name": "entity_id", "in": "query", "required": false, "description": "Tudo o que aconteceu com um registro específico.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "A partir desta data.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Até esta data.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "ff00ee11-dd22-4c33-8b44-a55566677788", "actor_id": null, "action": "contact.updated", "entity": "contacts", "entity_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "detail": { "via": "api", "api_key_name": "Site — formulário de contato", "fields": [ "city" ] }, "created_at": "2026-07-25T10:44:02Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 4021, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/boards": { "get": { "tags": [ "Funis" ], "summary": "Listar quadros do funil", "description": "Cada quadro é um kanban. O quadro com `is_system: true` é o funil operado pelo robô — evite reorganizá-lo pela API.\n\n**Permissão necessária:** `pipelines:read`", "operationId": "get_boards", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Funil comercial", "description": null, "color": "#2563EB", "icon": "target", "display_order": 0, "is_system": false, "created_at": "2026-06-01T10:00:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 3, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Funis" ], "summary": "Criar quadro do funil", "description": "Cria um quadro de funil. Depois de criado, acrescente as colunas com POST /stages.\n\n**Permissão necessária:** `pipelines:write`", "operationId": "post_boards", "parameters": [], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Funil comercial", "description": null, "color": "#2563EB", "icon": "target", "display_order": 0, "is_system": false, "created_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`CONFLICT` — Já existe um registro com esses dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CONFLICT": { "summary": "CONFLICT", "value": { "error": { "code": "CONFLICT", "message": "Já existe um registro com esses dados.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome do quadro.", "example": "Funil comercial" }, "description": { "type": "string", "description": "Para que serve." }, "color": { "type": "string", "description": "Cor em hexadecimal.", "example": "#2563EB" }, "icon": { "type": "string", "description": "Nome do ícone usado na tela.", "example": "target" }, "display_order": { "type": "integer", "description": "Posição na lista de quadros." } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Funil comercial", "color": "#2563EB", "icon": "target" } } } } } }, "/boards/{id}": { "patch": { "tags": [ "Funis" ], "summary": "Editar quadro do funil", "description": "Renomeia ou reordena um quadro do funil. Não altera os atendimentos que estão nele.\n\n**Permissão necessária:** `pipelines:write`", "operationId": "patch_boards__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do quadro.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Funil comercial 2026", "description": null, "color": "#2563EB", "icon": "target", "display_order": 0, "is_system": false, "created_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Novo nome." }, "description": { "type": "string", "description": "Nova descrição." }, "color": { "type": "string", "description": "Nova cor." }, "icon": { "type": "string", "description": "Novo ícone." }, "display_order": { "type": "integer", "description": "Nova posição." } }, "additionalProperties": false }, "example": { "name": "Funil comercial 2026" } } } } }, "delete": { "tags": [ "Funis" ], "summary": "Excluir quadro do funil", "description": "O quadro do robô (`is_system: true`) não pode ser excluído — o motor depende dele.\n\n**Permissão necessária:** `pipelines:write`", "operationId": "delete_boards__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do quadro.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Excluído. Sem corpo na resposta." }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`IN_USE` — O registro está em uso e não pode ser excluído.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "IN_USE": { "summary": "IN_USE", "value": { "error": { "code": "IN_USE", "message": "O registro está em uso e não pode ser excluído.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/bots": { "get": { "tags": [ "Robôs" ], "summary": "Listar robôs", "description": "Os robôs disponíveis para este workspace: os criados aqui e os robôs prontos da plataforma (`is_global: true`). `active` já considera o ligado/desligado deste workspace. O texto da tese dos robôs prontos não é devolvido.\n\n**Permissão necessária:** `bots:read`", "operationId": "get_bots", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "cc44dd55-ee66-4778-899a-bb0011223344", "name": "SDR — Auxílio-Acidente", "bot_key": "sdr-auxilio-acidente", "is_global": true, "active": true, "area": "Previdenciário", "thesis": "Auxílio-Acidente", "trigger_phrase": "Olá! Gostaria de mais informações sobre o Auxílio-Acidente, por favor.", "bot_action_mode": "contrato", "audio_enabled": false, "channel_ids": null, "transfer_queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "qualification_prompt": null, "created_at": "2026-07-01T09:00:00Z" } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/broadcasts": { "get": { "tags": [ "Campanhas" ], "summary": "Listar campanhas", "description": "As campanhas de disparo e os números de entrega de cada uma. **Somente leitura pela API**: criar e disparar campanha gasta mensagem paga da Meta e só é possível pela tela, onde a prévia do público é confirmada por uma pessoa.\n\n**Permissão necessária:** `broadcasts:read`", "operationId": "get_broadcasts", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Situação da campanha.", "schema": { "type": "string", "enum": [ "draft", "scheduled", "running", "paused", "completed", "cancelled", "failed" ] } }, { "name": "channel_id", "in": "query", "required": false, "description": "Filtra pelo canal usado.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "f1e2d3c4-b5a6-4978-8695-a4b3c2d1e0f9", "name": "Retomada — julho", "channel_id": "0a2b5c31-7e88-4f2a-b1d3-6a9c0e2f4b77", "status": "completed", "total_recipients": 480, "sent_count": 480, "delivered_count": 471, "read_count": 402, "failed_count": 9, "skipped_count": 0, "started_at": "2026-07-18T14:00:00Z", "finished_at": "2026-07-18T14:52:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 7, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/broadcasts/{id}": { "get": { "tags": [ "Campanhas" ], "summary": "Obter uma campanha", "description": "Os dados de uma campanha: público, velocidade de disparo e os números de envio, entrega, leitura e falha.\n\n**Permissão necessária:** `broadcasts:read`", "operationId": "get_broadcasts__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da campanha.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "f1e2d3c4-b5a6-4978-8695-a4b3c2d1e0f9", "name": "Retomada — julho", "status": "completed", "sent_count": 480, "delivered_count": 471 } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/calls": { "get": { "tags": [ "Ligações" ], "summary": "Listar ligações", "description": "O registro de ligações de WhatsApp, com duração, quem atendeu e a transcrição quando houver.\n\n**Permissão necessária:** `calls:read`", "operationId": "get_calls", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "description": "Ligações de um contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "direction", "in": "query", "required": false, "description": "Recebidas ou feitas.", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "answered", "in": "query", "required": false, "description": "Só as atendidas ou só as perdidas.", "schema": { "type": "boolean" } }, { "name": "started_from", "in": "query", "required": false, "description": "A partir desta data e hora.", "schema": { "type": "string", "format": "date-time" } }, { "name": "started_to", "in": "query", "required": false, "description": "Até esta data e hora.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "5a6b7c8d-9e0f-4112-a334-556677889900", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "direction": "inbound", "status": "completed", "answered": true, "duration_sec": 214, "started_at": "2026-07-24T16:02:00Z", "ended_at": "2026-07-24T16:05:34Z", "transcription": "Boa tarde, queria saber do andamento do meu processo…" } ], "pagination": { "limit": 25, "offset": 0, "total": 115, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels": { "get": { "tags": [ "Canais" ], "summary": "Listar canais conectados", "description": "Os canais de comunicação do workspace. **Nunca devolve token, segredo nem credencial** — só identificação e situação. Use o `id` de um canal com `status: \"connected\"` no envio de mensagem.\n\n`mode` diz a natureza da conexão: `cloud_api` e `waba` são o WhatsApp oficial (têm janela de 24 horas e template), `coex` é o oficial com o aplicativo no celular junto, e `zapi` é a conexão por QR Code (sem template da Meta).\n\n**Permissão necessária:** `channels:read`", "operationId": "get_channels", "parameters": [ { "name": "channel_type", "in": "query", "required": false, "description": "Filtra pelo tipo.", "schema": { "type": "string", "enum": [ "whatsapp", "instagram", "messenger", "telegram", "webchat" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filtra pela situação da conexão.", "schema": { "type": "string", "enum": [ "pending", "connected", "disconnected" ] } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "0a2b5c31-7e88-4f2a-b1d3-6a9c0e2f4b77", "channel_type": "whatsapp", "mode": "cloud_api", "display_name": "Atendimento principal", "external_id": "109371234567890", "status": "connected", "last_sync_at": "2026-07-25T08:00:00Z", "created_at": "2026-06-01T10:00:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 2, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contacts": { "get": { "tags": [ "Contatos" ], "summary": "Listar contatos", "description": "Devolve os contatos do workspace, do mais recente para o mais antigo. Todos os filtros são opcionais e podem ser combinados. Contatos que foram mesclados em outro ficam de fora por padrão.\n\n**Permissão necessária:** `contacts:read`", "operationId": "get_contacts", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Busca por nome, e-mail ou telefone. Não diferencia maiúsculas.", "schema": { "type": "string" }, "example": "maria" }, { "name": "phone", "in": "query", "required": false, "description": "Telefone exato. Tolera o formato sem o 9º dígito.", "schema": { "type": "string" }, "example": "+5511987654321" }, { "name": "tags", "in": "query", "required": false, "description": "Etiquetas separadas por vírgula. Traz quem tem TODAS elas.", "schema": { "type": "string" }, "example": "lead-quente,auxilio-acidente" }, { "name": "channel_type", "in": "query", "required": false, "description": "Canal de origem do contato.", "schema": { "type": "string", "enum": [ "whatsapp", "instagram", "messenger", "telegram", "webchat" ] } }, { "name": "is_blocked", "in": "query", "required": false, "description": "true traz só bloqueados; false só os liberados.", "schema": { "type": "boolean" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Responsável pelo contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "created_from", "in": "query", "required": false, "description": "Criado a partir desta data (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "required": false, "description": "Criado até esta data (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Alterado depois desta data. É o filtro para sincronizar só o que mudou.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-07-25T00:00:00Z" }, { "name": "include_merged", "in": "query", "required": false, "description": "Inclui contatos que foram mesclados em outro.", "schema": { "type": "boolean", "default": "false" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantos por página (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantos pular. Use com limit para paginar.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "name": "Maria Souza", "first_name": "Maria", "last_name": "Souza", "email": "maria.souza@exemplo.com.br", "phone": "+5511987654321", "channel_type": "whatsapp", "tags": [ "lead-quente", "auxilio-acidente" ], "is_blocked": false, "city": "São Paulo", "state": "SP", "metadata": { "crm_id": "A-1099" }, "created_at": "2026-07-20T13:02:11.482Z", "updated_at": "2026-07-25T09:41:55.017Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 137, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Contatos" ], "summary": "Criar contato (ou atualizar o existente pelo telefone)", "description": "Cria um contato. Por padrão, se já existir contato com o mesmo telefone, ATUALIZA aquele em vez de duplicar — é o comportamento certo para formulário de site, onde a mesma pessoa preenche duas vezes. Passe `merge_by_phone: false` para forçar a criação de um registro novo. Quando houve fusão, a resposta vem com `merged: true`.\n\n**Permissão necessária:** `contacts:write`\n\nAceita o cabeçalho `Idempotency-Key`.", "operationId": "post_contacts", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Identificador único desta operação. Repetir a chamada com a mesma chave devolve a resposta original em vez de executar de novo.", "schema": { "type": "string", "maxLength": 128 }, "example": "pedido-4821" } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "name": "Maria Souza", "first_name": "Maria", "last_name": "Souza", "email": "maria.souza@exemplo.com.br", "phone": "+5511987654321", "channel_type": "whatsapp", "tags": [ "lead-quente", "auxilio-acidente" ], "is_blocked": false, "city": "São Paulo", "state": "SP", "metadata": { "crm_id": "A-1099" }, "created_at": "2026-07-20T13:02:11.482Z", "updated_at": "2026-07-25T09:41:55.017Z", "merged": false } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`CONFLICT` — Já existe um registro com esses dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CONFLICT": { "summary": "CONFLICT", "value": { "error": { "code": "CONFLICT", "message": "Já existe um registro com esses dados.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de exibição. Se não vier, é montado a partir de first_name e last_name." }, "first_name": { "type": "string", "description": "Primeiro nome. É o que o robô usa para tratar a pessoa e o que vai para o contrato." }, "last_name": { "type": "string", "description": "Sobrenome." }, "email": { "type": "string", "description": "E-mail principal." }, "phone": { "type": "string", "description": "Celular com WhatsApp. Aceita qualquer formato brasileiro e é normalizado para +55DDD9XXXXXXXX." }, "phone_secondary": { "type": "string", "description": "Telefone alternativo (não recebe mensagem)." }, "cpf": { "type": "string", "description": "CPF, só números ou com máscara." }, "rg": { "type": "string", "description": "RG." }, "birth_date": { "type": "string", "description": "Data de nascimento, no formato AAAA-MM-DD." }, "gender": { "type": "string", "description": "Gênero, texto livre." }, "marital_status": { "type": "string", "description": "Estado civil." }, "nationality": { "type": "string", "description": "Nacionalidade." }, "profession": { "type": "string", "description": "Profissão." }, "ctps_number": { "type": "string", "description": "Número da carteira de trabalho." }, "pis_number": { "type": "string", "description": "Número do PIS." }, "postal_code": { "type": "string", "description": "CEP." }, "address": { "type": "string", "description": "Logradouro e número." }, "neighborhood": { "type": "string", "description": "Bairro." }, "address_complement": { "type": "string", "description": "Complemento." }, "city": { "type": "string", "description": "Cidade." }, "state": { "type": "string", "description": "Estado (UF)." }, "country": { "type": "string", "description": "País." }, "company_cnpj": { "type": "string", "description": "CNPJ da empresa do contato." }, "company_legal_name": { "type": "string", "description": "Razão social." }, "company_trade_name": { "type": "string", "description": "Nome fantasia." }, "owner_id": { "type": "string", "format": "uuid", "description": "Responsável pelo contato. Use um id de GET /users." }, "notes": { "type": "string", "description": "Observação livre no cadastro (diferente das notas datadas de /contacts/{id}/notes)." }, "utm_source": { "type": "string", "description": "Origem da campanha que trouxe o contato." }, "utm_medium": { "type": "string", "description": "Meio da campanha." }, "utm_campaign": { "type": "string", "description": "Nome da campanha." }, "utm_content": { "type": "string", "description": "Conteúdo do anúncio." }, "utm_term": { "type": "string", "description": "Termo de busca." }, "metadata": { "type": "object", "description": "Objeto livre para você guardar o que quiser (ex.: o id do contato no seu CRM)." }, "tags": { "type": "array", "description": "Etiquetas a aplicar já na criação. As que não existirem são criadas." }, "merge_by_phone": { "type": "boolean", "description": "Se o telefone já existir, atualiza o contato existente em vez de criar outro.", "example": true } }, "additionalProperties": false }, "example": { "first_name": "Maria", "last_name": "Souza", "phone": "11987654321", "email": "maria.souza@exemplo.com.br", "city": "São Paulo", "state": "SP", "tags": [ "lead-quente" ], "utm_source": "site", "metadata": { "crm_id": "A-1099" } } } } } } }, "/contacts/{id}": { "get": { "tags": [ "Contatos" ], "summary": "Obter um contato", "description": "Todos os dados de um contato: cadastro, endereço, documentos, dados da empresa, etiquetas e origem da campanha que o trouxe.\n\n**Permissão necessária:** `contacts:read`", "operationId": "get_contacts__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "name": "Maria Souza", "first_name": "Maria", "last_name": "Souza", "email": "maria.souza@exemplo.com.br", "phone": "+5511987654321", "channel_type": "whatsapp", "tags": [ "lead-quente", "auxilio-acidente" ], "is_blocked": false, "city": "São Paulo", "state": "SP", "metadata": { "crm_id": "A-1099" }, "created_at": "2026-07-20T13:02:11.482Z", "updated_at": "2026-07-25T09:41:55.017Z" } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Contatos" ], "summary": "Atualizar contato", "description": "Altera só os campos enviados. Campo ausente fica como está; para limpar um campo, mande string vazia.\n\n**Permissão necessária:** `contacts:write`", "operationId": "patch_contacts__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "name": "Maria Souza", "first_name": "Maria", "last_name": "Souza", "email": "maria.souza@exemplo.com.br", "phone": "+5511987654321", "channel_type": "whatsapp", "tags": [ "lead-quente", "auxilio-acidente" ], "is_blocked": false, "city": "São Paulo", "state": "SP", "metadata": { "crm_id": "A-1099" }, "created_at": "2026-07-20T13:02:11.482Z", "updated_at": "2026-07-25T09:41:55.017Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de exibição. Se não vier, é montado a partir de first_name e last_name." }, "first_name": { "type": "string", "description": "Primeiro nome. É o que o robô usa para tratar a pessoa e o que vai para o contrato." }, "last_name": { "type": "string", "description": "Sobrenome." }, "email": { "type": "string", "description": "E-mail principal." }, "phone": { "type": "string", "description": "Celular com WhatsApp. Aceita qualquer formato brasileiro e é normalizado para +55DDD9XXXXXXXX." }, "phone_secondary": { "type": "string", "description": "Telefone alternativo (não recebe mensagem)." }, "cpf": { "type": "string", "description": "CPF, só números ou com máscara." }, "rg": { "type": "string", "description": "RG." }, "birth_date": { "type": "string", "description": "Data de nascimento, no formato AAAA-MM-DD." }, "gender": { "type": "string", "description": "Gênero, texto livre." }, "marital_status": { "type": "string", "description": "Estado civil." }, "nationality": { "type": "string", "description": "Nacionalidade." }, "profession": { "type": "string", "description": "Profissão." }, "ctps_number": { "type": "string", "description": "Número da carteira de trabalho." }, "pis_number": { "type": "string", "description": "Número do PIS." }, "postal_code": { "type": "string", "description": "CEP." }, "address": { "type": "string", "description": "Logradouro e número." }, "neighborhood": { "type": "string", "description": "Bairro." }, "address_complement": { "type": "string", "description": "Complemento." }, "city": { "type": "string", "description": "Cidade." }, "state": { "type": "string", "description": "Estado (UF)." }, "country": { "type": "string", "description": "País." }, "company_cnpj": { "type": "string", "description": "CNPJ da empresa do contato." }, "company_legal_name": { "type": "string", "description": "Razão social." }, "company_trade_name": { "type": "string", "description": "Nome fantasia." }, "owner_id": { "type": "string", "format": "uuid", "description": "Responsável pelo contato. Use um id de GET /users." }, "notes": { "type": "string", "description": "Observação livre no cadastro (diferente das notas datadas de /contacts/{id}/notes)." }, "utm_source": { "type": "string", "description": "Origem da campanha que trouxe o contato." }, "utm_medium": { "type": "string", "description": "Meio da campanha." }, "utm_campaign": { "type": "string", "description": "Nome da campanha." }, "utm_content": { "type": "string", "description": "Conteúdo do anúncio." }, "utm_term": { "type": "string", "description": "Termo de busca." }, "metadata": { "type": "object", "description": "Objeto livre para você guardar o que quiser (ex.: o id do contato no seu CRM)." } }, "additionalProperties": false }, "example": { "profession": "Motorista", "city": "Campinas", "metadata": { "crm_id": "A-1099", "status_crm": "proposta" } } } } } }, "delete": { "tags": [ "Contatos" ], "summary": "Excluir ou anonimizar um contato (LGPD)", "description": "Atende pedido de exclusão de dados pessoais. **É irreversível e não tem desfazer.** Com `action=anonymize` (padrão) os dados pessoais são apagados mas o histórico de atendimento permanece sem identificação — é o que normalmente se quer, porque preserva estatística e obrigação de guarda. Com `action=delete` o contato e tudo dele somem. Exige a permissão `contacts:delete`, que não vem marcada em chave nova.\n\n**Permissão necessária:** `contacts:delete`", "operationId": "delete_contacts__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "query", "required": false, "description": "O que fazer com os dados.", "schema": { "type": "string", "enum": [ "anonymize", "delete" ], "default": "anonymize" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "action": "anonymize", "removed": { "messages": 0, "anonymized_fields": 18 } } } } } }, "400": { "description": "`INVALID_PARAM` — Parâmetro inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_PARAM": { "summary": "INVALID_PARAM", "value": { "error": { "code": "INVALID_PARAM", "message": "Parâmetro inválido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations": { "get": { "tags": [ "Conversas" ], "summary": "Listar conversas", "description": "As conversas do workspace, da mais movimentada para a mais antiga. Uma conversa é a linha do tempo com um contato num canal.\n\n**Permissão necessária:** `conversations:read`", "operationId": "get_conversations", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Situação na caixa de entrada. `open` é o que está em atendimento.", "schema": { "type": "string", "enum": [ "open", "closed", "none" ] } }, { "name": "channel_id", "in": "query", "required": false, "description": "Filtra por canal. Veja os ids em GET /channels.", "schema": { "type": "string", "format": "uuid" } }, { "name": "contact_id", "in": "query", "required": false, "description": "Conversas de um contato específico.", "schema": { "type": "string", "format": "uuid" } }, { "name": "queue_id", "in": "query", "required": false, "description": "Filtra por fila de atendimento.", "schema": { "type": "string", "format": "uuid" } }, { "name": "assigned_to", "in": "query", "required": false, "description": "Responsável atual. Use `none` para trazer só as sem dono.", "schema": { "type": "string", "format": "uuid" }, "example": "none" }, { "name": "board_id", "in": "query", "required": false, "description": "Quadro do funil.", "schema": { "type": "string", "format": "uuid" } }, { "name": "pipeline_stage_id", "in": "query", "required": false, "description": "Etapa do funil.", "schema": { "type": "string", "format": "uuid" } }, { "name": "priority", "in": "query", "required": false, "description": "Prioridade.", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, { "name": "unread", "in": "query", "required": false, "description": "true traz só as com mensagem não lida.", "schema": { "type": "boolean" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Alteradas depois desta data. É o filtro de sincronização.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantas por página (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantas pular.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "channel_id": "0a2b5c31-7e88-4f2a-b1d3-6a9c0e2f4b77", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "assigned_to": null, "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "priority": "normal", "inbox_status": "open", "unread_count": 0, "last_inbound_at": "2026-07-25T09:38:12.004Z", "last_message_at": "2026-07-25T09:41:55.017Z", "created_at": "2026-07-20T13:05:00.000Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 63, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations/{id}": { "get": { "tags": [ "Conversas" ], "summary": "Obter uma conversa", "description": "Os dados de uma conversa: canal, contato, fila, responsável, etapa do funil e quando foi a última mensagem de cada lado.\n\n**Permissão necessária:** `conversations:read`", "operationId": "get_conversations__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da conversa.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "channel_id": "0a2b5c31-7e88-4f2a-b1d3-6a9c0e2f4b77", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "assigned_to": null, "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "priority": "normal", "inbox_status": "open", "unread_count": 0, "last_inbound_at": "2026-07-25T09:38:12.004Z", "last_message_at": "2026-07-25T09:41:55.017Z", "created_at": "2026-07-20T13:05:00.000Z" } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/custom-fields": { "get": { "tags": [ "Contatos" ], "summary": "Listar campos personalizados do workspace", "description": "A definição dos campos extras que o escritório criou. Use o `id` para gravar valor em um contato.\n\n**Permissão necessária:** `contacts:read`", "operationId": "get_custom_fields", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "c9a1…", "field_name": "Número do processo", "field_type": "text", "is_required": false, "options": null, "display_order": 1, "regex": null } ], "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/documents": { "get": { "tags": [ "Documentos" ], "summary": "Listar documentos de assinatura", "description": "Os contratos e documentos enviados para assinatura eletrônica, com a situação de cada um. **Somente leitura pela API:** gerar documento novo consome crédito no serviço de assinatura e passa pelo robô ou pela tela.\n\n**Permissão necessária:** `documents:read`", "operationId": "get_documents", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "description": "Documentos de um contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Situação do documento.", "schema": { "type": "string" }, "example": "signed" }, { "name": "created_from", "in": "query", "required": false, "description": "Criados a partir desta data.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "required": false, "description": "Criados até esta data.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "doc_8fa1c2b3", "provider": "zapsign", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "document_name": "Contrato de honorários — Maria Souza", "document_status": "signed", "signer_name": "Maria Souza", "signer_email": "maria.souza@exemplo.com.br", "sign_url": "https://app.zapsign.com.br/verificar/…", "signed_file_url": "https://…/assinado.pdf", "source": "bot", "created_at": "2026-07-22T15:00:00Z", "signed_at": "2026-07-22T15:41:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 71, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/documents/{id}": { "get": { "tags": [ "Documentos" ], "summary": "Obter um documento de assinatura", "description": "Os dados de um documento de assinatura, incluindo o link para assinar e, depois de assinado, o link do arquivo final.\n\n**Permissão necessária:** `documents:read`", "operationId": "get_documents__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do documento (texto, não é UUID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "doc_8fa1c2b3", "document_name": "Contrato de honorários — Maria Souza", "document_status": "signed" } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/errors": { "get": { "tags": [ "Conta" ], "summary": "Listar todos os códigos de erro da API", "description": "O catálogo completo: código, status HTTP, a mensagem que você recebe e o que fazer para resolver. É a mesma lista que alimenta a documentação — não existe erro devolvido por esta API que não esteja aqui.\n\n**Permissão:** qualquer chave válida.", "operationId": "get_errors", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "code": "WINDOW_CLOSED", "status": 422, "message": "A janela de 24 horas está fechada. Fora dela o WhatsApp só aceita template aprovado.", "fix": "Envie type=\"template\" com um template aprovado, ou espere o contato responder para reabrir a janela.", "global": false }, { "code": "RATE_LIMITED", "status": 429, "message": "Limite de chamadas excedido.", "fix": "Espere o tempo indicado em Retry-After e reduza a frequência. Os cabeçalhos X-RateLimit-* mostram quanto resta.", "global": true } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/labels": { "get": { "tags": [ "Etiquetas" ], "summary": "Listar etiquetas cadastradas", "description": "As etiquetas cadastradas no workspace, com cor e descrição. Diferente de GET /tags, que traz só os nomes em uso.\n\n**Permissão necessária:** `tags:read`", "operationId": "get_labels", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Quantas por página (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantas pular.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "lead-quente", "color": "#F97316", "description": "Contato com intenção clara.", "created_at": "2026-06-01T10:00:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 12, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Etiquetas" ], "summary": "Criar etiqueta", "description": "Cria uma etiqueta. O nome não pode repetir no workspace.\n\n**Permissão necessária:** `tags:write`", "operationId": "post_labels", "parameters": [], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "lead-quente", "color": "#F97316", "description": "Contato com intenção clara.", "created_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`CONFLICT` — Já existe um registro com esses dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CONFLICT": { "summary": "CONFLICT", "value": { "error": { "code": "CONFLICT", "message": "Já existe um registro com esses dados.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da etiqueta. Não pode repetir no workspace.", "example": "lead-quente" }, "color": { "type": "string", "description": "Cor em hexadecimal.", "example": "#F97316" }, "description": { "type": "string", "description": "Para que serve, visível na tela de etiquetas." } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "lead-quente", "color": "#F97316", "description": "Contato com intenção clara." } } } } } }, "/labels/{id}": { "patch": { "tags": [ "Etiquetas" ], "summary": "Editar etiqueta", "description": "Renomear propaga para todos os contatos que a usam — nenhum contato perde a marcação.\n\n**Permissão necessária:** `tags:write`", "operationId": "patch_labels__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da etiqueta.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "lead-quente", "color": "#DC2626", "description": "Contato com intenção clara.", "created_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`CONFLICT` — Já existe um registro com esses dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CONFLICT": { "summary": "CONFLICT", "value": { "error": { "code": "CONFLICT", "message": "Já existe um registro com esses dados.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Novo nome." }, "color": { "type": "string", "description": "Nova cor em hexadecimal." }, "description": { "type": "string", "description": "Nova descrição." } }, "additionalProperties": false }, "example": { "color": "#DC2626" } } } } }, "delete": { "tags": [ "Etiquetas" ], "summary": "Excluir etiqueta", "description": "A etiqueta é removida de todos os contatos que a tinham. Não apaga contato nenhum.\n\n**Permissão necessária:** `tags:write`", "operationId": "delete_labels__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da etiqueta.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Excluído. Sem corpo na resposta." }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/macros": { "get": { "tags": [ "Biblioteca" ], "summary": "Listar macros", "description": "Sequências de ações que a equipe dispara com um clique no atendimento (etiquetar, transferir, responder, encerrar).\n\n**Permissão necessária:** `library:read`", "operationId": "get_macros", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "0a1b2c3d-4e5f-4061-8273-849506172839", "name": "Encerrar sem interesse", "description": null, "active": true, "actions": [ { "type": "add_tag", "value": "sem-interesse" }, { "type": "close_ticket" } ] } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/me": { "get": { "tags": [ "Conta" ], "summary": "Conferir a chave e o workspace", "description": "O jeito mais rápido de saber se a chave está funcionando e o que ela pode fazer. Não exige permissão nenhuma além de uma chave válida — use no primeiro teste da integração.\n\n**Permissão:** qualquer chave válida.", "operationId": "get_me", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "workspace": { "id": "d5e6f7a8-b9c0-41d2-83e4-f5a6b7c8d9e0", "name": "Advocacia Souza & Lima", "status": "active" }, "api_key": { "id": "e1f2a3b4-c5d6-4708-9a1b-2c3d4e5f6071", "name": "Site — formulário de contato", "prefix": "fj_live_9fK2xQ", "last_used_at": "2026-07-25T10:44:02Z" }, "scopes": [ "contacts:read", "contacts:write", "messages:send" ], "rate_limit": { "per_minute": 300, "per_day": 200000 } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/messages": { "post": { "tags": [ "Mensagens" ], "summary": "Enviar mensagem de WhatsApp", "description": "O endpoint principal da API. Diga para QUEM (por `contact_id`, por `phone` ou pela `conversation_id`) e O QUÊ. Se o telefone ainda não for contato, ele é criado — passe `create_contact: false` para impedir.\n\n**A regra das 24 horas do WhatsApp vale aqui igual à tela:** você só pode mandar mensagem livre se o contato escreveu nas últimas 24 horas. Fora disso, o WhatsApp só aceita template aprovado — a resposta vem como `WINDOW_CLOSED` e nada é cobrado.\n\nSe o workspace tiver mais de um canal conectado, informe `channel_id`; com um só, ele é escolhido sozinho.\n\n**Use sempre o cabeçalho `Idempotency-Key`.** Com ele, repetir a chamada depois de uma queda de rede devolve a resposta original em vez de enviar a mensagem duas vezes.\n\n**Permissão necessária:** `messages:send`\n\nAceita o cabeçalho `Idempotency-Key`.", "operationId": "post_messages", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Identificador único desta operação. Repetir a chamada com a mesma chave devolve a resposta original em vez de executar de novo.", "schema": { "type": "string", "maxLength": 128 }, "example": "pedido-4821" } ], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "message_id": "e4f1a733-90c2-4b58-8d16-77aa0b9e5c34", "external_message_id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABEYEjc3QkI2NkM5RjhBMkE0RTUxAA==", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "contact_id": "3f2a91c4-8d55-4b21-9e7f-1c0a6b3d8e42", "channel_id": "0a2b5c31-7e88-4f2a-b1d3-6a9c0e2f4b77", "status": "sent" } } } } }, "400": { "description": "`TEMPLATE_INVALID` — O template precisa de `name` e `language`.\n\n`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "TEMPLATE_INVALID": { "summary": "TEMPLATE_INVALID", "value": { "error": { "code": "TEMPLATE_INVALID", "message": "O template precisa de `name` e `language`.", "request_id": "req_9f8e7d6c5b4a" } } }, "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT` — A mesma Idempotency-Key já foi usada com um corpo diferente.\n\n`IDEMPOTENCY_IN_PROGRESS` — Uma requisição com esta Idempotency-Key ainda está em andamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "IDEMPOTENCY_CONFLICT": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "A mesma Idempotency-Key já foi usada com um corpo diferente.", "request_id": "req_9f8e7d6c5b4a" } } }, "IDEMPOTENCY_IN_PROGRESS": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "message": "Uma requisição com esta Idempotency-Key ainda está em andamento.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "422": { "description": "`CHANNEL_NOT_FOUND` — Canal não encontrado ou desconectado.\n\n`CHANNEL_UNLINKED` — A conversa não está vinculada a nenhum canal.\n\n`CONTACT_INVALID` — O contato não tem um telefone válido.\n\n`MEDIA_NOT_FOUND` — O arquivo indicado não foi encontrado.\n\n`SEND_FAILED` — O WhatsApp recusou o envio.\n\n`TEMPLATE_NOT_APPROVED` — O template não existe ou não está aprovado para este canal.\n\n`WINDOW_CLOSED` — A janela de 24 horas está fechada. Fora dela o WhatsApp só aceita template aprovado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CHANNEL_NOT_FOUND": { "summary": "CHANNEL_NOT_FOUND", "value": { "error": { "code": "CHANNEL_NOT_FOUND", "message": "Canal não encontrado ou desconectado.", "request_id": "req_9f8e7d6c5b4a" } } }, "CHANNEL_UNLINKED": { "summary": "CHANNEL_UNLINKED", "value": { "error": { "code": "CHANNEL_UNLINKED", "message": "A conversa não está vinculada a nenhum canal.", "request_id": "req_9f8e7d6c5b4a" } } }, "CONTACT_INVALID": { "summary": "CONTACT_INVALID", "value": { "error": { "code": "CONTACT_INVALID", "message": "O contato não tem um telefone válido.", "request_id": "req_9f8e7d6c5b4a" } } }, "MEDIA_NOT_FOUND": { "summary": "MEDIA_NOT_FOUND", "value": { "error": { "code": "MEDIA_NOT_FOUND", "message": "O arquivo indicado não foi encontrado.", "request_id": "req_9f8e7d6c5b4a" } } }, "SEND_FAILED": { "summary": "SEND_FAILED", "value": { "error": { "code": "SEND_FAILED", "message": "O WhatsApp recusou o envio.", "request_id": "req_9f8e7d6c5b4a" } } }, "TEMPLATE_NOT_APPROVED": { "summary": "TEMPLATE_NOT_APPROVED", "value": { "error": { "code": "TEMPLATE_NOT_APPROVED", "message": "O template não existe ou não está aprovado para este canal.", "request_id": "req_9f8e7d6c5b4a" } } }, "WINDOW_CLOSED": { "summary": "WINDOW_CLOSED", "value": { "error": { "code": "WINDOW_CLOSED", "message": "A janela de 24 horas está fechada. Fora dela o WhatsApp só aceita template aprovado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "503": { "description": "`SEND_UNAVAILABLE` — O WhatsApp não respondeu a tempo. A falha é transitória.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "SEND_UNAVAILABLE": { "summary": "SEND_UNAVAILABLE", "value": { "error": { "code": "SEND_UNAVAILABLE", "message": "O WhatsApp não respondeu a tempo. A falha é transitória.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "template", "image", "video", "document", "audio" ], "description": "O que enviar.", "example": "text" }, "contact_id": { "type": "string", "format": "uuid", "description": "Destinatário por identificador. Use este, `phone` ou `conversation_id`." }, "phone": { "type": "string", "description": "Destinatário por telefone, em qualquer formato brasileiro.", "example": "11987654321" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Responder numa conversa existente. Dispensa contato e canal." }, "channel_id": { "type": "string", "format": "uuid", "description": "Por qual canal enviar. Obrigatório se houver mais de um conectado." }, "text": { "type": "string", "description": "O texto. Em imagem, vídeo e documento vira a legenda." }, "template": { "type": "object", "description": "Para `type: \"template\"`: `{ name, language, components }`. O template precisa estar aprovado NESTE canal." }, "media_url": { "type": "string", "description": "Endereço https público do arquivo, para imagem, vídeo, áudio e documento." }, "filename": { "type": "string", "description": "Nome do arquivo mostrado ao destinatário (documentos)." }, "voice": { "type": "boolean", "description": "Em áudio, `true` envia como mensagem de voz (com a onda sonora). Exige arquivo ogg/opus." }, "reply_to_external_id": { "type": "string", "description": "Responder citando outra mensagem: informe o `external_message_id` dela." }, "create_contact": { "type": "boolean", "description": "Criar o contato quando o telefone for novo.", "example": true } }, "required": [ "type" ], "additionalProperties": false }, "example": { "phone": "11987654321", "type": "text", "text": "Bom dia, Maria! Recebemos os seus documentos." } } } } } }, "/messages/{id}": { "get": { "tags": [ "Mensagens" ], "summary": "Obter uma mensagem", "description": "Uma mensagem específica, com o texto, a situação de entrega e o link temporário do arquivo, quando houver.\n\n**Permissão necessária:** `messages:read`", "operationId": "get_messages__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da mensagem.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "e4f1a733-90c2-4b58-8d16-77aa0b9e5c34", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "direction": "outbound", "type": "text", "status": "sent", "text_body": "Bom dia, Maria! Recebemos os seus documentos.", "source": "api", "external_message_id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABEYEjc3QkI2NkM5RjhBMkE0RTUxAA==", "created_at": "2026-07-25T09:41:55.017Z", "media_url": null } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/queues": { "get": { "tags": [ "Filas" ], "summary": "Listar filas de atendimento", "description": "As filas de atendimento do workspace. A fila define quem recebe cada conversa e por qual critério de distribuição.\n\n**Permissão necessária:** `queues:read`", "operationId": "get_queues", "parameters": [ { "name": "is_active", "in": "query", "required": false, "description": "Só as ativas ou só as desativadas.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "name": "Previdenciário", "description": null, "channel_id": null, "assignment_strategy": "round_robin", "is_active": true, "created_at": "2026-06-01T10:00:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 5, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/quick-replies": { "get": { "tags": [ "Biblioteca" ], "summary": "Listar respostas rápidas", "description": "Os textos prontos que a equipe usa digitando um atalho no chat.\n\n**Permissão necessária:** `library:read`", "operationId": "get_quick_replies", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "f7a8b9c0-d1e2-4f30-a415-263748596071", "shortcut": "/docs", "title": "Lista de documentos", "content": "Para dar entrada, precisamos de: RG, CPF, comprovante de residência e CTPS." } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/schedules": { "get": { "tags": [ "Agenda" ], "summary": "Listar agendas", "description": "Cada agenda é um tipo de compromisso (consulta inicial, reunião de acompanhamento) com a própria duração, antecedência mínima e equipe.\n\n**Permissão necessária:** `agenda:read`", "operationId": "get_schedules", "parameters": [ { "name": "is_active", "in": "query", "required": false, "description": "Só as ativas ou só as desativadas.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "7c8d9e0f-1a2b-43c4-95d6-e7f8a9b0c1d2", "name": "Consulta inicial", "slug": "consulta-inicial", "description": null, "timezone": "America/Sao_Paulo", "duration_minutes": 30, "buffer_minutes": 15, "min_notice_minutes": 120, "meeting_types": [ "google_meet", "presencial" ], "location": null, "is_active": true, "public_booking_enabled": true, "created_at": "2026-06-10T12:00:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 2, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/schedules/{id}": { "get": { "tags": [ "Agenda" ], "summary": "Obter uma agenda", "description": "Os dados de uma agenda: duração, intervalo entre compromissos, antecedência mínima e os tipos de reunião que ela oferece.\n\n**Permissão necessária:** `agenda:read`", "operationId": "get_schedules__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da agenda.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "7c8d9e0f-1a2b-43c4-95d6-e7f8a9b0c1d2", "name": "Consulta inicial", "slug": "consulta-inicial", "description": null, "timezone": "America/Sao_Paulo", "duration_minutes": 30, "buffer_minutes": 15, "min_notice_minutes": 120, "meeting_types": [ "google_meet", "presencial" ], "location": null, "is_active": true, "public_booking_enabled": true, "created_at": "2026-06-10T12:00:00Z" } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/stages": { "get": { "tags": [ "Funis" ], "summary": "Listar todas as etapas do workspace", "description": "Todas as etapas de todos os quadros. É a lista de onde sai o `pipeline_stage_id` para mover um atendimento.\n\n**Permissão necessária:** `pipelines:read`", "operationId": "get_stages", "parameters": [ { "name": "board_id", "in": "query", "required": false, "description": "Filtra por quadro.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Qualificação", "color": "#64748B", "display_order": 0, "is_default": true, "created_at": "2026-06-01T10:00:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 6, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Funis" ], "summary": "Criar etapa no funil", "description": "Cria uma coluna no quadro do funil. `display_order` define a posição, da esquerda para a direita.\n\n**Permissão necessária:** `pipelines:write`", "operationId": "post_stages", "parameters": [], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Proposta enviada", "color": "#16A34A", "display_order": 2, "is_default": false, "created_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`CONFLICT` — Já existe um registro com esses dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CONFLICT": { "summary": "CONFLICT", "value": { "error": { "code": "CONFLICT", "message": "Já existe um registro com esses dados.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "description": "Quadro que recebe a etapa." }, "name": { "type": "string", "description": "Nome da etapa. Único dentro do quadro.", "example": "Proposta enviada" }, "color": { "type": "string", "description": "Cor em hexadecimal." }, "display_order": { "type": "integer", "description": "Posição da coluna, da esquerda para a direita." }, "is_default": { "type": "boolean", "description": "Etapa em que o atendimento entra ao chegar no quadro." } }, "required": [ "board_id", "name" ], "additionalProperties": false }, "example": { "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Proposta enviada", "color": "#16A34A", "display_order": 2 } } } } } }, "/stages/{id}": { "patch": { "tags": [ "Funis" ], "summary": "Editar etapa do funil", "description": "Renomeia, recolore ou reordena uma etapa. Os atendimentos que estão nela continuam onde estão.\n\n**Permissão necessária:** `pipelines:write`", "operationId": "patch_stages__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da etapa.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "name": "Qualificação", "color": "#64748B", "display_order": 1, "is_default": true, "created_at": "2026-06-01T10:00:00Z" } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`CONFLICT` — Já existe um registro com esses dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "CONFLICT": { "summary": "CONFLICT", "value": { "error": { "code": "CONFLICT", "message": "Já existe um registro com esses dados.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Novo nome." }, "color": { "type": "string", "description": "Nova cor." }, "display_order": { "type": "integer", "description": "Nova posição." }, "is_default": { "type": "boolean", "description": "Torna esta a etapa de entrada do quadro." } }, "additionalProperties": false }, "example": { "display_order": 1 } } } } }, "delete": { "tags": [ "Funis" ], "summary": "Excluir etapa do funil", "description": "Os atendimentos que estavam nela ficam sem etapa e voltam para a coluna de entrada do quadro.\n\n**Permissão necessária:** `pipelines:write`", "operationId": "delete_stages__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador da etapa.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Excluído. Sem corpo na resposta." }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "409": { "description": "`IN_USE` — O registro está em uso e não pode ser excluído.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "IN_USE": { "summary": "IN_USE", "value": { "error": { "code": "IN_USE", "message": "O registro está em uso e não pode ser excluído.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tags": { "get": { "tags": [ "Etiquetas" ], "summary": "Listar as etiquetas em uso", "description": "Só os nomes que estão realmente aplicados em algum contato. Para o cadastro completo, com cor e descrição, use GET /labels.\n\n**Permissão necessária:** `tags:read`", "operationId": "get_tags", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ "auxilio-acidente", "lead-quente", "sem-interesse" ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "Listar templates de WhatsApp", "description": "Os modelos de mensagem aprovados pela Meta — é o que permite falar com alguém fora da janela de 24 horas. Só os de `status: \"approved\"` podem ser enviados, e a aprovação vale **por canal**.\n\n**Permissão necessária:** `templates:read`", "operationId": "get_templates", "parameters": [ { "name": "channel_id", "in": "query", "required": false, "description": "Filtra pelo canal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Situação na Meta.", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "in_appeal", "pending_deletion", "deleted", "disabled", "paused" ] } }, { "name": "language", "in": "query", "required": false, "description": "Código do idioma.", "schema": { "type": "string" }, "example": "pt_BR" }, { "name": "category", "in": "query", "required": false, "description": "Categoria do template.", "schema": { "type": "string" }, "example": "UTILITY" } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "c3d4e5f6-a7b8-49c0-8d1e-2f3a4b5c6d7e", "channel_id": "0a2b5c31-7e88-4f2a-b1d3-6a9c0e2f4b77", "name": "retomada_documentos", "language": "pt_BR", "category": "UTILITY", "status": "approved", "components": [ { "type": "BODY", "text": "Olá {{1}}, ainda precisamos do seu {{2}} para seguir com o processo." } ], "sent_count": 340, "delivered_count": 331, "read_count": 288, "replied_count": 96 } ], "pagination": { "limit": 25, "offset": 0, "total": 18, "has_more": false } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "Obter um template", "description": "Os dados de um template, incluindo os componentes (cabeçalho, corpo, botões) e as variáveis que ele espera receber.\n\n**Permissão necessária:** `templates:read`", "operationId": "get_templates__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do template.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "c3d4e5f6-a7b8-49c0-8d1e-2f3a4b5c6d7e", "name": "retomada_documentos", "language": "pt_BR", "status": "approved" } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets": { "get": { "tags": [ "Atendimentos" ], "summary": "Listar atendimentos", "description": "Um atendimento é o ciclo aberto→resolvido dentro de uma conversa. É o que anda no funil e o que entra nos relatórios.\n\n**Permissão necessária:** `tickets:read`", "operationId": "get_tickets", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Abertos ou encerrados. Sem filtro, traz os dois.", "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "queue_id", "in": "query", "required": false, "description": "Fila de atendimento.", "schema": { "type": "string", "format": "uuid" } }, { "name": "assigned_to", "in": "query", "required": false, "description": "Responsável. Use `none` para os sem dono.", "schema": { "type": "string", "format": "uuid" } }, { "name": "board_id", "in": "query", "required": false, "description": "Quadro do funil.", "schema": { "type": "string", "format": "uuid" } }, { "name": "pipeline_stage_id", "in": "query", "required": false, "description": "Etapa do funil.", "schema": { "type": "string", "format": "uuid" } }, { "name": "priority", "in": "query", "required": false, "description": "Prioridade.", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, { "name": "contact_id", "in": "query", "required": false, "description": "Atendimentos de um contato.", "schema": { "type": "string", "format": "uuid" } }, { "name": "opened_from", "in": "query", "required": false, "description": "Abertos a partir desta data.", "schema": { "type": "string", "format": "date-time" } }, { "name": "opened_to", "in": "query", "required": false, "description": "Abertos até esta data.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_history", "in": "query", "required": false, "description": "Inclui os atendimentos técnicos criados na importação de histórico.", "schema": { "type": "boolean", "default": "false" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantos por página (máximo 100).", "schema": { "type": "integer", "default": "25" } }, { "name": "offset", "in": "query", "required": false, "description": "Quantos pular.", "schema": { "type": "integer", "default": "0" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "normal", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": null, "opened_by": "inbound", "resolution_note": null } ], "pagination": { "limit": 25, "offset": 0, "total": 482, "has_more": true } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}": { "get": { "tags": [ "Atendimentos" ], "summary": "Obter um atendimento", "description": "Os dados de um atendimento: número, fila, responsável, etapa do funil, quando abriu e quando encerrou.\n\n**Permissão necessária:** `tickets:read`", "operationId": "get_tickets__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do atendimento.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "aa10c5e6-2f81-4390-bb47-1d8e6c0a3f52", "conversation_id": "77c3f0a1-2b44-4de8-9a10-5c6b7e8d9f01", "ticket_number": 482, "priority": "normal", "queue_id": "5f1c8a20-3d47-4b90-8e21-0c7f6a5d3b19", "assigned_to": null, "pipeline_stage_id": "9e2d6b18-4f70-42a1-b5c9-8d3e0a7f2c61", "board_id": "b0d4e7f2-1a63-4c05-9f38-2e5a7c1b6d04", "opened_at": "2026-07-20T13:05:00.000Z", "closed_at": null, "opened_by": "inbound", "resolution_note": null } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/usage": { "get": { "tags": [ "Conta" ], "summary": "Consultar o consumo da chave", "description": "Quantas chamadas esta chave fez no minuto e no dia corrente, e quanto ainda resta. Os mesmos números vêm nos cabeçalhos `X-RateLimit-*` de toda resposta.\n\n**Permissão:** qualquer chave válida.", "operationId": "get_usage", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "minute": { "used": 12, "limit": 300, "remaining": 288 }, "day": { "used": 4310, "limit": 200000, "remaining": 195690 }, "total_requests": 128744 } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users": { "get": { "tags": [ "Equipe" ], "summary": "Listar membros do workspace", "description": "Quem faz parte deste workspace e com que papel. É de onde saem os identificadores para atribuir atendimento (`assigned_to`) e para marcar reunião (`member_user_id`). Quem está desativado aparece com `is_active: false`.\n\n**Permissão necessária:** `users:read`", "operationId": "get_users", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "aa11bb22-cc33-44dd-88ee-ff0011223344", "first_name": "Géssica", "last_name": "Dias", "role": "supervisor", "is_active": true, "avatar_url": null } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Listar avisos automáticos configurados", "description": "O caminho inverso da API: em vez de você perguntar, nós avisamos. Cada webhook é um endereço seu que recebe um POST quando algo acontece aqui.\n\nA lista completa de eventos, com o corpo que cada um envia, está em **GET /webhooks/events**.\n\nO `secret` devolvido aqui é o que assina cada entrega: nós mandamos o cabeçalho `X-Fluxo-Signature: sha256=…` com o HMAC-SHA256 do corpo usando esse segredo. Confira a assinatura antes de confiar no aviso.\n\n**Permissão necessária:** `webhooks:read`", "operationId": "get_webhooks", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "1b2c3d4e-5f60-4718-a293-a4b5c6d7e8f9", "url": "https://meusistema.com.br/hooks/fluxo", "secret": "whsec_7Yb3…", "events": [ "message.created", "ticket.resolved" ], "active": true, "created_at": "2026-07-10T09:00:00Z" } ] } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Criar aviso automático", "description": "Cadastra um endereço seu para receber avisos automáticos. A resposta traz o `secret` que assina cada entrega — guarde-o.\n\n**Permissão necessária:** `webhooks:write`", "operationId": "post_webhooks", "parameters": [], "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "1b2c3d4e-5f60-4718-a293-a4b5c6d7e8f9", "url": "https://meusistema.com.br/hooks/fluxo", "secret": "whsec_7Yb3…", "events": [ "message.created", "ticket.resolved" ], "active": true } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Endereço https que vai receber o POST.", "example": "https://meusistema.com.br/hooks/fluxo" }, "events": { "type": "array", "description": "Quais eventos avisar. A lista completa está em GET /webhooks/events.", "example": [ "message.created", "ticket.stage_changed" ] }, "active": { "type": "boolean", "description": "Começar ligado.", "example": true } }, "required": [ "url", "events" ], "additionalProperties": false }, "example": { "url": "https://meusistema.com.br/hooks/fluxo", "events": [ "message.created", "ticket.resolved" ], "active": true } } } } } }, "/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Editar aviso automático", "description": "Altera o endereço, os eventos ou liga/desliga um aviso automático. A lista de eventos substitui a anterior por inteiro.\n\n**Permissão necessária:** `webhooks:write`", "operationId": "patch_webhooks__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do webhook.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "1b2c3d4e-5f60-4718-a293-a4b5c6d7e8f9", "url": "https://meusistema.com.br/hooks/fluxo", "events": [ "message.created" ], "active": false } } } } }, "400": { "description": "`VALIDATION` — Dados inválidos na requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "VALIDATION": { "summary": "VALIDATION", "value": { "error": { "code": "VALIDATION", "message": "Dados inválidos na requisição.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Novo endereço https." }, "events": { "type": "array", "description": "Nova lista de eventos (substitui a anterior por inteiro)." }, "active": { "type": "boolean", "description": "Ligar ou desligar." } }, "additionalProperties": false }, "example": { "active": false } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Remover aviso automático", "description": "Remove o aviso automático. O seu sistema para de receber na hora e o segredo se perde.\n\n**Permissão necessária:** `webhooks:write`", "operationId": "delete_webhooks__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do webhook.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Excluído. Sem corpo na resposta." }, "401": { "description": "`INVALID_KEY` — Chave de API inválida.\n\n`KEY_EXPIRED` — Esta chave de API expirou.\n\n`KEY_REVOKED` — Esta chave de API foi revogada.\n\n`MISSING_KEY` — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INVALID_KEY": { "summary": "INVALID_KEY", "value": { "error": { "code": "INVALID_KEY", "message": "Chave de API inválida.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_EXPIRED": { "summary": "KEY_EXPIRED", "value": { "error": { "code": "KEY_EXPIRED", "message": "Esta chave de API expirou.", "request_id": "req_9f8e7d6c5b4a" } } }, "KEY_REVOKED": { "summary": "KEY_REVOKED", "value": { "error": { "code": "KEY_REVOKED", "message": "Esta chave de API foi revogada.", "request_id": "req_9f8e7d6c5b4a" } } }, "MISSING_KEY": { "summary": "MISSING_KEY", "value": { "error": { "code": "MISSING_KEY", "message": "Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_…", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "403": { "description": "`FORBIDDEN_SCOPE` — Esta chave não tem permissão para esta operação.\n\n`WORKSPACE_INACTIVE` — O workspace está suspenso ou com a assinatura vencida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "FORBIDDEN_SCOPE": { "summary": "FORBIDDEN_SCOPE", "value": { "error": { "code": "FORBIDDEN_SCOPE", "message": "Esta chave não tem permissão para esta operação.", "request_id": "req_9f8e7d6c5b4a" } } }, "WORKSPACE_INACTIVE": { "summary": "WORKSPACE_INACTIVE", "value": { "error": { "code": "WORKSPACE_INACTIVE", "message": "O workspace está suspenso ou com a assinatura vencida.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "404": { "description": "`RESOURCE_NOT_FOUND` — Registro não encontrado neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RESOURCE_NOT_FOUND": { "summary": "RESOURCE_NOT_FOUND", "value": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Registro não encontrado neste workspace.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "429": { "description": "`RATE_LIMITED` — Limite de chamadas excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Limite de chamadas excedido.", "request_id": "req_9f8e7d6c5b4a" } } } } } } }, "500": { "description": "`INTERNAL` — Erro interno. A falha foi registrada do nosso lado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "INTERNAL": { "summary": "INTERNAL", "value": { "error": { "code": "INTERNAL", "message": "Erro interno. A falha foi registrada do nosso lado.", "request_id": "req_9f8e7d6c5b4a" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } } } }