Skip to content
ver .md original

Convenções da API

Convenções que valem para todo endpoint da API do Dailybot: identificadores, timestamps, casing, paginação, busca, intervalo de datas e versionamento.

Todo endpoint da API pública do Dailybot segue as mesmas convenções para identificadores, timestamps, casing, paginação, busca, intervalo de datas e versionamento. Aprenda uma vez aqui e cada página de referência se lerá exatamente como você espera.

Identificadores

Todo recurso tem um UUID globalmente único (RFC 4122 v4). Dependendo do modelo, a API retorna como uuid (Form, Form Response, User) ou como id (Kudo, Check-in, Workflow) — em ambos os casos o valor é um UUID e serve como chave estável e opaca para a sua integração.

Regra: se o recurso tem uma coluna UUID dedicada separada da sua chave primária interna, a API retorna uuid; se a própria chave primária é um UUID, a API retorna id. Ambos são UUIDs.

Recurso Campo identificador
Form uuid
Form Response uuid
Agent Report uuid (também retorna id com o mesmo valor por retrocompatibilidade)
Agent Message uuid (também retorna id com o mesmo valor por retrocompatibilidade)
Usuário uuid
Kudo id (UUID)
Check-in (Follow-up) id (UUID)
Workflow id (UUID)

Timestamps

Todos os timestamps são ISO-8601 em UTC com precisão de milissegundos (ex. 2026-07-02T14:33:19.412Z). Campos terminados em _at são timestamps; campos terminados em _date são só data (YYYY-MM-DD). Nunca emitimos strings de hora local.

Casing de campos

Todas as chaves JSON são snake_case (first_name, created_at). Os segmentos de path são kebab-case (/pending-invitations/, /agent-reports/). Os parâmetros de query são snake_case (include_email, only_active).

Paginação

Todo endpoint de lista /v1/* retorna o mesmo envelope de resposta:

{
  "count": 152,
  "next": "https://api.dailybot.com/v1/...?page=2&page_size=50",
  "previous": null,
  "results": [ ... ]
}

Parâmetros de query

Parâmetro Tipo Padrão Máx. Descrição
page integer 1 — Número de página (indexado a partir de 1)
page_size integer 25 100 Itens por página. Valores > 100 são silenciosamente reduzidos.

Aliases legados (retrocompatíveis)

Parâmetro legado Equivale a
limit page_size
offset Paginação por offset

Esses aliases retornam o mesmo envelope. As URLs next/previous refletem o estilo usado pelo chamador.

Paginação opt-in removida: O parâmetro de query ?paginated=true e o header de requisição X-Dailybot-Paginate: true são ignorados. Todo endpoint de lista sempre retorna o envelope.

Campos do envelope de resposta

Campo Tipo Descrição
count integer Total de itens que correspondem (em todas as páginas)
next string | null URL completa da próxima página, ou null se for a última
previous string | null URL completa da página anterior, ou null se for a primeira
results array Itens desta página (sempre um array, nunca null)

Iterar todas as páginas

PAGE=1
while true; do
  RESP=$(curl -s "https://api.dailybot.com/v1/forms/?page=$PAGE&page_size=100" \
    -H "X-API-KEY: $DAILYBOT_API_KEY")
  echo "$RESP" | jq '.results[]'
  NEXT=$(echo "$RESP" | jq -r '.next')
  [ "$NEXT" = "null" ] && break
  PAGE=$((PAGE + 1))
done

O parâmetro ?search=<termo> está disponível nos endpoints de lista que expõem conteúdo textual. Realiza correspondência de substring sem diferenciação de maiúsculas/minúsculas, aplicada após o escopo de papel. Combina com paginação e filtros de intervalo de datas.

Comprimento máximo: 256 caracteres. Requisições que excedem esse limite retornam 400 com code: "search_query_too_long".

Endpoints que suportam busca

Endpoint Campos buscados
GET /v1/forms/?search=<termo> Nome do form
GET /v1/checkins/?search=<termo> Nome do check-in
GET /v1/forms/{uuid}/responses/?search=<termo> Conteúdo das respostas
GET /v1/checkins/{uuid}/responses/?search=<termo> Conteúdo das respostas
GET /v1/kudos/?search=<termo> Mensagem do kudo
GET /v1/kudos/organization/?search=<termo> Mensagem do kudo
GET /v1/workflows/?search=<termo> Nome do workflow
GET /v1/followups/?search=<termo> Nome do check-in (alias depreciado de /v1/checkins/)
GET /v1/users/?search=<termo> Nome completo, e-mail 
curl "https://api.dailybot.com/v1/forms/?search=retro&page_size=10" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Intervalo de datas

Um filtro de intervalo de datas com reconhecimento de fuso horário está disponível em todo endpoint paginado.

Parâmetros canônicos

Parâmetro Formato Descrição
start_date YYYY-MM-DD Início inclusivo — 00:00:00 no fuso horário do chamador
end_date YYYY-MM-DD Fim inclusivo — 23:59:59.999999 no fuso horário do chamador

Comportamento de fuso horário: As datas são interpretadas no fuso horário do usuário autenticado (do perfil). Usa UTC como fallback se nenhum fuso horário estiver configurado.

Também aceitos (aliases legados)

Parâmetros legados Equivalente
date_start / date_end start_date / end_date
date_from / date_to start_date / end_date

Composição

Combina com ?search= e paginação:

curl "https://api.dailybot.com/v1/checkins/{uuid}/responses/?start_date=2026-07-01&end_date=2026-07-31&search=blocker&page_size=100" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Erro: Datas mal formadas retornam 400 com code: "invalid_date_range".

Filtros sem distinção de maiúsculas

Parâmetros de query com estilo enum aceitam qualquer capitalização. Por exemplo, ?filter=kudos_received, ?filter=KUDOS_RECEIVED e ?filter=Kudos_Received resolvem todos para kudos_received. Valores inválidos retornam 400 com code: "invalid_kudos_filter".

Versionamento

A API pública é versionada por prefixo de URL (/v1/). Mudanças aditivas (novos endpoints, novos campos opcionais, novos valores de enum com fallback) podem chegar a qualquer momento. Mudanças breaking chegam em um novo prefixo (/v2/) com uma janela mínima de sunset de 6 meses sobre a versão anterior. Veja /pt/developers/api-changelog.

Idempotência

Todo GET, PATCH, DELETE é idempotente por semântica HTTP — reenviá-los é seguro. Os POST que criam um recurso, no caso geral, não são idempotentes; um retry ingênuo após uma falha de rede pode criar recursos duplicados. Ao fazer retry após um 5xx ou erro de rede, primeiro releia o recurso pela sua chave natural (e-mail, nome, id externo) e só re-crie se a leitura retornar 404. A política de retry vive em /pt/developers/errors#retry-policy.

A API do Plan (Beta) é a exceção: suas criações aceitam o header Idempotency-Key, então um retry retorna o primeiro resultado em vez de criar um duplicado.

null vs. ausente

Um campo definido como null significa explicitamente “este atributo não tem valor”. Um campo ausente da resposta significa “o chamador não tem permissão de vê-lo” ou “o campo não foi solicitado via include-flag”. Não os trate como iguais.