---
title: "rib"
description: "Additional requirements for integrating Rest PKI Core with the Assinador Web of Registro de Imóveis do Brasil (RIB), such as the required cartorio and cns metadata."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/rib"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-11-10"
---

# Additional integration requirements - RIB

The integration with the **Assinador Web** of the **Registro de Imóveis do Brasil - RIB** has some additional requirements not mentioned in the
rest of this documentation.

## Required metadata

When creating [signature sessions](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions), you must provide the following required [metadata](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions/document-metadata):

* `cartorio`: name of the issuing registry office (*cartório*); this value is shown on the document validation page
* `cns`: CNS (*Código Nacional de Serventia*, the national registry office code) of the issuing registry office

The CNS can be given in any of the forms below:

* `1234` (digits only)
* `001234` (with leading zeros)
* `00.123-4` (fully formatted)

In .NET:

```cs
var response = await restPkiService.CreateSignatureSessionAsync(new CreateSignatureSessionRequest() {
	...
}, metadata: new NameValueCollection {
	["cartorio"] = "XXº Oficial de Registro de Imóveis do Município - UF",
	["cns"] = "123456",
});
```

In PHP:

```PHP
$request = new CreateSignatureSessionRequest();
...
$request->documentMetadata = [
	"cartorio" => "XXº Oficial de Registro de Imóveis do Município - UF",
	"cns" => "123456"
];
```

In Java:

```java
CreateSignatureSessionRequest request = new CreateSignatureSessionRequest();
...
List<String> firstElement = new ArrayList<>();
firstElement.add("XXº Oficial de Registro de Imóveis do Município - UF");
request.putDocumentMetadataItem("cartorio", firstElement);

List<String> secondElement = new ArrayList<>();
secondElement.add("123456");
request.putDocumentMetadataItem("cns", secondElement);
```

If you are calling the API directly:

```plaintext
POST {endpoint}/api/signature-sessions
{
	...,
	"documentMetadata": {
		"cartorio": ["XXº Oficial de Registro de Imóveis do Município - UF"],
		"cns": ["123456"]
	}
}
```

Besides the metadata above, every document on the Assinador Web also has the `validade` metadata, in the `yyyy-mm-dd` format, for instance
*2021-04-01* (April 1st, 2021). This metadata is assigned to documents automatically, counting 30 days from the signature date, and **cannot be
specified** when creating the session.

## Allocating document validation keys

The document validation key, sometimes called "hash" in the context of RIB processes, is the alphanumeric code printed on the margin of the
document that lets it be looked up later:

![Document key](https://docs.lacunasoftware.com/images/rest-pki/core/rib/document-key.png)

When signing the document, the user may enter the validation key that the document should have, instead of having the system generate a new
random key:

![Document key input](https://docs.lacunasoftware.com/images/rest-pki/core/rib/document-key-input.png)

Real estate registry offices must be able to allocate validation keys for later use through the service centers (*centrais de serviços*). To
do so, your service center must call the document key allocation API. This call requires the same metadata described above:

In .NET:

```cs
// Allocate one key
var documentKey = await restPkiService.AllocateDocumentKeyAsync(new NameValueCollection {
	["cartorio"] = "XXº Oficial de Registro de Imóveis do Município - UF",
	["cns"] = "123456",
});

// Allocate N keys
var documentKeys = await restPkiService.AllocateDocumentKeysAsync(10, new NameValueCollection {
	["cartorio"] = "XXº Oficial de Registro de Imóveis do Município - UF",
	["cns"] = "123456",
});
```

In PHP:

```PHP
$defaultDocumentMetadata = [
    "cartorio" => "XXº Oficial de Registro de Imóveis do Município - UF", 
    "cns" => "123456"
];
// Allocate one key
$documentKey = $service->allocateDocumentKey($defaultDocumentMetadata);
// Allocate N keys
$documentKeys = $service->allocateDocumentKeys(10, $defaultDocumentMetadata);
```

In Java:

```java
Map<String, List<String>> defaultDocumentMetadata = new HashMap<>();
List<String> firstElement = new ArrayList<>();
firstElement.add("XXº Oficial de Registro de Imóveis do Município - UF");
defaultDocumentMetadata.put("cartorio", firstElement);
List<String> secondElement = new ArrayList<>();
secondElement.add("123456");
defaultDocumentMetadata.put("cns", secondElement);

// Allocate one key
DocumentKeyModel documentKey = service.allocateDocumentKey(defaultDocumentMetadata);

// Allocate N keys
List<DocumentKeyModel> documentKeys = service.allocateDocumentKeys(10, defaultDocumentMetadata);
```

If you are calling the API directly:

```plaintext
// Allocate one key
POST {endpoint}/api/document-keys
{
	"provisionalMetadata": {
		"cartorio": ["XXº Oficial de Registro de Imóveis do Município - UF"],
		"cns": ["123456"]
	}
}

// Allocate N keys
POST {endpoint}/api/document-keys/batch
{
	"count": 10,
	"provisionalMetadata": {
		"cartorio": ["XXº Oficial de Registro de Imóveis do Município - UF"],
		"cns": ["123456"]
	}
}
```

The `provisionalMetadata` parameter of the key allocation tells which registry office is responsible for submitting the document that will
have a given key, so that the system can show this information if the key is used to look up documents:

![Pending document key](https://docs.lacunasoftware.com/images/rest-pki/core/rib/pending-document-key.png)

## Generating API keys for the command-line tool

Real estate registry offices will have a [command-line tool](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/client-tool) available to sign documents from their *desktop*
applications. Using this tool requires an **API key**.

Real estate registry offices must be able to generate API keys for the tool through the service centers. To do so, your service center must
implement logic similar to the following:

1.	Check in your database whether an *application* has already been created on the Assinador Web for the registry office in question
   * If not, create an *application* specifying:
     1. *roles*: `Worker`
     1. *defaultDocumentMetadata*: CNS and name of the registry office (following the rules described above)
1.	Store the resulting `applicationId` in your database, associated with the registry office
1.	Create an *application key*, passing the registry office's `applicationId`, and show the result to the user

Example in .NET:

```cs
var cartorio = ... // registry office entity in the service center's system
if (cartorio.AssinadorWebAppId == null) {
   var metadata = new NameValueCollection {
      ["cns"] = cartorio.Cns,
      ["cartorio"] = cartorio.Nome,
   };
   var app = await restPkiService.CreateApplicationAsync($"CENTRAL-{cartorio.Cns}", new[] { Roles.Worker }, metadata);
   cartorio.AssinadorWebAppId = app.Id;
   Save();
}
var appKey = await restPkiService.CreateApplicationKeyAsync(cartorio.AssinadorWebAppId.Value, description: $"Generated by {User.Name}");
return appKey.Key;
```

Some important points:

* The `$"CENTRAL-{cartorio.Cns}"` parameter is the application name. These names must be unique on the Assinador Web, regardless of the
  service center. Hence the suggestion of using the CNS prefixed with an identifier that refers to the name of the service center (for
  instance, `OE-` for Ofício Eletrônico)
* For security reasons, the Assinador Web does not store the generated API key (only its hash). Service centers should do the same: each
  time a registry office asks for an API key, a new key is generated (but not a new application)
* The `description` field in the call to `CreateApplicationKeyAsync` is optional and can be used to record the user who triggered the key
  generation

In PHP:

```PHP
$cartorio = ... // registry office entity in the service center's system
if($cartorio->assinadorWebAppId == null){
	$name = "CENTRAL-" . $cartorio->cns;
	$roles = [Roles::WORKER];
	$metadata = [
		"cartorio" => $cartorio->nome,
		"cns" => $cartorio->cns
	];
	$app = $service->createApplication($name, $roles, $metadata);
	$cartorio->assinadorWebAppId = $app->id;
}
$appKey = $service->createApplicationKey($cartorio->assinadorWebAppId, null, "Generated by " . $user->name);
return $appKey->key;
```

In Java:

```java
if(cartorio.getAssinadorWebAppId() == null){
	String name = "CENTRAL-" + cartorio.getCns();
	List<Roles> roles = new ArrayList<>();
	roles.add(Roles.fromValue("Worker"));

	Map<String, List<String>> metadata = new HashMap<>();
	List<String> firstElement = new ArrayList<>();
	firstElement.add(cartorio.getNome());
	metadata.put("cartorio", firstElement);
	List<String> secondElement = new ArrayList<>();
	secondElement.add(cartorio.getCns());
	metadata.put("cns", secondElement);

	ApplicationModel app = service.createApplication(name, roles, metadata);
	cartorio.setAssinadorWebAppId(app.getId());
}
CreateApplicationApiKeyResponse appKey = service.createApplicationKey(cartorio.getAssinadorWebAppId(), null, "Generated by " + user.getName());
return appKey.getKey();
```

If you are calling the API directly, the calls are:

```plaintext
// Create the application (once per registry office)
POST {endpoint}/api/applications
{
	"name": "CENTRAL-123456",
	"authorizationData": {
		"roles": ["Worker"]
	},
	"rootAuthorizationData": {
		"roles": []
	}
}

// Set the metadata associated with the registry office's application
PUT {endpoint}/api/applications/{id}/default-document-metadata
{
	"cartorio": ["XXº Oficial de Registro de Imóveis do Município - UF"],
	"cns": ["123456"]
}

// Create the API key
POST {endpoint}/api/applications/{id}/api-keys
{
	"description": "Generated by JOHN DOE"
}
```