GET /api/beneficiaires/{id}

Obtem as informacoes detalhadas de um beneficiario.

Endpoint

GET /api/beneficiaires/{id}

Parametros de URL

Parametro	Tipo	Descricao
id	UUID	Identificador unico do beneficiario

Cabecalhos

Cabecalho	Valor	Obrigatorio
Authorization	Bearer {token}	Sim

Resposta de Sucesso

Codigo: 200 OK

{
    "@context": "/api/contexts/Beneficiaire",
    "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000",
    "@type": "Beneficiaire",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "codeBeneficiaire": "BEN-2024-00001",
    "nomComplet": "Fatou Diallo",
    "telephone": "771234567",
    "modePaiement": "orange_money",
    "compteMobile": "771234567",
    "compteBancaire": null,
    "numeroMTN": null,
    "typeBeneficiaire": "principal",
    "actif": true,
    "sexe": "F",
    "statutEnrolement": "actif",
    "dateEnrolement": "2024-01-15T10:30:00+00:00",
    "dateSortie": null,
    "motifSortie": null,
    "documentVerifie": true,
    "dateVerificationDocument": "2024-01-20",
    "statutCycle": "actif",
    "prochaineRecertification": "2025-01-15",
    "estGradue": false,
    "dateGraduation": null,
    "tauxConformiteGlobal": "92.50",
    "nombreCyclesCompletes": 3,
    "dernierSuivi": "2024-06-15",
    "menage": {
        "@id": "/api/menages/1",
        "@type": "Menage",
        "id": 1,
        "codeMenage": "MEN-2024-00001",
        "tailleMenage": 5,
        "chefMenage": {
            "@id": "/api/chef_menages/1",
            "nomComplet": "Mamadou Diallo"
        },
        "region": {
            "@id": "/api/regions/1",
            "nom": "Dakar"
        },
        "commune": {
            "@id": "/api/communes/1",
            "nom": "Commune 1"
        }
    },
    "programme": {
        "@id": "/api/programmes/1",
        "@type": "Programme",
        "id": 1,
        "nom": "Transferts Monétaires 2024",
        "code": "TM-2024"
    },
    "beneficiairePrincipal": null
}

Respostas de Erro

404 Not Found

{
    "@context": "/api/contexts/Error",
    "@type": "hydra:Error",
    "hydra:title": "An error occurred",
    "hydra:description": "Item not found for \"/api/beneficiaires/invalid-uuid\""
}

403 Forbidden

{
    "@context": "/api/contexts/Error",
    "@type": "hydra:Error",
    "hydra:title": "An error occurred",
    "hydra:description": "Access Denied."
}

Exemplos

cURL

curl https://sig.example.com/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getBeneficiaire = async (id) => {
    const response = await fetch(
        `https://sig.example.com/api/beneficiaires/${id}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );

    if (response.status === 404) {
        throw new Error('Beneficiario nao encontrado');
    }

    return response.json();
};

// Utilizacao
try {
    const beneficiaire = await getBeneficiaire('550e8400-e29b-41d4-a716-446655440000');
    console.log(`Nome: ${beneficiaire.nomComplet}`);
    console.log(`Tipo: ${beneficiaire.typeBeneficiaire}`);
    console.log(`Estado: ${beneficiaire.statutCycle}`);
    console.log(`Ciclos concluidos: ${beneficiaire.nombreCyclesCompletes}`);
    console.log(`Agregado familiar: ${beneficiaire.menage.codeMenage}`);
} catch (error) {
    console.error(error.message);
}

Python

import requests

def get_beneficiaire(token, beneficiaire_id):
    response = requests.get(
        f'https://sig.example.com/api/beneficiaires/{beneficiaire_id}',
        headers={'Authorization': f'Bearer {token}'}
    )

    if response.status_code == 404:
        raise Exception('Beneficiario nao encontrado')

    return response.json()

# Utilizacao
beneficiaire = get_beneficiaire(token, '550e8400-e29b-41d4-a716-446655440000')
print(f"Codigo: {beneficiaire['codeBeneficiaire']}")
print(f"Nome: {beneficiaire['nomComplet']}")
print(f"Modo de pagamento: {beneficiaire['modePaiement']}")
print(f"Taxa de conformidade: {beneficiaire['tauxConformiteGlobal']}%")

Campos da Resposta

Identidade

Campo	Tipo	Descricao
id	UUID	Identificador unico
codeBeneficiaire	string	Codigo unico (BEN-YYYY-NNNNN)
nomComplet	string	Nome completo do beneficiario
telephone	string	Numero de telefone
sexe	string	"M" ou "F"

Pagamento

Campo	Tipo	Descricao
modePaiement	string	Modo de pagamento (orange_money, wave, etc.)
compteMobile	string	Numero da conta Mobile Money
compteBancaire	string	Numero da conta bancaria
numeroMTN	string	Numero MTN Mobile Money

Tipo e Estado

Campo	Tipo	Descricao
typeBeneficiaire	string	"principal" ou "substitut"
actif	boolean	Beneficiario ativo
statutEnrolement	string	Estado do registo
statutCycle	string	Estado no ciclo de vida
documentVerifie	boolean	Documento de identidade verificado

Ciclo de Vida

Campo	Tipo	Descricao
dateEnrolement	datetime	Data de registo
prochaineRecertification	date	Data da proxima recertificacao
estGradue	boolean	Concluiu o programa
dateGraduation	date	Data de graduacao
nombreCyclesCompletes	integer	Numero de ciclos de pagamento concluidos
tauxConformiteGlobal	decimal	Taxa de conformidade com as condicionalidades (0-100)
dernierSuivi	date	Data do ultimo acompanhamento no terreno

Notas

• Os identificadores de beneficiarios sao UUIDs
• O beneficiario substituto referencia o seu beneficiario principal atraves de beneficiairePrincipal
• A taxa de conformidade e calculada sobre todas as condicionalidades do programa
• A recertificacao e obrigatoria periodicamente para manter a elegibilidade