CCN - Documentação Técnica

Modificado em Sex, 8 Mar na (o) 10:44 AM

HISTÓRICO


VersãoData da Publicação
Alterações
v2
28/10/2020

- Melhoramos o XSD da importação para refletir a real obrigatoriedade dos campos.

- Adicionamos os campos da CNH na importação

- Adicionamos a possibilidade de envio de imagens em PDF

v2.11.0
23/11/2020
- Inclusão da tag fichaBloqueada no XSD e tela do sistema
- Apresentação do campo nacionalidade na tela do sistema
- Adicionar filtro de status na listagem de importações realizadas
- Adicionar CPF na listagem de erros
- Facilitar fluxo de criação de chaves de API
v2.11.0
06/12/2020
- Incluídas explicações da tag nacionalidade e nacionalidadeTipo
- Anexado arquivo XML exemplo com as tags nacionalidadeTipo e fichaBloqueada 
v2.11.0
25/03/2021
- Esclarecimentos adicionais nas regras de formatação das tags, regimeBem
v2.11.0
29/04/2022
- Inclusão de instruções para obter os erros de importação por API
v.2.11.1
01/03/2023
- contentType deve obrigatoriamente conter "text/xml". Antes permitia outros conteúdos
v.2.11.1
16/05/2023
- Incluído exemplo de XML com imagens de documentos anexas e explicações a respeito de cadastros com mais de um documento pessoal
v.2.1228/07/2023- Inclusão da tag fotoVerificada para indicar se a foto coletada da pessoa foi presencial no cartório ou não

ÍNDICE


Introdução


O CCN - Cadastro Único de Clientes do Notariado da plataforma e-notariado é a base nacional de pessoas prevista no Provimento CNJ nº 149/2023. Contempla os dados biográficos e biométricos de pessoas físicas, além de seus documentos pessoais, a saber, documento de identidade, CNH, ficha de assinatura do cartório, dentre outros. 


Para conhecimento das funcionalidades deste módulo, acesse AQUI.


Acesse no link aqui para conhecer as orientações gerais do CCN.



Processo de Integração com os sistemas de gestão de cartórios


A integração com os sistemas de gestão de cartórios é realizada através da formatação de arquivos XML, conforme modelos anexos (XSD e XML), sendo que as transmissões deverão ser realizadas pelas APIs desenvolvidas pelo CNB-CF.


Também há a possibilidade de carregar os arquivos diretamente na plataforma e-notariado, por upload em tela específica do sistema, sendo este processo mais direcionado para cargas iniciais apenas, embora a API seja ainda mais recomendável.


A cada nova atualização no cadastro de uma determinada pessoa, é gerada uma nova versão do cadastro do CCN. O sistema trata duplicidade de envio de arquivos, caso todos os dados da pessoa sejam idênticos.


O ideal é que a periodicidade de transmissão seja realizada a cada atualização do cadastro de pessoas do sistema de gestão de cartórios, não excedendo a 15 (quinze) dias da data do cadastro, conforme previsto no Provimento CNJ n 149/2023.


Para acessar o sistema no ambiente de homologação e obter a chave da API, envie um e-mail para servicos@notariado.org.br informando o CPF, Nome e e-mail de quem deverá acessar.


Integração por API


A documentação da API do Identificação de pessoas está disponível no endereço https://pessoas-hml.e-notariado.org.br/swagger/index.html. A parte referente à importação está na seção Imports.


Atentem-se que as urls dos ambientes de homologação e produção são diferentes e, portanto, devem ser tratadas pela aplicação.


Segue abaixo um exemplo de uso das APIs para realização de uma importação. Há também um arquivo anexo para .Net (ccnexample.zip) como referência.


Os valores informados nos headers X-Subscription e X-Api-Key dependem dos cartórios que enviarão as requisições.

  

O primeiro passo após gerar o arquivo XML é fazer o seu upload (segue exemplo usando o arquivo CCN27052020-10.xml):

 

Importante: deve-se fazer um request multipart e não application/xml


Exemplo com url de homologação

Request:

curl --location --request POST 'https://pessoas-hml.e-notariado.org.br/api/uploads' \

--header 'X-Api-Key: your-app|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \

--form 'file=@/C:/CCN27052020-10.xml' \

--form 'name=CCN27052020-10.xml' \

--form 'contentType=text/xml'

 

Response:

{

    "location": "/api/uploads/6ba5fc64-a747-41d0-86f5-ed9d6f046fad?access_ticket=CfDJ8HUKpopGElVMr9z4pVGvFUJiw40wOJG-ml-c31lE4WptJ8sey0hzCxGPKSexhEhyQY7PLnLxhvf-owz66sUPbMU7N5IA5SQd0yIh3Rrw9RFcYucRwigEsJiJ2EySqw_5T749YsCXQUsfKbsLMWNuBrNZMWtoJ1E2oTVz22kvheeMsgXJ-ZJS2KiifAtBk2tBSw&culture=en&contentType=text%2Fxml",

    "id": "6ba5fc64-a747-41d0-86f5-ed9d6f046fad",

    "name": "CCN27052020-10.xml",

    "contentType": "text/xml"

}

 

Em seguida é criada a importação, usando a resposta obtida anteriormente no campo "upload" da próxima requisição.

Também é necessário especificar o id do cartório no header X-Subscription.

 

Request:

curl --location --request POST 'https://pessoas-hml.e-notariado.org.br/api/imports' \

--header 'X-Subscription: adb07367-c4f2-4f79-b388-156a071b8af2' \

--header 'X-Api-Key: your-app|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \

--header 'Content-Type: application/json' \

--data-raw '{

"type": "CcnPessoaFisica",

"upload": {

   "location": "/api/uploads/6ba5fc64-a747-41d0-86f5-ed9d6f046fad?access_ticket=CfDJ8HUKpopGElVMr9z4pVGvFUJiw40wOJG-ml-c31lE4WptJ8sey0hzCxGPKSexhEhyQY7PLnLxhvf-owz66sUPbMU7N5IA5SQd0yIh3Rrw9RFcYucRwigEsJiJ2EySqw_5T749YsCXQUsfKbsLMWNuBrNZMWtoJ1E2oTVz22kvheeMsgXJ-ZJS2KiifAtBk2tBSw&culture=en&contentType=text%2Fxml",

   "id": "6ba5fc64-a747-41d0-86f5-ed9d6f046fad",

   "name": "CCN27052020-10.xml",

   "contentType": "text/xml"

}

}'

 

Response:

{

    "id": "e99065b2-77e7-4a7b-9f51-776f0e78b063",

    "agentId": "b1f1a709-6299-446b-b72f-8d347467a0ad",

    "subscriptionId": "adb07367-c4f2-4f79-b388-156a071b8af2",

    "dateCreated": "2020-06-04T00:33:44.285868+00:00",

    "type": "CcnPessoaFisica",

    "status": "Pending",

    "processedRecords": 0,

    "failedRecords": 0,

    "totalRecords": 0,

    "fileName": "CCN27052020-10.xml",

    "uploadId": "6ba5fc64-a747-41d0-86f5-ed9d6f046fad",

    "errorCode": null,

    "duplicateRecords": null

}

 

Pode-se usar o "id" da resposta recebida na criação da importação para acompanhar o progresso da importação fazendo uma requisição GET para a URL https://pessoas-hml.e-notariado.org.br/api/imports/{id}:

 

Request:

curl --location --request GET 'https://pessoas-hml.e-notariado.org.br/api/imports/e99065b2-77e7-4a7b-9f51-776f0e78b063' \
 --header 'X-Api-Key: your-app|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response:

{

    "id": "e99065b2-77e7-4a7b-9f51-776f0e78b063",

    "agentId": "b1f1a709-6299-446b-b72f-8d347467a0ad",

    "subscriptionId": "adb07367-c4f2-4f79-b388-156a071b8af2",

    "dateCreated": "2020-06-04T00:33:44.285868+00:00",

    "type": "CcnPessoaFisica",

    "status": "Successful",

    "processedRecords": 8,

    "failedRecords": 0,

    "totalRecords": 8,

    "fileName": "CCN27052020-10.xml",

    "uploadId": "6ba5fc64-a747-41d0-86f5-ed9d6f046fad",

    "errorCode": null,

    "duplicateRecords": null

}


Considerações para testes no Postman
Se desejar efetuar um teste inicial no Postman, faça um request multipart usando a opção "form-data", trocando "Text" no tipo da chave para "File". Se fizer com request application/xml não funcionará.


Considerações para as cargas


O tamanho máximo das requisições por API deve ser de 30.000 KB, portanto, para realizar o upload por API, é necessário que o arquivo seja menor que o limite. 

 

Recomenda-se adicionar o máximo de pessoas possível por arquivo XML, respeitando a restrição de tamanho. Desse modo, a carga será dividida em vários arquivos.

Utilizando a tela de upload do sistema, o tamanho dos arquivos aumenta, já que a tela realiza o upload segmentado do arquivo, dividindo um único arquivo em várias requisições. Nesse caso, sugere-se enviar arquivos até 100MB.


Confira o resultado das cargas conforme procedimentos descritos no link aqui.



Obter os erros de importação


Para obter os erros de importação, utilize a  api/imports/{importId}/errors que retorna o modelo completo dos erros de uma importação com id específico


Explicação dos campos


CampoTipoFormato
Pessoa

chaveRegistro***Ignorar o preenchimentostring
dataRegistroData de criação do registro
Máscara: YYYY-MM-DD
string

estadoCivil

Estado civil da pessoa (vide domínio)

string (30 bytes)

ibgeCidadeNaturalidade

Código do IBGE da cidade de naturalidade da pessoa

Máscara: 9999999

string
nacionalidadeNacionalidade da pessoa - Informar o nome do País (BRASIL, ALEMANHA, etc)string (50 bytes)
nacionalidadeTipoxmlTipoNacionalidadeTipoNacionalidade
ufNaturalidadeUF da naturalidade da pessoa
Obs.: preencher se a UF for do Brasil, caso contrário, deixar em branco.
string
cidadeNaturalidadeCidade da naturalidade da pessoa
Obs.: preencher quando não existir código do IBGE
string (50 bytes)
cpfCPF da pessoastring
nomeNome completo da pessoastring (300 bytes)
sexoSexo da pessoastring
maeNome completo da mãe da pessoastring (100 bytes)
paiNome completo do pai da pessoastring (100 bytes)
telefoneNúmero do telefone fixo da pessoa
Formato:+556199999999
string
celularNúmero de celular da pessoa
Máscara: +5561999999999
string
profissaoProfissão da pessoastring (100 bytes)
dataNascimentoData de nascimento da pessoa
Máscara: YYYY-MM-DD
string
emailemail da pessoastring (100 bytes)
enderecoxmlEndereçoEndereco
observacaoObservação da pessoa (se houver)string (4000 bytes)
documentoxmlDocumentoDocumento
carteiraHabilitacaoxmlCarteiraHabilitacaoCarteiraHabilitacao
biometriaxmlBiometriaBiometria
fichaxmlFichaFicha
imagemFotoImagem em formato .png ou .jpg, codificada em Base64Base64Binary
cartorioxmlCartorio
Obs.: o cartório da importação é definido pelo cartório selecionado na tela ou pelo header X-Subscription na requisição.
Cartorio
termoTitularidadexmlTermoTitularidadeTermoTitularidade
certidaoCasamentoxmlCertidaoCasamentoCertidaoCasamento
anexoxmlAnexoAnexo
enderecoTrabalhoxmlEnderecoEndereco
politicamenteexpostaIndicativo de pessoa politicamente expostaboolean
(true; false)
investigadaAcusadaTerrorismoIndicativo de pessoa acusada de terrorismoboolena
conjugexmlConjugeConjuge
fichaBloqueadaIndicativo de ficha bloqueada por questões de fraudes, bloqueios judiciais, etc.
Obs.: utilizar o campo de observação para complementar
boolean
(true;false)
fotoVerificada
Indicativo se a foto foi coletada presencialmente no cartório (true) ou remotamente (false)boolean
(true;false)
Endereco

ibgeCidadeCódigo do IBGE da cidade de residência da pessoa

Máscara: 9999999

string
cepCEP de residência da pessoastring (8 bytes)
bairroBairro de residência da pessoastring (50 bytes)
cidadeCidade de residência da pessoastring (50 bytes)
ufUF de residência da pessoastring (2 bytes)
complementoComplemento do endereço de residência da pessoastring (50 bytes)
enderecoLogradouro de residência da pessoastring (100 bytes)
numeroNúmero do logradouro de residência da pessoastring (20 bytes)
imagemComprovanteResidenciaImagem do comprovante de residênciabase64Binary
CarteiraHabilitacao

numeroCarteiraHabilitacaoNúmero da carteira de Habilitaçãostring (11 bytes)
categoriaCarteiraHabilitacaoCategoria da Carteira de Habilitaçãostring (5 bytes)
dataPrimeiraHabilitacaoData da primeira habilitação
Máscara: YYYY-MM-DD
string
dataExpiracaoHabilitacaoData da expiração da carteira de habilitação
Máscara: YYYY-MM-DD
string
imagemDocumentoIImagem da CNHbase64Binary
Documento** só permite informar um número de documento com uma imagem. Para imagens adicionais, utilizar a tag Anexos
tipoxmlTipoDocumento
TipoDocumento
docIdentidadeNúmero do documento de identidadestring (15 bytes)
orgaoEmissorÓrgão emissor do documento de identidadestring (50 bytes)
ufOrgaoEmissorUF do órgão emissorstring
dataEmissaoData de emissão do documento de identidade
Máscara: YYYY-MM-DD
string
imagemDocumentoImagem em formato .png ,.jpg, .pdf ou .tiff, codificada em Base64base64Binary
Conjuge** se esse grupo de tag for informado, o CPF e nome do cônjuge devem ser informados com conteúdo. Se o regimeBem não tiver conteúdo, não informe a tag regimeBem
cpfCPF do cônjuge ou companheirostring
nomeNome do cônjuge ou companheirostring (300 bytes)
regimeBemxmlRegimeBem
Obs.: se não tiver o regime de bens, não formate essa tag. Por outro lado, se tiver o regime de bens, mas não o CPF e nome do cônjuge, não formate o grupo Conjuge
RegimeBem
Biometria** se esse grupo de tag for informado, o dedo e a imagem  devem ser informados com conteúdo.
dedoDedo correspondente à digital (vide domínio)positiveInteger
imagemBiometriaImagem em formato .png, .jpg ou .pdf, codificada em Base64base64Binary
Ficha

datafichaData da ficha de assinatura
Máscara: YYYY-MM-DD
string
numeroFichaNúmero da ficha de assinaturastring (100 bytes)
imagensFichaImagem em formato .png, .jpg, .pdf ou .tiff, codificada em Base64base64Binary
Cartório*** os campos do cartório são ignorados
cdCnjCNS do cartóriolong
nomeNome do cartóriostring
cidadeCidade do cartóriostring
TermoTitularidade** desconsiderar na integração **
imagemTermoTitularidadeImagem do termo de titularidade do certificado digital notarizadobase64Binary
CertidaoCasamento

imagemCertidaoCasamentoImagem da certidão de casamento ou união estávelbase64Binary
Anexo

imagemAnexoImagem dos anexosbase64Binary


Obs.: para facilitar o processo de carga de todos os cartórios, o sistema atualmente apenas obriga o preenchimento do CPF e Nome, devendo o cartório enviar os outros dados existentes em sua base cadastral. 




Anexo de documentos pessoais


Todas as imagens de documentos pessoais existentes na base do cartório devem ser transmitidas, por exemplo, enviar as imagens do RG e Passaporte da pessoa.


Regras:

Tag <Documentos>: informar um número de documento de identificação da pessoa e uma imagem apenas.

Tag <Anexos>: informar as outras imagens dos documentos pessoais da pessoa, caso existam


Exemplo: 

Situação: o cadastro do cartório contém duas imagens do RG, correspondendo a frente e verso, além de uma imagem do passaporte e uma imagem da carteira profissional.


Como formatar o XML

Na tag documento, informar os dados do RG, além da imagem da frente desse documento. Já na tag anexo, enviar o base64 das imagens do verso do RG, do passaporte e da carteira profissional.

<documento>

        <tipo>RG</tipo>

        <docIdentidade>27610007</docIdentidade>

        <orgaoEmissor>SSP</orgaoEmissor>

        <ufOrgaoEmissor>MG</ufOrgaoEmissor>

        <dataEmissao>2009-05-18</dataEmissao>

        <imagemDocumento>Base64dafrentedoRG</imagemDocumento>

</documento>

...

<anexo>Base64doversodoRG</anexo>

<anexo>Base64dopassaporte</anexo>

<anexo>Base64dacarteiraprofissional</anexo>

Vide exemplo anexo - CCN16052023-1.xml


Tabelas Domínio


sexo

Tipo 

Descrição 

Feminino 

Masculino 


EstadoCivil

Código

Descrição 

1Solteiro

Casado

3Separado Judicialmente
4Divorciado
5Viúvo
6União Estável
7Desquitado
8Separado Extrajudicialmente


dedo (Biometria)

Código

Descrição 

1Polegar direito

Indicador direito
3Dedo médio direito
4Dedo anelar direito
5Dedo mínimo direito
6Polegar esquerdo
7Indicador esquerdo
8Dedo médio esquerdo
9Dedo anelar esquerdo
10Dedo mínimo esquerdo

 

TipoDocumento

Código

RG

Carteira Profissional 

Passaporte
Carteira de Reservista
RNE



TipoNacionalidade

Valor

Brasileiro Nato
Brasileiro Naturalizado
Estrangeiro
Brasileiro Nascido no Exterior


RegimeBem

Código

Comunhao Parcial

Comunhao Universal 

Participacao Final nos Aquestos
Separacao Total

ALTERNATIVA: Importação do XML diretamente no sistema


1. Acessar a plataforma e-notariado (www.e-notariado.org.br) e efetuar login no sistema


2. Acessar o módulo CCN, clicar sobre o nome e selecionar a opção Importações.


3. Efetuar o upload do XML para efetuar a importação do cadastro de pessoas





Este artigo foi útil?

Que bom!

Obrigado pelo seu feedback

Desculpe! Não conseguimos ajudar você

Obrigado pelo seu feedback

Deixe-nos saber como podemos melhorar este artigo!

Selecione pelo menos um dos motivos
A verificação do CAPTCHA é obrigatória.

Feedback enviado

Agradecemos seu esforço e tentaremos corrigir o artigo