{"openapi":"3.0.0","info":{"title":"notify API","version":"1.0.0","description":"API server-to-server do notify (SaaS de notificações). Autenticação: API key do app via Authorization: Bearer."},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key do app no formato nk_<accountId>_<appId>_<secret>"}},"schemas":{"Ok":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]},"UpsertUserInput":{"type":"object","properties":{"email":{"type":"string","nullable":true,"format":"email"},"phone":{"type":"string","nullable":true,"minLength":5,"maxLength":20}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"RegisterPushTokenInput":{"type":"object","properties":{"platform":{"type":"string","maxLength":20}}},"SendEventResult":{"type":"object","properties":{"eventId":{"type":"string"},"recipientCount":{"type":"number"}},"required":["eventId","recipientCount"]},"SendEventInput":{"type":"object","properties":{"groupKey":{"type":"string"},"groupId":{"type":"string"},"data":{"type":"object","additionalProperties":{"type":"string"},"description":"replacement global do template"},"recipients":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","minLength":1},"data":{"type":"object","additionalProperties":{"type":"string"},"description":"override por destinatário (merge sobre o global)"}},"required":["userId"]},"minItems":1,"maxItems":1000},"channels":{"type":"array","items":{"type":"string","enum":["push","email","inapp"]},"description":"Se informado, restringe os canais ativos do grupo a esse subconjunto"}},"required":["recipients"]},"InboxItem":{"type":"object","properties":{"itemId":{"type":"string"},"groupKey":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"data":{"type":"object","additionalProperties":{"type":"string"}},"readAt":{"type":"string","nullable":true},"createdAt":{"type":"string","nullable":true}},"required":["itemId","groupKey","title","body","data","readAt","createdAt"]},"InboxPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InboxItem"}},"unreadCount":{"type":"number"},"nextCursor":{"type":"string","nullable":true}},"required":["items","unreadCount","nextCursor"]},"ReadAllResult":{"type":"object","properties":{"marked":{"type":"number"}},"required":["marked"]}},"parameters":{}},"paths":{"/v1/users/{userId}":{"put":{"security":[{"apiKey":[]}],"summary":"Cria ou atualiza um user e seus contatos","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertUserInput"}}}},"responses":{"200":{"description":"User criado/atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}}}},"delete":{"security":[{"apiKey":[]}],"summary":"Remove o user, seus devices e inbox","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Removido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}}}}},"/v1/users/{userId}/push-tokens/{token}":{"put":{"security":[{"apiKey":[]}],"summary":"Registra/atualiza um push token (FCM) do user — multi-device","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"token","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPushTokenInput"}}}},"responses":{"200":{"description":"Token registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"404":{"description":"User não existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"apiKey":[]}],"summary":"Remove um push token do user","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Removido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}}}}},"/v1/events":{"post":{"security":[{"apiKey":[]}],"summary":"Dispara uma notificação (grupo + destinatários + replacement)","description":"Cria o event e responde 202 imediatamente; o envio é assíncrono. Acompanhe a trilha pelo painel. Semântica at-least-once.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEventInput"}}}},"responses":{"202":{"description":"Disparo aceito","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEventResult"}}}},"404":{"description":"Grupo não encontrado/inativo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/users/{userId}/inbox":{"get":{"security":[{"apiKey":[]}],"summary":"Feed in-app do user (mais recentes primeiro)","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"},{"schema":{"type":"boolean","nullable":true,"default":false},"required":false,"name":"unreadOnly","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"itemId do último item da página anterior"},"required":false,"description":"itemId do último item da página anterior","name":"cursor","in":"query"}],"responses":{"200":{"description":"Inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxPage"}}}}}}},"/v1/users/{userId}/inbox/{itemId}/read":{"post":{"security":[{"apiKey":[]}],"summary":"Marca um item como lido","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"itemId","in":"path"}],"responses":{"200":{"description":"Marcado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/users/{userId}/inbox/read-all":{"post":{"security":[{"apiKey":[]}],"summary":"Marca todos os itens não lidos como lidos","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Quantidade marcada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadAllResult"}}}}}}}}}