API de acompanhamento do bebê: registre pelo seu código

A mamadeira está morna e o bebê finalmente se aninhou no seu ombro. O celular com o app de acompanhamento, claro, está carregando no outro quarto. Enquanto isso, tem um Raspberry Pi zumbindo no armário do corredor, e uma parte teimosa do seu cérebro já está pensando: eu podia só mandar um POST.

Pode mesmo. O nappi tem uma API REST pública que qualquer família com o nappi Premium pode usar com os próprios dados. Você cria uma chave pessoal, envia em cada requisição, e seus scripts conseguem registrar fraldas, mamadeiras, amamentação, extração, sono, atividades e crescimento, iniciar e parar cronômetros e ler os registros mais recentes. A especificação completa é pública em https://api.nappi.app/v1/openapi.json.

O nappi tem uma API?

Tem. A URL base é https://api.nappi.app/v1, e cada chamada é HTTPS comum, com JSON na ida e na volta.

A API é descrita por um documento OpenAPI 3.1, o formato padrão e independente de linguagem para descrever APIs HTTP.¹ Aponte um gerador de código ou o Postman para a especificação e você ganha um cliente funcionando, sem adivinhar nome de campo.

Se você prefere clicar a ler JSON, a referência interativa da API mostra cada endpoint com exemplos. Não precisa de conta para ler. Entrar na conta só lista suas chaves no painel de testes, para você mandar requisições de verdade direto da página.

A API ainda está em beta, então o formato das requisições pode mudar conforme a gente vê como as famílias usam. A referência é gerada a partir da API em produção, por isso sempre bate com o que está no ar.

Como conseguir uma chave da API do nappi?

As chaves são criadas na web, não no app:

1. Entre em nappi.app/app/connections, de preferência no computador.
2. Dê à chave um nome que você vá reconhecer depois ("Pi do quarto", "painel da cozinha") e escolha quanto tempo ela dura: 30 dias, 90 dias ou 1 ano.
3. Copie. Ela começa com nappi_ e só aparece uma vez.

Toda requisição envia a chave no cabeçalho Authorization como Bearer nappi_YOUR_KEY, o formato de token bearer definido na RFC 6750.² Quem tem um token bearer em mãos consegue usá-lo, então trate o seu como uma senha.

Algumas regras antes de construir qualquer coisa:

• A API faz parte do nappi Premium. Uma assinatura cobre a casa inteira, e as chaves param de funcionar enquanto a família estiver sem Premium.
• Só cuidadores podem criar chaves. Observadores e convidados, não.
• Você pode ter até 10 chaves ao mesmo tempo.
• A gente manda um e-mail uma semana antes de vencer uma chave que você está usando.

O que a API do nappi faz?

Oito endpoints, todos restritos aos bebês da sua casa:

Método	Caminho	O que faz
GET	/v1/babies	Lista seus bebês e os IDs deles
GET	/v1/babies/{babyId}/entries/latest	Registro mais recente de cada tipo
GET	/v1/babies/{babyId}/entries/latest/{type}	Registro mais recente de um tipo
POST	/v1/babies/{babyId}/entries	Salva um registro já terminado
GET	/v1/babies/{babyId}/timers	Cronômetros de sono, amamentação e extração rodando agora
GET	/v1/babies/{babyId}/status	Cronômetros e registros recentes numa leitura só
POST	/v1/babies/{babyId}/timers/{timerType}/start	Inicia um cronômetro
POST	/v1/babies/{babyId}/timers/{timerType}/stop	Para um cronômetro e salva o registro

O que falta também conta. Ainda não dá para registrar remédios nem sólidos, embora você consiga ler o mais recente de cada um. E a API só devolve o registro mais novo de cada tipo, não o histórico inteiro, sem como editar ou apagar registros.

Seu primeiro registro com curl

Comece descobrindo o ID do seu bebê:

curl https://api.nappi.app/v1/babies \
  -H "Authorization: Bearer nappi_YOUR_KEY"

Você recebe uma lista:

[
  {
    "id": "BABY_ID",
    "name": "Phoebe",
    "birth_date": "2026-05-02",
    "timezone": "America/New_York"
  }
]

Depois registre uma fralda molhada:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/entries \
  -H "Authorization: Bearer nappi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type": "diaper", "diaper_type": "wet"}'

Um 201 quer dizer que foi registrado, e o corpo da resposta mostra o que foi criado:

{ "id": "ENTRY_ID", "type": "diaper", "duplicate": false }

O cabeçalho Idempotency-Key é opcional. Mesmo assim, a gente nunca deixaria esse cabeçalho de fora de uma automação. Se a conexão cair e o script tentar de novo com a mesma chave, a segunda requisição devolve 200 com "duplicate": true e nada novo é gravado, então você não fica com duas fraldas.

Um registro feito pela API é um registro comum do nappi. Todo mundo da casa vê no app, e ele fica no seu nome, como a pessoa que criou a chave.

Os horários seguem a ISO 8601 com o deslocamento em relação ao UTC, como 2026-10-21T14:30:00-04:00, e o padrão é o momento atual. As quantidades são em mililitros, a não ser que você envie "unit": "oz".

Quais tipos de registro dá para salvar?

POST /entries recebe um type e os campos que esse tipo pede:

type	Obrigatório	Opcional
diaper	diaper_type: wet, poo, mixed ou dry	time
potty	outcome: potty, accident ou sat_dry	time
bottle	mais nada	amount, unit (ml ou oz), bottle_type (como breast_milk ou formula), time
nursing	mais nada	side, left_minutes, right_minutes, duration_minutes, time
pumping	mais nada	amount, left_amount, right_amount, unit, duration_minutes, time
sleep	start_time, end_time	sleep_type (nap ou night)
activity	activity_type (como bath ou tummy_time)	duration_minutes, time
growth	mais nada	weight, weight_unit (kg ou lb), length, head, length_unit (cm ou in), time

Uma mamadeira de 4 onças de fórmula fica assim:

{ "type": "bottle", "amount": 4, "unit": "oz", "bottle_type": "formula" }

Se você não mandar sleep_type, o nappi decide entre soneca e noite pelo horário do dia do bebê, do mesmo jeito que o app. Para algo que ainda está acontecendo, como uma soneca em andamento, use um cronômetro.

Iniciar e parar o cronômetro de sono por um script

Os cronômetros são os mesmos compartilhados que a casa toda vê no app. Para começar uma soneca:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start \
  -H "Authorization: Bearer nappi_YOUR_KEY"

Parar salva o registro de sono, exatamente como parar no celular:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop \
  -H "Authorization: Bearer nappi_YOUR_KEY"

timerType pode ser sleep, nursing ou pumping. Iniciar um cronômetro que já está rodando não muda nada e devolve o cronômetro com "status": "already_running". Parar quando nada está rodando devolve 409 com o código timer_not_running, o que facilita montar um botão único que liga e desliga.

Funciona nos dois sentidos. GET /timers também traz cronômetros que alguém iniciou num celular, num relógio ou pela Alexa. Os de amamentação aceitam um side opcional, e com start_time você pode voltar o início em até 48 horas.

Um script pequeno: quanto tempo desde a última mamada

Este script de Node (Node 18 ou mais novo, sem pacotes) mostra há quanto tempo o bebê comeu pela última vez, contando mamadeiras e amamentação. Salve como last-feed.mjs e rode com node last-feed.mjs:

const KEY = "nappi_YOUR_KEY";
const BABY = "BABY_ID";

const res = await fetch(
  `https://api.nappi.app/v1/babies/${BABY}/status?types=bottle,nursing`,
  { headers: { Authorization: `Bearer ${KEY}` } },
);
if (!res.ok) throw new Error(`nappi returned ${res.status}`);
const { timers, latest } = await res.json();

const feeds = [latest.bottle, latest.nursing].filter(Boolean);
if (timers.some((t) => t.type === "nursing")) {
  console.log("Nursing right now");
} else if (feeds.length === 0) {
  console.log("No feeds logged yet");
} else {
  const last = Math.max(...feeds.map((f) => new Date(f.time).getTime()));
  const min = Math.round((Date.now() - last) / 60000);
  console.log(`Last feed ${Math.floor(min / 60)}h ${min % 60}m ago`);
}

Ligue isso a um cron e a uma tela de tinta eletrônica na geladeira, e ninguém precisa desbloquear o celular às 3 da manhã para descobrir quando foi a última mamadeira.

Consultar sem estourar o limite de requisições

Cada chave tem 12 leituras e 30 escritas por minuto. Passou disso, você recebe 429 Too Many Requests, com um cabeçalho Retry-After dizendo quantos segundos esperar.³⁴

Para um painel, consulte /status no máximo uma vez por minuto. As respostas trazem um ETag. Mande o ETag de volta como If-None-Match e você recebe 304 Not Modified, sem corpo, até alguma coisa mudar.⁴

Tem uma exceção. Enquanto um cronômetro está rodando, o tempo decorrido muda a cada segundo, então /status sempre devolve um 200 completo.

Atalhos do iPhone: registre uma mamadeira com um toque

Aqui nem precisa de computador. No app Atalhos, adicione a ação Obter Conteúdo do URL e configure assim:

• URL: https://api.nappi.app/v1/babies/BABY_ID/entries
• Método: POST
• Cabeçalhos: Authorization com o valor Bearer nappi_YOUR_KEY
• Pedir Corpo: JSON, com type em bottle, amount em 120 (como Número) e unit em ml

É ao trocar o método para POST que aparece o campo "Pedir Corpo", e JSON é uma das opções dele.⁵ Coloque o atalho na Tela de Início, ou adicione antes um passo "Pedir Entrada" para digitar a quantidade a cada vez.

O app do nappi já registra por voz com a Siri. Este caminho é para o que for sob medida, como um botão de um toque para "120 ml de fórmula" ou uma automação que roda quando o celular encosta numa etiqueta NFC colada no escorredor de mamadeiras.

Home Assistant: a integração ou comandos REST simples

Se o Home Assistant comanda a sua casa, comece pela integração. Ela é de código aberto, com licença MIT (nappi-app/nappi-home-assistant no GitHub), e está na loja padrão do HACS, é só buscar "nappi". Ela consulta /status uma vez a cada 2 minutos por bebê e entrega botões de registro, interruptores de cronômetro e sensores do último registro sem você mexer em YAML. Nosso guia do Home Assistant mostra a instalação passo a passo, além de algumas automações que valem a pena copiar.

Prefere YAML? A integração RESTful Command do Home Assistant chama a API direto, com seus próprios cabeçalhos e corpo JSON.⁶ Estes dois comandos iniciam e param uma soneca:

# secrets.yaml
nappi_auth: "Bearer nappi_YOUR_KEY"

# configuration.yaml
rest_command:
  nappi_sleep_start:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start"
    method: post
    headers:
      Authorization: !secret nappi_auth
  nappi_sleep_stop:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop"
    method: post
    headers:
      Authorization: !secret nappi_auth

Chame rest_command.nappi_sleep_start a partir de um botão ao lado do berço, e o cronômetro de soneca começa no celular de todo mundo da família. A página de casa inteligente lista as outras formas de conectar, incluindo Alexa e Google Home.

É seguro dar a um script acesso aos dados do meu bebê?

Nada consegue ler os dados da sua família pela API até você criar uma chave. Cada chave pertence a um cuidador de uma casa, e o nappi guarda só um hash SHA-256 dela. É por isso que você vê a chave uma vez e nunca mais.

Dá para revogar uma chave quando quiser em nappi.app/app/connections, ou no app em Configurações → Conexões → Casa inteligente. A chave também para de funcionar quando vence, ou se você sair da casa ou virar observador.

Uma chave registra e lê para a sua família do mesmo jeito que você no app, cronômetros incluídos. Ela não consegue mudar sua conta nem ver sua senha. Deixe a chave longe de repositórios públicos no Git e de capturas de tela, e revogue na hora se ela vazar.

Teste hoje à noite: crie uma chave de 30 dias, rode o curl do /babies e registre uma fralda de teste. Quando ela aparecer no celular do seu parceiro ou parceira, apague por lá, porque a API não apaga.

Perguntas frequentes

A API do nappi custa a mais?

Não tem cobrança separada, mas a API faz parte do nappi Premium. Uma assinatura cobre todo mundo da sua casa. Ler a documentação e a especificação OpenAPI é grátis para qualquer pessoa.

Dá para exportar todo o meu histórico pela API?

Não. A API devolve o registro mais recente de cada tipo e os cronômetros rodando. Para o histórico completo, use a exportação em CSV do app do nappi.

Funciona com gêmeos ou irmãos?

Funciona. GET /v1/babies devolve todos os bebês da sua casa, e cada uma das outras chamadas indica um bebê pelo ID. Rode o script uma vez por bebê.

Dá para registrar remédios pela API?

Ainda não. Você consegue ler o registro de remédio mais recente, mas registrar remédios ou sólidos não é possível, então continue usando o app para isso.