Documentação

curl https://www.tellia.com.br/api/v1/uploads \
  -H "Authorization: Bearer $TELLIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mimeType": "video/mp4", "tamanhoBytes": 48213901 }'

{
  "objeto": "upload",
  "uploadId": "up_4Zt9QmW2xLr7Kp1Vb8Nc3Hs6",
  "expiraEm": "2026-10-30T15:00:00.000Z",
  "simulado": false,
  "envio": {
    "url": "https://envio.example.com/",
    "metodo": "POST",
    "cabecalhos": {
      "x-session-url": "https://envio.example.com/sessao/8c1f",
      "x-exp": "1793372400000",
      "x-sig": "4b7e0c9a..."
    },
    "parteBytes": 16777216,
    "instrucoes": "Envie os bytes do vídeo em partes de `parteBytes` (a última pode ser menor), em ordem. Cada parte é um POST para `envio.url` com os cabeçalhos de `envio.cabecalhos` e mais `x-offset` (a posição, em bytes, do início da parte). Na última parte, mande também `x-final: 1`. A resposta da última parte traz o JSON do arquivo, `{ file: { name: \"files/...\" } }`: use esse `name` como `fileName` em POST /v1/analises. A assinatura vale até `expiraEm`."
  }
}

// tellia.mjs (Node 18 ou mais novo: fetch nativo)
const API = "https://www.tellia.com.br/api/v1";
const CHAVE = process.env.TELLIA_API_KEY; // segredo do SEU servidor

export async function tellia(caminho, init = {}) {
  const r = await fetch(`${API}${caminho}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${CHAVE}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  // Lê como texto: resposta sem corpo vem vazia, e um erro da plataforma no caminho
  // (tempo esgotado, por exemplo) pode chegar sem JSON.
  const texto = await r.text();
  let corpo = null;
  let semJson = false;
  try {
    corpo = texto ? JSON.parse(texto) : null;
  } catch {
    semJson = true;
  }
  if (!r.ok || semJson) {
    const erro = corpo?.erro ?? null; // o erro da API, ou null se não veio dela
    const e = new Error(erro ? `${erro.codigo}: ${erro.mensagem}` : `HTTP ${r.status} sem o erro da API`);
    e.status = r.status; // guie as retentativas por aqui (429 e 5xx)
    e.erro = erro;
    throw e;
  }
  return corpo; // null quando a resposta não tem corpo
}

import { open, stat } from "node:fs/promises";
import { tellia } from "./tellia.mjs";

/** Envia um arquivo de vídeo e devolve { uploadId, fileName }. */
export async function enviarVideo(caminho, mimeType = "video/mp4") {
  const { size } = await stat(caminho);
  const upload = await tellia("/uploads", {
    method: "POST",
    body: JSON.stringify({ mimeType, tamanhoBytes: size }),
  });

  // Chave de teste: não há o que enviar. Crie a análise sem uploadId e fileName.
  if (!upload.envio) return {};

  const { url, cabecalhos, parteBytes } = upload.envio;
  const arquivo = await open(caminho, "r");
  try {
    let resposta = null;
    for (let offset = 0; offset < size; offset += parteBytes) {
      const tamanho = Math.min(parteBytes, size - offset);
      const parte = Buffer.alloc(tamanho);
      await arquivo.read(parte, 0, tamanho, offset);
      const final = offset + tamanho >= size;

      const r = await fetch(url, {
        method: "POST",
        headers: {
          ...cabecalhos,                 // x-session-url, x-exp, x-sig
          "x-offset": String(offset),    // byte inicial desta parte
          ...(final ? { "x-final": "1" } : {}),
        },
        body: parte,
      });
      if (!r.ok) throw new Error(`Envio falhou no byte ${offset}: HTTP ${r.status}`);
      resposta = await r.json();
    }
    // A resposta da última parte traz o arquivo: { file: { name: "files/..." } }
    return { uploadId: upload.uploadId, fileName: resposta.file.name };
  } finally {
    await arquivo.close();
  }
}

import { randomUUID } from "node:crypto";
import { tellia } from "./tellia.mjs";
import { enviarVideo } from "./enviar-video.mjs";

const { uploadId, fileName } = await enviarVideo("./pitch.mp4");

const analise = await tellia("/analises", {
  method: "POST",
  headers: { "Idempotency-Key": randomUUID() }, // guarde e reuse se precisar repetir
  body: JSON.stringify({
    uploadId,
    fileName,
    duracaoSeg: 95,
    regua: "vendas",
    contexto: {
      situacao: "Pitch de vendas",
      publico: "Diretores de compras",
      objetivo: "Agendar uma demonstração",
    },
    consentimento: {
      coletadoEm: consentimentoDoUsuario.aceitoEm, // quando a pessoa marcou a caixa
      versaoTexto: "consentimento-v1",             // qual texto ela viu
    },
    referencia: "usuario-4821", // seu id interno, sem nome nem e-mail
  }),
});

console.log(analise.id, analise.status); // produção: "na_fila"

{
  "id": "Xb3kP9qL2mT7vR4sW8nY",
  "objeto": "analise",
  "ambiente": "live",
  "simulado": false,
  "status": "na_fila",
  "criadoEm": "2026-10-30T14:00:00.000Z",
  "referencia": "usuario-4821",
  "duracaoSeg": 95,
  "regua": {
    "id": "vendas",
    "versao": null
  },
  "notaGeral": null,
  "faixa": null,
  "dimensoes": [],
  "cenario": null,
  "metricas": null,
  "relatorio": null
}

{
  "id": "sb_7Hq2Lm9Xc4Vt1Rk8Pw3Z",
  "objeto": "analise",
  "ambiente": "test",
  "simulado": true,
  "status": "pronta",
  "criadoEm": "2026-10-30T14:00:00.000Z",
  "referencia": "usuario-4821",
  "duracaoSeg": 95,
  "regua": {
    "id": "vendas",
    "versao": "1.0"
  },
  "notaGeral": 72,
  "faixa": "Bom",
  "dimensoes": [
    {
      "id": "clareza",
      "nome": "Clareza",
      "nota": 78,
      "faixa": "Bom"
    },
    {
      "id": "dominioAssunto",
      "nome": "Domínio do assunto",
      "nota": 74,
      "faixa": "Bom"
    },
    {
      "id": "seguranca",
      "nome": "Segurança",
      "nota": 64,
      "faixa": "Médio"
    },
    {
      "id": "engajamento",
      "nome": "Engajamento",
      "nota": 70,
      "faixa": "Médio"
    }
  ],
  "cenario": {
    "reguaId": "vendas",
    "nome": "Pitch e conversa de vendas",
    "versao": "1.0",
    "nota": 68,
    "faixa": "consistente",
    "criterios": [
      {
        "id": "ven-problema",
        "nome": "Problema do cliente antes do produto",
        "nota": 2,
        "escala": 4
      },
      {
        "id": "ven-implicacao",
        "nome": "Consequência e valor quantificados",
        "nota": 3,
        "escala": 4
      },
      {
        "id": "ven-prova",
        "nome": "Prova concreta",
        "nota": 4,
        "escala": 4
      },
      {
        "id": "ven-objecao",
        "nome": "Antecipa a objeção",
        "nota": 2,
        "escala": 4
      },
      {
        "id": "ven-proximo-passo",
        "nome": "Próximo passo explícito",
        "nota": 3,
        "escala": 4
      }
    ]
  },
  "metricas": {
    "palavrasPorMinuto": 140,
    "totalPalavras": 222,
    "abertura": {
      "segundosAteIdeiaPrincipal": 9,
      "estimado": true,
      "faixa": "direta"
    }
  },
  "relatorio": {
    "resumo": "[SIMULADO] Comunicação clara, com abertura direta. O ponto a treinar é a segurança na conclusão.",
    "pontosFortes": [
      "[SIMULADO] Vai direto ao ponto nos primeiros segundos.",
      "[SIMULADO] Usa um exemplo concreto para explicar a ideia."
    ],
    "ajustes": [
      "[SIMULADO] A voz cai no fim das frases.",
      "[SIMULADO] A conclusão termina sem um próximo passo."
    ],
    "momentos": [
      {
        "inicioSeg": 4,
        "categoria": "Abertura",
        "descricao": "[SIMULADO] Começou direto na ideia principal."
      },
      {
        "inicioSeg": 76,
        "categoria": "Volume",
        "descricao": "[SIMULADO] A voz caiu no fim da frase."
      }
    ],
    "plano7Dias": {
      "foco": "seguranca",
      "objetivo": "[SIMULADO] Sustentar o volume até a última palavra.",
      "dias": [
        {
          "dia": 1,
          "titulo": "[SIMULADO] Dia 1",
          "exercicio": "Leitura em voz alta",
          "instrucoes": "[SIMULADO] Leia um parágrafo mantendo o volume até o ponto final.",
          "duracaoMin": 10
        },
        {
          "dia": 2,
          "titulo": "[SIMULADO] Dia 2",
          "exercicio": "Leitura em voz alta",
          "instrucoes": "[SIMULADO] Leia um parágrafo mantendo o volume até o ponto final.",
          "duracaoMin": 10
        },
        {
          "dia": 3,
          "titulo": "[SIMULADO] Dia 3",
          "exercicio": "Leitura em voz alta",
          "instrucoes": "[SIMULADO] Leia um parágrafo mantendo o volume até o ponto final.",
          "duracaoMin": 10
        },
        {
          "dia": 4,
          "titulo": "[SIMULADO] Dia 4",
          "exercicio": "Leitura em voz alta",
          "instrucoes": "[SIMULADO] Leia um parágrafo mantendo o volume até o ponto final.",
          "duracaoMin": 10
        },
        {
          "dia": 5,
          "titulo": "[SIMULADO] Dia 5",
          "exercicio": "Leitura em voz alta",
          "instrucoes": "[SIMULADO] Leia um parágrafo mantendo o volume até o ponto final.",
          "duracaoMin": 10
        },
        {
          "dia": 6,
          "titulo": "[SIMULADO] Dia 6",
          "exercicio": "Leitura em voz alta",
          "instrucoes": "[SIMULADO] Leia um parágrafo mantendo o volume até o ponto final.",
          "duracaoMin": 10
        },
        {
          "dia": 7,
          "titulo": "[SIMULADO] Dia 7",
          "exercicio": "Leitura em voz alta",
          "instrucoes": "[SIMULADO] Leia um parágrafo mantendo o volume até o ponto final.",
          "duracaoMin": 10
        }
      ]
    }
  }
}

{
  "objeto": "lista",
  "dados": [
    {
      "id": "Xb3kP9qL2mT7vR4sW8nY",
      "objeto": "analise",
      "ambiente": "live",
      "simulado": false,
      "status": "pronta",
      "referencia": "usuario-4821",
      "notaGeral": 72,
      "faixa": "Bom"
    },
    {
      "id": "Qm8vT2kX9pL4nR7sW1cZ",
      "objeto": "analise",
      "ambiente": "live",
      "simulado": false,
      "status": "pronta",
      "referencia": "usuario-4821",
      "notaGeral": 64,
      "faixa": "Médio"
    }
  ],
  "temMais": true,
  "proximo": "2026-10-29T14:00:00.000Z"
}

import { tellia } from "./tellia.mjs";

let antesDe = null;
do {
  const qs = new URLSearchParams({ limite: "50" });
  if (antesDe) qs.set("antesDe", antesDe);
  const pagina = await tellia(`/analises?${qs}`);
  for (const a of pagina.dados) console.log(a.id, a.status, a.notaGeral);
  antesDe = pagina.temMais ? pagina.proximo : null;
} while (antesDe);

curl -X DELETE https://www.tellia.com.br/api/v1/analises/Xb3kP9qL2mT7vR4sW8nY \
  -H "Authorization: Bearer $TELLIA_API_KEY"

# 200
{ "id": "Xb3kP9qL2mT7vR4sW8nY", "objeto": "analise", "apagada": true }

{
  "objeto": "lista",
  "dados": [
    {
      "id": "universal",
      "nome": "Régua universal de comunicação",
      "descricao": "Nota de 0 a 100 em clareza, domínio do assunto, segurança e engajamento. Vem em toda análise e é a única comparável entre análises.",
      "versao": "1.0",
      "tipo": "universal",
      "aviso": null
    },
    {
      "id": "vendas",
      "nome": "Pitch e conversa de vendas",
      "descricao": "Se a fala parte do problema do cliente, mostra valor com prova, antecipa a objeção e fecha com um próximo passo.",
      "versao": "1.0",
      "tipo": "cenario",
      "aviso": null
    }
  ]
}

{
  "objeto": "uso",
  "ambiente": "live",
  "saldoCentavos": 700300,
  "saldoValidoAte": "2027-10-30T14:00:00.000Z",
  "precoAnaliseCentavos": 14900,
  "hoje": {
    "chamadas": 3,
    "gastoCentavos": 44700,
    "tetoCentavos": 300000
  },
  "limites": {
    "requisicoesPorMinuto": 60,
    "duracaoMaxSeg": 600
  }
}

{
  "id": "ev_3f9a1c7e2b8d4f60a1c5e9b7",
  "objeto": "evento",
  "tipo": "analise.concluida",
  "criadoEm": "2026-10-30T14:02:00.000Z",
  "dados": {
    "id": "sb_7Hq2Lm9Xc4Vt1Rk8Pw3Z",
    "objeto": "analise",
    "ambiente": "test",
    "simulado": true,
    "status": "pronta",
    "referencia": "usuario-4821",
    "notaGeral": 72,
    "faixa": "Bom"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

// whsec_... do webhook deste ambiente (o de teste e o de produção são diferentes)
const SEGREDO = process.env.TELLIA_WEBHOOK_SECRET;
const TOLERANCIA_SEG = 300;

function assinaturaValida(cabecalho, corpo) {
  const partes = Object.fromEntries(
    String(cabecalho ?? "").split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    }),
  );
  const t = Number(partes.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCIA_SEG) return false;
  const esperado = Buffer.from(createHmac("sha256", SEGREDO).update(`${t}.${corpo}`).digest("hex"));
  const recebido = Buffer.from(String(partes.v1 ?? ""));
  return recebido.length === esperado.length && timingSafeEqual(recebido, esperado);
}

const app = express();

// Corpo BRUTO: a assinatura vale para os bytes exatos, antes do JSON.parse.
app.post("/webhooks/tellia", express.raw({ type: "application/json" }), (req, res) => {
  const corpo = req.body.toString("utf8");
  if (!assinaturaValida(req.get("Tellia-Assinatura"), corpo)) return res.sendStatus(400);
  res.sendStatus(204);             // responda rápido...
  processarEvento(JSON.parse(corpo)); // ...e trabalhe depois (descarte ids já vistos)
});

app.listen(3000);

import hashlib, hmac, os, time
from flask import Flask, abort, request

SEGREDO = os.environ["TELLIA_WEBHOOK_SECRET"]  # whsec_... do webhook deste ambiente
TOLERANCIA_SEG = 300
app = Flask(__name__)

def assinatura_valida(cabecalho: str, corpo: bytes) -> bool:
    partes = dict(p.strip().split("=", 1) for p in cabecalho.split(",") if "=" in p)
    try:
        t = int(partes.get("t", ""))
    except ValueError:
        return False
    if abs(time.time() - t) > TOLERANCIA_SEG:
        return False
    esperado = hmac.new(SEGREDO.encode(), f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado.encode(), partes.get("v1", "").encode())

@app.post("/webhooks/tellia")
def webhook_tellia():
    corpo = request.get_data()  # bytes exatos, antes de qualquer parse
    if not assinatura_valida(request.headers.get("Tellia-Assinatura", ""), corpo):
        abort(400)
    evento = request.get_json()
    # guarde evento["id"] para não processar duas vezes; trabalhe fora da requisição
    return "", 204

segredo: whsec_EXEMPLOexemploEXEMPLOexemploEXEMPLOexem
cabeçalho: Tellia-Assinatura: t=1793368920,v1=56844b353e19ef55ee6c3fbce1cb369f679b4c4e8bd61f7ae50892986a3518a5
corpo: {"id":"ev_3f9a1c7e2b8d4f60a1c5e9b7","objeto":"evento","tipo":"analise.concluida","criadoEm":"2026-10-30T14:02:00.000Z","dados":{"id":"sb_7Hq2Lm9Xc4Vt1Rk8Pw3Z","status":"pronta"}}

{
  "erro": {
    "codigo": "saldo_insuficiente",
    "mensagem": "Saldo insuficiente. Compre saldo no painel (Minha empresa > API).",
    "saldoCentavos": 1200,
    "precoCentavos": 14900
  }
}