Status: Approved · v2 · SPEC-API-ENGAGEMENT-001

depends_on: SPEC-DOMAIN-FEED-001, SPEC-DOMAIN-NOTIFICATION-001, SPEC-DOMAIN-SHARE-001

used_by: IS-MVP-11.1, IS-MVP-11.2, IS-MVP-11.3, IS-MVP-11.4, IS-MVP-12.3

API de feed, notificações, push pago e cards

Conteúdo oficial e compartilhamento externo sem transformar o MVP em rede social de posts livres.

Princípios e padrões

• Base path /api/v1; JSON UTF-8; chaves em camelCase.
• Toda resposta usa ApiResponse<T> com ok, data|error e meta contendo requestId e timestamp.
• IDs são strings opacas; datas são ISO-8601 UTC; dinheiro é inteiro em centavos com moeda BRL.
• Listas usam page e pageSize no MVP; default 20, máximo 100; metadados ficam em meta.pagination.
• Endpoints públicos usam DTOs públicos específicos; entidades internas, memberships, saldos e dados privados nunca vazam.
• Erros de domínio são estáveis e acionáveis; stack traces e detalhes internos não são retornados.
• Alterações sensíveis usam Idempotency-Key, confirmação recente quando necessário e audit log.
• Uploads usam fluxo presigned; o backend valida propósito, MIME, tamanho e ownership antes de confirmar o asset.

Endpoints

Método	Rota	Acesso	Request	Response	Regras principais
GET	/feed	Público/auth opcional	FeedQuery	FeedResponse	Ordenação e reasons.
POST	/feed/posts	Entity permission	CreateFeedPostRequest	FeedPostResponse	Official/template only.
PATCH	/feed/posts/:postId	Entity permission	UpdateFeedPostRequest	FeedPostResponse	Draft/published rules.
POST	/feed/suggestions/:id/approve	Entity permission	ApproveSuggestionRequest	FeedPostResponse	Publica/agenda conforme escolha.
POST	/feed/suggestions/:id/reject	Entity permission	RejectSuggestionRequest	OperationResponse	Motivo opcional.
POST	/feed/posts/:postId/hide	Autenticado	—	OperationResponse	Preferência pessoal.
POST	/feed/mutes	Autenticado	CreateMuteRequest	MuteResponse	7/30/forever.
GET	/notifications	Autenticado	NotificationQuery	NotificationsResponse	Personal/management.
POST	/notifications/read	Autenticado	ReadNotificationsRequest	OperationResponse	Batch.
POST	/notifications/:id/archive	Autenticado	—	OperationResponse	Own.
PATCH	/notification-settings	Autenticado	UpdateNotificationSettingsRequest	NotificationSettingsResponse	Categorias/canais.
POST	/paid-push-campaigns	Entity permission	CreatePaidPushCampaignRequest	PaidPushCampaignResponse	Preview de audience/custo.
POST	/paid-push-campaigns/:id/confirm	Entity permission	ConfirmPaidPushCampaignRequest	PaidPushCampaignResponse	Consome créditos.
POST	/shareable-cards	Contextual	CreateShareableCardRequest	ShareableCardResponse	Template/format/data snapshot.
POST	/shareable-cards/:id/generate	Contextual	GenerateShareableCardRequest	GeneratedCardResponse	Client-first; server future.
GET	/shareable-cards/templates	Público	TemplateQuery	TemplatesResponse	Templates MVP controlados.

Autenticação e autorização

• Feed público pode ser lido anônimo; personalização/mute/hide exige auth.
• Posts só por manager permission; platform cards por system.
• Notifications sempre do próprio usuário e permissions atuais.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
POST_TYPE_NOT_ALLOWED	422	Post livre/reaction/comment	Não oferecer UI.
SUGGESTION_ALREADY_RESOLVED	409	Approve/reject concorrente	Atualizar.
MUTE_INVALID_DURATION	422	Duração inválida	Usar opções.
NOTIFICATION_ACTION_EXPIRED	410	CTA perdeu validade	Abrir contexto.
INSUFFICIENT_CREDITS	409	Push pago	Mostrar saldo.
SHARE_CARD_PRIVACY_BLOCKED	403	DTO contém dado privado	Remover campo.

Idempotência e concorrência

• Approve suggestion, paid push confirm e generation request são idempotentes.
• Hide/mute/read são naturally idempotent.

Auditoria e efeitos colaterais

• Post status/approvals e paid push auditados.
• Notification actions delegam ao domínio e não duplicam regra.
• Share card registra tipo/formato/target, não conteúdo privado.

Exemplos

feedItem

{
  "id": "post_001",
  "type": "match_result",
  "source": "entity_official",
  "publishedAt": "2026-07-12T17:00:00.000Z",
  "reason": {
    "code": "CHEERED_TEAM",
    "label": "Você torce para este time."
  }
}

shareCard

{
  "id": "card_001",
  "type": "match_result",
  "format": "story",
  "status": "preview",
  "targetUrl": "https://raizfc.com.br/matches/match_001"
}

Mocks

• Ordering deterministic por seed/time.
• Mute/hide/read stateful.
• Preview de share cards usa tokens e assets fixtures.

Testes obrigatórios

• No user posts/reactions/comments.
• Reason ordering.
• Mute durations.
• Action expiry.
• Paid push debit idempotent.
• Privacy card.

Critérios de aceite

• Feed tem conteúdo e estados acordados.
• Notifications personal/management.
• Fallback link/text sempre possível.

Machine summary

spec: SPEC-API-ENGAGEMENT-001
api_group: API de feed, notificações, push pago e cards
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents