API Contas de Operadores

A API de Contas de Operadores permite gerir as contas dos operadores de Mobile Money e acompanhar os seus movimentos financeiros.

Vista geral

Endpoint	Método	Descrição
`/api/comptes-operateurs`	GET	Lista de contas
`/api/comptes-operateurs/{id}`	GET	Detalhe de uma conta
`/api/comptes-operateurs`	POST	Criar uma conta
`/api/comptes-operateurs/{id}`	PUT	Modificar uma conta
`/api/comptes-operateurs/{id}`	DELETE	Eliminar uma conta
`/api/comptes-operateurs/operateurs`	GET	Lista de operadores
`/api/comptes-operateurs/stats`	GET	Estatísticas globais
`/api/comptes-operateurs/alertes`	GET	Alertas de saldo
`/api/comptes-operateurs/by-projet-operateur`	GET	Conta por projeto/operador
`/api/comptes-operateurs/{id}/depots`	POST	Registar um depósito
`/api/comptes-operateurs/{id}/mouvements`	GET	Histórico de movimentos
`/api/comptes-operateurs/{id}/stats`	GET	Estatísticas da conta
`/api/comptes-operateurs/{id}/recalculer`	POST	Recalcular o saldo

Lista de contas de operadores

Endpoint

GET /api/comptes-operateurs

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`page`	int	Não	Número de página (por defeito: 1)
`limit`	int	Não	Elementos por página (por defeito: 20)
`operateur`	string	Não	Filtrar por operador (orange_money, mtn_money)
`projet`	UUID	Não	Filtrar por projeto
`statut`	string	Não	Filtrar por estado (actif, inactif)
`search`	string	Não	Pesquisa textual

Resposta

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "OM-PCH-001",
      "operateur": "orange_money",
      "operateurLabel": "Orange Money",
      "numeroCompte": "955123456",
      "nomCompte": "PCH Pagamentos Oio",
      "projet": {
        "id": "...",
        "nom": "PCH Guiné-Bissau"
      },
      "solde": 125000000,
      "soldeMinimum": 10000000,
      "devise": "XOF",
      "statut": "actif",
      "alerteSolde": false,
      "dernierDepot": "2025-03-10T14:30:00+00:00",
      "dernierPaiement": "2025-03-15T09:00:00+00:00",
      "createdAt": "2025-01-01T08:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "pages": 1
  }
}

Detalhe de uma conta

Endpoint

GET /api/comptes-operateurs/{id}

Resposta

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001",
    "operateur": "orange_money",
    "operateurLabel": "Orange Money",
    "numeroCompte": "955123456",
    "nomCompte": "PCH Pagamentos Oio",
    "description": "Conta principal para os pagamentos da região Oio",
    "projet": {
      "id": "...",
      "nom": "PCH Guiné-Bissau",
      "code": "PCH-GW"
    },
    "solde": 125000000,
    "soldeMinimum": 10000000,
    "seuilAlerte": 15000000,
    "devise": "XOF",
    "statut": "actif",
    "alerteSolde": false,
    "contacts": {
      "responsable": "Mamadou Diallo",
      "telephone": "+245955789012",
      "email": "m.diallo@pch.gw"
    },
    "dernierDepot": {
      "date": "2025-03-10T14:30:00+00:00",
      "montant": 50000000,
      "reference": "DEP-2025-0045"
    },
    "dernierPaiement": {
      "date": "2025-03-15T09:00:00+00:00",
      "montant": 12500000,
      "cycleId": "..."
    },
    "statsResume": {
      "totalDepots": 450000000,
      "totalPaiements": 325000000,
      "nombrePaiements": 13000
    },
    "createdAt": "2025-01-01T08:00:00+00:00",
    "updatedAt": "2025-03-15T09:00:00+00:00"
  }
}

Criar uma conta

Endpoint

POST /api/comptes-operateurs

Corpo do pedido

{
  "operateur": "orange_money",
  "numeroCompte": "955123456",
  "nomCompte": "PCH Pagamentos Oio",
  "description": "Conta principal para os pagamentos da região Oio",
  "projetId": "550e8400-e29b-41d4-a716-446655440001",
  "soldeInitial": 0,
  "soldeMinimum": 10000000,
  "seuilAlerte": 15000000,
  "contacts": {
    "responsable": "Mamadou Diallo",
    "telephone": "+245955789012",
    "email": "m.diallo@pch.gw"
  }
}

Operadores disponíveis

Operador	Rótulo	Descrição
`orange_money`	Orange Money	Orange Money Guiné-Bissau
`mtn_money`	MTN Mobile Money	MTN Mobile Money
`wave`	Wave	Wave
`free_money`	Free Money	Free Money

Resposta

{
  "success": true,
  "message": "Conta de operador criada com sucesso",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001"
  }
}

Lista de operadores

Endpoint

GET /api/comptes-operateurs/operateurs

Resposta

{
  "success": true,
  "data": [
    {
      "value": "orange_money",
      "label": "Orange Money",
      "logo": "/images/operators/orange.png",
      "actif": true
    },
    {
      "value": "mtn_money",
      "label": "MTN Mobile Money",
      "logo": "/images/operators/mtn.png",
      "actif": true
    },
    {
      "value": "wave",
      "label": "Wave",
      "logo": "/images/operators/wave.png",
      "actif": true
    }
  ]
}

Estatísticas globais

Endpoint

GET /api/comptes-operateurs/stats

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`projet`	UUID	Não	Filtrar por projeto
`dateDebut`	date	Não	Data de início
`dateFin`	date	Não	Data de fim

Resposta

{
  "success": true,
  "data": {
    "totalComptes": 8,
    "comptesActifs": 7,
    "soldeTotal": 850000000,
    "devise": "XOF",
    "parOperateur": [
      {
        "operateur": "orange_money",
        "label": "Orange Money",
        "comptes": 4,
        "solde": 500000000
      },
      {
        "operateur": "mtn_money",
        "label": "MTN Mobile Money",
        "comptes": 3,
        "solde": 300000000
      }
    ],
    "alertes": {
      "soldeFaible": 1,
      "inactifs": 1
    },
    "activiteRecente": {
      "depotsJour": 2,
      "montantDepotsJour": 75000000,
      "paiementsJour": 1500,
      "montantPaiementsJour": 37500000
    }
  }
}

Alertas de saldo

Endpoint

GET /api/comptes-operateurs/alertes

Resposta

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "OM-PCH-002",
      "nomCompte": "PCH Pagamentos Bafata",
      "operateur": "orange_money",
      "solde": 8000000,
      "soldeMinimum": 10000000,
      "deficit": 2000000,
      "typeAlerte": "solde_critique",
      "message": "Saldo inferior ao mínimo exigido"
    }
  ]
}

Conta por projeto e operador

Endpoint

GET /api/comptes-operateurs/by-projet-operateur

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`projetId`	UUID	Sim	ID do projeto
`operateur`	string	Sim	Código do operador

Resposta

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001",
    "solde": 125000000,
    "operateur": "orange_money"
  }
}

Registar um depósito

Endpoint

POST /api/comptes-operateurs/{id}/depots

Corpo do pedido

{
  "montant": 50000000,
  "reference": "VIR-2025-0045",
  "dateDepot": "2025-03-15",
  "source": "Transferência bancária",
  "notes": "Aprovisionamento para ciclo de Março 2025",
  "pieceJustificative": "id_ficheiro_opcional"
}

Resposta

{
  "success": true,
  "message": "Depósito registado com sucesso",
  "data": {
    "depotId": "550e8400-e29b-41d4-a716-446655440010",
    "reference": "DEP-2025-0046",
    "montant": 50000000,
    "nouveauSolde": 175000000
  }
}

Histórico de movimentos

Endpoint

GET /api/comptes-operateurs/{id}/mouvements

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`page`	int	Não	Número de página
`limit`	int	Não	Elementos por página
`type`	string	Não	Tipo de movimento (depot, paiement, ajustement)
`dateDebut`	date	Não	Data de início
`dateFin`	date	Não	Data de fim

Resposta

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "type": "depot",
      "typeLabel": "Depósito",
      "reference": "DEP-2025-0046",
      "montant": 50000000,
      "soldeAvant": 125000000,
      "soldeApres": 175000000,
      "date": "2025-03-15T10:30:00+00:00",
      "description": "Aprovisionamento Março 2025",
      "createdBy": {
        "id": "...",
        "nom": "Admin User"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "type": "paiement",
      "typeLabel": "Pagamento",
      "reference": "CYC-2025-003",
      "montant": -12500000,
      "soldeAvant": 175000000,
      "soldeApres": 162500000,
      "date": "2025-03-15T14:00:00+00:00",
      "description": "Ciclo de pagamento Março 2025 - 500 beneficiários",
      "cycleId": "..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}

Estatísticas de uma conta

Endpoint

GET /api/comptes-operateurs/{id}/stats

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`periode`	string	Não	mês, trimestre, ano (por defeito: mês)

Resposta

{
  "success": true,
  "data": {
    "compte": {
      "id": "...",
      "code": "OM-PCH-001",
      "soldeActuel": 162500000
    },
    "periode": {
      "debut": "2025-03-01",
      "fin": "2025-03-15"
    },
    "resume": {
      "totalDepots": 100000000,
      "nombreDepots": 2,
      "totalPaiements": 62500000,
      "nombrePaiements": 2500,
      "soldeDebut": 125000000,
      "soldeFin": 162500000
    },
    "evolution": [
      {"date": "2025-03-01", "solde": 125000000},
      {"date": "2025-03-05", "solde": 112500000},
      {"date": "2025-03-10", "solde": 162500000},
      {"date": "2025-03-15", "solde": 162500000}
    ],
    "moyennePaiementJour": 4166667
  }
}

Recalcular o saldo

Endpoint

POST /api/comptes-operateurs/{id}/recalculer

Descrição

Recalcula o saldo da conta em função de todos os movimentos registados. Útil em caso de dessincronização.

Resposta

{
  "success": true,
  "message": "Saldo recalculado com sucesso",
  "data": {
    "ancienSolde": 160000000,
    "nouveauSolde": 162500000,
    "difference": 2500000,
    "nombreMouvements": 156
  }
}

aviso

Esta operação pode modificar o saldo apresentado. É recomendada apenas em caso de incoerência detetada.

Vista geral​

Lista de contas de operadores​

Endpoint​

Parâmetros de consulta​

Resposta​

Detalhe de uma conta​

Endpoint​

Resposta​

Criar uma conta​

Endpoint​

Corpo do pedido​

Operadores disponíveis​

Resposta​

Lista de operadores​

Endpoint​

Resposta​

Estatísticas globais​

Endpoint​

Parâmetros de consulta​

Resposta​

Alertas de saldo​

Endpoint​

Resposta​

Conta por projeto e operador​

Endpoint​

Parâmetros de consulta​

Resposta​

Registar um depósito​

Endpoint​

Corpo do pedido​

Resposta​

Histórico de movimentos​

Endpoint​

Parâmetros de consulta​

Resposta​

Estatísticas de uma conta​

Endpoint​

Parâmetros de consulta​

Resposta​

Recalcular o saldo​

Endpoint​

Descrição​

Resposta​

Vista geral

Lista de contas de operadores

Endpoint

Parâmetros de consulta

Resposta

Detalhe de uma conta

Endpoint

Resposta

Criar uma conta

Endpoint

Corpo do pedido

Operadores disponíveis

Resposta

Lista de operadores

Endpoint

Resposta

Estatísticas globais

Endpoint

Parâmetros de consulta

Resposta

Alertas de saldo

Endpoint

Resposta

Conta por projeto e operador

Endpoint

Parâmetros de consulta

Resposta

Registar um depósito

Endpoint

Corpo do pedido

Resposta

Histórico de movimentos

Endpoint

Parâmetros de consulta

Resposta

Estatísticas de uma conta

Endpoint

Parâmetros de consulta

Resposta

Recalcular o saldo

Endpoint

Descrição

Resposta