> 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/docs/collateral-allocation-management/create-collateral-asset-account/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 Asset Administration 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": "AKZ" } }, "collateralAssetPledgedDate": { "dateContent": "2026-01-01", "dateType": "MaturityDate" } }, "collateralAssets": [ { "assetAccountReference": "{{DP-Account}}", "asseValuationAmount": { "amountValue": 100000.00, "amountCurrency": { "currencyCode": "AOA" }, "AmountType": "Principal" }, "assetValuationDate": { "dateContent": "2026-01-01", "dateType": "MaturityDate" }, "assetClassProperties": { "assetClassType": "Bonds/Titulos", "assetMarketReference": "BODIVA", "assetQuantity": 2, "assetISIN": "BAIOAAAA", "assetDossier": "15100144-54541-1100" } } ] } ``` ### 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. | ### 3.3 Objecto: `collateralAssetAccountReference` | Campo | Tipo | Obrigatório | Descrição | | ------------------------------------------------------------ | ----------------- | ----------- | ------------------------------------------------------ | | `collateralAssetAccountType` | string | Sim | Código do Componente. | | `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 | Sim | 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. | *** ## 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 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 scope para `collateral:asset-accounts:create`. | | 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 | **Protecção contra Duplicação** | O sistema verifica a existência prévia de uma conta de garantia para o mesmo cliente e activo. Se já existir, devolve 409 Conflict sem criar duplicado. | *** ## 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 — scope `collateral:asset-accounts:create`. Pedidos sem token ou com token inválido retornam 401. | | **Auditoria** | Registo persistente obrigatório de todas as criações (log estruturado). | | **Logging Estruturado** | Todos os logs devem incluir o campo `x-request-id` para correlação de pedidos. | | **Idempotência** | A operação deve ser protegida contra duplicação via verificação de existência prévia antes do processamento. |