Notificações push

Chame a cada abertura do app. É idempotente por `(app, token)`: reabrir o aplicativo atualiza a linha existente em vez de duplicar o aparelho na sua base.

Ambiente: vem da credencial. Uma chave ccx_test_* grava o aparelho no sandbox, e ele só recebe pushes de sandbox — nunca de uma campanha real.

Web Push exige `p256dh` e `auth` (as keys da subscription do navegador). Sem elas não há como cifrar o payload e o navegador descarta a notificação, então o registro é recusado com 400.

Campos de identificação (externalId, userName, userEmail) são o que faz a busca do compositor achar a pessoa. Mande-os no primeiro registro; nas chamadas seguintes eles podem ser omitidos sem apagar o que já está gravado.

Permissão: push:send.

Chame quando o usuário desligar as notificações no aparelho. O aparelho sai de todos os envios seguintes e passa a contar no seu KPI de opt-out.

A linha NÃO é apagada — quem saiu precisa ser contável. Um novo POST /v2/push/tokens com optedIn: true traz o aparelho de volta.

Permissão: push:send.

Chame quando o usuário TOCAR a notificação. Esta é a única origem da taxa de abertura do canal: nem a APNs nem o FCM contam abertura por você.

O id é o do dispatch, entregue ao app no payload da notificação.

Só a PRIMEIRA abertura conta. Reabrir a mesma notificação devolve counted: false — não é erro, é a proteção contra uma taxa de abertura acima de 100%.

Não afeta cobrança. O que se cobra é o aceite do provedor, não a abertura — ninguém consegue provar que a pessoa viu, e cobrar por isso seria cobrar pela sorte.

Permissão: push:send.

Ordem decrescente de criação. limit default 50, teto 200.

A lista é do ambiente da credencial: uma chave ccx_test_* vê os envios de sandbox e nada mais. Para ler a produção, use uma ccx_live_*.

Paginação por cursor, e não por `skip` — aqui push difere de SMS e e-mail de propósito. Um envio transacional grava uma linha por mensagem, então esta tabela cresce como uma tabela de mensagens; com skip o Mongo caminha por todos os registros pulados e a página 200 rasteja, enquanto o cursor custa o mesmo na primeira e na milésima.

Mande de volta o nextCursor que veio na resposta; quando ele vier ausente, acabou.

Filtros: status, origin (composer = painel, api, automation), from e to por data de criação (ISO-8601). status e origin aceitam repetição (?status=sent&status=sending).

Permissão: push:read.

Cria o envio e materializa uma linha por aparelho na fila. A resposta chega assim que a fila é montada — não depois de a APNs/FCM aceitar: um disparo para 100 mil aparelhos não cabe num request.

Acompanhe pelo GET /v2/push/messages/{id}, que traz metrics com entregues, abertos e falhas.

`Idempotency-Key` é obrigatória. Sem ela o envio para com 400. Não derivamos uma do corpo: duas campanhas idênticas de propósito não podem virar uma.

Público: mande segment ou tokenIds, nunca os dois. segment aceita all_opt_in (toda a base com permissão) ou o id de um segmento salvo de contatos (seg_…).

Ambiente: vem da credencial. Uma chave ccx_test_* só alcança aparelhos de sandbox, debita a carteira de sandbox e não toca APNs/FCM de verdade.

Janela silenciosa: se o horário cair na janela configurada, o envio é ADIADO e a resposta traz quietDeferredTo com o horário real de saída.

Preço: cobrado por aparelho no ACEITE do provedor, pela tabela publicada. simple só texto, rich com imagem ou botão, silent data-only. Use POST /v2/push/preview para saber o custo antes.

Permissão: push:send.

Devolve o envio do AMBIENTE da credencial: uma chave ccx_test_* nunca vê disparo de produção, e vice-versa.

metrics.reach é quantos aparelhos entraram na fila; delivered é quantos o provedor ACEITOU; opened só sobe quando o seu app chama POST /v2/push/dispatches/{id}/opened.

breakdown quebra entregues/abertos/falhas por plataforma.

Espelho do POST /v2/sms/preview: diz quantos aparelhos o público alcança e quanto o envio custa, sem criar nada e sem debitar.

rateKind é a modalidade deduzida do conteúdo — rich quando há imagem ou botão, senão simple. Ela decide a linha da tabela de preço.

charged: false significa que a instalação não tem carteira: o envio sairia sem debitar.