Documentação completa da API

Visão geral

A API recebe uma mensagem do cliente por texto ou áudio, mantém contexto por ticket_id, consulta a Gemini para decidir a ação, pode sintetizar a resposta em áudio e devolve um JSON pronto para o Flowbuilder.

Endpoints

JSONs de entrada

1) Texto simples

{
  "ticket_id": "{{__protocolo}}",
  "cliente": {
    "login": "alexandro8281",
    "cpf_cnpj": "04622603306",
    "nome": "ALEXANDRO SOARES DO NASCIMENTO",
    "cidade": "Fortaleza",
    "bairro": "Centro"
  },
  "rede": {
    "status_conexao": "Conectado"
  },
  "message": {
    "text": "{{__pergunta}}"
  }
}

2) Áudio de entrada

{
  "ticket_id": "{{__protocolo}}",
  "cliente": {
    "login": "alexandro8281",
    "cpf_cnpj": "04622603306",
    "nome": "ALEXANDRO SOARES DO NASCIMENTO"
  },
  "message": {
    "audio_url": "https://seu-dominio.com/audio-cliente.ogg"
  },
  "voice_options": {
    "engine": "edge",
    "voice": "pt-BR-FranciscaNeural",
    "format": "wav",
    "rate": "-2%",
    "pitch": "+0Hz",
    "volume": "+0%"
  }
}

3) Body completo sugerido para o Flowbuilder

{
  "ticket_id": "{{__protocolo}}",
  "cliente": {
    "login": "alexandro8281",
    "cpf_cnpj": "04622603306",
    "nome": "Cliente Teste",
    "cidade": "Fortaleza",
    "bairro": "Centro"
  },
  "rede": {
    "status_conexao": "Conectado"
  },
  "message": {
    "text": "{{__pergunta}}"
  },
  "context": {
    "status_ticket": "EM_ATENDIMENTO",
    "ultimo_setor": "SUPORTE",
    "ultima_acao": "CONTINUAR",
    "historico_resumido": "Cliente em atendimento inicial de suporte."
  },
  "providers": {
    "transcribe": {
      "url": "https://ai.dctsistemas.com.br/transcribe",
      "headers": {
        "Content-Type": "application/json"
      },
      "default_language": "pt"
    },
    "tts": {
      "url": "https://ai.dctsistemas.com.br/tts",
      "headers": {
        "Content-Type": "application/json"
      },
      "defaults": {
        "engine": "edge",
        "voice": "pt-BR-FranciscaNeural",
        "format": "wav",
        "rate": "-2%",
        "pitch": "+0Hz",
        "volume": "+0%"
      }
    }
  },
  "gemini": {
    "api_key": "SUA_CHAVE_GEMINI_AQUI",
    "model": "gemini-2.5-flash",
    "endpoint": "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent",
    "temperature": 0.2,
    "system_instruction": "COLE AQUI O PROMPT COMPLETO USADO NO FLOWBUILDER",
    "schema": {
      "type": "object"
    }
  },
  "voice_options": {
    "engine": "edge",
    "voice": "pt-BR-FranciscaNeural",
    "format": "wav",
    "rate": "-2%",
    "pitch": "+0Hz",
    "volume": "+0%"
  }
}

JSONs de saída

Resposta de texto

{
  "ok": true,
  "ticket_id": "123321",
  "decision": {
    "acao": "CONTINUAR",
    "intencao": "SEM_CONEXAO",
    "mensagem": "Entendi. Me diga as luzes do modem/ONU e as cores.",
    "motivo": "triagem inicial",
    "setor": "SUPORTE",
    "coleta": ["LUZ_ONU"],
    "proximo_passo": "COLETAR_DADOS_BASICOS",
    "resolvido": false,
    "consome_tentativa": false,
    "assunto_chamado": "",
    "resumo_chamado": "",
    "obs": ""
  },
  "reply": {
    "type": "text",
    "text": "Entendi. Me diga as luzes do modem/ONU e as cores."
  }
}

Resposta de áudio

{
  "reply": {
    "type": "audio",
    "text": "Entendi. Me diga as luzes do modem/ONU e as cores.",
    "audio_url": "https://orchestrate.dctsistemas.com.br/storage/tts/tts_20260416_201500_ab12cd34.wav",
    "audio": {
      "mime_type": "audio/wav",
      "url": "https://orchestrate.dctsistemas.com.br/storage/tts/tts_20260416_201500_ab12cd34.wav",
      "base64": "UklGR..."
    }
  },
  "input": {
    "metadata": {
      "original_audio_url": "https://dominio.com/audio-cliente.ogg"
    }
  }
}

Variáveis do Flowbuilder

Fluxo de troca de endereço

Quando o cliente pedir mudança de endereço, a API deve conduzir a coleta e confirmação antes de abrir o chamado.

• Se não houver CEP novo, pedir apenas o CEP.
• Ao receber o CEP, consultar automaticamente o endereço.
• Depois pedir apenas número e ponto de referência.
• Montar o endereço completo e pedir confirmação final com SIM ou NÃO.
• Se o cliente responder NÃO, reiniciar a coleta do CEP.
• Se o cliente responder SIM, retornar ABRIR_CHAMADO com assunto_chamado = TROCA DE ENDERECO.

Exemplo de mensagem de confirmação

Confirma pra mim se o novo endereço está certo:
Rua Exemplo, Centro, Fortaleza-CE, número 123, referência próximo à praça.
Responda só SIM ou NÃO.

Abertura de chamado

Quando a API retornar ABRIR_CHAMADO, o Flowbuilder deve fazer um segundo HTTP Request para o endpoint externo.

Endpoint

POST https://skynetfibra.net.br/apidct/chamado.php

Body sugerido

{
  "acao": "abrir_chamado",
  "login": "{{response.data.ticket_state.cliente.login}}",
  "nome": "{{response.data.ticket_state.cliente.nome}}",
  "assunto": "{{response.data.decision.assunto_chamado}}",
  "prioridade": "normal",
  "obs": "{{response.data.decision.obs}}",
  "atendente": "CHATBOT",
  "reply": "nao",
  "ramal": "todos",
  "tecnico": 0
}

Padronização do assunto

• SEM INTERNET para falta de conexão.
• CONEXAO para lentidão, Wi-Fi, instabilidade e suporte técnico.
• TROCA DE ENDERECO para mudança de endereço confirmada.

Áudio de saída

Se a entrada vier por áudio, a API transcreve, gera a resposta em texto com Gemini, sintetiza um novo áudio no TTS e devolve a URL pública do áudio gerado.

Dicas práticas

• Use sempre ticket_id único por conversa.
• Passe cliente.login quando quiser abrir chamado externo sem precisar buscar o login em outro lugar.
• Passe rede.status_conexao como Conectado ou Desconectado para orientar melhor a triagem.
• Use reply.audio_url no canal que espera uma URL pública de mídia.
• O histórico operacional salvo pela API fica em https://orchestrate.dctsistemas.com.br/storage/tickets.json.
• Troque a chave Gemini antes de produção e prefira mantê-la no servidor, não no Flowbuilder, quando possível.