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

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

HISTÓRICO


VersãoData 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


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
isDeletedfalse, trueIndica se o documento foi cancelado
isFlowConcludedfalse, trueIndica 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)
notarizationDatedatetimeData e hora (UTC 0) do reconhecimento da assinatura eletrônica
notarizationDescriptionnulldesconsiderar
shouldNotarizefalsedesconsiderar
step1...nOrdem de atuação dos participantes do fluxo
creationDatedatetimeData/hora da criação do fluxo de assinaturas
pendingDatedatetimeData/hora que ficou disponível para o participante atuar no fluxo
updateDatedatetimeData/hora da última atualização do fluxo de assinaturas
user : ididchave de referência interna do usuário
user : namestringNome completo do participante do fluxo
user : identifierstringCPF do participante do fluxo
user : emailstringe-mail do participante do fluxo
numberRequiredSignatures0...ndesconsiderar
ruleName
desconsiderar
titlestringcampo para indicar uma referência do participante
signRuleUsersnulldesconsiderar
allowElectronicSignaturefalsedesconsiderar
requireSmsAuthenticationToSignElectronicallyfalsedesconsiderar
requireAuthenticatorAppToSignElectronicallyfalsedesconsiderar
notarizedfalse, trueIndicativo que a assinatura do participante foi reconhecida pelo tabelião
notarizationCodenulldesconsiderar
notarizationSubscriptionIdidCódigo interno do cartório que fez o reconhecimento da assinatura eletrônica
notarizationSubscriptionNamestringDenominação do cartório que fez o reconhecimento da assinatura eletrônica
notarizationNotaryNamestringNome do tabelião responsável pelo cartório
notarizationMnestringMNE - matrícula notarial eletrônica do reconhecimento da assinatura eletrônica
signerTypenulldesconsiderar
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:
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

  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ódigoMensagemComo resolver
DocumentCreationRequiresBillingInfoPara 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
CannotHaveImmediatePaymentSubscriptionCannot have imeddiate payment subscriptionA chave de integração da empresa não foi marcada como Administrador
CantSubmitEmptyFileNão é possível enviar um arquivo vazio. Nome do arquivo: {Name}Verifique se o documento PDF e seu Id submetido estão corretos.
DocumentMustBePdfApenas PDFs são aceitos nesse tipo de documentoSomente PDF
FileHasNoValidSignersO documento não possui signatários válidos ({FileKey})Não foram informados signatários no fluxo a ser criado.
NoValidParticipantEmailO signatário ({identifier}) do arquivo {fileKey} não possui um endereço de e-mail válidoCorrija o e-mail do signatário
OrganizationNotFoundA organização não foi encontradaCorrija o conteúdo da tag OrganizationId
AllParticipantsMustHaveExclusiveSubscriptionTodos 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.
AllParticipantsMustHaveACertificateTodos os participantes devem ter um certificado antes de realizar açõesÉ necessário que todos os signatários tenham emitido um certificado digital notarizado.
CannotCreatePrivateDocumentWithDefaultingNotariesOcorreu um problema na criação do seu fluxo. Cartórios bloqueados. Contate o(s) cartório(s) {notaries} para maiores esclarecimentosA empresa pode estar bloqueada por não pagamento ou outro problema. Contate o cartório para verific


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