Notificações

Envio de notificações aos utilizadores da MetCare por email, SMS e push. O destino pode ser um utilizador, todos os utilizadores de um plano ou todos (broadcast).

---

Resumo

Item	Valor
Endpoint	POST /v1/notification/send
Autenticação	Bearer token
Canais	sms, email, push

URLs: Sandbox — https://integration.met-care.com/sandbox/v1/notification/send · Produção — https://integration.met-care.com/v1/notification/send
Token: solicitar em developers@met-care.com. Exemplos com dados angolanos (Kz, português).

---

Referência do endpoint

Método: POST /v1/notification/send
Headers: Authorization: Bearer YOUR_TOKEN · Content-Type: application/json

Corpo da requisição (body)

Campo	Tipo	Obrigatório	Descrição
user_id	integer	Não	Enviar apenas a este utilizador. Não usar com plan_id.
plan_id	string	Não	Enviar a todos os utilizadores do plano. Não usar com user_id.
title	string	Sim	Título da notificação.
message	string	Sim	Corpo da mensagem.
type	string	Sim	Tipo (ver valores abaixo).
priority	string	Sim	low, normal, high.
channels	array	Sim	Ex.: ["email", "sms"], ["push"].
metadata	object	Não	Dados extras (ex.: {"campaign": "promo-2026"}).
scheduled_at	string (RFC3339)	Não	Data/hora agendada.

Destino (target): só user_id → um utilizador; só plan_id → plano; nenhum → todos. Não enviar user_id e plan_id juntos.

Valores aceites

type: promotion, alert, plan, update, reminder, transaction, marketing, system

priority: low, normal, high

channels: sms (telefone angolano válido), email, push (requer token FCM).

---

Resposta

Sucesso (200)

Resposta no mesmo modelo dos outros endpoints: data com o payload aceite e meta com informação adicional.

{
  "data": {
    "user_id": 12345,
    "title": "Lembrete de renovação",
    "message": "A sua subscrição renova em 5 dias.",
    "type": "reminder",
    "priority": "normal",
    "channels": ["email", "sms"],
    "plan_id": null,
    "metadata": null,
    "scheduled_at": null
  },
  "meta": {
    "message": "Notification sent"
  }
}

Erro (400, 401, 403, 500)

Validação (400):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "descrição do erro"
  }
}

Requisição inválida / erro do serviço (400):

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "descrição do erro"
  }
}

Código	Descrição
400	Validação do body (VALIDATION_ERROR) ou erro ao processar (BAD_REQUEST)
401	Token em falta ou inválido
403	Não autorizado
500	Erro interno do servidor

---

Exemplos de requisição

Um utilizador (email + SMS):

{
  "user_id": 12345,
  "title": "Pagamento recebido",
  "message": "O seu pagamento de 29.990 Kz foi confirmado.",
  "type": "transaction",
  "priority": "normal",
  "channels": ["email", "sms"]
}

Todos de um plano (push + email):

{
  "plan_id": "plan-premium-001",
  "title": "Atualização do plano",
  "message": "O Plano Premium tem novas vantagens disponíveis.",
  "type": "plan",
  "priority": "normal",
  "channels": ["push", "email"]
}

Todos (broadcast):

{
  "title": "Manutenção programada",
  "message": "O sistema estará em manutenção no dia 25 de Janeiro, entre 02:00 e 04:00 (hora de Luanda).",
  "type": "system",
  "priority": "high",
  "channels": ["email", "push"]
}

---

Exemplos de código

BASE_URL: Produção — https://integration.met-care.com/v1 · Sandbox — https://integration.met-care.com/sandbox/v1

JavaScript

const BASE_URL = 'https://integration.met-care.com/v1';
const API_TOKEN = 'YOUR_TOKEN';

async function sendNotification(payload) {
  const response = await fetch(`${BASE_URL}/notification/send`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });
  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.error?.message || response.statusText);
  }
  return response.json();
}

await sendNotification({
  user_id: 12345,
  title: 'Lembrete',
  message: 'A sua subscrição renova em 5 dias.',
  type: 'reminder',
  priority: 'normal',
  channels: ['email', 'sms']
});

PHP

<?php
$baseUrl = 'https://integration.met-care.com/v1';
$apiToken = 'YOUR_TOKEN';

function sendNotification($baseUrl, $apiToken, array $payload) {
    $ch = curl_init($baseUrl . '/notification/send');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiToken,
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode($payload)
    ]);
    $response = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $data = json_decode($response, true);
    if ($code >= 400) throw new \RuntimeException($data['error']['message'] ?? 'Request failed');
    return $data;
}

sendNotification($baseUrl, $apiToken, [
    'user_id' => 12345,
    'title' => 'Lembrete',
    'message' => 'A sua subscrição renova em 5 dias.',
    'type' => 'reminder',
    'priority' => 'normal',
    'channels' => ['email', 'sms']
]);

Python

import requests

BASE_URL = 'https://integration.met-care.com/v1'
API_TOKEN = 'YOUR_TOKEN'

def send_notification(payload):
    response = requests.post(
        f'{BASE_URL}/notification/send',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Content-Type': 'application/json'
        },
        json=payload
    )
    response.raise_for_status()
    return response.json()

send_notification({
    'user_id': 12345,
    'title': 'Lembrete',
    'message': 'A sua subscrição renova em 5 dias.',
    'type': 'reminder',
    'priority': 'normal',
    'channels': ['email', 'sms']
})

---

Eventos de webhook

Quando uma notificação é processada, podem ser emitidos eventos de webhook. Lista completa em Webhooks — Lista completa de eventos.

Exemplos: notification.created, notification.completed, notification.failed, notification.channel.email.sent, notification.channel.sms.sent, notification.channel.push.sent, etc.

---

Suporte

Email: developers@met-care.com — tokens, dúvidas sobre canais ou limites de envio.