API de Análise Só de Leitura

A API HTTP api.jonot.io/v1/* dá acesso só de leitura aos dados de senhas e filas da sua organização — sem necessidade de início de sessão no admin, apenas um bearer token. Use-a para extrair dados para um data warehouse, uma ferramenta de BI ou um painel personalizado.

Cuidado

A API está disponível no plano Pro e superiores. O separador de tokens da API na página de Integrações mostra uma sugestão de upgrade no plano Starter.

Obter um token

1. Abra admin.jonot.io/settings/integrations.
2. Clique no separador Tokens da API.
3. Clique em Criar token, dê-lhe um nome (ex.: “Power BI”) e confirme.
4. Copie o token imediatamente — é mostrado apenas uma vez e não pode ser recuperado. Se o perder, revogue-o e crie um novo.

Os tokens têm o prefixo jot_ e não expiram por si só; revogue-os no mesmo separador quando deixarem de ser necessários.

Autenticação

Perigo

Envie o token apenas no cabeçalho Authorization. Nunca o coloque numa query string — as query strings acabam em registos de acesso, registos de proxy e histórico do navegador. Um token fornecido via ?token=... é rejeitado com 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Estado	Significado
401	Token em falta, malformado, desconhecido ou revogado.
402	Token válido, mas a organização não tem a funcionalidade da API ativa.
429	Limite de pedidos excedido — consulte Limites de pedidos abaixo.
400	Parâmetros de consulta inválidos, ou um intervalo de datas superior a 90 dias.

Endpoints

GET /v1/queues

Devolve os estabelecimentos e filas da sua organização, sem filtragem nem paginação:

curl https://api.jonot.io/v1/queues \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "locations": [
    {
      "id": "loc_…",
      "name": "Downtown",
      "slug": "downtown",
      "queues": [
        {
          "id": "q_…",
          "name": "Main Queue",
          "slug": "main-queue",
          "status": "ACTIVE"
        }
      ]
    }
  ]
}

Use os valores id devolvidos para filtrar /v1/tickets e a exportação CSV por queueId / locationId.

GET /v1/tickets

Leitura paginada de senhas, com âmbito na sua organização.

Parâmetro	Obrigatório	Repetível	Notas
from	sim	não	ISO-8601, limite inferior inclusivo em createdAt.
to	sim	não	ISO-8601, limite superior exclusivo. Intervalo máximo de 90 dias.
queueId	não	sim	Repita o parâmetro para filtrar várias filas.
locationId	não	sim	Repita o parâmetro para filtrar vários estabelecimentos.
status	não	sim	Um de WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	não	não	Valor opaco obtido do nextCursor da página anterior.
limit	não	não	Predefinição 100, máximo 500.

curl "https://api.jonot.io/v1/tickets?from=2026-06-01T00:00:00Z&to=2026-06-08T00:00:00Z&status=COMPLETED" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "items": [
    {
      "id": "tkt_…",
      "number": 42,
      "queueId": "q_…",
      "locationId": "loc_…",
      "status": "COMPLETED",
      "createdAt": "2026-06-01T09:14:02.000Z",
      "calledAt": "2026-06-01T09:20:11.000Z",
      "completedAt": "2026-06-01T09:24:47.000Z",
      "cancelledAt": null,
      "skippedAt": null,
      "noShowAt": null,
      "calledByDeviceSessionId": "dev_…"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQi…"
}

As linhas nunca incluem o hash de credencial da senha nem qualquer dado pessoal inserido pelo cliente (nome, notas, número de pessoas) — apenas identificadores, estado e os registos de data/hora do ciclo de vida.

Paginação: quando nextCursor não for nulo, passe-o como cursor no pedido seguinte para continuar de onde ficou (mesmos from/to/filtros). Um nextCursor null significa que chegou ao fim do intervalo.

GET /v1/exports/tickets.csv

Os mesmos filtros de /v1/tickets (from/to obrigatórios, queueId/locationId/status repetíveis) menos cursor/limit — todo o intervalo correspondente é transmitido como uma única resposta CSV, pelo que não há um limite de 500 linhas por página a contornar numa extração em massa.

A ordem das colunas é estável, mas analise as colunas pelo nome do cabeçalho em vez da posição fixa. A linha de cabeçalho está sempre presente e corresponde exatamente a esta lista:

id,number,queueId,locationId,status,createdAt,calledAt,completedAt,cancelledAt,skippedAt,noShowAt,calledByDeviceSessionId

curl "https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o tickets.csv

A resposta é transmitida em fluxo (Transfer-Encoding: chunked), pelo que uma exportação de 90 dias/100 mil linhas não precisa de ser armazenada em memória em nenhum dos lados — encaminhe-a diretamente para um ficheiro ou para um processador.

Limite de intervalo de 90 dias

Todos os endpoints que recebem from/to rejeitam um intervalo superior a 90 dias com 400. Extraia dados de forma incremental (ex.: uma chamada por semana) se precisar de um histórico mais longo — os registos de data/hora do ciclo de vida da senha (calledAt, completedAt, …) permitem-lhe reconstruir durações de espera/atendimento sem voltar a obter as mesmas linhas duas vezes.

Limites de pedidos

60 pedidos/minuto por token (não por IP — o limite acompanha o token). Todas as respostas incluem:

X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1751328000000

Um 429 inclui adicionalmente Retry-After (segundos). Aguarde e tente novamente após essa janela; uma sincronização agendada a cada poucos minutos mantém-se confortavelmente abaixo do limite.

Python + pandas

import requests
import pandas as pd

TOKEN = "jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE = "https://api.jonot.io/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def fetch_tickets(frm: str, to: str) -> pd.DataFrame:
    rows = []
    cursor = None
    while True:
        params = {"from": frm, "to": to, "limit": 500}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(f"{BASE}/tickets", headers=HEADERS, params=params, timeout=30)
        res.raise_for_status()
        body = res.json()
        rows.extend(body["items"])
        cursor = body["nextCursor"]
        if not cursor:
            break
    return pd.DataFrame(rows)

df = fetch_tickets("2026-06-01T00:00:00Z", "2026-07-01T00:00:00Z")
df["waitSeconds"] = (
    pd.to_datetime(df["calledAt"]) - pd.to_datetime(df["createdAt"])
).dt.total_seconds()
print(df.groupby("queueId")["waitSeconds"].mean())

Ou leia diretamente a exportação CSV — o pandas trata a resposta em fluxo de forma transparente:

df = pd.read_csv(
    f"{BASE}/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z",
    storage_options={"Authorization": f"Bearer {TOKEN}"},
)

Power BI (conector Web)

1. No Power BI Desktop: Obter Dados → Web.
2. Escolha Avançado e construa o URL com o seu intervalo de datas, ex.: https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. Em Parâmetros de cabeçalho de pedido HTTP, adicione um cabeçalho chamado Authorization com o valor Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Clique em OK — o Power BI deteta o CSV e abre a pré-visualização da tabela.
5. Clique em Carregar (ou primeiro em Transformar Dados se quiser definir os tipos de coluna — createdAt/calledAt/etc. são importados como texto; converta-os para Data/Hora no Power Query).
6. Defina uma atualização agendada no serviço Power BI se estiver a extrair dados com regularidade; mantenha o intervalo confortavelmente abaixo de 90 dias por atualização.

Dica

O armazenamento de credenciais do Power BI mantém o cabeçalho Authorization fora da query string e fora do código M visível no ficheiro .pbix guardado, pelo que esta é a forma recomendada de autenticar a partir do Power BI — nunca incorpore o token diretamente no URL.