---
title: "rib"
description: "Requisitos extras da integração do Rest PKI Core com o Assinador Web do Registro de Imóveis do Brasil (RIB), como os metadados obrigatórios cartorio e cns."
canonical: "https://docs.lacunasoftware.com/articles/rest-pki/core/integration/rib"
locale: "pt-BR"
product: "Rest PKI Core"
last_updated: "2026-11-10"
---

# Requisitos adicionais de integração - RIB

A integração com o **Assinador Web** do **Registro de Imóveis do Brasil - RIB** possui alguns requisitos adicionais não mencionados no restante dessa documentação.

## Metadados obrigatórios

Ao criar [sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions), é necessário fornecer os seguintes [metadados](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions/document-metadata) obrigatórios:

* `cartorio`: Nome do cartório emitente (esse valor é exibido na página de validação do documento)
* `cns`: CNS (Código Nacional de Serventia) do cartório emitente

O CNS pode ser informado em qualquer uma das formas abaixo:

* `1234` (apenas dígitos)
* `001234` (com zeros à esquerda)
* `00.123-4` (formatação completa)

Em .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",
});
```

Em PHP:

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

Em 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);
```

Caso esteja chamando a API diretamente:

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

Além dos metadados mencionados acima, todo documento no Assinador Web tem também o metadado `validade`, no formato `aaaa-mm-dd`, por exemplo *2021-04-01*
(1º de abril de 2021). Esse metadado é automaticamente atribuído aos documentos contando 30 dias a partir da data de assinatura e **não pode ser especificado**
na criação da sessão.

## Alocação de chaves de validação de documento

A chave de validação do documento, às vezes chamada de "hash" no contexto dos processos do RIB, é o código alfanumérico que consta na margem do
documento e que permite que este seja consultado posteriormente:

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

No momento da assinatura do documento, o usuário tem a opção de informar a chave de validação que aquele documento deve ter, ao invés de o sistema
gerar uma nova chave aleatória:

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

Deve ser possível aos registros de imóveis, através das centrais de serviços, alocar chaves de validação para uso posterior. Para isso, a sua central
deve chamar a API de alocação de chaves de documentos. Nessa chamada, é necessário passar os mesmos metadados obrigatórios descritos acima:

Em .NET:

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

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

Em PHP:

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

Em 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);

// Alocar uma chave
DocumentKeyModel documentKey = service.allocateDocumentKey(defaultDocumentMetadata);

// Alocar N chaves
List<DocumentKeyModel> documentKeys = service.allocateDocumentKeys(10, defaultDocumentMetadata);

```

Caso esteja chamando a API diretamente:

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

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

O parâmetro `provisionalMetadata` na alocação de chaves serve para informar qual é o cartório responsável por submeter o documento correspondente
a uma determinada chave, permitindo ao sistema exibir essa informação caso a chave seja usada na consulta de documentos:

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

## Geração de chave de API para uso do utilitário

Os registros de imóveis terão à sua disposição um [utilitário de linha de comando](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/client-tool) para assinar documentos a partir de suas aplicações
*desktop*. O uso desse utilitário requer uma **chave de API**.

Deve ser possível aos registros de imóveis, através das centrais de serviços, gerar chaves de API para uso do utilitário. Para isso, a sua central
deve implementar uma lógica semelhante à seguinte:

1.	Verifique no banco de dados se já foi criada uma *application* no Assinador Web para o cartório em questão
   * Caso não tenha sido, crie uma *application* especificando:
     1. *roles*: `Worker`
     1. *defaultDocumentMetadata*: CNS e nome do cartório (conforme regras descritas acima)
1.	Armazene o `applicationId` resultante no banco de dados associado ao cartório
1.	Crie uma *application key* passando o `applicationId` do cartório e informe o resultado ao usuário

Exemplo em .NET:

```cs
var cartorio = ... // entidade de cartório no sistema da central
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: $"Gerada por {User.Name}");
return appKey.Key;
```

Alguns pontos importantes:

* O parâmetro `$"CENTRAL-{cartorio.Cns}"` é o nome da aplicação. Esses nomes precisam ser únicos no Assinador Web, independentemente da central. Por
  isso a sugestão de usar o CNS prefixado com um identificador que remeta ao nome da central (por exemplo, `OE-` para o caso do Ofício Eletrônico)
* Por motivo de segurança, o Assinador Web não armazena a chave de API gerada (apenas o hash dela). As centrais devem fazer o mesmo, ou seja, a cada
  vez que um cartório pede uma chave de API gera-se uma nova chave (mas não uma nova aplicação)
* O campo `description` na chamada ao `CreateApplicationKeyAsync` é opcional e pode ser usado para registrar o usuário que disparou a geração da
  chave

Em PHP:

```PHP
$cartorio = ... // entidade de cartório no sistema da central
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, "Gerada por " . $user->name);
return $appKey->key;
```

Em 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, "Gerada por " + user.getName());
return appKey.getKey();
```

Caso esteja chamando a API diretamente, as chamadas são:

```plaintext
// Criar aplicação (uma vez por cartório)
POST {endpoint}/api/applications
{
	"name": "CENTRAL-123456",
	"authorizationData": {
		"roles": ["Worker"]
	},
	"rootAuthorizationData": {
		"roles": []
	}
}

// Envio dos metadados associados à aplicação do cartório
PUT {endpoint}/api/applications/{id}/default-document-metadata
{
	"cartorio": ["XXº Oficial de Registro de Imóveis do Município - UF"],
	"cns": ["123456"]
}

// Criação da chave de API
POST {endpoint}/api/applications/{id}/api-keys
{
	"description": "Gerada por FULANO DE TAL"
}
```