Clientes

Consulta de clientes (utilizadores) da MetCare. Listagem com paginação por cursor e filtro por data de atualização; consulta individual por ID.

---

Resumo

Item	Valor
Endpoints	GET /v1/clients · GET /v1/clients/:id
Autenticação	Bearer token
Paginação	Cursor-based (limit, cursor)
Filtro	updated_since (RFC3339)

URLs: Sandbox — https://integration.met-care.com/sandbox/v1/clients · Produção — https://integration.met-care.com/v1/clients
Token: solicitar em developers@met-care.com.

---

Listar clientes

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

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
limit	integer	Não	Registos por página (1–500; padrão: 100)
cursor	string	Não	Cursor para a próxima página (da resposta anterior)
updated_since	string (RFC3339)	Não	Apenas clientes atualizados desde esta data

Exemplo de requisição (cURL)

# Produção
curl -X GET "https://integration.met-care.com/v1/clients?limit=50&updated_since=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Sandbox
curl -X GET "https://integration.met-care.com/sandbox/v1/clients?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta de sucesso (200)

{
  "data": [
    {
      "id": 12345,
      "name": "Manuel Costa",
      "phone": "+244912345678",
      "email": "manuel.costa@exemplo.ao",
      "birthday": "1990-05-15T00:00:00Z",
      "identity": "00012345678",
      "identity_type": "BI",
      "nif": "123456789",
      "gender": "male",
      "active": true,
      "identity_expire_date": "2030-05-15T00:00:00Z",
      "registration_source": "web"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTAxLTEwVDA4OjAwOjAwWiIsImlkIjoiMTIzNDUifQ"
  },
  "links": {
    "self": "/v1/clients?limit=50&updated_since=2026-01-01T00:00:00Z",
    "next": "/v1/clients?limit=50&updated_since=...&cursor=..."
  }
}

---

Obter um cliente por ID

Método: GET /v1/clients/:id
Headers: Authorization: Bearer YOUR_TOKEN

O id é o identificador numérico do cliente (ex.: 12345).

Exemplo de requisição (cURL)

curl -X GET "https://integration.met-care.com/v1/clients/12345" \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta de sucesso (200)

{
  "data": {
    "id": 12345,
    "name": "Manuel Costa",
    "phone": "+244912345678",
    "email": "manuel.costa@exemplo.ao",
    "birthday": "1990-05-15T00:00:00Z",
    "identity": "00012345678",
    "identity_type": "BI",
    "nif": "123456789",
    "gender": "male",
    "active": true,
    "identity_expire_date": "2030-05-15T00:00:00Z",
    "registration_source": "web"
  },
  "meta": {
    "client_id": 12345
  }
}

Erro (404)

Quando o cliente não existe:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "subscription not found"
  }
}

---

Campos do objeto Client (User)

Campo	Tipo	Descrição
id	integer	ID do cliente
name	string	Nome completo
phone	string	Telefone (ex.: +244 912 345 678)
email	string	Email
birthday	datetime (RFC3339)	Data de nascimento
identity	string	Número de identificação
identity_type	string	Documento (ex.: BI)
nif	string	NIF angolano
gender	string	male, female, unknown
active	boolean	Cliente ativo
identity_expire_date	datetime (RFC3339)	Validade do documento
registration_source	string	Origem do registo

Exemplos com dados angolanos: telefone +244, documento BI.

---

Paginação

A API usa paginação por cursor (igual às subscrições):

1. Primeira página: não envie cursor.
2. Próximas páginas: use o valor de meta.next_cursor como parâmetro cursor.
3. Fim: quando meta.has_more for false, não há mais páginas.

Exemplo de navegação:

GET .../v1/clients?limit=50
GET .../v1/clients?limit=50&cursor=<next_cursor da resposta anterior>

---

Filtro por data

Use updated_since em formato RFC3339 para obter apenas clientes atualizados desde uma data (sincronização incremental).

Exemplo: GET .../v1/clients?updated_since=2026-01-01T00:00:00Z

---

Erros comuns

Código HTTP	code	Descrição
400	VALIDATION_ERROR	Parâmetros inválidos (ex.: limit fora de 1–500, updated_since não RFC3339)
400	BAD_REQUEST	Erro ao processar a listagem
401	—	Token em falta ou inválido
403	—	Não autorizado
404	NOT_FOUND	Cliente não encontrado (GET /v1/clients/:id)

---

Exemplo de integração (JavaScript)

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

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

async function listClients(cursor = null, updatedSince = null) {
  const url = new URL(`${BASE_URL}/clients`);
  url.searchParams.set('limit', '50');
  if (cursor) url.searchParams.set('cursor', cursor);
  if (updatedSince) url.searchParams.set('updated_since', updatedSince);
  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${API_TOKEN}` }
  });
  return response.json();
}

async function getClient(id) {
  const response = await fetch(`${BASE_URL}/clients/${id}`, {
    headers: { 'Authorization': `Bearer ${API_TOKEN}` }
  });
  return response.json();
}

// Listar todos (paginação)
let cursor = null;
do {
  const result = await listClients(cursor);
  console.log('Clients:', result.data);
  cursor = result.meta?.next_cursor;
} while (result.meta?.has_more);

// Obter um cliente
const client = await getClient(12345);
console.log('Client:', client.data);