2.4 Averbação de Contratos

Significado dos Campos

O significado de cada um dos campos do Payload que podem conter na criação de um contrato ou em uma notificação de criação dele, se encontra disponível na seção Dicionário de Campos do Payload. Porém, é importante lembrar que para cada tipo de contrato pode ou não haver todos eles:

1 - Averbação de Ônus e Gravames ou Alteração de Titularidade

A Averbação de Ônus e Gravames ou Alteração de Titularidade, bem como as demais operações de registro e alteração da API, funciona de forma assíncrona. Portanto, a resposta destes EndPoints têm duas etapas: resposta de aceite da requisição e notificação de processamento.

📘
Dica
A chave de idempotência (idempotencyKey) serve para evitar que você envie duas vezes uma mesma requisição de maneira equivocada. Esse campo aceita apenas informações em GUID.
Para fins de testes, aconselhamos que o parâmetro seja omitido nos envios durante a execução dos exercícios.

Acesse a referência da API - Averbação de Ônus e Gravames e Alteração de Titularidade para uma melhor experiência. Seguem abaixo, exemplos de arquivo JSON para o preenchimento:

Exemplo 1: Averbação de Ônus e Gravames com regra de repartição fixedAmount.

{
 "processReference":"referencia",
 "contractInfo":[
   {
   "reference":"CG_15",
   "contractDueDate":"2020-10-13",
   "assetHolderDocumentType":"CPF,CNPJ",
   "assetHolder":"99999999999999",
   "contractUniqueIdentifier":"12100000123",
   "signatureDate":"2020-10-13",
   "effectType":"warranty",
   "warrantyType":"fiduciary,pledge", 
   "warrantyAmount":8000000,
   "balanceDue":8000000, 
   "divisionMethod":"fixedAmount",
   "effectStrategy":"specific",
   "BankAccount":
       {
        "branch":"3232",
        "account":"00121",
        "accountDigit":"X3",
        "accountType":"CC",
        "ispb":"12100000",
        "documentType":"CNPJ",
        "documentNumber":"77777777777777"
       },
   "contractSpecifications":
     [
       {
         "expectedSettlementDate":"2021-11-01",
         "originalAssetHolderDocumentType":"CNPJ",
         "originalAssetHolder":"99999999999999",
         "receivableDebtor":"88888888888888",
         "paymentScheme":"VCC",
         "effectValue":8000000
       }
     ]
   }
 ]
};

Exemplo 2: Averbação de Ônus e Gravames com regra de repartição percentage.

{
 "contractInfo":[
   {
   "reference":"CG_15",
   "contractDueDate":"2020-10-13",
   "assetHolderDocumentType":"CPF,CNPJ",
   "assetHolder":"99999999999999",
   "contractUniqueIdentifier":"12100000123",
   "signatureDate":"2020-10-13",
   "effectType":"warranty",
   "warrantyType":"fiduciary,pledge", 
   "warrantyAmount":8000000,
   "balanceDue":8000000, 
   "divisionMethod":"percentage",
   "effectStrategy":"specific",
   "percentageValue":10000, 
   "bankAccount":
       {
        "branch":"3232",
        "account":"00121",
        "accountDigit":"X3",
        "accountType":"CC",
        "ispb":"12100000",
        "documentType":"CNPJ",
        "documentNumber":"77777777777777"
       },
   "contractSpecifications":
     [
       {
         "expectedSettlementDate":"2021-11-01",
         "originalAssetHolderDocumentType":"CNPJ",
         "originalAssetHolder":"99999999999999",
         "receivableDebtor":"88888888888888",
         "paymentScheme":"VCC",
       }
     ]
   }
 ]
};

Exemplo 3: Averbação de Alteração de Titularidade com regra de repartição fixedAmount.

{
 "contractInfo":[
   {
   "reference":"CG_15",
   "contractDueDate":"2020-10-13",
   "assetHolderDocumentType":"CPF,CNPJ",
   "assetHolder":"99999999999999",
   "contractUniqueIdentifier":"12100000123",
   "signatureDate":"2020-10-13",
   "effectType":"ownershipAssignment",
   "balanceDue":8000000, 
   "divisionMethod":"fixedAmount",
   "effectStrategy":"specific",
   "bankAccount":
       {
        "branch":"3232",
        "account":"00121",
        "accountDigit":"X3",
        "accountType":"CC",
        "ispb":"12100000",
        "documentType":"CNPJ",
        "documentNumber":"77777777777777"
       },
   "contractSpecifications":
     [
       {
         "expectedSettlementDate":"2021-11-01",
         "originalAssetHolderDocumentType":"CNPJ",
         "originalAssetHolder":"99999999999999",
         "receivableDebtor":"88888888888888",
         "paymentScheme":"VCC",
         "effectValue":8000000
       }
     ]
   }
 ]
};

Exemplo 4: Averbação de Troca de Titularidade com regra de repartição percentage.

{
 "contractInfo":[
   {
   "reference":"CG_15",
   "contractDueDate":"2020-10-13",
   "assetHolderDocumentType":"CPF,CNPJ",
   "assetHolder":"99999999999999",
   "contractUniqueIdentifier":"12100000123",
   "signatureDate":"2020-10-13",
   "effectType":"ownershipAssignment",
   "balanceDue":8000000, 
   "divisionMethod":"percentage",
   "effectStrategy":"specific",
   "percentageValue":10000, 
   "bankAccount":
       {
        "branch":"3232",
        "account":"00121",
        "accountDigit":"X3",
        "accountType":"CC",
        "ispb":"12100000",
        "documentType":"CNPJ",
        "documentNumber":"77777777777777"
       },
   "contractSpecifications":
     [
       {
         "expectedSettlementDate":"2021-11-01",
         "originalAssetHolderDocumentType":"CNPJ",
         "originalAssetHolder":"99999999999999",
         "receivableDebtor":"88888888888888",
         "paymentScheme":"VCC",
       }
     ]
   }
 ]
};

Em caso de envio correto da Averbação, você receberá uma resposta com status code 202. Caso tenha tido algum preenchimento errôneo, receberá um status code 400 (bad request).

2 - Alteração de Averbação de Ônus de Gravames ou Alteração de Titularidade

Uma Alteração de Averbação tem por objetivo alterar os termos de um contrato. No entanto, dentro do Payload do Contrato, há campos que são imutáveis e, caso algum deles precisem de alteração, a averbação deve ser cancelada, e uma nova averbação deve ser firmada. Os campos imutáveis são:

key
assetHolder
assetHolderdocumentType
reference
signatureDate
effectType
divisionMethod
effectStrategy

Acesse a referência da API - Alteração de Averbação de Ônus e Gravames ou Alteração de Titularidade para uma melhor experiência. Seguem abaixo, exemplos de arquivo JSON para o preenchimento:

Exemplo 1: Averbação com regra de repartição fixedAmount.

{
 "contracts": [
 {
  "key": "e07d6c53-7dc0-429d-a1da-d76f955f6dfd",
  "isCanceled": true,
  "contractDueDate": "2020-10-13",
  "contractUniqueIdentifier":"12100000123",
  "warrantyAmount":"8000000",
  "balanceDue":8000000,
  "bankAccount":
  {
   "branch":"3232",
   "account":"00121",
   "accountDigit":"X3",
   "accountType":"CC",
   "ispb":"12100000",
   "documentType":"CNPJ",
   "documentNumber":"0000000000000"
  },
  "contractSpecifications":
   [
    {
     "expectedSettlementDate": "2021-11-01",
     "originalAssetHolderDocumentType": "CNPJ",
     "originalAssetHolder":"99999999999999",
     "receivableDebtor":"88888888888888",
     "paymentScheme":"VCC",
     "effectValue": 10
    }
   ]
  }
 ]
};

Exemplo 2: Averbação com regra de repartição percentage.

{
 "contracts": [
 {
  "key":"e07d6c53-7dc0-429d-a1da-d76f955f6dfd",
  "isCanceled":false,
  "contractDueDate":"2020-10-13",
  "contractUniqueIdentifier":"12100000123",
  "warrantyAmount":"100000",
  "balanceDue":100000,
  "percentageValue":1000,
  "bankAccount":
  {
   "branch": "3232",
   "account": "00121",
   "accountDigit": "X3",
   "accountType": "CC",
   "ispb": "12100000",
   "documentType": "CNPJ",
   "documentNumber": "0000000000000"
  },
  "contractSpecifications":
   [
    {
     "expectedSettlementDate": "2021-11-01",
     "originalAssetHolderDocumentType": "CNPJ",
     "originalAssetHolder": "99999999999999",
     "receivableDebtor": "88888888888888",
     "paymentScheme": "VCC",
    }
   ]
  }
 ]
};

3 - Consulta de Contrato

Após o envio dos contratos e alterações, realize uma nova Consulta de Posição de Agenda por Titular e verifique se todos os contratos enviados estão sendo refletidos em seus respectivos alvos.

Em seguida, realize uma nova Consulta de Posição de Agenda por Titular utilizando seu próprio CNPJ no parâmetro documentNumber para verificar se as Obrigações de Liquidação às quais você é titular, devido aos contratos de Alteração de Titularidade aparecem em suas próprias agendas.

Existem diversas formas de se consultar um Contrato criado. Seguem abaixo como realizar cada uma delas:

Consulta de Ônus e Gravames/Alteração de Titularidade por ProcessKey
Consulta de Ônus e Gravames ou Alteração de Titularidade por Chave
Consulta de Ônus e Gravames/Alteração de Titularidade por Referência
Consulta de Ônus e Gravames/Alteração de Titularidade por Parâmetros

A chamada do endpoint da Consulta de Ônus e Gravames/Alteração de Titularidade por Parâmetros deve conter os parâmetros de identificação da Averbação de Ônus e Gravames/Alteração de Titularidade a ser consultada, por query, podendo utilizar os parâmetros abaixo:

startContractDueDate
endContractDueDate
contractDebtor
contractHolder
startSignatureDate
endSignatureDate
endSignatureDate
startCreatedAt
endCreatedAt
perPage
page

Consulta de Notificação de Contrato

Como o EndPoint de Averbação de Ônus e Gravames ou Alteração de Titularidade é assíncrono, ao receber uma averbação válida, uma resposta de aceite será retornada. Em seguida, uma notificação será disponibilizada para consulta ou enviada caso o participante tenha o webhook cadastrado, com o estado do processamento juntamente com os dados de cada objeto.

Caso deseje consultar a Notificação criada pela Averbação do Contrato, utilize o EndPoint de Notificação de Averbação de Contrato ou a Consulta de Notificação por Chave, nesse segundo caso, utilizando a chave do Contrato criado. Segue um exemplo de notificação de Contrato, ou seja, onde o eventType é do tipo contract:

{
    "Key": "39836816-2a2d-4af6-87d1-5370ad59d8fa",
    "Status": "Error",
    "ParticipantDocument": "31345107000103",
    "Message": "No client info",
    "EventType": "Contract",
    "Data": {
        "notificationReferenceDate": "2022-11-17T22:28:58.6514078Z",
        "notificationRecipientDocumentType": "CNPJ",
        "notificationRecipient": "31688539000109",
        "contractInfo": {
            "key": "09775d9a-7d49-5ef9-6600-65c2e4c66784",
            "isCanceled": true,
            "contractDueDate": "2022-10-11T00:00:00",
            "contractHolderDocumentType": "CNPJ",
            "contractHolder": "31688539000109",
            "assetHolderDocumentType": "CNPJ",
            "assetHolder": "01030087000102",
            "contractUniqueIdentifier": "3168853900010902162010300870001021249399",
            "signatureDate": "2021-05-20T00:00:00",
            "effectType": "Warranty",
            "warrantyType": "Fiduciary",
            "warrantyAmount": 49525,
            "balanceDue": 49525,
            "divisionMethod": "Percentage",
            "percentageValue": 10000,
            "effectStrategy": "Specific",
            "bankAccount": {
                "uniqueId": "655151b7-1894-4903-b8d9-2dd29fc7e147",
                "branch": "123456",
                "account": "47990",
                "accountDigit": "3",
                "accountType": "CC",
                "ispb": "90400888",
                "documentType": "CNPJ",
                "documentNumber": "01030087000102",
                "createdAt": "0001-01-01T00:00:00",
                "updatedAt": "0001-01-01T00:00:00"
            },
            "settlementExpectationAffected": [],
            "contractStatus": "Canceled"
        },
        "eventType": "Canceled",
        "eventSource": "ContractHolder",
        "processKey": "b88d05bf-7466-4f5a-95e1-172fc451413d",
        "createdAt": "2022-11-07T12:00:04.774979Z",
        "hasError": false,
        "contractSpecificationsCount": 0
    }}

O significado de cada um dos campos do Payload se encontra disponível na seção Dicionário de Campos do Payload.

🚧
To-dos de Desenvolvimento

Ler a documentação e entender os conceitos abaixo:

Averbação de Unidades de Recebíveis;

Alteração de Titularidade;

Garantia (Ônus e Gravames);

Desenvolver a integração com o serviço Ônus e Gravames ou Alteração de Titularidade;

Realizar a Consulta dos Contratos Enviados.

2.4 Averbação de Contratos

Significado dos Campos

1 - Averbação de Ônus e Gravames ou Alteração de Titularidade

📘
Dica

Exemplo 1: Averbação de Ônus e Gravames com regra de repartição fixedAmount.

Exemplo 2: Averbação de Ônus e Gravames com regra de repartição percentage.

Exemplo 3: Averbação de Alteração de Titularidade com regra de repartição fixedAmount.

Exemplo 4: Averbação de Troca de Titularidade com regra de repartição percentage.

2 - Alteração de Averbação de Ônus de Gravames ou Alteração de Titularidade

Exemplo 1: Averbação com regra de repartição fixedAmount.

Exemplo 2: Averbação com regra de repartição percentage.

3 - Consulta de Contrato

Consulta de Notificação de Contrato

🚧
To-dos de Desenvolvimento

Significado dos Campos

1 - Averbação de Ônus e Gravames ou Alteração de Titularidade

📘Dica

Exemplo 1: Averbação de Ônus e Gravames com regra de repartição fixedAmount.

Exemplo 2: Averbação de Ônus e Gravames com regra de repartição percentage.

Exemplo 3: Averbação de Alteração de Titularidade com regra de repartição fixedAmount.

Exemplo 4: Averbação de Troca de Titularidade com regra de repartição percentage.

2 - Alteração de Averbação de Ônus de Gravames ou Alteração de Titularidade

Exemplo 1: Averbação com regra de repartição fixedAmount.

Exemplo 2: Averbação com regra de repartição percentage.

3 - Consulta de Contrato

Consulta de Notificação de Contrato

🚧To-dos de Desenvolvimento

📘
Dica

🚧
To-dos de Desenvolvimento