{ "openapi": "3.1.0", "info": { "title": "Rittech Public API", "version": "1.0.0", "description": "API servidor a servidor. Configure o domínio da sua instalação. As chaves são geradas no painel da plataforma." }, "servers": [ { "url": "https://rit.api.rittech.com.br/v1", "description": "URL base da instalação; substitua se necessário." } ], "paths": { "/agents": { "get": { "operationId": "list-agents", "tags": [ "Agentes" ], "summary": "Listar agentes", "description": "Retorna somente agentes da conta proprietária e permitidos pela chave. A ordenação é pelo ID.", "x-required-scope": "agents:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Quantidade máxima por página." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Use o nextCursor da página anterior." } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "agents", "nextCursor" ], "additionalProperties": false }, "example": { "agents": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Atendimento", "description": "Assistente comercial", "provider": "openai", "model": "gpt-4.1", "status": "active", "aiEnabled": true, "updatedAt": "2026-11-05T12:00:00.000Z" } ], "nextCursor": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}": { "get": { "operationId": "get-agent", "tags": [ "Agentes" ], "summary": "Consultar agente", "description": "Consulte os dados públicos e o estado da IA. Instruções, credenciais e configurações privadas não são retornadas.", "x-required-scope": "agents:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent" } }, "required": [ "agent" ], "additionalProperties": false }, "example": { "agent": { "id": "11111111-1111-4111-8111-111111111111", "name": "Atendimento", "description": "Assistente comercial", "provider": "openai", "model": "gpt-4.1", "status": "active", "aiEnabled": true, "updatedAt": "2026-11-05T12:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}/messages": { "post": { "operationId": "send-message", "tags": [ "Agentes" ], "summary": "Enviar mensagem", "description": "Envia uma mensagem ao agente e retorna sua resposta. Cada chamada começa sem histórico de conversa; as ferramentas configuradas podem ser executadas. Não envia uma mensagem pelo WhatsApp. O agente deve estar ativo e com a IA habilitada.", "x-required-scope": "messages:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID único por mensagem. Reutilize-o com o mesmo corpo em tentativas de recuperação por pelo menos 24 horas." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 6000 } }, "required": [ "message" ], "additionalProperties": false }, "example": { "message": "Olá! Quais são os horários de atendimento?" } } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "response": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" } }, "required": [ "inputTokens", "outputTokens" ], "additionalProperties": false } }, "required": [ "agentId", "response", "provider", "model", "usage" ], "additionalProperties": false }, "example": { "agentId": "11111111-1111-4111-8111-111111111111", "response": "Olá! Atendemos de segunda a sexta, das 9h às 18h.", "provider": "openai", "model": "gpt-4.1", "usage": { "inputTokens": 84, "outputTokens": 25 } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}/kanban/contacts/{contactId}/disable": { "post": { "operationId": "disable-contact", "tags": [ "Agentes" ], "summary": "Desligar IA para um contato", "description": "Pausa a IA somente para o contato informado, sem alterar os demais contatos do agente. Mantém configuração e histórico. A reativação é feita no painel. Repetir esta operação é seguro.", "x-required-scope": "agents:control", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "contactId": { "type": "string", "format": "uuid" }, "aiEnabled": { "type": "boolean", "const": false } }, "required": [ "agentId", "contactId", "aiEnabled" ], "additionalProperties": false }, "example": { "agentId": "11111111-1111-4111-8111-111111111111", "contactId": "33333333-3333-4333-8333-333333333333", "aiEnabled": false } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}/kanban": { "get": { "operationId": "get-kanban", "tags": [ "Kanban" ], "summary": "Consultar colunas", "description": "Retorna o Kanban principal de contatos do workspace do agente. As colunas são compartilhadas pelos agentes desse workspace. Esta versão não cria ou exclui colunas.", "x-required-scope": "kanban:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "board": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "columns" ], "additionalProperties": false } }, "required": [ "board" ], "additionalProperties": false }, "example": { "board": { "id": "22222222-2222-4222-8222-222222222222", "name": "Kanban", "columns": [ "Novo", "Em atendimento", "Aguardando", "Concluído" ] } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}/kanban/contacts": { "get": { "operationId": "list-contacts", "tags": [ "Kanban" ], "summary": "Listar contatos", "description": "Lista os contatos vinculados ao agente. Use o ID retornado aqui ao mover um contato; ele é diferente do ID da conversa do WhatsApp.", "x-required-scope": "kanban:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Quantidade máxima por página." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Use o nextCursor da página anterior." }, { "name": "column", "in": "query", "schema": { "type": "string", "maxLength": 80 }, "description": "Nome exato de uma coluna retornada pelo Kanban." } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "contacts", "nextCursor" ], "additionalProperties": false }, "example": { "contacts": [ { "id": "33333333-3333-4333-8333-333333333333", "name": "Contato de exemplo", "phone": "+5511999999999", "column": "Novo" } ], "nextCursor": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}/kanban/contacts/{contactId}": { "patch": { "operationId": "move-contact", "tags": [ "Kanban" ], "summary": "Mover contato", "description": "Move um contato para uma coluna existente. O contato precisa estar vinculado ao agente. O cartão é compartilhado no workspace; a mudança aparece também no painel.", "x-required-scope": "kanban:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "column": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "column" ], "additionalProperties": false }, "example": { "column": "Em atendimento" } } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "column": { "type": "string" } }, "required": [ "id", "name", "column" ], "additionalProperties": false } }, "required": [ "contact" ], "additionalProperties": false }, "example": { "contact": { "id": "33333333-3333-4333-8333-333333333333", "name": "Contato de exemplo", "column": "Em atendimento" } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}/knowledge": { "post": { "operationId": "upload-knowledge", "tags": [ "Base de conhecimento" ], "summary": "Enviar arquivo", "description": "Envia o arquivo original no corpo binário, sem multipart e sem Base64. Aceita PDF, DOCX, TXT, MD, CSV e JSON de até 20 MiB. Limite compartilhado com o painel: 100 MiB ou 100 arquivos por conta. O processamento é assíncrono. Arquivos duplicados retornam 409.", "x-required-scope": "knowledge:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-File-Name", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome com extensão, codificado com encodeURIComponent (percent-encoding)." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "202": { "description": "Arquivo aceito para processamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/File" } }, "required": [ "file" ], "additionalProperties": false }, "example": { "file": { "id": "44444444-4444-4444-8444-444444444444", "name": "catalogo.pdf", "size": 182400, "status": "pending", "error": null, "chunkCount": 0, "createdAt": "2026-11-05T12:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/agents/{agentId}/knowledge/{fileId}": { "get": { "operationId": "get-knowledge", "tags": [ "Base de conhecimento" ], "summary": "Consultar processamento", "description": "Acompanhe o ID retornado pelo upload até ready ou failed. O conteúdo só fica disponível ao agente depois de ready. Evite consultar mais de uma vez a cada 5 segundos.", "x-required-scope": "knowledge:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/File" } }, "required": [ "file" ], "additionalProperties": false }, "example": { "file": { "id": "44444444-4444-4444-8444-444444444444", "name": "catalogo.pdf", "size": 182400, "status": "ready", "error": null, "chunkCount": 12, "createdAt": "2026-11-05T12:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "rit_live_..." } }, "schemas": { "Agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "draft" ] }, "aiEnabled": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "provider", "model", "status", "aiEnabled", "updatedAt" ], "additionalProperties": false }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": "string" }, "column": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "column" ], "additionalProperties": false }, "File": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "processing", "ready", "failed" ] }, "error": { "type": [ "string", "null" ] }, "chunkCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "size", "status", "error", "chunkCount", "createdAt" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } }, "responses": { "Error400": { "description": "Solicitação inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Permissão insuficiente ou origem de navegador", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "Conflito, agente pausado ou solicitação em processamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error413": { "description": "Corpo acima do limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error415": { "description": "Tipo de conteúdo inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Limite de chamadas excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error502": { "description": "Falha do provedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Serviço indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }