Documentação da API

Primeiros passos

No painel, vá a Definições → Developer. Aí encontra o URL base, o Broker ID da sua corretora, as chaves de API e o webhook. Só o Master e o Administrador têm acesso.

Autenticação

Cada pedido leva a chave de API no cabeçalho Authorization. As chaves começam por sk_live_ e só são mostradas uma vez. Guarde-as no servidor, nunca no navegador ou numa app.

curl https://seguros.co.mz/api/public/v1/clients \
  -H "Authorization: Bearer sk_live_…"

Recursos disponíveis

A API expõe sete recursos de leitura, sempre limitados aos dados da corretora dona da chave: clientes, cotações (proposals), apólices (policies), sinistros (claims), comissões (commissions), leads e facturas emitidas a clientes (invoices). Todos os recursos partilham a mesma forma de resposta.

Paginação e filtros

Todos os endpoints de listagem aceitam os mesmos parâmetros: limit (1 a 100, por defeito 50), offset (a partir de 0) e status (filtra pelo estado do registo). A resposta devolve data, total, limit e offset.

GET https://seguros.co.mz/api/public/v1/<recurso>?limit=50&offset=0&status=active

200 OK
{
  "data": [ { "id": "…", "status": "active", "data": { … }, "created_at": "…" } ],
  "total": 123, "limit": 50, "offset": 0
}

Clientes

Devolve os clientes da corretora, do mais recente para o mais antigo. Inclui nome, contactos, NUIT e demais campos de KYC dentro de data.

GET https://seguros.co.mz/api/public/v1/clients

{ "data": [
  { "id": "…", "title": "…", "status": "active",
    "data": { "name": "…", "email": "…", "phone": "…", "nuit": "…" },
    "created_at": "…" } ], "total": 12 }

Cotações (proposals)

Devolve as cotações emitidas. O campo amount tem o valor da cotação e data inclui seguradora, ramo e outros detalhes. Estados possíveis: draft, sent, accepted, rejected.

GET https://seguros.co.mz/api/public/v1/proposals

{ "data": [
  { "id": "…", "title": "Nissa Sienta MHZ 105 MP", "status": "sent",
    "amount": 45000, "client_id": "…",
    "data": { "insurer": "…", "branch": "…" } } ], "total": 8 }

Apólices (policies)

Devolve as apólices registadas, com número de apólice, produto, seguradora, ramo e data de início em data, além de amount (prémio) e estado.

GET https://seguros.co.mz/api/public/v1/policies

{ "data": [
  { "id": "…", "title": "…", "status": "active", "amount": 12500,
    "data": { "policy_no": "…", "product": "…", "insurer": "…",
              "branch": "…", "start_date": "…" } } ], "total": 5 }

Sinistros (claims)

Devolve os sinistros abertos e tratados na corretora, com o número da apólice, seguradora e data do incidente em data, e amount no valor reclamado.

GET https://seguros.co.mz/api/public/v1/claims

{ "data": [
  { "id": "…", "title": "…", "status": "open", "amount": 30000,
    "data": { "client": "…", "policy_no": "…", "insurer": "…",
              "incident_date": "…" } } ], "total": 2 }

Comissões (commissions)

Devolve as comissões registadas por seguradora e período, com o valor em amount e o estado de processamento em status.

GET https://seguros.co.mz/api/public/v1/commissions

{ "data": [
  { "id": "…", "title": "…", "status": "pending", "amount": 1875,
    "data": { "insurer": "…", "policy_no": "…", "period": "…" } } ], "total": 14 }

Leads

Devolve os leads do CRM da corretora, com contactos, província e NUIT em data, e o estado do funil (novo, contactado, qualificado, proposta, negociação, ganho, perdido) em status.

GET https://seguros.co.mz/api/public/v1/leads

{ "data": [
  { "id": "…", "title": "…", "status": "contacted", "amount": 21000,
    "data": { "phone": "…", "province": "…", "nuit": "…" } } ], "total": 30 }

Facturas (invoices)

Devolve as facturas emitidas pela corretora aos seus clientes, com número, nome e NUIT do cliente, totais e moeda, e datas de emissão e pagamento.

GET https://seguros.co.mz/api/public/v1/invoices

{ "data": [
  { "id": "…", "number": "FT 2026/1", "status": "paid",
    "customer_name": "…", "total": 35000, "currency": "MZN",
    "issued_at": "…", "paid_at": "…" } ], "total": 6 }

Erros

Uma chave em falta, inválida ou revogada devolve 401.

401 { "error": "unauthorized" }

Webhooks

Cada corretora tem um único endereço de webhook (https). Os eventos são enviados por POST, em JSON, e o seu servidor deve responder com 2xx em menos de 8 segundos.

POST https://o-seu-servidor/webhook
X-Seguros-Event: ping
X-Seguros-Timestamp: 1759676400
X-Seguros-Signature: sha256=…

{ "id": "…", "event": "ping", "created_at": "…", "data": { … } }

Verificar a assinatura

Calcule o HMAC-SHA256 de "timestamp.corpo" com o segredo do webhook e compare com o cabeçalho X-Seguros-Signature. Rejeite pedidos com timestamp antigo.

import crypto from "crypto";
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET)
  .update(timestamp + "." + rawBody).digest("hex");
const ok = signature === "sha256=" + expected;

Boas práticas

Revogue imediatamente uma chave exposta e crie outra. Gere um novo segredo de webhook se suspeitar de fuga. Use uma chave por integração para poder revogá-las em separado.