Documentação da API

Autenticação

Crie uma chave no painel e envie no cabeçalho Authorization: Bearer l17_…. Cada chave pertence a um projeto, e o consumo aparece separado por projeto. A chave é mostrada uma única vez: guarde num cofre de segredos.

POST /v1/decide

Responde todas as perguntas do pedido numa única passada do modelo.

curl

curl https://api.logo17.com.br/v1/decide \
  -H "Authorization: Bearer $L17_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "l17-decide",
    "state": {"canal": "WhatsApp", "mensagem": "Fui cobrado duas vezes na fatura..."},
    "questions": {
      "motivo": {"type": "choice", "instructions": "Qual o motivo do contato?",
                 "criteria": {"cobranca": "problema com cobrança ou fatura",
                              "tecnico": "problema técnico",
                              "informacao": "dúvida ou pedido de informação"}},
      "irritacao": {"type": "score", "instructions": "Quão irritado o cliente está?",
                    "criteria": ["calmo", "incomodado", "irritado", "furioso"]},
      "quer_cancelar": {"type": "noul", "instructions": "O cliente ameaça cancelar o serviço"}
    }
  }'

python

import httpx

r = httpx.post("https://api.logo17.com.br/v1/decide",
               headers={"Authorization": f"Bearer {L17_API_KEY}"},
               json={"model": "l17-decide", "state": texto, "questions": perguntas})
r.raise_for_status()
for nome, resposta in r.json()["answers"].items():
    print(nome, resposta)

campo	tipo	descrição
model	string	produto (ver Produtos). Padrão: `l17-decide`
state	texto \| objeto \| lista	o que o modelo lê. Objetos viram linhas "chave: valor"
questions	objeto	perguntas por nome; cada uma com `type`, `instructions` e `criteria`

POST /v1/qualifica

Uma pergunta só: qual tabulação da sua lista melhor descreve o atendimento. Mande o ticket, a conversa de WhatsApp ou a transcrição da chamada, e a lista de tabulações com código, nome e descrição. Volta a escolhida, o ranking e se vale mandar para revisão humana.

requisiçãoPOST /v1/qualifica

{
  "model": "l17-qualifica",
  "canal": "whatsapp",
  "state": [
    {"autor": "cliente", "texto": "fui cobrado duas vezes na fatura de setembro"},
    {"autor": "agente",  "texto": "vou abrir a contestação e o estorno sai em 5 dias"}
  ],
  "tabulacoes": [
    {"codigo": "FAT-02", "nome": "Contestação de cobrança", "descricao": "cobrança indevida ou em duplicidade",
     "categoria": "Financeiro > Fatura"},
    {"codigo": "CAN-01", "nome": "Pedido de cancelamento", "descricao": "cliente quer encerrar o contrato"},
    {"codigo": "TEC-03", "nome": "Sem conexão", "descricao": "internet ou linha sem funcionar"}
  ],
  "top_k": 3
}

200 OK

{
  "model": "l17-qualifica",
  "tabulacao": {"codigo": "FAT-02", "nome": "Contestação de cobrança", "probabilidade": 0.87},
  "ranking": [
    {"codigo": "FAT-02", "nome": "Contestação de cobrança", "probabilidade": 0.87},
    {"codigo": "CAN-01", "nome": "Pedido de cancelamento", "probabilidade": 0.08},
    {"codigo": "TEC-03", "nome": "Sem conexão", "probabilidade": 0.02}
  ],
  "nenhuma": 0.03,
  "confianca": 0.71,
  "revisar": false,
  "usage": {"input_tokens": 142, "output_tokens": 0}
}

state	texto solto ou lista de turnos {autor, texto}; os turnos viram "autor: texto", uma linha cada
canal	opcional: ticket, whatsapp, chamada… ajuda o modelo a ler o texto
tabulacoes	itens {codigo, nome, descricao, categoria}; a descrição é o que mais pesa. categoria é opcional: "Financeiro > Fatura" ou ["Financeiro", "Fatura"], até 4 níveis
categorias	opcional: descrição de cada categoria, {"Financeiro": "fatura, cobrança e pagamentos"}
modo	auto (padrão): lista quando cabem numa escolha só (até 254), hierarquia quando não cabem · lista · hierarquia
feixe	na hierarquia, quantas categorias seguem abertas em cada nível (1 a 5, padrão 2)
top_k	quantas tabulações voltam no ranking (1 a 20, padrão 3)
limite_revisao	abaixo desta probabilidade, revisar = true (0 a 1, padrão 0,5)
incluir_nenhuma	acrescenta a opção "nenhuma se aplica" (padrão true); se ela vencer, tabulacao = null e revisar = true
instrucoes	opcional: troca a pergunta padrão, "Qual tabulação melhor descreve este atendimento?"

Lista ou hierarquia. Em lista, o modelo escolhe entre todas as tabulações de uma vez, com a categoria no texto de cada uma. Em hierarquia, escolhe a categoria e desce nível a nível (uma passada do modelo por nível), mantendo as feixe categorias mais prováveis abertas; a probabilidade é o produto do caminho. Listas de até 254 tabulações acertam mais em lista; acima disso, agrupe em categorias. Cada item do ranking traz a categoria.

Cobrança igual à do /v1/decide: tokens de entrada (atendimento + lista de tabulações, somados em todos os níveis) × preço do modelo. Textos muito longos são cortados no fim; em chamadas de mais de ~30 minutos, mande a parte que importa.

Tipos de pergunta

choice

criteria

objeto {"opção": "descrição"}, de 2 a 255 opções

resposta

choice, probabilities, confidence

score

criteria

lista de 2 a 10 níveis, em ordem

resposta

score (média ponderada dos níveis, a partir de 0), probabilities, legend, confidence

noul

criteria

opcional {"true": …, "false": …}

resposta

noul: probabilidade de verdadeiro, de 0 a 1

A descrição de cada opção é o que o modelo lê: descrições claras dão respostas melhores.

Resposta

200 OKX-L17-Custo · X-L17-Saldo

{
  "model": "l17-decide",
  "answers": {
    "motivo":        {"type": "choice", "choice": "cobranca", "confidence": 0.67,
                      "probabilities": {"cobranca": 0.89, "tecnico": 0.03, "informacao": 0.08}},
    "irritacao":     {"type": "score", "score": 2.64, "confidence": 0.44,
                      "probabilities": {"0": 0.02, "1": 0.04, "2": 0.24, "3": 0.70},
                      "legend": {"0": "calmo", "1": "incomodado", "2": "irritado", "3": "furioso"}},
    "quer_cancelar": {"type": "noul", "noul": 0.92}
  },
  "usage": {"input_tokens": 386, "output_tokens": 0}
}

confidence = 1 − entropia normalizada da distribuição: alta quando uma opção domina. Os cabeçalhos X-L17-Custo e X-L17-Saldo trazem o custo da chamada e o saldo restante.

Erros e cobrança

Cobramos os tokens de entrada (state + perguntas) × o preço do produto, só em respostas 200. Erros não são cobrados.

400	corpo inválido ou sem state/questions
401	chave ausente, inválida ou revogada
402	saldo insuficiente
404	produto (model) inexistente ou indisponível
422	pergunta inválida: o corpo diz qual e por quê
502	modelo indisponível no momento; tente de novo

// produtos

Produtos

Cada produto é um modelo do catálogo, escolhido pelo campo model, na chamada indicada ao lado dele.

L17 Decide

"model": "l17-decide" POST /v1/decide

disponível

R$ 0,15 entrada · R$ 0,00 saída / 1M tokens

Modelo genérico: responde qualquer pergunta tipada sobre textos em português, com a probabilidade de cada opção.

→Triagem de mensagens e tickets
→Classificação de avaliações e reclamações
→Roteamento de pedidos por intenção
→Filtro antes de chamar um LLM caro

ver pedido de exemplo

{
  "state": {
    "canal": "WhatsApp",
    "mensagem": "Já é a terceira vez que eu reclamo! Fui cobrado duas vezes na fatura de setembro e ninguém resolve. Se não estornarem até sexta eu cancelo o plano e vou no Procon."
  },
  "questions": {
    "motivo": {
      "type": "choice",
      "instructions": "Qual o motivo do contato?",
      "criteria": {
        "cobranca": "problema com cobrança ou fatura",
        "tecnico": "problema técnico ou falha no serviço",
        "entrega": "atraso ou problema na entrega",
        "informacao": "dúvida ou pedido de informação"
      }
    },
    "irritacao": {
      "type": "score",
      "instructions": "Quão irritado o cliente está?",
      "criteria": [
        "calmo",
        "um pouco incomodado",
        "irritado",
        "furioso"
      ]
    },
    "quer_cancelar": {
      "type": "noul",
      "instructions": "O cliente ameaça cancelar o serviço"
    },
    "elogio": {
      "type": "noul",
      "instructions": "O cliente está elogiando o atendimento"
    }
  }
}

L17 Qualifica

"model": "l17-qualifica" POST /v1/qualifica

disponível

R$ 0,15 entrada · R$ 0,00 saída / 1M tokens

Tabulação automática de atendimentos: escolhe na sua lista de tabulações a que melhor descreve o ticket, a conversa de WhatsApp ou a chamada transcrita.

→Tabulação automática no fim do atendimento
→Sugestão das 3 tabulações mais prováveis para o agente
→Auditoria: comparar com o que o agente marcou
→Relatórios de motivo de contato confiáveis

ver pedido de exemplo

{
  "canal": "whatsapp",
  "state": [
    {
      "autor": "cliente",
      "texto": "Boa tarde, veio cobrado duas vezes o plano na fatura de setembro."
    },
    {
      "autor": "agente",
      "texto": "Verifiquei aqui, houve duplicidade. Vou abrir a contestação e o estorno sai em até 5 dias úteis."
    },
    {
      "autor": "cliente",
      "texto": "Ok, obrigado."
    }
  ],
  "tabulacoes": [
    {
      "codigo": "FAT-01",
      "nome": "Segunda via de fatura",
      "descricao": "cliente pede boleto, código de barras ou cópia da fatura"
    },
    {
      "codigo": "FAT-02",
      "nome": "Contestação de cobrança",
      "descricao": "cobrança indevida, em duplicidade ou valor diferente do contratado"
    },
    {
      "codigo": "CAN-01",
      "nome": "Pedido de cancelamento",
      "descricao": "cliente quer encerrar o contrato ou o serviço"
    },
    {
      "codigo": "TEC-03",
      "nome": "Sem conexão",
      "descricao": "internet, linha ou serviço sem funcionar"
    },
    {
      "codigo": "INF-01",
      "nome": "Informação sobre planos",
      "descricao": "dúvidas sobre preços, planos ou ofertas"
    }
  ],
  "top_k": 3
}

L17 Atendimento

"model": "l17-atendimento" POST /v1/decide

em breve

preço a definir

Especializado em atendimento ao cliente: triagem de tickets, chats e WhatsApp e monitoria de ligações transcritas.

→Roteamento automático por motivo e urgência
→Fila prioritária para risco de cancelamento e Procon
→Monitoria de 100% das ligações transcritas
→Indicadores de qualidade por agente

ver pedido de exemplo

{
  "state": {
    "canal": "WhatsApp",
    "mensagem": "Já é a terceira vez que eu reclamo! Fui cobrado duas vezes na fatura de setembro e ninguém resolve. Se não estornarem até sexta eu cancelo o plano e vou no Procon."
  },
  "questions": {
    "motivo": {
      "type": "choice",
      "instructions": "Qual o motivo do contato?",
      "criteria": {
        "cobranca": "problema com cobrança ou fatura",
        "tecnico": "problema técnico ou falha no serviço",
        "entrega": "atraso ou problema na entrega",
        "informacao": "dúvida ou pedido de informação"
      }
    },
    "irritacao": {
      "type": "score",
      "instructions": "Quão irritado o cliente está?",
      "criteria": [
        "calmo",
        "um pouco incomodado",
        "irritado",
        "furioso"
      ]
    },
    "quer_cancelar": {
      "type": "noul",
      "instructions": "O cliente ameaça cancelar o serviço"
    },
    "elogio": {
      "type": "noul",
      "instructions": "O cliente está elogiando o atendimento"
    }
  }
}

Em treinamento. Quer usar no seu projeto ou ajudar a definir as perguntas? Fale com a Logo17.

L17 Fiscal

"model": "l17-fiscal" POST /v1/decide

em breve

preço a definir

Classificação fiscal de itens pela descrição: NCM, CFOP e CEST em cascata, com a confiança de cada nível.

→Cadastro de produtos
→Revisão de notas fiscais
→Auditoria de classificação

Em treinamento. Quer usar no seu projeto ou ajudar a definir as perguntas? Fale com a Logo17.

GET /v1/models

Produtos disponíveis e preço por milhão de tokens de entrada. Não exige chave.

GET /v1/balance

Saldo disponível para a chave, incluindo créditos concedidos ao projeto dela.

Boas práticas

→Use a probabilidade como limite: decida sozinho acima de um valor (ex. 0,9) e mande o resto para revisão.
→Escreva perguntas noul afirmativas ("O cliente quer cancelar"), sem dupla negação.
→O modelo não faz contas, não conta itens nem compara datas: deixe isso no seu código.
→Coloque no state só o que importa para as perguntas: texto irrelevante piora a resposta.