Integração Corporativa

Gestão de segurados

Cadastre, liste, atualize e desative os segurados/usuários vinculados ao seu contrato. Operações idempotentes pelo par (insurer_id, cpf).

Listar segurados

Retorna a lista paginada de segurados do contrato.

GET/api/v1/insurer-portal/customers

X-API-Key

Campo	Tipo	Descrição
`status`opcional	`"active" \| "inactive"`	Filtra por status do segurado.
`page`opcional	`integer` default: `1`	Página (1-indexed).
`pageSize`opcional	`integer` default: `20`	Itens por página (máx 100).
`search`opcional	`string`	Busca parcial por nome, email ou CPF.

cURL

curl 'https://api.netguincho.com.br/api/v1/insurer-portal/customers?status=active&page=1' \
  -H 'X-API-Key: live_sk_...'

JSON

{
  "data": [
    {
      "id": "2a1c4f67-...",
      "cpf": "12345678900",
      "name": "João da Silva",
      "email": "joao@email.com",
      "phone": "11999999999",
      "status": "active",
      "monthly_limit": 3,
      "usage_this_month": 1,
      "created_at": "2026-01-12T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 47, "totalPages": 3 }
}

Cadastrar / vincular segurado

Idempotente por cpf: se já existir vínculo, retorna o registro existente (200) em vez de criar duplicado.

POST/api/v1/insurer-portal/customers

X-API-Key

Campo	Tipo	Descrição
`cpf`obrigatório	`string (11 dígitos)`	CPF do segurado, sem máscara.
`name`obrigatório	`string`	Nome completo do segurado.
`email`opcional	`string`	Email para login e notificações.
`phone`opcional	`string`	Telefone celular com DDD.
`monthlyLimit`opcional	`integer`	Limite mensal de acionamentos. Se omitido, usa o default do contrato.

cURL

curl -X POST 'https://api.netguincho.com.br/api/v1/insurer-portal/customers' \
  -H 'X-API-Key: live_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpf": "12345678900",
    "name": "João da Silva",
    "email": "joao@email.com",
    "phone": "11999999999",
    "monthlyLimit": 5
  }'

Atualizar segurado

Atualize limite mensal, status ou dados de contato. CPF é imutável.

PATCH/api/v1/insurer-portal/customers/:id

X-API-Key

cURL

curl -X PATCH 'https://api.netguincho.com.br/api/v1/insurer-portal/customers/2a1c4f67-...' \
  -H 'X-API-Key: live_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{ "monthlyLimit": 10 }'

Desativar segurado

Soft-delete: o registro permanece para fins de relatório histórico, mas o segurado não consegue mais acionar o serviço.

DELETE/api/v1/insurer-portal/customers/:id

X-API-Key