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 das averbações e alterações, é possível consultar os Contratos de diversas formas. Segue 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
Você também poderá realizar uma nova Consulta de Posição de Agenda por Titular para verificar se todos os contratos enviados estão sendo refletidos em seus respectivos alvos.
Caso tenha passado a ser titular de Obrigações de Liquidação após o envio de contratos de Alteração de Titularidade, realize uma nova Consulta de Posição de Agenda por Titular utilizando seu próprio CNPJ no parâmetro documentNumber para verificar os recebíveis sob sua titularidade.
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:
- Desenvolver a integração com o serviço Ônus e Gravames ou Alteração de Titularidade;
- Realizar a Consulta dos Contratos Enviados.
Updated 17 days ago