Referência de API

Referência dos endpoints REST da OBBU FLOW — a mesma API que a própria plataforma usa por trás de cada tela. Útil pra quem está integrando um sistema externo (webhooks, automações, parceiros white-label).

Esta página cobre só os endpoints de uso geral. Endpoints operacionais/sensíveis (controle remoto de equipamento via ACS, credenciais de integração, log de auditoria, gestão de usuários e permissões) ficam documentados na área interna (priv.obbuflow.com.br), não aqui — por não serem seguros de descrever publicamente sem risco.

Autenticação

Toda chamada (exceto /auth/login e o webhook do WhatsApp) exige um token de acesso real:

1. POST /api/v1/auth/login com e-mail e senha — devolve um token de acesso (válido por 15 minutos) e um refresh token (válido por 7 dias).
2. Envie o token de acesso em todo request: Authorization: Bearer <token>.
3. Quando o token de acesso expirar, use POST /api/v1/auth/refresh com o refresh token pra obter um novo, sem precisar logar de novo.

Não existe chave de API separada — a autenticação é sempre por login de usuário real do tenant, com as mesmas permissões (Grupos de Acesso) que esse usuário tem dentro da plataforma.

Base URL

https://obbuflow.com.br/api/v1

Endpoints

Autenticação

Método	Caminho	Descrição	Campos
POST	/api/v1/auth/login	Login	email* (texto/email), senha* (texto)
POST	/api/v1/auth/logout	Logout	—
GET	/api/v1/auth/me	Dados do usuário autenticado	—
POST	/api/v1/auth/refresh	Renovar token de acesso	—

Conversas

Método	Caminho	Descrição	Campos
GET	/api/v1/conversas	Listar	sub_aba (texto)
POST	/api/v1/conversas	Criar	nome_contato* (texto), telefone* (texto), canal (texto), departamento_id* (texto/uuid), motivo_atendimento (texto), mensagem_inicial (texto), nome_template_whatsapp (texto), mensagem_template_texto (texto), cliente_vinculado_id (texto), cliente_vinculado_nome (texto)
GET	/api/v1/conversas/{conversa_id}	Obter	—
PATCH	/api/v1/conversas/{conversa_id}	Atualizar	sub_aba (texto), assumido_por_id (texto/uuid), nao_lida (booleano), fixado_no_topo (booleano), motivo_atendimento (texto), etiquetas (lista), satisfacao (inteiro), pendencia_assunto (booleano), pendencia_assunto_texto (texto), pendencia_assunto_resolvida (booleano), cliente_vinculado_nome (texto), cliente_vinculado_id (texto), contrato_ativo_id (texto), alerta_pendencia_visto (booleano), handoff_solicitado (booleano), handoff_visto (booleano), agente_ativo (booleano)
POST	/api/v1/conversas/{conversa_id}/ativar-agente	Ativar o Agente de IA nessa conversa	—
POST	/api/v1/conversas/{conversa_id}/parar-agente	Parar o Agente de IA nessa conversa	—
POST	/api/v1/conversas/{conversa_id}/gerar-resumo	Gerar resumo da conversa	—
POST	/api/v1/conversas/{conversa_id}/mensagens	Enviar mensagem de texto	autor (texto), texto* (texto)
POST	/api/v1/conversas/{conversa_id}/mensagens/arquivo	Enviar mensagem com arquivo	arquivo* (texto), nome_exibicao* (texto), texto (texto)
POST	/api/v1/conversas/{conversa_id}/mensagens/audio	Enviar mensagem de áudio	arquivo* (texto), duracao_segundos (inteiro)
GET	/api/v1/conversas/{conversa_id}/mensagens/{mensagem_id}/arquivo	Baixar arquivo de uma mensagem	—
GET	/api/v1/conversas/{conversa_id}/mensagens/{mensagem_id}/audio	Baixar áudio de uma mensagem	—
POST	/api/v1/conversas/{conversa_id}/mensagens/{mensagem_id}/transcrever	Transcrever áudio de uma mensagem	—
POST	/api/v1/conversas/{conversa_id}/observacoes	Adicionar observação	texto* (texto)
POST	/api/v1/conversas/{conversa_id}/participantes	Adicionar participante	usuario_id* (texto/uuid)
DELETE	/api/v1/conversas/{conversa_id}/participantes/{usuario_id}	Remover participante	—
POST	/api/v1/conversas/{conversa_id}/preferencia-atendente	Definir atendente preferido pro contato	—
DELETE	/api/v1/conversas/{conversa_id}/preferencia-atendente	Remover atendente preferido	—

Copiloto de IA

Método	Caminho	Descrição	Campos
GET	/api/v1/conversas/{conversa_id}/copiloto	Listar conversas de copiloto	—
POST	/api/v1/conversas/{conversa_id}/copiloto	Criar conversa de copiloto	tipo* (texto)
GET	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}	Obter	—
POST	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}/anotacao	Adicionar anotação	texto* (texto)
POST	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}/instrucao	Instruir a IA	texto* (texto), contexto_erp (texto), imagem_base64 (texto), imagem_mime (texto)
POST	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}/gerar-resposta	Gerar sugestão de resposta	contexto_erp (texto)
POST	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}/confirmar-enviar	Confirmar e enviar ao cliente	—
POST	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}/perguntar	Perguntar (modo privado)	texto* (texto), contexto_erp (texto), imagem_base64 (texto), imagem_mime (texto)
POST	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}/encerrar	Encerrar	—
GET	/api/v1/conversas/{conversa_id}/copiloto/{copiloto_id}/mensagens/{mensagem_id}/imagem	Obter imagem de uma mensagem	—

Clientes

Método	Caminho	Descrição	Campos
GET	/api/v1/clientes	Listar	busca (texto), pagina (inteiro), rp (inteiro)
GET	/api/v1/clientes/{id_cliente}	Obter	—
GET	/api/v1/clientes/{id_cliente}/contratos	Contratos do cliente	—
GET	/api/v1/clientes/{id_cliente}/faturas	Faturas do cliente	—
GET	/api/v1/clientes/{id_cliente}/arquivos	Arquivos do cliente (ERP)	—
GET	/api/v1/clientes/{id_cliente}/arquivos/{id_arquivo}/conteudo	Baixar arquivo	—
GET	/api/v1/clientes/{id_cliente}/ocorrencias	Ocorrências/OS do cliente	—
GET	/api/v1/clientes/{id_cliente}/ocorrencias/{id_ocorrencia}/arquivos	Arquivos de uma ocorrência	—
GET	/api/v1/clientes/{id_cliente}/ocorrencias/{id_ocorrencia}/arquivos/{id_arquivo}/conteudo	Baixar arquivo de ocorrência	—

Arquivos ERP

Método	Caminho	Descrição	Campos
GET	/api/v1/arquivos-erp	Listar	cliente_id* (texto)

Anexos do Cliente (no Atendimento)

Método	Caminho	Descrição	Campos
GET	/api/v1/clientes/{id_cliente}/pastas	Listar pastas	—
POST	/api/v1/clientes/{id_cliente}/pastas	Criar pasta	nome* (texto)
POST	/api/v1/clientes/{id_cliente}/pastas/{pasta_id}/arquivos	Anexar arquivo	nome* (texto), arquivo* (texto)
GET	/api/v1/clientes/{id_cliente}/pastas/{pasta_id}/arquivos/{arquivo_id}/download	Baixar	—
POST	/api/v1/clientes/{id_cliente}/pastas/{pasta_id}/arquivos/{arquivo_id}/remover	Remover arquivo	senha* (texto)
POST	/api/v1/clientes/{id_cliente}/pastas/{pasta_id}/remover	Remover pasta	senha* (texto)

Faturas

Método	Caminho	Descrição	Campos
GET	/api/v1/faturas/{id_areceber}/boleto-pdf	Baixar boleto em PDF	—
GET	/api/v1/faturas/{id_areceber}/recibo	Obter recibo	—
GET	/api/v1/faturas/{id_areceber}/recibo-pdf	Baixar recibo em PDF	—
POST	/api/v1/faturas/{id_areceber}/enviar-whatsapp	Enviar fatura por WhatsApp	conversa_id (texto/uuid), telefone (texto)
POST	/api/v1/faturas/{id_areceber}/enviar-recibo-whatsapp	Enviar recibo por WhatsApp	conversa_id (texto/uuid), telefone (texto)

Leads

Método	Caminho	Descrição	Campos
GET	/api/v1/leads	Listar	—
POST	/api/v1/leads	Criar	nome* (texto), nota (texto), origem* (texto), contato (texto)
PATCH	/api/v1/leads/{lead_id}	Mover de estágio	estagio* (texto)
DELETE	/api/v1/leads/{lead_id}	Excluir	—

Agenda

Método	Caminho	Descrição	Campos
GET	/api/v1/agenda/categorias	Listar categorias	—
POST	/api/v1/agenda/categorias	Criar categoria	nome* (texto), cor* (texto), ativa (booleano)
PATCH	/api/v1/agenda/categorias/{categoria_id}	Atualizar categoria	nome (texto), cor (texto), ativa (booleano)
DELETE	/api/v1/agenda/categorias/{categoria_id}	Remover categoria	—
GET	/api/v1/agenda/eventos	Listar eventos	—
POST	/api/v1/agenda/eventos	Criar evento	titulo* (texto), categoria_id* (texto/uuid), data* (texto), hora_inicio* (texto), hora_fim* (texto), observacao (texto)
PATCH	/api/v1/agenda/eventos/{evento_id}	Atualizar evento	titulo (texto), categoria_id (texto/uuid), data (texto), hora_inicio (texto), hora_fim (texto), observacao (texto)
DELETE	/api/v1/agenda/eventos/{evento_id}	Remover evento	—

Chat Interno

Método	Caminho	Descrição	Campos
GET	/api/v1/canais-internos	Listar canais e DMs	—
POST	/api/v1/canais-internos	Criar canal	nome* (texto)
POST	/api/v1/canais-internos/dm	Criar ou obter DM	usuario_alvo_id* (texto/uuid)
PATCH	/api/v1/canais-internos/{canal_id}	Renomear canal	nome* (texto)
DELETE	/api/v1/canais-internos/{canal_id}	Remover canal	—
POST	/api/v1/canais-internos/{canal_id}/membros	Adicionar membro	usuario_id* (texto/uuid)
DELETE	/api/v1/canais-internos/{canal_id}/membros/{membro_id}	Remover membro	—
POST	/api/v1/canais-internos/{canal_id}/mensagens	Enviar mensagem	texto* (texto)
POST	/api/v1/canais-internos/{canal_id}/mensagens/arquivo	Enviar mensagem com arquivo	arquivo* (texto), texto (texto)
GET	/api/v1/canais-internos/{canal_id}/mensagens/{mensagem_id}/arquivo	Baixar arquivo	—

Envio em Massa

Método	Caminho	Descrição	Campos
GET	/api/v1/campanhas	Listar campanhas	—
POST	/api/v1/campanhas	Criar campanha	nome* (texto), departamento_id* (texto/uuid), nome_template_whatsapp* (texto), contatos* (lista), agendado_para (texto/date-time)
PATCH	/api/v1/campanhas/{campanha_id}	Atualizar campanha	status (texto), status_label (texto)
GET	/api/v1/campanhas/{campanha_id}/contatos	Contatos da campanha	—
GET	/api/v1/segmentos	Listar segmentos	—
POST	/api/v1/segmentos	Criar segmento	nome* (texto), filtro* (texto), alcance (inteiro)
PATCH	/api/v1/segmentos/{segmento_id}	Atualizar segmento	nome (texto), filtro (texto), alcance (inteiro)
DELETE	/api/v1/segmentos/{segmento_id}	Remover segmento	—
GET	/api/v1/variaveis-mensagem	Listar variáveis	—
POST	/api/v1/variaveis-mensagem	Criar variável	token* (texto), descricao* (texto)
PATCH	/api/v1/variaveis-mensagem/{variavel_id}	Atualizar variável	token (texto), descricao (texto)
DELETE	/api/v1/variaveis-mensagem/{variavel_id}	Remover variável	—

Tags & Mensagens Rápidas

Método	Caminho	Descrição	Campos
GET	/api/v1/etiquetas	Listar etiquetas	—
POST	/api/v1/etiquetas	Criar etiqueta	nome* (texto), cor* (texto), departamentos (lista)
PATCH	/api/v1/etiquetas/{etiqueta_id}	Atualizar etiqueta	nome (texto), cor (texto), departamentos (lista)
DELETE	/api/v1/etiquetas/{etiqueta_id}	Remover etiqueta	—
GET	/api/v1/mensagens-rapidas	Listar mensagens rápidas	—
POST	/api/v1/mensagens-rapidas	Criar mensagem rápida	atalho* (texto), texto* (texto), departamentos (lista)
PATCH	/api/v1/mensagens-rapidas/{mensagem_id}	Atualizar mensagem rápida	atalho (texto), texto (texto), departamentos (lista)
DELETE	/api/v1/mensagens-rapidas/{mensagem_id}	Remover mensagem rápida	—
GET	/api/v1/motivos-atendimento	Listar motivos	—
POST	/api/v1/motivos-atendimento	Criar motivo	texto* (texto), departamentos (lista)
PATCH	/api/v1/motivos-atendimento/{motivo_id}	Atualizar motivo	texto (texto), departamentos (lista)
DELETE	/api/v1/motivos-atendimento/{motivo_id}	Remover motivo	—

Departamentos

Método	Caminho	Descrição	Campos
GET	/api/v1/departamentos	Listar	—
POST	/api/v1/departamentos	Criar	nome* (texto), max_atendimentos_por_atendente (inteiro), cor (texto)
PATCH	/api/v1/departamentos/{departamento_id}	Atualizar	nome (texto), max_atendimentos_por_atendente (inteiro), cor (texto)
DELETE	/api/v1/departamentos/{departamento_id}	Remover	—
GET	/api/v1/departamentos/{departamento_id}/status-horario	Status de horário (aberto/fechado agora)	—

Horários de Atendimento

Método	Caminho	Descrição	Campos
GET	/api/v1/horarios-atendimento	Listar	—
POST	/api/v1/horarios-atendimento	Criar	nome* (texto), dias* (lista), departamentos (lista), plantao_ativo (booleano), plantao_inicio (texto), plantao_fim (texto), plantao_descricao (texto), plantao_dias (lista)
PATCH	/api/v1/horarios-atendimento/{horario_id}	Atualizar	nome (texto), dias (lista), departamentos (lista), plantao_ativo (booleano), plantao_inicio (texto), plantao_fim (texto), plantao_descricao (texto), plantao_dias (lista)
DELETE	/api/v1/horarios-atendimento/{horario_id}	Remover	—

Feriados

Método	Caminho	Descrição	Campos
GET	/api/v1/feriados	Listar	ano (inteiro)
POST	/api/v1/feriados	Criar feriado personalizado	data* (texto), nome* (texto), atende (booleano), horario_inicio (texto), horario_fim (texto), mensagem_saudacao (texto), departamentos (lista)
PUT	/api/v1/feriados/nacional/{slug}	Customizar feriado nacional	atende (booleano), horario_inicio (texto), horario_fim (texto), mensagem_saudacao (texto), departamentos (lista)
PATCH	/api/v1/feriados/{feriado_id}	Atualizar personalizado	nome (texto), atende (booleano), horario_inicio (texto), horario_fim (texto), mensagem_saudacao (texto), departamentos (lista)
DELETE	/api/v1/feriados/{feriado_id}	Remover personalizado	—

Webhooks (saída, configuráveis pelo tenant)

Método	Caminho	Descrição	Campos
GET	/api/v1/webhooks	Listar	—
POST	/api/v1/webhooks	Criar	nome* (texto), url* (texto), eventos (lista), ativo (booleano)
PATCH	/api/v1/webhooks/{webhook_id}	Atualizar	nome (texto), url (texto), eventos (lista), ativo (booleano)
DELETE	/api/v1/webhooks/{webhook_id}	Remover	—

Templates de Modelo

Método	Caminho	Descrição	Campos
GET	/api/v1/templates-modelo	Listar	—
POST	/api/v1/templates-modelo	Criar	label* (texto), nome_padrao* (texto), categoria* (texto), cabecalho (texto), corpo* (texto), rodape (texto), botoes (lista), exemplos (objeto), variaveis_mapeadas (objeto), finalidade (texto), respostas (objeto)
PATCH	/api/v1/templates-modelo/{modelo_id}	Atualizar	label (texto), nome_padrao (texto), categoria (texto), cabecalho (texto), corpo (texto), rodape (texto), botoes (lista), exemplos (objeto), variaveis_mapeadas (objeto), finalidade (texto), respostas (objeto)
DELETE	/api/v1/templates-modelo/{modelo_id}	Remover	—

Assistente IA

Método	Caminho	Descrição	Campos
GET	/api/v1/assistente-ia	Listar conversas	—
POST	/api/v1/assistente-ia	Criar conversa	—
GET	/api/v1/assistente-ia/{conversa_id}	Obter	—
POST	/api/v1/assistente-ia/{conversa_id}/perguntar	Perguntar	texto* (texto), imagem_base64 (texto), imagem_mime (texto)
POST	/api/v1/assistente-ia/{conversa_id}/encerrar	Encerrar	—
GET	/api/v1/assistente-ia/{conversa_id}/mensagens/{mensagem_id}/imagem	Obter imagem de uma mensagem	—

Base de Conhecimento

Método	Caminho	Descrição	Campos
GET	/api/v1/base-conhecimento	Listar	—
POST	/api/v1/base-conhecimento/upload	Adicionar documento	nome* (texto), categoria* (texto), arquivo (texto), link (texto)
PATCH	/api/v1/base-conhecimento/{item_id}	Atualizar categoria	categoria* (texto)
DELETE	/api/v1/base-conhecimento/{item_id}	Remover	—
GET	/api/v1/base-conhecimento/{item_id}/arquivo	Baixar arquivo	—
GET	/api/v1/base-conhecimento/itens-padrao	Listar itens padrão OBBU	—
PATCH	/api/v1/base-conhecimento/itens-padrao/{item_id}	Ativar/desativar item padrão	ativo* (booleano)
POST	/api/v1/base-conhecimento/importar-padrao	Importar itens padrão	—

Base de Comportamento

Método	Caminho	Descrição	Campos
GET	/api/v1/diretrizes-comportamento	Listar	—
POST	/api/v1/diretrizes-comportamento	Criar	categoria* (texto), texto* (texto), forcar (booleano)
PATCH	/api/v1/diretrizes-comportamento/{diretriz_id}	Atualizar	categoria (texto), texto (texto), forcar (booleano)
DELETE	/api/v1/diretrizes-comportamento/{diretriz_id}	Remover	—
POST	/api/v1/diretrizes-comportamento/importar	Importar de arquivo .txt	categoria* (texto), linhas* (lista)
POST	/api/v1/diretrizes-comportamento/importar-padrao	Importar diretrizes padrão OBBU	—

Base de Decisão

Método	Caminho	Descrição	Campos
GET	/api/v1/regras-decisao	Listar	—
POST	/api/v1/regras-decisao	Criar	funcao_id* (texto), funcao_nome* (texto), condicao* (texto), forcar (booleano)
PATCH	/api/v1/regras-decisao/{regra_id}	Atualizar	funcao_id (texto), funcao_nome (texto), condicao (texto), forcar (booleano)
DELETE	/api/v1/regras-decisao/{regra_id}	Remover	—
POST	/api/v1/regras-decisao/importar	Importar de arquivo .txt	funcao_id* (texto), funcao_nome* (texto), linhas* (lista)

Agente de IA

Método	Caminho	Descrição	Campos
GET	/api/v1/agente-ia/config	Obter configuração	—
PATCH	/api/v1/agente-ia/config	Atualizar configuração	nome_agente (texto), tom_de_voz (texto), instrucoes_sistema (texto), transferir_se_cliente_pedir_humano (booleano), transferir_apos_tentativas (booleano), tentativas_por_departamento (objeto), fallback_acs_offline (booleano), fallback_modo (texto), motor_ia_habilitado (booleano), execucao_acoes_habilitada (booleano), mensagem_encerramento_habilitada (booleano), pesquisa_satisfacao_habilitada (booleano), pesquisa_satisfacao_texto (texto), pesquisa_satisfacao_prazo_minutos (inteiro), encerramento_por_inatividade_habilitado (booleano), minutos_encerramento_inatividade (inteiro)
POST	/api/v1/agente-ia/config/avatar	Enviar foto do agente	arquivo* (texto)
DELETE	/api/v1/agente-ia/config/avatar	Remover foto	—
GET	/api/v1/agente-ia/ferramentas	Listar ferramentas (permitido/negado)	—
PATCH	/api/v1/agente-ia/ferramentas/{funcao_id}	Permitir/negar uma ferramenta	permitido (booleano), departamentos (lista)
GET	/api/v1/agente-ia/desempenho	Métricas de desempenho	—
GET	/api/v1/agente-ia/uso-ferramentas	Uso/taxa de sucesso por ferramenta	—

Status do Atendente

Método	Caminho	Descrição	Campos
GET	/api/v1/status-atendente	Status atual de todos os atendentes	—
POST	/api/v1/status-atendente	Alterar o próprio status	status* (texto)
GET	/api/v1/status-atendente/me	Meu histórico de status	—
GET	/api/v1/status-atendente/{usuario_id}/historico	Histórico de um atendente	—

Dados da Empresa

Método	Caminho	Descrição	Campos
GET	/api/v1/dados-empresa	Obter	—
PATCH	/api/v1/dados-empresa	Atualizar	nome_fantasia (texto), razao_social (texto), cnpj (texto), telefone (texto), email (texto), endereco (texto), site (texto)

Lembrete de Fatura

Método	Caminho	Descrição	Campos
GET	/api/v1/lembrete-fatura/configuracao	Obter configuração	—
PUT	/api/v1/lembrete-fatura/configuracao	Atualizar configuração	ativo* (booleano), regras* (lista), horario_envio* (texto), template_modelo_id (texto/uuid)
GET	/api/v1/lembrete-fatura/resumo	Resumo	—
GET	/api/v1/lembrete-fatura/historico	Histórico de envios	—
GET	/api/v1/lembrete-fatura/varreduras	Histórico de varreduras do job	—

WhatsApp (webhook público, usado pela Meta)

Método	Caminho	Descrição	Campos
GET	/api/v1/whatsapp/webhook	Verificação do webhook (challenge da Meta)	hub.mode (texto), hub.verify_token (texto), hub.challenge (texto)
POST	/api/v1/whatsapp/webhook	Recebimento de mensagens/eventos (chamado pela Meta, valida assinatura HMAC)	—

Saúde

Método	Caminho	Descrição	Campos
GET	/health	Health check, sem autenticação	—