API для разработчиков

Fridgie даёт данные семьи внешним сервисам через REST API и вебхуки. Так работает импорт графиков вывоза мусора, так же можно подключить своё.

Доступ

Администратор семьи создаёт токен в «Ещё → Интеграции → Токены API» и выбирает права. Токен передаётся в заголовке Authorization: Bearer frg_…. Каждый токен можно отозвать отдельно. Лимит: 120 запросов в минуту на токен.

curl https://fridgie.app/api/v1/shopping/items \
  -H "Authorization: Bearer frg_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Milk", "quantity": "2"}'

Права

household:readcalendar:readcalendar:writeshopping:readshopping:writetasks:readtasks:writepoints:readpoints:write

Запросы

Все адреса начинаются с /api/v1. Полное описание схем в формате OpenAPI 3.1: /api/v1/openapi.json

get /household	The token's household, members and scopes household:read
get /events	Calendar occurrences with repeats expanded (default: next 7 days, at most 92) calendar:read
get /shopping/items	Shopping list items shopping:read
post /shopping/items	Add an item; the category is picked like in the app unless given shopping:write
patch /shopping/items/{id}	Check or uncheck an item shopping:write
delete /shopping/items/{id}	Remove an item shopping:write
get /shopping/categories	Shopping tabs and categories shopping:read
get /tasks	Chore occurrences: overdue, upcoming and recently done tasks:read
post /tasks/{id}/complete	Mark a chore done (default today); awards points to a child assignee tasks:write
get /points	Children's star balances points:read
post /points	Give or take stars points:write
get /weather	Forecast for the family's place (MET Norway): now, next 24 hours, 7 days. 404 no_location until the place is set household:read
put /events/sync	Keep a source's events in sync: creates new, updates changed, deletes ones no longer sent within [from, to] calendar:write

Вебхуки

Fridgie отправляет POST с JSON {id, type, createdAt, householdId, data} на адрес, указанный в «Интеграциях». Ответ 2xx считается доставкой; иначе повторы через 1 мин, 5 мин, 30 мин, 2 ч и 12 ч. После 20 неудач подряд вебхук выключается.

События

shopping.item.addedshopping.item.checkedshopping.item.removedtask.completedpoints.changedevent.createdevent.updatedevent.deleted

Проверка подписи

Заголовок Fridgie-Signature: t=<время>,v1=<HMAC-SHA256 секрета от "<t>.<тело запроса>">. Проверяйте по сырому телу и отклоняйте запросы старше 5 минут.

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

// body: the raw request body (string), before JSON.parse
function verify(secret, header, body) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  return v1?.length === 64 && timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

Ошибки

Ошибки возвращаются как {"error": {"code", "message"}}: 400 неверный запрос, 401 нет или отозван токен, 402 нет в тарифе, 403 не хватает прав, 404 не найдено (в том числе чужие данные), 429 превышен лимит.

Готовые интеграции

fridgie-waste-nkom: импорт графиков вывоза мусора с nkom.lt, держит их в календаре семьи как напоминания.