> 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-asset-administration/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 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": "" } } ] } ``` ### 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. Máx. 15. | *** ## 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 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. | *** ## 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). | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://selenium-4.gitbook.io/nexus-docs/docs/collateral-asset-administration/create-collateral-asset-account/main.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.