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

Modificado em Sat, 08 Jul 2023 na (o) 01:54 PM

HISTÓRICO


VersãoData da Publicação
Alterações
v1
19/01/2023

- Primeira versão


ÍNDICE


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


APIObjetivo

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


CampoTipoFormato
NameNome do documentostring
ContentTypeapplication/pdfstring
Filelocal de armazenamento do documento na origemstring


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


CampoTipoFormato
FlowActions
. typeTipo 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

.. nameNome completo do signatáriostring
.. emaile-mail do signatáriostring
.. identifierCPF do signatáriostring
. titleCampo livre para indicar uma referência do participante.
Ex.: Vendedor, Comprador, Advogado, etc
string
. prepositionedMarksPosicionamento da representação da assinatura digital no documento. Consulte orientações no Anexo 1.grupo de tags
. signerTypeTipo do signatário (não utilizar)null
. observers

. folderIdId da pasta de trabalho do fluxo.
Os documentos podem ser criados em pastas previamente criadas no fluxo de assinaturas.
string
. newFolderNameSe a pasta não existe ainda é possível informar o nome na criação do fluxo por essa API.string
. organizationIdId da empresa mensalista, obtido na criação da chave de integraçãostring
. type Informar "PrivateDocument"
string
. files

.. idId do arquivo gerado na execução do endpoint /api/uploadsId
.. nameNome do arquivo com extensão
Ex: "Documento.pdf"
string
.. displayNameNome do fluxo/documento que será apresentado ao consultarstring
.. contentTypeInformar "application/pdf"string
. areFilesScannedInformar "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

            }

          }

        }

      ]



CampoTipoFormato
. typeInformar "SignatureVisualRepresentation"
string
. marks


.. id do documentoid do documento que haverá o posicionamento da assinatura
... topLeftXCoordenada horizontal (0...n)
Ex. (ATPV-e):  330.6

... topLeftYCoordenada vertical (0...n)
Ex. (ATPV-e): 462.456 e 609.123

... heightTamanho da representação da assinatura digital
Ex.: 129.4

... pageNumberNú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. 


CampoContéudos possíveisExplicação
isDeleted
false, trueIndica se o documento foi cancelado
isFlowConcluded
false, true
Indica se o documento já teve todas as assinaturas e reconhecimentos realizados
typeSigner,
Approver,
Observer
Signer - signatário
Approver - aprovador do documento
Observer - acompanha o andamento apenas por notificações
statusPending, CompletedPending - não assinado
Completed - assinado e com reconhecimento pelo tabelião
notarizationStatusnull, NotarizedIndica 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
nulldesconsiderar
shouldNotarize
falsedesconsiderar
step
1...nOrdem de atuação dos participantes do fluxo
creationDate
datetimeData/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 : ididchave de referência interna do usuário
user : name
stringNome completo do participante do fluxo
user : identifierstringCPF do participante do fluxo
user : emailstringe-mail do participante do fluxo
numberRequiredSignatures
0...ndesconsiderar
ruleName

desconsiderar
title
stringcampo para indicar uma referência do participante
signRuleUsers
nulldesconsiderar
allowElectronicSignature
false
desconsiderar
requireSmsAuthenticationToSignElectronically
falsedesconsiderar
requireAuthenticatorAppToSignElectronically
falsedesconsiderar
notarized
false, trueIndicativo que a assinatura do participante foi reconhecida pelo tabelião
notarizationCode
nulldesconsiderar
notarizationSubscriptionId
idCódigo interno do cartório que fez o reconhecimento da assinatura eletrônica
notarizationSubscriptionName
stringDenominação do cartório que fez o reconhecimento da assinatura eletrônica
notarizationNotaryName
stringNome do tabelião responsável pelo cartório
notarizationMne
stringMNE - matrícula notarial eletrônica do reconhecimento da assinatura eletrônica
signerType
nulldesconsiderar
marksgrupo de tagscoordenadas de posicionamento da assinatura eletrônica do signatário
observersstringobservadores 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:

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


Exemplo de resultado

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

Gerar a chave de integração

  1. No Fluxo de Assinaturas, acesse a opção Organizações e selecione a empresa desejada. Em seguida, clique em Integração.
     
  2. Clique em Criar.
     
  3. Copie a chave de acesso e o Id da organização e cole na autenticação das APIs.
     
  4. Clique em Editar.
     
  5. Marque a opção Administrador.
     
  6. Clique em Salvar.
     
  7. 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ódigoDescriçãoComo resolver
CannotHaveImmediatePaymentSubscriptionCannot have imeddiate payment subscriptionA chave de integração da empresa não foi marcada como Administrador
AllParticipantsMustHaveExclusiveSubscriptionTodos os participantes devem ter um cartório de exclusividade antes de realizar açõesOs signatários precisam primeiramente emitir o certificado digital notarizado no mesmo cartório que a empresa é mensalista.


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

Feedback enviado

Agradecemos seu esforço e tentaremos corrigir o artigo