> For the complete documentation index, see [llms.txt](https://selenium-4.gitbook.io/nexus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://selenium-4.gitbook.io/nexus-docs/service-domain/party-reference-data-directory/operacoes/main.md). # Retrieve Party Reference Data Directory | Campo | Valor | | -------------- | --------------------------------------- | | Service Domain | Party Reference Data Directory | | BIAN Version | 14.0.0 | | Operation | Retrieve Party Reference Data Directory | | Method | GET | | API Name | Party Reference Data Directory API | | Versão | v1.0.0 | ## 1. Descrição da Operação O serviço de Consulta de Dados de Referência de uma Entidade (Party) permite obter a ficha completa de um cliente — particular (pessoa singular) ou corporate (pessoa colectiva/empresa) — registada no directório de dados de referência. A operação retorna dados de identificação, demográficos/sócio-económicos, de localização, documentos de identificação, atributos adicionais (regulatórios, AML, CIRC, etc.) e, consoante o tipo de entidade, campos específicos de particular (ex: estado civil, agregado familiar, residência fiscal) ou de empresa (ex: capital social, volume de vendas, estrutura legal). > **Nota importante:** o serviço é **único** (mesmo endpoint), mas a **estrutura do payload de resposta varia conforme o tipo de entidade**, identificado pelo campo `partyReference.partyType`: > > * `"Normal Particular"` - devolve a estrutura de **Pessoa Singular** (ver secção 4.1/4.2). > * `"Normal Empresa"` - devolve a estrutura de **Pessoa Colectiva/Corporate** (ver secção 4.3/4.4). > > Os dois exemplos de payload de resposta enviados foram documentados em separado, indicando quais os campos comuns e quais os específicos de cada tipo. | Campo | Valor | | ------------ | ------------------------------------------------------------------------------- | | API Name | Party Reference Data Directory API | | Versão | v1.0.0 | | Endpoint | GET /v1/party-reference-data-directory/{partyReferenceDataDirectoryId}/retrieve | | Autenticação | Bearer Token (OAuth 2.0 / OIDC) | ## 2. Cabeçalhos HTTP | Header | Obrigatório | Notas | | ------------------------------ | ----------- | -------------------------------------------- | | Authorization: Bearer {token} | Sim | OAuth2 / JWT client\_credentials para M2M | | Content-Type: application/json | Sim | — | | Accept: application/json | Sim | — | | x-channel | Recomendado | Canal de origem (SOP, MOBILE, BACKOFFICE, …) | ## 3. Parâmetros ### 3.1 Path Parameters | Parâmetro | Tipo | Obrigatório | Descrição | | ----------------------------- | ------ | ----------- | ----------------------------------------------------------------------------- | | partyReferenceDataDirectoryId | string | Sim | Identificador único da entidade (party) no directório de dados de referência. | ### 3.2 Query Parameters *Não aplicável — esta operação não recebe parâmetros de query.* ## 4. Payload de Resposta (Response - 200 OK) ### 4.1 Exemplo — Party Particular (Pessoa Singular) ```json { "partyReference": { "partyName": { "name": "JOAO MANUEL DOS SANTOS PEREIRA" }, "partyType": "Normal Particular" }, "partyDemographics": { "socioEconomicClassificationReference": { "referenceType": "Codigo de Actividade Economica", "referenceIdentification": { "identifierValue": "62010", "identifierDescription": "Actividades de programação informática" } }, "sectorialClassificationReference": { "sectorialType": "Codigo Sectorial", "sectorialIdentification": { "identifierValue": "51", "identifierDescription": "Sector Privado Empresarial N/Financeiro" }, "sectorialClassificationDate": { "dateContent": "2025-01-15", "dateType": "UpdatedDate" } }, "educationLevel": { "educationLevelCode": "4", "educationLevelDescription": "CURSO SUPERIOR" } }, "partyLocation": { "partyAddress": { "addressType": "LocationIsPlaceOfBirthOfParty", "addressLine": "Huambo" }, "residentialAddress": { "addressType": "Individual", "addressLine": "RUA DAS ACACIAS Nº 45 BAIRRO MAIANGA", "country": { "countryName": { "name": "Angola" }, "countryCode": "AGO" } } }, "residencyStatus": { "statusCode": "R", "statusDescription": "Residente no País" }, "nationality": { "countryName": { "name": "Angola" }, "countryCode": "AGO" }, "factaArrangement": { "factaStatus": "Non US Person" }, "birthDate": { "dateContent": "1985-07-12", "dateType": "BirthDate" }, "financialStatementBalances": [ { "statementBalanceAmount": { "amountValue": 250000, "amountCurrency": { "currencyCode": "AKZ" }, "amountType": "MonthlyIncome" } }, { "statementBalanceAmount": { "amountValue": 3000000, "amountCurrency": { "currencyCode": "AKZ" }, "amountType": "YearlyIncome" } }, { "statementBalanceAmount": { "amountValue": 120000, "amountCurrency": { "currencyCode": "AKZ" }, "amountType": "MonthlyExpenses" } } ], "civilStatus": { "statusCode": "CAS", "statusDescription": "Casado(a)" }, "gender": { "genderCode": "M", "genderDescription": "Masculino" }, "partyFamilyReference": { "familyMembers": [ { "memberName": { "name": "MANUEL ANTONIO PEREIRA" }, "relationshipType": { "typeCode": "PAI", "typeDescription": "Pai" } }, { "memberName": { "name": "MARIA JOSEFINA DOS SANTOS" }, "relationshipType": { "typeCode": "MAE", "typeDescription": "Mãe" } } ], "householdReference": 1, "dependentCount": 3 }, "partyProfessionalActivity": { "activityCode": "12", "activityDescription": "TÉCNICO DE INFORMÁTICA" }, "governmentIssuedDocumentDetails": { "documentsReference": [ { "documentIdentification": { "identifierValue": "001234567LA042" }, "documentType": "NIF", "documentIdentificationDescription": "IdentificationDocument", "documentDescription": "Num Ident Fiscal (PARTICULAR)", "documentIssuingReference": "9999 Desconhecida", "documentCountry": { "countryName": { "name": "Angola" }, "countryCode": "AGO" }, "documentValidityPeriod": { "fromDate": null, "toDate": null } }, { "documentIdentification": { "identifierValue": "001234567LA042" }, "documentType": "BI", "documentIdentificationDescription": "IdentificationDocument", "documentDescription": "Bilhete Identidade", "documentIssuingReference": "LUANDA", "documentCountry": { "countryName": { "name": "Angola" }, "countryCode": "AGO" }, "documentValidityPeriod": { "fromDate": { "dateContent": "2022-03-10", "dateType": "StartDate" }, "toDate": { "dateContent": "2032-03-09", "dateType": "MaturityDate" } } } ] }, "partyAdditionalAttribute": [ { "attributeCode": "STATUTE", "attributeDescription": "Estatuto Fiscal", "attributeValue": "Non US Person" }, { "attributeCode": "FATHER", "attributeDescription": "Nome do Pai", "attributeValue": "MANUEL ANTONIO PEREIRA" }, { "attributeCode": "MOTHER", "attributeDescription": "Nome da Mãe", "attributeValue": "MARIA JOSEFINA DOS SANTOS" }, { "attributeCode": "COUNTRYBIRTH", "attributeDescription": "Naturalidade", "attributeValue": "HUAMBO" }, { "attributeCode": "NCHILD", "attributeDescription": "Número de Filhos", "attributeValue": "3" }, { "attributeCode": "FAMHOUSE", "attributeDescription": "Agregado Familiar", "attributeValue": "1" }, { "attributeCode": "HASPIC", "attributeDescription": "Possui Fotografia", "attributeValue": "true" }, { "attributeCode": "LASTCHG", "attributeDescription": "Data da última alteração", "attributeValue": "2025-01-15" }, { "attributeCode": "DTSOCECO", "attributeDescription": "Data Ref. Sócio-económica", "attributeValue": "2025-01-15" }, { "attributeCode": "RAML", "attributeDescription": "Risco AML", "attributeValue": "1" }, { "attributeCode": "DTREV", "attributeDescription": "Data da última Revisão", "attributeValue": "20250115" }, { "attributeCode": "RCOMPO", "attributeDescription": "Risco comportamental", "attributeValue": "1" } ] } ``` ### 4.2 Campos da Resposta — Particular | Campo | Tipo | Descrição | | ---------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------- | | partyReference.partyName.name | string | Nome completo do cliente. | | partyReference.partyType | string | Tipo de entidade. Valor para particular: `Normal Particular`. | | partyDemographics.socioEconomicClassificationReference.referenceType | string | Tipo de classificação sócio-económica (ex: `Codigo de Actividade Economica`). | | partyDemographics.socioEconomicClassificationReference.referenceIdentification.identifierValue | string | Código de actividade económica (CAE) do cliente. | | partyDemographics.socioEconomicClassificationReference.referenceIdentification.identifierDescription | string | Descrição da actividade económica associada ao código. | | partyDemographics.sectorialClassificationReference.sectorialType | string | Tipo de classificação sectorial (ex: `Codigo Sectorial`). | | partyDemographics.sectorialClassificationReference.sectorialIdentification.identifierValue | string | Código do sector de actividade. | | partyDemographics.sectorialClassificationReference.sectorialIdentification.identifierDescription | string | Descrição do sector de actividade. | | partyDemographics.sectorialClassificationReference.sectorialClassificationDate.dateContent | string (ISO 8601) | Data de actualização da classificação sectorial. | | partyDemographics.sectorialClassificationReference.sectorialClassificationDate.dateType | string | Tipo de data (ex: `UpdatedDate`). | | partyDemographics.educationLevel.educationLevelCode | string | Código do nível de escolaridade. | | partyDemographics.educationLevel.educationLevelDescription | string | Descrição do nível de escolaridade (ex: `CURSO SUPERIOR`). | | partyLocation.partyAddress.addressType | string | Tipo de morada. Para naturalidade: `LocationIsPlaceOfBirthOfParty`. | | partyLocation.partyAddress.addressLine | string | Local de nascimento (naturalidade) do cliente. | | partyLocation.residentialAddress.addressType | string | Tipo de morada residencial (ex: `Individual`). | | partyLocation.residentialAddress.addressLine | string | Endereço residencial completo. | | partyLocation.residentialAddress.country.countryName.name | string | Nome do país de residência. | | partyLocation.residentialAddress.country.countryCode | string | Código do país de residência (ISO). | | residencyStatus.statusCode | string | Código do estado de residência fiscal (ex: `R`). | | residencyStatus.statusDescription | string | Descrição do estado de residência (ex: `Residente no País`). | | nationality.countryName.name | string | Nome do país de nacionalidade. | | nationality.countryCode | string | Código do país de nacionalidade (ISO). | | factaArrangement.factaStatus | string | Estatuto FATCA do cliente (ex: `Non US Person`). | | birthDate.dateContent | string (ISO 8601) | Data de nascimento do cliente. | | birthDate.dateType | string | Tipo de data (ex: `BirthDate`). | | financialStatementBalances\[] | array | Lista de indicadores financeiros declarados do cliente (rendimento, despesas, etc.). | | financialStatementBalances\[].statementBalanceAmount.amountValue | number | Valor do indicador financeiro. | | financialStatementBalances\[].statementBalanceAmount.amountCurrency.currencyCode | string | Código da moeda (ISO 4217). | | financialStatementBalances\[].statementBalanceAmount.amountType | string | Tipo de indicador (ex: `MonthlyIncome`, `YearlyIncome`, `MonthlyExpenses`). | | civilStatus.statusCode | string | Código do estado civil (ex: `CAS`). | | civilStatus.statusDescription | string | Descrição do estado civil (ex: `Casado(a)`). | | gender.genderCode | string | Código do género (ex: `M`). | | gender.genderDescription | string | Descrição do género (ex: `Masculino`). | | partyFamilyReference.familyMembers\[] | array | Lista de familiares directos associados ao cliente. | | partyFamilyReference.familyMembers\[].memberName.name | string | Nome do familiar. | | partyFamilyReference.familyMembers\[].relationshipType.typeCode | string | Código do grau de parentesco (ex: `PAI`, `MAE`). | | partyFamilyReference.familyMembers\[].relationshipType.typeDescription | string | Descrição do grau de parentesco (ex: `Pai`, `Mãe`). | | partyFamilyReference.householdReference | integer | Identificador do agregado familiar. | | partyFamilyReference.dependentCount | integer | Número de dependentes/filhos do cliente. | | partyProfessionalActivity.activityCode | string | Código da profissão/actividade profissional. | | partyProfessionalActivity.activityDescription | string | Descrição da profissão (ex: `TÉCNICO DE INFORMÁTICA`). | | governmentIssuedDocumentDetails.documentsReference\[] | array | Lista de documentos de identificação do cliente. | | governmentIssuedDocumentDetails.documentsReference\[].documentIdentification.identifierValue | string | Número do documento. | | governmentIssuedDocumentDetails.documentsReference\[].documentType | string | Tipo de documento (ex: `NIF`, `BI`). | | governmentIssuedDocumentDetails.documentsReference\[].documentIdentificationDescription | string | Categoria do documento (ex: `IdentificationDocument`). | | governmentIssuedDocumentDetails.documentsReference\[].documentDescription | string | Descrição do documento (ex: `Num Ident Fiscal (PARTICULAR)`, `Bilhete Identidade`). | | governmentIssuedDocumentDetails.documentsReference\[].documentIssuingReference | string | Entidade/local emissor do documento (ex: `LUANDA`). | | governmentIssuedDocumentDetails.documentsReference\[].documentCountry.countryName.name | string | País emissor do documento. | | governmentIssuedDocumentDetails.documentsReference\[].documentCountry.countryCode | string | Código do país emissor (ISO). | | governmentIssuedDocumentDetails.documentsReference\[].documentValidityPeriod.fromDate.dateContent | string (ISO 8601) \| null | Data de início de validade do documento. Pode ser `null` quando não aplicável (ex: NIF). | | governmentIssuedDocumentDetails.documentsReference\[].documentValidityPeriod.toDate.dateContent | string (ISO 8601) \| null | Data de fim de validade do documento. Pode ser `null` quando não aplicável. | | partyAdditionalAttribute\[] | array | Lista de atributos adicionais (regulatórios, AML, CIRC, comerciais) do cliente, em formato chave/valor. | | partyAdditionalAttribute\[].attributeCode | string | Código do atributo (ex: `PEP`, `RAML`, `NCHILD`). | | partyAdditionalAttribute\[].attributeDescription | string | Descrição do atributo. | | partyAdditionalAttribute\[].attributeValue | string | Valor do atributo. | ### 4.3 Exemplo — Party Corporate (Pessoa Colectiva / Empresa) ```json { "partyReference": { "partyName": { "name": "TECHNOVA SOLUCOES LDA" }, "partyType": "Normal Empresa", "partyDate": { "dateContent": "2024-11-01", "dateType": "OpenDate" } }, "partyDemographics": { "socioEconomicClassificationReference": { "referenceType": "Codigo de Actividade Economica", "referenceIdentification": { "identifierValue": "62010", "identifierDescription": "Actividades de programação informática" } }, "sectorialClassificationReference": { "sectorialType": "Codigo Sectorial", "sectorialIdentification": { "identifierValue": "51", "identifierDescription": "Sector Privado Empresarial N/Financeiro" } } }, "partyLocation": { "residentialAddress": { "addressType": "PostalAddres", "addressLine": "AVENIDA DOS COMBATENTES Nº 120, TALATONA", "country": { "countryName": { "name": "Angola" }, "countryCode": "AGO" } } }, "partyCapital": { "partyShareCapital": { "shareCapitalAmountValue": 500000, "shareCapitalAmountCurrency": { "currencyCode": "AKZ" }, "shareCapitalAmountType": "ShareCapital" }, "partySalesVolume": { "salesVolumeAmountValue": 8000000, "salesVolumeAmountCurrency": { "currencyCode": "AKZ" }, "salesVolumeAmountType": "SalesVolume", "salesVolumeReferenceYear": 2024 } }, "partyLegalStructureType": { "typeCode": "Q", "typeDescription": "Por Quotas" }, "governmentIssuedDocumentDetails": { "documentsReference": [ { "documentIdentification": { "identifierValue": "5000112233" }, "documentType": "NPC", "documentIdentificationDescription": "IdentificationDocument", "documentDescription": "Num Ident Fiscal (EMPRESA)", "documentCountry": { "countryName": { "name": "Angola" }, "countryCode": "AGO" }, "documentStatus": { "statusReason": "Normal" }, "documentValidityPeriod": { "fromDate": { "dateContent": "2024-11-01", "dateType": "StartDate" }, "toDate": { "dateContent": "2034-11-01", "dateType": "MaturityDate" } } } ] }, "partyAdditionalAttribute": [ { "attributeCode": "EXPORT", "attributeDescription": "Empresa Exportadora", "attributeValue": "não" }, { "attributeCode": "NCOMER", "attributeDescription": "Nome Comercial", "attributeValue": "TECHNOVA" }, { "attributeCode": "RAML", "attributeDescription": "Risco AML", "attributeValue": "1" }, { "attributeCode": "EF", "attributeDescription": "Estado Filtering", "attributeValue": "06 - Não Filtrado" }, { "attributeCode": "CAML", "attributeDescription": "Categoria AML", "attributeValue": "n/a" }, { "attributeCode": "FGD", "attributeDescription": "Excluir do Fundo Garantia", "attributeValue": "não" }, { "attributeCode": "CLMPME", "attributeDescription": "CIRC - Classificação MPME", "attributeValue": "PQ - Pequenas empresas" }, { "attributeCode": "ATVTOT", "attributeDescription": "CIRC - Activo total", "attributeValue": "500000" }, { "attributeCode": "RECLIQ", "attributeDescription": "CIRC - Receitas Líquidas", "attributeValue": "8000000" }, { "attributeCode": "PAISEM", "attributeDescription": "CIRC - País empresa mãe", "attributeValue": "ANGOLA" }, { "attributeCode": "CLIRIS", "attributeDescription": "CIRC - Cliente de alto risco", "attributeValue": "00 - Não é alto risco" } ] } ``` ### 4.4 Campos da Resposta — Corporate | Campo | Tipo | Descrição | | ---------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- | | partyReference.partyName.name | string | Denominação/firma da empresa. | | partyReference.partyType | string | Tipo de entidade. Valor para corporate: `Normal Empresa`. | | partyReference.partyDate.dateContent | string (ISO 8601) | Data de constituição/abertura da entidade. | | partyReference.partyDate.dateType | string | Tipo de data (ex: `OpenDate`). | | partyDemographics.socioEconomicClassificationReference.referenceType | string | Tipo de classificação sócio-económica (ex: `Codigo de Actividade Economica`). | | partyDemographics.socioEconomicClassificationReference.referenceIdentification.identifierValue | string | Código de actividade económica (CAE) da empresa. | | partyDemographics.socioEconomicClassificationReference.referenceIdentification.identifierDescription | string | Descrição da actividade económica associada ao código. | | partyDemographics.sectorialClassificationReference.sectorialType | string | Tipo de classificação sectorial (ex: `Codigo Sectorial`). | | partyDemographics.sectorialClassificationReference.sectorialIdentification.identifierValue | string | Código do sector de actividade. | | partyDemographics.sectorialClassificationReference.sectorialIdentification.identifierDescription | string | Descrição do sector de actividade. | | partyLocation.residentialAddress.addressType | string | Tipo de morada (ex: `PostalAddres`). | | partyLocation.residentialAddress.addressLine | string | Endereço/sede da empresa. | | partyLocation.residentialAddress.country.countryName.name | string | Nome do país da sede. | | partyLocation.residentialAddress.country.countryCode | string | Código do país da sede (ISO). | | partyCapital.partyShareCapital.shareCapitalAmountValue | number | Valor do capital social da empresa. | | partyCapital.partyShareCapital.shareCapitalAmountCurrency.currencyCode | string | Código da moeda do capital social (ISO 4217). | | partyCapital.partyShareCapital.shareCapitalAmountType | string | Tipo de montante (ex: `ShareCapital`). | | partyCapital.partySalesVolume.salesVolumeAmountValue | number | Volume de vendas/facturação da empresa. | | partyCapital.partySalesVolume.salesVolumeAmountCurrency.currencyCode | string | Código da moeda do volume de vendas (ISO 4217). | | partyCapital.partySalesVolume.salesVolumeAmountType | string | Tipo de montante (ex: `SalesVolume`). | | partyCapital.partySalesVolume.salesVolumeReferenceYear | integer | Ano de referência do volume de vendas declarado. | | partyLegalStructureType.typeCode | string | Código da estrutura legal da empresa (ex: `Q`). | | partyLegalStructureType.typeDescription | string | Descrição da estrutura legal (ex: `Por Quotas`). | | governmentIssuedDocumentDetails.documentsReference\[] | array | Lista de documentos de identificação da empresa. | | governmentIssuedDocumentDetails.documentsReference\[].documentIdentification.identifierValue | string | Número do documento (ex: NIF/NPC da empresa). | | governmentIssuedDocumentDetails.documentsReference\[].documentType | string | Tipo de documento (ex: `NPC`). | | governmentIssuedDocumentDetails.documentsReference\[].documentIdentificationDescription | string | Categoria do documento (ex: `IdentificationDocument`). | | governmentIssuedDocumentDetails.documentsReference\[].documentDescription | string | Descrição do documento (ex: `Num Ident Fiscal (EMPRESA)`). | | governmentIssuedDocumentDetails.documentsReference\[].documentCountry.countryName.name | string | País emissor do documento. | | governmentIssuedDocumentDetails.documentsReference\[].documentCountry.countryCode | string | Código do país emissor (ISO). | | governmentIssuedDocumentDetails.documentsReference\[].documentStatus.statusReason | string | Estado do documento (ex: `Normal`). | | governmentIssuedDocumentDetails.documentsReference\[].documentValidityPeriod.fromDate.dateContent | string (ISO 8601) | Data de início de validade do documento. | | governmentIssuedDocumentDetails.documentsReference\[].documentValidityPeriod.toDate.dateContent | string (ISO 8601) | Data de fim de validade do documento. | | partyAdditionalAttribute\[] | array | Lista de atributos adicionais (regulatórios, AML, CIRC, comerciais) da empresa, em formato chave/valor. | | partyAdditionalAttribute\[].attributeCode | string | Código do atributo (ex: `EXPORT`, `RAML`, `CLMPME`). | | partyAdditionalAttribute\[].attributeDescription | string | Descrição do atributo. | | partyAdditionalAttribute\[].attributeValue | string | Valor do atributo. | > **Nota:** as tabelas de campos acima documentam apenas os campos observados nos exemplos fornecidos. `partyAdditionalAttribute[]` é uma estrutura extensível (chave/valor); a lista de `attributeCode` possíveis pode variar e não está limitada aos exemplos apresentados. ## 5. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | ---------------------------------------------------------------------------------- | | 200 | OK | Consulta executada com sucesso. | | 400 | Bad Request | Parâmetros inválidos ou em falta (ex: partyReferenceDataDirectoryId não indicado). | | 401 | Unauthorized | Token ausente, expirado ou inválido. | | 404 | Not Found | Rota não encontrada. | | 500 | Internal Server Error | Erro inesperado no sistema. | | 502 | Bad Gateway | Resposta inválida ou indisponibilidade do serviço. | | 504 | Gateway Timeout | Timeout na chamada do serviço. | ## 6. Envelope Padrão de Erro ```json { "status": 404, "reason": "RESOURCE_NOT_FOUND", "message": "Não foi encontrada nenhuma entidade para o identificador indicado.", "path": "/v1/party-reference-data-directory/12345/retrieve", "errors": [ { "code": "PTY-404-001", "reason": "PARTY_NOT_FOUND", "message": "partyReferenceDataDirectoryId '12345' não encontrado." } ] } ``` ### 6.1 Estrutura do Envelope de Erro | Campo | Tipo | Descrição | | ----------------- | ------- | ----------------------------------------------------------------------- | | status | integer | Código HTTP do erro. | | reason | string | Código textual de alto nível que identifica a categoria do erro. | | message | string | Mensagem legível que descreve o problema ocorrido. | | path | string | Caminho do endpoint que originou o erro. | | errors\[] | array | Lista de erros detalhados. Pode estar ausente em erros genéricos (500). | | errors\[].code | string | Código específico do domínio (ex: PTY-404-001). | | errors\[].reason | string | Identificador textual da causa específica do erro. | | errors\[].message | string | Mensagem detalhada com valores concretos quando aplicável. | ## 7. Regras de Negócio | # | Regra | Detalhe | | - | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Entidade Válida | O partyReferenceDataDirectoryId deve corresponder a uma entidade (party) existente no directório de dados de referência. | | 2 | Payload Variável por Tipo | A estrutura da resposta varia consoante `partyReference.partyType`: `Normal Particular` devolve campos de pessoa singular (estado civil, agregado familiar, residência fiscal, etc.); `Normal Empresa` devolve campos de pessoa colectiva (capital social, volume de vendas, estrutura legal, etc.). | | 3 | Campos Nulos em Documentos | Em `governmentIssuedDocumentDetails.documentsReference[].documentValidityPeriod`, `fromDate`/`toDate` podem ser devolvidos como `null` quando o tipo de documento não possui prazo de validade (ex: NIF). | | 4 | Atributos Adicionais | `partyAdditionalAttribute[]` é uma lista extensível de pares chave/valor usada para dados regulatórios e de risco (AML, PEP, CIRC, Fundo de Garantia de Depósitos, etc.); o conjunto de atributos devolvidos pode variar por cliente e por tipo de entidade. | ## 8. Requisitos Não-Funcionais | Requisito | Detalhe | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTPS / TLS | Obrigatório TLS 1.2 ou superior em todas as comunicações. | | Bearer Token | Obrigatório — scope party-reference-data-directory:retrieve. Pedidos sem token ou com token inválido retornam 401. | | Auditoria | Registo persistente obrigatório de todas as consultas (log estruturado). | | Dados Sensíveis | A resposta contém dados pessoais e sensíveis (PII, informação financeira, AML/PEP); o acesso deve respeitar as políticas de protecção de dados e minimização de exposição da informação. |