> 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/collateral-asset-administration/operacoes/main.md). # Create Collateral Asset Account | Campo | Valor | | ------------------ | ------------------------------------------------- | | **Service Domain** | Collateral Asset Administration | | **BIAN Version** | 14.0.0 | | **Operation** | Create Collateral Asset Account | | **Method** | POST | | **API Name** | Collateral API | | **Versão** | v1.0.0 | | **Endpoint** | `POST /v1/collateral-asset-administration/create` | | **Autenticação** | Bearer Token (OAuth 2.0 / OIDC) | *** ## 1. Descrição da Operação O serviço de Abertura de Conta de Garantia Recebida permite registar e associar uma garantia a um cliente ou contrato de crédito. A operação cria uma conta de garantia no sistema, identificando o tipo de colateral, o valor de avaliação, a data de maturidade e os activos subjacentes. *** ## 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. Payload de Pedido (Request) ### 3.1 Exemplo ```json { "collateralAssetCustomerReference": "123456", "collateralAssetAccountReference": { "collateralAssetAccountType": "GAR_DP_COL", "collateralAssetAccountProductReference": "FINANC", "collateralAssetType": "01", "collateralAssetValuationAmount": { "amountValue": 100000.00, "amountCurrency": { "currencyCode": "AOA" } }, "collateralAssetPledgedDate": { "dateContent": "2026-01-01", "dateType": "MaturityDate" } }, "collateralAssets": [ { "assetAccountReference": "{{DP-Account}}", "asseValuationAmount": { "amountValue": 100000.00, "amountCurrency": { "currencyCode": "AKZ" }, "AmountType": "Principal" }, "assetValuationDate": { "dateContent": "2026-01-01", "dateType": "MaturityDate" }, "assetClassProperties": { "assetClassType": "", "assetMarketReference": "", "assetQuantity": 2, "assetISIN": "", "assetDossier": "" } } ], "additionalAttributes": [ { "attributeCode": "HAIRCU", "attributeValue": "10" } ] } ``` ### 3.2 Objecto Raiz | Campo | Tipo | Obrigatório | Descrição | | ---------------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `collateralAssetCustomerReference` | string | Sim | Identificador único do cliente. | | `collateralAssetAccountReference` | object | Sim | Dados de configuração da conta de garantia a criar. | | `collateralAssets` | array | Sim | Lista de activos que compõem a garantia. Deve conter pelo menos um elemento. | | `additionalAttributes` | array | Condicional | Lista de atributos de caracterização da garantia (ex: haircut). Obrigatório quando `collateralAssetAccountType` = `GAR_REC`. Ver secção 3.5. | ### 3.3 Objecto: `collateralAssetAccountReference` | Campo | Tipo | Obrigatório | Descrição | | ------------------------------------------------------------ | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `collateralAssetAccountType` | string | Sim | Código do Componente (ex: `GAR_DP_COL`, `GAR_REC`). Quando `GAR_REC`, é obrigatório o envio do atributo `HAIRCU` em `additionalAttributes`. | | `collateralAssetAccountProductReference` | string | Sim | Referência do produto associado. | | `collateralAssetType` | string (enum) | Sim | Código do tipo de garantia. Ver tabela da secção 4. | | `collateralAssetValuationAmount.amountValue` | BigDecimal (>= 0) | Sim | Valor da garantia. | | `collateralAssetValuationAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim | Código de moeda (ex: `AKZ`, `USD`, `EUR`). | | `collateralAssetPledgedDate.dateContent` | string (ISO 8601) | Sim | Data de vencimento da garantia. Formato: `YYYY-MM-DD`. | | `collateralAssetPledgedDate.dateType` | string | Sim | Tipo de data (ex: `MaturityDate`). | ### 3.4 Objecto: `collateralAssets[]` | Campo | Tipo | Obrigatório | Descrição | | ------------------------------------------------- | ----------------- | ----------- | ------------------------------------------------------- | | `assetAccountReference` | string | Sim | Número da conta do activo (ex: número de uma conta DP). | | `asseValuationAmount.amountValue` | decimal | Sim | Valor do activo. | | `asseValuationAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim | Moeda do activo. | | `asseValuationAmount.AmountType` | string | Não | Tipo de montante (ex: `Principal`). | | `assetValuationDate.dateContent` | string (ISO 8601) | Sim | Data de valorização do activo. Formato: `YYYY-MM-DD`. | | `assetValuationDate.dateType` | string | Sim | Tipo de data (ex: `MaturityDate`). | | `assetClassProperties.assetClassType` | string | Não | Classe do activo (ex: `Bonds/Titulos`). | | `assetClassProperties.assetMarketReference` | string | Não | Mercado de referência do activo (ex: `BODIVA`). | | `assetClassProperties.assetQuantity` | integer | Não | Quantidade de títulos. | | `assetClassProperties.assetISIN` | string | Não | Código ISIN do título. | | `assetClassProperties.assetDossier` | string | Não | Referência do dossier associado ao activo. Máx. 15. | ### 3.5 Objecto: `additionalAttributes[]` Permite enviar elementos adicionais de caracterização da garantia, sob a forma de pares código/valor. | Campo | Tipo | Obrigatório | Descrição | | ---------------- | ------ | ----------- | ------------------------------------------------------- | | `attributeCode` | string | Sim | Código do atributo de caracterização. Ver tabela 3.5.1. | | `attributeValue` | string | Sim | Valor do atributo. | #### 3.5.1 Códigos de Atributo Suportados | Elemento | Descritivo | Interpretação | | -------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CIDFGG` | Identificação Garantia (Fundo Garantias) | Indica se a garantia é prestada por um fundo de garantia, como o FGC de Angola. Provavelmente leva S/N ou o código/identificação do fundo. | | `TIPAVG` | Tipo de avaliação | Como o bem dado em garantia foi avaliado: avaliação interna, avaliador externo independente, valor de mercado, etc. Deve ser um código de uma tabela do BNA. | | `IEXGAR` | Indicador de execução de garantia | Indica se a garantia já foi executada, ou seja, se o banco já a acionou por incumprimento (S/N). | | `MTEGAR` | Montante de execução da garantia | Valor recuperado ou executado quando a garantia foi acionada. Fica a 0 se não houve execução. | | `CCTRGA` | Código contraparte garantia | Código de quem presta a garantia (o garante), que pode ser diferente do devedor. Normalmente é o nº de cliente ou o código CIRC da contraparte. | | `NIFCTR` | NIF contraparte garantia | NIF desse garante. | | `HAIRCU` | Haircut atribuído | Percentagem de desconto aplicada ao valor da garantia para refletir risco de desvalorização ou de liquidez. Por exemplo, uma garantia de 100 com 10% de haircut conta como 90. | | `VLCOFI` | Valor colateral financeiro | Valor das garantias financeiras (depósitos, títulos) dadas como colateral. | | `VLRGAT` | Valor garantia de terceiros | Valor coberto por garantias de terceiros, como avales, fianças ou garantias bancárias. | | `DTVEND` | Data da venda | Data em que o bem dado em garantia foi vendido, depois de executado ou recuperado. É provável que use o formato AAAAMMDD, e talvez fique em branco se não houve venda. | | `MTLQVD` | Montante líquido da venda | Valor recebido na venda do bem, já descontados os custos. | | `CUSTRE` | Custo da recuperação | Custos estimados ou incorridos para recuperar a garantia (judiciais, advogados, etc.). | | `CUSTVD` | Custo de venda | Custos associados à venda do bem (comissões, impostos, avaliações). | | `TPEREC` | Tempo estimado até à recuperação | Tempo previsto até conseguir recuperar o bem, provavelmente em meses. | | `TPEVND` | Tempo estimado até à venda | Tempo previsto até conseguir vender o bem depois de recuperado, provavelmente em meses. | #### 3.5.2 Haircut O **haircut** é uma redução percentual aplicada ao valor de um activo dado como garantia, para reflectir os riscos associados a esse activo. > **Componente `GAR_REC`:** sempre que a conta de garantia for criada com o componente `GAR_REC`, o pedido deve incluir em `additionalAttributes` um elemento com `attributeCode` = `HAIRCU` e o respectivo `attributeValue`. Exemplo para o componente `GAR_REC`: ```json { "collateralAssetAccountReference": { "collateralAssetAccountType": "GAR_REC", "...": "..." }, "additionalAttributes": [ { "attributeCode": "HAIRCU", "attributeValue": "10" } ] } ``` *** ## 4. Tipos de Garantia | Valor | Descrição | | ----- | -------------------------------------------------------------- | | 00 | Ausência de garantias | | 01 | Caução - Depósitos junto da própria Instituição | | 02 | Caução - Depósitos junto de outras Instituições | | 03 | Caução - Títulos públicos | | 04 | Caução - Outros títulos de rendimento fixo | | 05 | Caução - Títulos de rendimento variável | | 06 | Apólices de seguro de vida de natureza financeira | | 07 | Alienação fiduciária | | 08 | Hipoteca - Crédito à habitação, LTV > 75% | | 09 | Hipoteca - Crédito à habitação, LTV < 75% | | 10 | Hipoteca - Outros fins | | 11 | Penhor mercantil | | 12 | Penhor rural | | 13 | Penhor cível | | 14 | Seguros e equiparados | | 15 | Garantias bancárias (créditos documentários e cartas-conforto) | | 16 | Coobrigações | | 17 | Fiança bancária | | 18 | Outras fianças | | 19 | Avais governamentais | | 20 | Outros avais | | 21 | Procuração irrevogável para constituição de hipoteca | | 22 | Outras garantias pessoais | *** ## 5. Payload de Resposta (Response — 200 OK) ```json { "CollateralAssetReference": { "collateralAssetAccountIdentification": { "collateralAssetAccountIdentifierValue": "20381023" }, "CollateralAssetStatus": "Normal" } } ``` ### 5.1 Campos da Resposta | Campo | Tipo | Descrição | | ----------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------- | | `CollateralAssetReference.collateralAssetAccountIdentification.collateralAssetAccountIdentifierValue` | string | Número da conta de garantia criada no sistema. | | `CollateralAssetReference.CollateralAssetStatus` | string | Estado actual da conta de garantia. | *** ## 6. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | ---------------------------------------------------------------------------------------------------- | | 200 | OK | Conta de garantia criada com sucesso. | | 400 | Bad Request | Payload inválido: campos obrigatórios em falta, datas inconsistentes ou moeda inválida. | | 401 | Unauthorized | Token ausente, expirado ou inválido. | | 403 | Forbidden | Cliente autenticado mas sem permissão para executar esta operação. | | 404 | Not Found | Cliente ou conta de activo referenciada inexistente ou endpoint não encontrado. | | 409 | Conflict | Conta de garantia já existente para o mesmo cliente e activo. | | 422 | Unprocessable Entity | Regra de negócio violada: tipo de garantia inválido, valor de avaliação nulo, moeda divergente, etc. | | 500 | Internal Server Error | Erro inesperado no sistema. | | 502 | Bad Gateway | Resposta inválida ou indisponibilidade do core bancário. | | 504 | Gateway Timeout | Timeout na chamada ao core bancário. | *** ## 7. Envelope Padrão de Erro ```json { "status": 422, "reason": "BUSINESS_RULE_VIOLATION", "message": "Tipo de garantia inválido ou não suportado para o produto indicado.", "path": "/v1/collateral/asset-accounts", "errordetail": [ { "code": "COL-422-001", "reason": "INVALID_COLLATERAL_TYPE", "message": "collateralAssetType '99' não consta da tabela de tipos de garantia suportados." } ] } ``` ### 7.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. | | `errordetail[]` | array | Lista de erros detalhados. Pode estar ausente em erros genéricos (500). | | `errordetail[].code` | string | Código específico do domínio (ex: `COL-422-001`). | | `errordetail[].reason` | string | Identificador textual da causa específica do erro. | | `errordetail[].message` | string | Mensagem detalhada com valores concretos quando aplicável. | *** ## 8. Regras de Negócio | # | Regra | Detalhe | | - | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 1 | Cliente Válido | O `collateralAssetCustomerReference` deve corresponder a um cliente activo e existente no sistema. | | 2 | Tipo de Garantia | O valor de `collateralAssetType` deve constar da tabela de tipos suportados (secção 4). | | 3 | Valor de Avaliação | `amountValue` deve ser maior que zero. | | 4 | Consistência de Moeda | A moeda dos activos em `collateralAssets` deve coincidir com a moeda definida em `collateralAssetValuationAmount`. | | 5 | Activos Obrigatórios | O array `collateralAssets` deve conter pelo menos um elemento válido. | | 6 | Haircut no Componente `GAR_REC` | Quando `collateralAssetAccountType` = `GAR_REC`, `additionalAttributes` deve conter um elemento com `attributeCode` = `HAIRCU`. | *** ## 9. Requisitos Não-Funcionais | Requisito | Detalhe | | ------------ | ----------------------------------------------------------------------- | | HTTPS / TLS | Obrigatório TLS 1.2 ou superior em todas as comunicações. | | Bearer Token | Obrigatório. Pedidos sem token ou com token inválido retornam 401. | | Auditoria | Registo persistente obrigatório de todas as criações (log estruturado). |