URL base
https://api.zeepnotti.example/v1TBD - o domínio de produção ainda não foi definido; substitua este placeholder quando ele for. Todos os endpoints abaixo são relativos a esta base, incluindo o prefixo /v1 - atualmente existe apenas uma versão da API.
Autenticação
O Notti tem três formas de autenticar uma requisição. Qual delas vale depende do endpoint - a maioria das rotas aceita exatamente uma, algumas aceitam uma de duas:
| Método de autenticação | Header / mecanismo | Usado para |
|---|---|---|
| Chave REST | Authorization: Bearer rk_... | Chamadas servidor-a-servidor: Notifications, Templates, Segments, Webhooks |
| Chave de cliente | Authorization: Bearer ck_... | Apenas chamadas voltadas ao dispositivo: registro de dispositivo (Devices) |
| Sessão de admin | Cookie de sessão (POST /v1/auth/login) | Gerenciamento exclusivo do painel: Apps |
- Devices é o único grupo de rotas que aceita uma chave REST ou uma chave de cliente - a chave de cliente foi feita para ir dentro de um cliente mobile/web, por isso seu escopo é registrar e atualizar o dispositivo desse próprio cliente.
- Notifications, Templates, Segments, Webhooks aceitam uma sessão de admin ou uma chave REST - use a chave REST em qualquer integração server-side; o caminho por sessão existe para o próprio painel.
- Apps (criar um App, rotacionar suas chaves) aceita apenas sessão de admin. Não existe caminho por chave REST para criar ou modificar um App - as chaves autenticam como um App, elas não gerenciam Apps.
Os dois tipos de chave são gerados por App (rk_ + 32 bytes hex para REST, ck_ + 32 bytes hex para cliente) e exibidos por completo exatamente uma vez, na criação ou na rotação. O Notti armazena apenas um hash - se você perder uma chave, rotacione-a; não é possível recuperar o valor original. Veja a Referência da API de Apps e Primeiros passos com o Notti para as chamadas de criação e rotação.
Uma credencial inválida, ausente ou expirada retorna 401:
{ "error": { "code": "unauthorized", "message": "missing or invalid API key" } }Formato de requisição / resposta
Os corpos das requisições são JSON, enviados com Content-Type: application/json.
As respostas de sucesso retornam o recurso diretamente - não existe envelope data:
{ "id": "ntf_...", "status": "pending", "app_id": "app_..." }Os erros sempre vêm como um objeto JSON sob a chave error, com um code estável e uma message legível por humanos:
{ "error": { "code": "invalid_target", "message": "target_type and target_value are required" } }Valores de code comuns que você verá nos endpoints: unauthorized / unauthenticated (401), forbidden (403), idempotency_conflict (409), invalid_target / invalid_content / invalid_body / not_scheduled (422), internal_error (500). Os códigos exatos estão documentados por endpoint na página de referência de cada grupo de handlers.