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

Envio directo de SMS

Envia SMS para números de telefone arbitrários — não precisam de estar registados na base de dados. Útil para campanhas, lembretes ou comunicações a destinatários externos.

Quando o pedido contém mais de um número, o envio é feito numa única requisição ao provider (Bulkgate promotional). Com um único número, é usado o envio transactional individual.

Resumo

Item	Valor
Endpoint	`POST /v1/notification/send/sms`
Autenticação	Bearer token
Canal	SMS (telefone angolano válido: 9 dígitos, começa por 9)

URLs: Sandbox — https://integration.met-care.com/sandbox/v1/notification/send/sms · Produção — https://integration.met-care.com/v1/notification/send/sms

Corpo da requisição (body)

Campo	Tipo	Obrigatório	Descrição
`phones`	array de string	Sim	Lista de números angolanos. Aceita formatos `"912345678"`, `"+244912345678"` ou `"244912345678"`.
`title`	string	Sim	Título do SMS.
`message`	string	Sim	Corpo da mensagem.

Validação de telefones: cada número é validado (9 dígitos, começa por 9, prefixo +244/244 opcional). Números inválidos são rejeitados sem impedir o envio dos válidos. Se nenhum for válido, devolve erro 400.

Resposta

Campos de data:

Campo	Tipo	Descrição
`phones_accepted`	int	Quantidade de números válidos enviados para a fila.
`phones_rejected`	int	Quantidade de números que falharam a validação.
`rejected_numbers`	array de string	Lista dos números rejeitados (só aparece quando há rejeições).

Sucesso (200):

{
  "data": {
    "phones_accepted": 3,
    "phones_rejected": 1,
    "rejected_numbers": ["+244800000000"]
  },
  "meta": {
    "message": "SMS queued for delivery"
  }
}

Erro (400):

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "no valid phone numbers provided"
  }
}

Código	Descrição
200	SMS colocado na fila para envio
400	Validação do body (`VALIDATION_ERROR`) ou nenhum número válido (`BAD_REQUEST`)
401	Token em falta ou inválido

Exemplos de requisição

Um número (transactional):

{
  "phones": ["912345678"],
  "title": "Confirmação",
  "message": "O seu código de verificação é 1234."
}

Múltiplos números (promotional — uma única requisição ao provider):

{
  "phones": ["+244912345678", "923456789", "244931234567"],
  "title": "Promoção Met-Care",
  "message": "Ganhe 50% de desconto no Plano Premium até 30 de Abril."
}

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 sendDirectSMS(phones, title, message) {
  const response = await fetch(`${BASE_URL}/notification/send/sms`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ phones, title, message })
  });
  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.error?.message || response.statusText);
  }
  return response.json();
}

await sendDirectSMS(
  ['+244912345678', '923456789'],
  'Promoção Met-Care',
  'Ganhe 50% de desconto no Plano Premium.'
);

PHP:

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

function sendDirectSMS($baseUrl, $apiToken, array $phones, $title, $message) {
    $ch = curl_init($baseUrl . '/notification/send/sms');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiToken,
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'phones' => $phones,
            'title' => $title,
            'message' => $message
        ])
    ]);
    $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;
}

sendDirectSMS($baseUrl, $apiToken,
    ['+244912345678', '923456789'],
    'Promoção Met-Care',
    'Ganhe 50% de desconto no Plano Premium.'
);

Python:

import requests

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

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

send_direct_sms(
    ['+244912345678', '923456789'],
    'Promoção Met-Care',
    'Ganhe 50% de desconto no Plano Premium.'
)

SMS de boas-vindas

Envia uma mensagem de boas-vindas Met-Care para números arbitrários. Segue a mesma lógica do envio directo de SMS (validação de telefones, transactional para um número, promotional para múltiplos), mas não requer título nem mensagem — o conteúdo é fixo.

Resumo

Item	Valor
Endpoint	`POST /v1/notification/send/sms/welcome`
Autenticação	Bearer token
Canal	SMS (telefone angolano válido: 9 dígitos, começa por 9)

URLs: Sandbox — https://integration.met-care.com/sandbox/v1/notification/send/sms/welcome · Produção — https://integration.met-care.com/v1/notification/send/sms/welcome

Corpo da requisição (body)

Campo	Tipo	Obrigatório	Descrição
`phones`	array de string	Sim	Lista de números angolanos. Aceita formatos `"912345678"`, `"+244912345678"` ou `"244912345678"`.

Mensagem enviada:

Bem-vindo à Met-Care

Olá! Seja bem-vindo à Met-Care, o seu parceiro de saúde em Angola. Estamos aqui para cuidar de si e da sua família. Para mais informações, visite met-care.com.

Resposta

Campos de data:

Campo	Tipo	Descrição
`phones_accepted`	int	Quantidade de números válidos enviados para a fila.
`phones_rejected`	int	Quantidade de números que falharam a validação.
`rejected_numbers`	array de string	Lista dos números rejeitados (só aparece quando há rejeições).

Sucesso (200):

{
  "data": {
    "phones_accepted": 2,
    "phones_rejected": 0
  },
  "meta": {
    "message": "Welcome SMS queued for delivery"
  }
}

Erro (400):

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "no valid phone numbers provided"
  }
}

Código	Descrição
200	SMS de boas-vindas colocado na fila para envio
400	Validação do body (`VALIDATION_ERROR`) ou nenhum número válido (`BAD_REQUEST`)
401	Token em falta ou inválido

Exemplos de requisição

Um número:

{
  "phones": ["912345678"]
}

Múltiplos números:

{
  "phones": ["+244912345678", "923456789", "244931234567"]
}

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 sendWelcomeSMS(phones) {
  const response = await fetch(`${BASE_URL}/notification/send/sms/welcome`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ phones })
  });
  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.error?.message || response.statusText);
  }
  return response.json();
}

await sendWelcomeSMS(['+244912345678', '923456789']);

PHP:

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

function sendWelcomeSMS($baseUrl, $apiToken, array $phones) {
    $ch = curl_init($baseUrl . '/notification/send/sms/welcome');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiToken,
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode(['phones' => $phones])
    ]);
    $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;
}

sendWelcomeSMS($baseUrl, $apiToken, ['+244912345678', '923456789']);

Python:

import requests

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

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

send_welcome_sms(['+244912345678', '923456789'])

Listagem de notificações

Permite consultar as notificações já registadas na base de dados (uma entrada por destinatário/canal), com paginação por cursor.

Método: GET /v1/notification
Headers: Authorization: Bearer YOUR_TOKEN

Query params

Param	Tipo	Obrigatório	Descrição
`limit`	int	Não	Número máximo de registos por página. Padrão `100`. Min `1`, máx `500`.
`cursor`	string	Não	Cursor opaco devolvido em `meta.next_cursor` da resposta anterior.
`updated_since`	string	Não	Filtra notificações com `updated_at` >= valor informado (formato RFC3339).

Validação de limit: se não for inteiro entre 1 e 500, devolve 400 com code = VALIDATION_ERROR.
Validação de updated_since: deve estar em formato RFC3339, por ex.: 2026-01-01T00:00:00Z.

Estrutura de resposta

Campo	Tipo	Descrição
`data`	array de object	Lista de notificações.
`meta`	object	Metadados de paginação.
`meta.limit`	int	Limite usado na consulta.
`meta.has_more`	bool	Indica se existe uma próxima página.
`meta.next_cursor`	string \| null	Cursor a usar na próxima requisição (se existir).
`links`	object	Links de navegação (`self`, `next`).

Cada item em data tem o formato:

{
  "id": "NOTIFICATION_ID",
  "title": "Lembrete de renovação",
  "message": "A sua subscrição renova em 5 dias.",
  "type": "reminder",
  "status": "sent",
  "priority": "normal",
  "channels": ["email", "sms"]
}

status possíveis: pending, sent, failed, scheduled.

Exemplo de resposta

{
  "data": [
    {
      "id": "8d2e6f1a-8f6a-4a4e-9b1c-123456789abc",
      "title": "Lembrete de renovação",
      "message": "A sua subscrição renova em 5 dias.",
      "type": "reminder",
      "status": "sent",
      "priority": "normal",
      "channels": ["email", "sms"]
    }
  ],
  "meta": {
    "limit": 100,
    "has_more": true,
    "next_cursor": "opaque-cursor-value"
  },
  "links": {
    "self": "https://integration.met-care.com/v1/notification?limit=100",
    "next": "https://integration.met-care.com/v1/notification?cursor=opaque-cursor-value&limit=100"
  }
}

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.