e-Not Assina Empresas Mensalistas - Integração por API

Modificado em Dom, 13 Out na (o) 8:41 PM

HISTÓRICO

Versão	Data da Publicação	Alterações
v1	19/01/2023	- Primeira versão
v2	05/07/2024	Inclusão de tabela de códigos de erros no retorno da api
v2.1	13/10/2024	Acrescentar os parâmetros para baixar a versão do documento assinado digitalmente e com os reconhecimentos realizados.

ÍNDICE

Introdução
Lista de APIs
POST /api/uploads
POST /api/documents
GET/api/documents/{id}
GET/api/documents/{id}/ticket
Gerar a chave de integração

Introdução

As empresas mensalistas de cartórios que submetem documentos no e-Not Assina podem também criar seus fluxos automaticamente no e-Notariado, por integração via API com seus sistemas próprios.

Para ativar a integração automática com o e-Not Assina, o mensalista deve ter sido cadastrado como pessoa jurídica pelo cartório correspondente.

Além de criar os fluxos de assinaturas automaticamente no e-Not Assina, as empresas poderão baixar os documentos assinados posteriormente.

Para consumir as APIs do e-Notariado, cada empresa deverá gerar previamente uma chave de integração a ser informada nas requisições das APIs. Vide explicações AQUI.

Lista de APIs

API	Objetivo
POST /api/uploads	Envia o arquivo (documento PDF)
POST /api/documents	Cria o fluxo de assinaturas
GET /api/documents/{id}	Verifica se o documento foi concluído
GET /api/documents/{id}/ticket	Baixa o documento assinado pela url

POST /api/uploads

Objetivo: subir o documento PDF para o e-Not Assina antes de criar o fluxo de assinaturas

Request:
curl -X POST -H "Authorization: EmpresaXXX|5d69344aa3d62b439db289c2d13695a56524e4041d45ccd902445e468b6b966b" -H "Content-Type: multipart/form-data" -F "File=@C:\Documentos\Contrato XXXX.pdf"

https://https://assinatura.e-notariado.org.br/api/uploads

Explicação dos campos

Campo	Tipo	Formato
Name	Nome do documento	string
ContentType	application/pdf	string
File	local de armazenamento do documento na origem	string

Exemplo de resultado:

{

"fileType": "Unknown",

"location": "/api/uploads/8b09fb32-57fd-415c-83a9-848f12374ea9?access_ticket=CfDJ8EEs-tCq80xDuFNe20Zd27v3xYXps-k0qzdKTm-nOGzU-wfRy3I7QRbrxKN2tz-vVS-rTMix8hmSFP_N6JBZEYfhJkE0dumc-Jo4YS4-mhw2FBG2PQ_Lwy8pkZ9NSLubONc6AOk68OGPCLtnsJFzXkLlOKNhWu3XPG1Mep0Pd_m8IqU4m7lXsmv1WqRFyTFv6Q&culture=pt&contentType=application%2Foctet-stream",

"id": "8b09fb32-57fd-415c-83a9-848f12374ea9",

"name": null,

"contentType": "application/octet-stream"

}

Copie o id do documento para informar no endpoint de criação de documento

POST /api/documents

Objetivo: cria o fluxo de assinaturas com o documento que subiu no endpoint /api/upload

Request:

Exemplo mais simplificado, com somente signatários, sem posicionamento das assinaturas e pastas vinculadas.

{

"flowActions": [

{

"type": "Signer",

"step": 1,

"user": {

"name": "Nome completo do signatário",

"email": "email do signatário",

"identifier": "CPF do signatário sem pontuação",

"title": "Vendedor"

{

"type": "Signer",

"step": 2,

"user": {

"name": "Nome completo do signatário",

"email": "email do signatário",

"identifier": "CPF do signatário sem pontuação",

"title": "Comprador"

"organizationId": "006dc15c-5743-4dd5-81c1-08d73587c915",

"type": "PrivateDocument",

"files": [

{

"id": "8b09fb32-57fd-415c-83a9-848f12374ea9",

"name": "Documento1.pdf",

"displayName": "Documento1",

"contentType": "application/pdf"

}

]

}

curl -X POST https://https://assinatura.e-notariado.org.br/api/documents -H "Content-Type:

application/json" -H "Authorization: EmpresaXXX|5d69344aa3d62b439db289c2d13695a56524e4041d45ccd902445e468b6b966b" -d "{\"flowActions\":

[{\"type\":\"Signer\",\"step\":1,\"user\":{\"name\":\"Nome

Sobrenome\",\"email\":\"email@email.com\",\"identifier\":\"12345678901\"}},

{\"type\":\"Signer\",\"step\":1,\"user\":{\"name\":\"Nome

Sobrenome\",\"email\":\"email@email.com\",\"identifier\":\"23456789012\"}}],\"organizationId\":\

"006dc15c-5743-4dd5-81c1-08d73587c915\",\"type\":\"PrivateDocument\",\"files\":

[{\"id\":\"8b09fb32-57fd-415c-83a9-848f12374ea9"\",\"name\":\"file.pdf\",\"displayName\":\"fileName\",\"contentType\":\"application/

pdf\"}]}"

Explicação dos campos

Campo	Tipo	Formato
FlowActions
. type	Tipo do participante do fluxo: "Signer" - Signatário "Approver" - Aprovador	string
. step	Número sequencial da etapa (1, 2, 3...) que permitirá que as assinaturas ocorram sequencialmente, ou seja, somente após o signatário anterior assinar que o próximo receberá a notificação e poderá assinar. Se desejar que todos os signatários assinem ao mesmo tempo, informe a mesma etapa para eles.	string
. user
.. name	Nome completo do signatário	string
.. email	e-mail do signatário	string
.. identifier	CPF do signatário	string
. title	Campo livre para indicar uma referência do participante. Ex.: Vendedor, Comprador, Advogado, etc	string
. prepositionedMarks	Posicionamento da representação da assinatura digital no documento. Consulte orientações no Anexo 1.	grupo de tags
. signerType	Tipo do signatário (não utilizar)	null
. observers
. folderId	Id da pasta de trabalho do fluxo. Os documentos podem ser criados em pastas previamente criadas no fluxo de assinaturas.	string
. newFolderName	Se a pasta não existe ainda é possível informar o nome na criação do fluxo por essa API.	string
. organizationId	Id da empresa mensalista, obtido na criação da chave de integração	string
. type	Informar "PrivateDocument"	string
. files
.. id	Id do arquivo gerado na execução do endpoint /api/uploads	Id
.. name	Nome do arquivo com extensão Ex: "Documento.pdf"	string
.. displayName	Nome do fluxo/documento que será apresentado ao consultar	string
.. contentType	Informar "application/pdf"	string
. areFilesScanned	Informar "false"	boolean

Exemplo de resultado

[

{

"uploadId":"6fb5ce24-bb89-41d2-ba25-5bd2c9b41602",

"documentId":"aad7706e-460e-4f4b-9228-693166af436c",

"mne":null

}

]

Armazene o documentId que identifica o fluxo de assinaturas criado. Com ele, conseguirá posteriormente executar as APIs para consultar o status do documento e obter a url para download do documento concluído.

Posicionamento da representação das assinaturas digitais no documento

O sistema posiciona automaticamente a representação das assinaturas digitais no final do documento, entretanto, há o risco de sobreporem o conteúdo do documento, caso não seja formatado adequadamente.

Caso queira que o posicionamento da representação da assinatura digital seja automático pelo sistema, formate a requisição da API com "prepositionedMarks": null em cada signatário.

Entretanto, se desejar já deixar posicionado, utilize as instruções abaixo:

"prePositionedMarks": [

{

"type": "SignatureVisualRepresentation",

"marks": {

"aad7706e-460e-4f4b-9228-693166af436c ": {

"topLeftX": 0,

"topLeftY": 0,

"width": 0,

"height": 0,

"pageNumber": 0

}

]

Campo	Tipo	Formato
. type	Informar "SignatureVisualRepresentation"	string
. marks
.. id do documento	id do documento que haverá o posicionamento da assinatura
... topLeftX	Coordenada horizontal (0...n) Ex. (ATPV-e): 330.6
... topLeftY	Coordenada vertical (0...n) Ex. (ATPV-e): 462.456 e 609.123
... height	Tamanho da representação da assinatura digital Ex.: 129.4
... pageNumber	Número da página do documento que a representação será posicionada: Ex.: 1

Inclusão de observadores do fluxo de assinaturas

Caso deseje incluir observadores no fluxo de assinaturas, os quais serão notificados por e-mail quando alguém aprovar ou assinar o documento, formate a requisição como o exemplo abaixo:

"observers": [

{

"user": {

"name": "Fulano de tal",

"email": "email@email.com.br",

"identifier": "09909370199"

}

GET/api/documents/{id}

Objetivo: verifica se o documento foi concluído.

Campo	Contéudos possíveis	Explicação
isDeleted	false, true	Indica se o documento foi cancelado
isFlowConcluded	false, true	Indica se o documento já teve todas as assinaturas e reconhecimentos realizados
type	Signer, Approver, Observer	Signer - signatário Approver - aprovador do documento Observer - acompanha o andamento apenas por notificações
status	Pending, Completed	Pending - não assinado Completed - assinado e com reconhecimento pelo tabelião
notarizationStatus	null, Notarized	Indica que houve o reconhecimento da assinatura eletrônica pelo tabelião (null = não, Notarized = sim)
notarizationDate	datetime	Data e hora (UTC 0) do reconhecimento da assinatura eletrônica
notarizationDescription	null	desconsiderar
shouldNotarize	false	desconsiderar
step	1...n	Ordem de atuação dos participantes do fluxo
creationDate	datetime	Data/hora da criação do fluxo de assinaturas
pendingDate	datetime	Data/hora que ficou disponível para o participante atuar no fluxo
updateDate	datetime	Data/hora da última atualização do fluxo de assinaturas
user : id	id	chave de referência interna do usuário
user : name	string	Nome completo do participante do fluxo
user : identifier	string	CPF do participante do fluxo
user : email	string	e-mail do participante do fluxo
numberRequiredSignatures	0...n	desconsiderar
ruleName		desconsiderar
title	string	campo para indicar uma referência do participante
signRuleUsers	null	desconsiderar
allowElectronicSignature	false	desconsiderar
requireSmsAuthenticationToSignElectronically	false	desconsiderar
requireAuthenticatorAppToSignElectronically	false	desconsiderar
notarized	false, true	Indicativo que a assinatura do participante foi reconhecida pelo tabelião
notarizationCode	null	desconsiderar
notarizationSubscriptionId	id	Código interno do cartório que fez o reconhecimento da assinatura eletrônica
notarizationSubscriptionName	string	Denominação do cartório que fez o reconhecimento da assinatura eletrônica
notarizationNotaryName	string	Nome do tabelião responsável pelo cartório
notarizationMne	string	MNE - matrícula notarial eletrônica do reconhecimento da assinatura eletrônica
signerType	null	desconsiderar
marks	grupo de tags	coordenadas de posicionamento da assinatura eletrônica do signatário
observers	string	observadores do fluxo

Request:

GET https://assinatura.e-notariado.org.br/api/documents/99105812-9d18-403f-b963-57939580610d

Exemplo de resultado

{

"checksumMd5": "9b2c2a51c5d7cac7fa795f2667db455e",

"isDeleted": false,

"isFlowConcluded": true,

"flowActions": [

{

"id": "3172c8fb-cedb-4ad1-af4d-216ac10d0ceb",

"type": "Signer",

"status": "Completed",

"notarizationStatus": "Notarized",

"notarizationDate": "2023-04-20T00:54:48.6824189+00:00",

"notarizationDescription": null,

"shouldNotarize": false,

"step": 1,

"creationDate": "2023-04-20T00:53:29.2159409+00:00",

"pendingDate": "2023-04-20T00:53:30.2685437+00:00",

"updateDate": "2023-04-20T00:54:39+00:00",

"user": {

"id": "335c4b6a-f49d-4717-86c1-14c6db4ef092",

"name": "Bruno Vinicius Oliveira",

"identifier": "64157436270",

"email": "tecnologia@notariado.org.br"

"numberRequiredSignatures": 0,

"ruleName": null,

"title": null,

"signRuleUsers": null,

"allowElectronicSignature": false,

"requireSmsAuthenticationToSignElectronically": false,

"requireAuthenticatorAppToSignElectronically": false,

"notarized": true,

"notarizationCode": null,

"notarizationSubscriptionId": "14ae23f1-a167-47fb-5086-08d99babf272",

"notarizationSubscriptionName": "200º Tabelionato de Notas - SÃO PAULO/SP",

"notarizationNotaryName": "Maria Julia Catarina",

"notarizationMne": "991018202304200000026766",

"signerType": null,

"marks": [

{

"id": "31ab6aeb-9837-44b1-d9b8-08db4139a814",

"type": "SignatureVisualRepresentation",

"isPrePositioned": true,

"isReadyToBeStamped": true,

"isStampedOnCMS": true,

"imageTicket": null,

"flowActionId": "3172c8fb-cedb-4ad1-af4d-216ac10d0ceb",

"topLeftX": 310.6666666666667,

"topLeftY": 395.78666666666663,

"width": 170.0848484848484,

"height": 93.54666666666662,

"pageNumber": 2

}

]

{

"id": "67db736a-9a4b-4b0f-b76e-a531f3b4e71b",

"type": "Signer",

"status": "Completed",

"notarizationStatus": "Notarized",

"notarizationDate": "2023-04-20T00:55:36.6902185+00:00",

"notarizationDescription": null,

"shouldNotarize": false,

"step": 1,

"creationDate": "2023-04-20T00:53:29.188057+00:00",

"pendingDate": "2023-04-20T00:53:30.2684883+00:00",

"updateDate": "2023-04-20T00:55:35+00:00",

"user": {

"id": "767fdcde-abb6-46a2-af42-59bd129a93b4",

"name": "Lavínia Giovanna Ramos",

"identifier": "69008897865",

"email": "tecnologia@cnbcf.org.br"

"numberRequiredSignatures": 0,

"ruleName": null,

"title": null,

"signRuleUsers": null,

"allowElectronicSignature": false,

"requireSmsAuthenticationToSignElectronically": false,

"requireAuthenticatorAppToSignElectronically": false,

"notarized": true,

"notarizationCode": null,

"notarizationSubscriptionId": "14ae23f1-a167-47fb-5086-08d99babf272",

"notarizationSubscriptionName": "200º Tabelionato de Notas - SÃO PAULO/SP",

"notarizationNotaryName": "(DEMO) Maria Julia Catarina",

"notarizationMne": "991018202304200000026863",

"signerType": null,

"marks": [

{

"id": "39a59b45-8272-4fcc-d9b7-08db4139a814",

"type": "SignatureVisualRepresentation",

"isPrePositioned": true,

"isReadyToBeStamped": true,

"isStampedOnCMS": true,

"imageTicket": null,

"flowActionId": "67db736a-9a4b-4b0f-b76e-a531f3b4e71b",

"topLeftX": 108.0,

"topLeftY": 398.4533333333333,

"width": 170.0848484848485,

"height": 93.54666666666662,

"pageNumber": 2

}

]

}

"observers": [],

"notaryType": null,

"numberOfExtraPagesToNotarize": 1,

"files": null,

"permissions": {

"move": true,

"editFlow": true,

"viewDocumentConferences": true,

"viewDocumentMeetings": true,

"createFlowActionReminder": true,

"viewDocumentUserNotifications": true,

"downloadFile": true,

"downloadSigned": true,

"manageConferences": true,

"assignConferences": true,

"cancelDocument": false,

"cancelTranscript": false,

"canSendAcknowledgment": true,

"canSendPrivateDocument": false,

"canViewSentDocuments": true,

"canListAcknowledgements": true,

"canAddDocumentsToOrganization": true,

"canSendConcludedTranscript": true,

"viewSignedDocumentWithExternalFlowBeforeCompleted": true,

"submitExternalFlowFiles": true,

"canPayPrivateDocumentDebit": false,

"canUpdatePrivateDocumentPayment": false

"pending": {

"signerId": null,

"approverId": null,

"signRuleId": null

"book": null,

"page": null,

"flowConcludedDate": "2023-04-20T00:55:36.3484121Z",

"docConcludedDate": "2023-04-20T00:55:36.6967462Z",

"id": "99105812-9d18-403f-b963-57939580610c",

"qrCode": "sgnr://assinatura.e-notariado.org.br/?a=p&d=ElgQmRidP0C5Y1eTlYChDA==",

"name": "Contrato de Aluguel Cond. Gramado",

"mne": null,

"filename": "Contrato de Aluguel Cond. Gramado.pdf",

"fileSize": 55034,

"mimeType": "application/pdf",

"hasSignature": true,

"isConcluded": true,

"isCanceled": false,

"folder": null,

"organization": {

"id": "006dc15c-5743-4dd5-81c1-08d73587c915",

"parentId": "f99fac88-63c0-44be-95e0-90bb2e7a50ec",

"name": "Construtora Terra da Garoa Ltda.",

"identifier": "00259680000162",

"cns": null,

"uf": null,

"owner": null,

"type": "Company",

"subscriptionCertificateRequestInfo": {

"periodStartHour": null,

"periodStartMinute": null,

"periodEndHour": null,

"periodEndMinute": null,

"timeZone": null,

"email": null,

"phoneNumber": null,

"optEmailNotifications": false,

"optSmsNotifications": false

"subscriptionTravelPermitInfo": {

"email": null,

"phoneNumber": null,

"optEmailNotifications": false,

"optSmsNotifications": false

}

"isOwner": false,

"creationDate": "2023-04-20T00:53:29.1855593+00:00",

"updateDate": "2023-04-20T00:55:36.3484083+00:00",

"createdBy": {

"id": "335c4b6a-f49d-4717-86c1-14c6db4ef092",

"name": "Bruno Vinicius Oliveira"

"type": "PrivateDocument",

"hasExternalFlow": true,

"forceCadesSignature": false,

"isScanned": false,

"orderNumber": "RAE000000638",

"privateDocumentType": null,

"detranStatus": null,

"detranUf": null,

"inconsistency": null

GET/api/documents/{id}/ticket

Objetivo: obtém a url para baixar o documento concluído

Request:
Para baixar o documento original sem as assinaturas:

GET https://assinatura.e-notariado.org.br/api/documents/99105812-9d18-403f-b963-57939580610d/ticket

Para baixar o documento assinado e com os reconhecimentos da assinatura eletrônica:

GET https://assinatura.e-notariado.org.br/api/documents/99105812-9d18-403f-b963-57939580610d/ticket

?type=Signatures&preview=false

Exemplo de resultado

{

"location": "/api/documents/99105812-9d18-403f-b963-57939580610d/original?access_ticket=CfDJ8DBLaJCAJLhDtWCdbAwu...&culture=pt"

}

Gerar a chave de integração

No Fluxo de Assinaturas, acesse a opção Organizações e selecione a empresa desejada. Em seguida, clique em Integração.
Clique em Criar.
Copie a chave de acesso e o Id da organização e cole na autenticação das APIs.
Clique em Editar.
Marque a opção Administrador.
Clique em Salvar.
Comece a consumir as APIs com a chave de integração e Id da organização.

Possíveis erros na execução das APIs

Código	Mensagem	Como resolver
DocumentCreationRequiresBillingInfo	Para criar um documento é preciso adicionar os dados de faturamento da organização	É necessário criar os dados de faturamento da empresa na tela do Fluxo de Assinaturas
CannotHaveImmediatePaymentSubscription	Cannot have imeddiate payment subscription	A chave de integração da empresa não foi marcada como Administrador
CantSubmitEmptyFile	Não é possível enviar um arquivo vazio. Nome do arquivo: {Name}	Verifique se o documento PDF e seu Id submetido estão corretos.
DocumentMustBePdf	Apenas PDFs são aceitos nesse tipo de documento	Somente PDF
FileHasNoValidSigners	O documento não possui signatários válidos ({FileKey})	Não foram informados signatários no fluxo a ser criado.
NoValidParticipantEmail	O signatário ({identifier}) do arquivo {fileKey} não possui um endereço de e-mail válido	Corrija o e-mail do signatário
OrganizationNotFound	A organização não foi encontrada	Corrija o conteúdo da tag OrganizationId
AllParticipantsMustHaveExclusiveSubscription	Todos os participantes devem ter um cartório de exclusividade antes de realizar ações	É necessário que todos os signatários tenham emitido um certificado digital notarizado. Essa mennsagem indica que alguém nunca emitiu um.
AllParticipantsMustHaveACertificate	Todos os participantes devem ter um certificado antes de realizar ações	É necessário que todos os signatários tenham emitido um certificado digital notarizado.
CannotCreatePrivateDocumentWithDefaultingNotaries	Ocorreu um problema na criação do seu fluxo. Cartórios bloqueados. Contate o(s) cartório(s) {notaries} para maiores esclarecimentos	A empresa pode estar bloqueada por não pagamento ou outro problema. Contate o cartório para verific

Anexos (1)

txt

Put api_docu....txt
2.53 KB