Introdução

Este documento tem como objetivo apoiar o cliente a compreender a integração com o produto de assinatura de contratos. Nesse documento iremos explicar o Fluxo, a autenticação e os Endpoints da integração. Para utilização destes serviços é necessário realizar a contratação do produto.

Pré requisitos para implementação:

• Possuir uma chave API da Celcoin, essa chave API é enviada após contratar o serviço conosco. link.

• Ter familiaridade com APIs Rest usando o protocolo OAuth 2.0.

• Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

• Após finalizar a integração, realizar a homologação.

Fluxo de integração

Antes de iniciar a integração, defina em quais momentos do seu processo o fluxo de assinatura será utilizado.
No response da requisição, você receberá uma URL de Webview. Essa URL deve ser disponibilizada ao seu cliente final, que irá acessá-la para realizar o processo completo.

Criar Link para fluxo de assinatura

A criação do processo de assinatura deve ser realizada através do endpoint

Link para fluxo de assinatura de documentos

URL Sandbox: https://sandbox.openfinance.celcoin.com.br/onboarding/v1/docsign

Exemplo Request:

form-data

{
  "flow": "DOC_SIGN", //Tipo de flow (DOC_SIGN ou DOC_SIGN_SERPRO)
  "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //Código único cliente
  "documentNumber": "37167700002", // CPF do usuário
  "fullName": "José da Silva", //Nome Completo do usuário que será autenticado
  "docToSign": [
    {
      "docName": "string", //Nome do documento
      "doc": "string" //Conteúdo do documento em base64
    }
  ],
  "metadata": { //Campo aberto para envio de dados adicionais, como finalidade para realizar a autenticação.
   "type": "TRANSACAO PIX",
	 "paymentId": "71996290076"

}, 
	
  "expiresIn": "100000", //Tempo de expiração do webview em segundos
  "notificationWebview": {
    "phoneNumber": "11998729212", //Número de telefone para recebimento de webview
    "notificationsChannel": [ //Canais para recebimento de webview (SMS e/ou WHATSAPP)
      "SMS"
    ]
  },
  "redirectUrlWebview": "https://www.google.com" // Url para redirecionamento
}

Exemplo Response Sucesso:

form-data

{
    "body": {
        "docSignId": "80742ec2-de88-4e80-890b-95932662c10e",
        "clientCode": "eab5d010-36d5-4ac4-936b-7e5f2e1feb93",
        "documentNumber": "91868537676",
        "urlWebview": "https://cadastro.uat.unico.app/process/5d5e406c-2b3b-4591-b033-58ad59c03967",
        "urlExpirationAt": "2026-03-23T16:18:33.808Z",
        "metadata": {
            "transacaoId": "123456",
            "tipoTransacao": "ASSINATURA_CONTRATO"
        },
        "status": "PENDING"
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Exemplo Response Error:

form-data

{
    "error": {
        "errorCode": "OBE034",
        "message": "Formato do JSON esta fora do padrão. Verifique a documentação."
    },
    "version": "1.0.0",
    "status": "ERROR"
}

Consultar Fluxo de Assinatura

É possível consultar as autenticações criadas e seus status utilizando o seguinte endpoint

É possível utilizar os seguintes filtros:
• Data início e data fim (Obrigatório caso não inclua o nº da autenticação)
• Status da autenticação
• documentNumber
• clientCode
• docSignId

URL Sandbox: https://sandbox.openfinance.celcoin.com.br/onboarding/v1/docsign

Exemplo Request:

docsign?docSignId=f773bb7f-599b-450b-93d0-0665c6d70581&clientCode=f83f55e8-77fb-4e48-a312-22a6c0f9e89a&status=PENDING &documentNumber=37138444028&dateFrom=2025-07-10T06:30:00&dateTo=2025-07-16T06:30:00

Exemplo Response:

{
    "body": {
        "limit": 1,
        "currentPage": 1,
        "limitPerPage": 200,
        "totalPages": 1,
        "totalItems": 1,
        "docsToSign": [
            {
                "docSignId": "f773bb7f-599b-450b-93d0-0665c6d70581",
                "clientCode": "f83f55e8-77fb-4e48-a312-22a6c0f9e89a",
                "documentNumber": "37138444028",
                "urlWebview": "https://cadastro.uat.unico.app/process/531c958b-3fe8-41c3-87fa-691e3e933c18",
                "urlExpirationAt": "2025-07-22T17:34:12.838Z",
                "metadata": {
                    "type": "NOVO CONTRATO"
                },
                "status": "PENDING"
            }
        ]
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Buscar documentos endpoint

É possível utilizar os seguintes filtros:
• clientCode
• docSignId

Também é possível utilizar ambos os filtros, porém caso um dos parâmetros estejam errados não irá retornar nada.

Observação: As URLs retornadas possuem duração de 15minutos, após a expiração é necessário realizar uma nova chamada.

URL Sandbox: https://sandbox.openfinance.celcoin.com.br/onboarding/v1/docsign

Exemplo Request:

docsign/files?docSignId=38672b6a-2440-4f5f-b3ca-fe9bf8c50017

Exemplo Response:

{
    "body": {
        "files": [
            {
                "type": "DOC_SIGNED",
                "url": "https://onboardingexterno.blob.core.windows.net/onboarding/docSign/SANDBOX/972/11144477735/38672b6a-2440-4f5f-b3ca-fe9bf8c50017/11144477735_38672b6a-2440-4f5f-b3ca-fe9bf8c50017_3183bc96-9dc4-431c-8315-69a8507101df_DOC_SIGNED.pdf?sv=2025-05-05&se=2026-03-23T18%3A58%3A38Z&sr=b&sp=r&sig=FEZmqlAAgTtJBiBp%2BaExX36vyCxy2%2BAXo%2B2tZDrZdPA%3D",
                "expirationTime": "2026-03-23T15:58:38Z"
            },
            {
                "type": "CONJUNTO_PROBATORIO",
                "url": "https://onboardingexterno.blob.core.windows.net/onboarding/docSign/SANDBOX/972/11144477735/38672b6a-2440-4f5f-b3ca-fe9bf8c50017/11144477735_38672b6a-2440-4f5f-b3ca-fe9bf8c50017_CONJUNTO_PROBATORIO.pdf?sv=2025-05-05&se=2026-03-23T18%3A58%3A39Z&sr=b&sp=r&sig=IncPgWwwbETlLdLTvzRubmZeoyEZVyGxSTYuI4%2BlR%2BM%3D",
                "expirationTime": "2026-03-23T15:58:39Z"
            },
            {
                "type": "SELFIE",
                "url": "https://onboardingexterno.blob.core.windows.net/onboarding/docSign/SANDBOX/972/11144477735/38672b6a-2440-4f5f-b3ca-fe9bf8c50017/11144477735_38672b6a-2440-4f5f-b3ca-fe9bf8c50017_SELFIE.jpeg?sv=2025-05-05&se=2026-03-23T18%3A58%3A39Z&sr=b&sp=r&sig=xD0r4%2F4Gr7R2VjBm8K9IelQgkUNA%2FSW9QWNpUkTIQzU%3D",
                "expirationTime": "2026-03-23T15:58:39Z"
            }
        ],
        "clientCode": "5bec138a-5abb-4896-9b2c-738fe44e262b",
        "documentNumber": "11144477735",
        "docSignId": "38672b6a-2440-4f5f-b3ca-fe9bf8c50017"
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Cadastrar Webhook

Nesta chamada você realizará a definição das rotas que receberão as notificações relacionados aos fluxos.

Passos para integrar

Realizar autenticação na API - [API Reference]
Cadastrar Webhook - [API Reference]

Disponibilizamos duas opções de autenticação nas notificações, Basic Auth ou OAuth 2.0. A definição será feita através da requisição, conforme os exemplos abaixo:

Utilizando Basic Authentication:

Neste formato o basic auth definido será enviado nas notificações.

cURL da Chamada

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '
{
  "entity": "onboarding-docsign", //Incluir evento que deseja cadastrar webhook
  "context": "ONBOARDING",
  "webhookUrl": "string",
  "auth": {
    "login": "string",
    "pwd": "string",
    "type": "string",
    "urlAuth": "string",
    "requestType": "string",
    "responsePathToken": "string",
    "requestAuth": [
      {
        "key": "string",
        "value": "string",
        "type": "string"
      }
    ]
  }
}

Eventos

Evento: onboarding-docsign

Evento que informa a resposta do processo de assinatura realizado.

{
    "status": "APPROVED", //Status 
    "docSignId": "a2b8f524-2c0e-4c90-ace0-3e2d1aea1d10", //ID único gerado pela Celcoin
    "clientCode": "b0e71c12-eb2a-432e-82d1-9e09d17127ab", //Código único do cliente
    "metadata": { //Campo aberto para envio de dados adicionais, como finalidade para realizar a autenticação.
        "type": "TRANSACAO PIX",
    		"paymentId": "71996290076"
    },
    "documentNumber": "03743579197", //CPF do usuário autenticado.
		"webhookId": "5f851e6f-6ea0-401a-8c48-e9c730968332" //ID do Webhook
}

Evento: onboarding-docsign-file

Evento que informa os documentos gerados por aquele processo de assinatura realizado.

{
  "docSignId": "609f429b-3112-4938-bc6e-72658c89a7b8", //ID único gerado pela Celcoin
  "clientCode": "7affe105-1186-4534-a42d-7bd136b1c32d", //Código único cliente
  "documentNumber": "02147645087", //CPF do usuário autenticado
  "files": [ //documentos
    {
      "type": "CONJUNTO_PROBATORIO", //documento tipo conjunto probatório
      "url": "https://onboardingexterno.blob.core.windows.net/onboarding/02147645087_609f429b-3112-4938-bc6e-72658c89a7b8_CONJUNTO_PROBATORIO?sv=2025-05-05&se=2025-05-27T21%3A15%3A22Z&sr=b&sp=r&sig=dDj5%2BAuu0KD3T5h2%2BwFU0Dah%2B2tFKxRO%2BO7H%2Bn1LBV0%3D", //URL onde está disponível o documento.
      "expirationTime": "2025-05-27T18:15:22Z" //tempo de expiração
    },
    {
      "type": "SELFIE", //documento tipo selfie
      "url": "https://onboardingexterno.blob.core.windows.net/onboarding/02147645087_609f429b-3112-4938-bc6e-72658c89a7b8_SELFIE?sv=2025-05-05&se=2025-05-27T21%3A15%3A22Z&sr=b&sp=r&sig=qY8vzDInSTFPg8WyWRHRRv%2FJv88lLC3Yo8d6fcMJl8o%3D", //URL onde está disponível o documento.
      "expirationTime": "2025-05-27T18:15:22Z" //tempo de expiração
    },
		{
      "type": "CNH", //documento tipo selfie
      "url": "https://onboardingexterno.blob.core.windows.net/onboarding/02147645087_609f429b-3112-4938-bc6e-72658c89a7b8_CNH?sv=2025-05-05&se=2025-05-27T21%3A15%3A22Z&sr=b&sp=r&sig=qY8vzDInSTFPg8WyWRHRRv%2FJv88lLC3Yo8d6fcMJl8o%3D", //URL onde está disponível o documento.
      "expirationTime": "2025-05-27T18:15:22Z" //tempo de expiração
    }
  ],
  "webhookId": "5f851e6f-6ea0-401a-8c48-e9c730968332" //ID do Webhook
}

Integração com o Webview

Esta seção oferecerá suporte à integração do WebView, a jornada que o seu cliente envia os documentos.

Recomendamos a utilização do Webview nos seguintes navegadores: Google Chrome, Mozilla Firefox e Safari.

Android

Para que as integrações para Android funcionem corretamente, é necessário que setDomStorageEnabled esteja definido como true. Exemplo abaixo:

myWebView.getSettings().setDomStorageEnabled(true);

iOS

Para que as integrações para iOS funcionem corretamente, é necessário customizar a configuração para permitir a reprodução de mídia sem solicitação de ação do usuário e para reproduzir a mídia. Exemplo abaixo:

let webView: WKWebView

init() {
    let audioVisualMediaType: WKAudiovisualMediaTypes = []
    let configuration = WKWebViewConfiguration()
    configuration.mediaTypesRequiringUserActionForPlayback = audioVisualMediaType
    configuration.allowsInlineMediaPlayback = true

    webView = WKWebView(frame: .zero, configuration: configuration)
}

Outras plataformas

Em outras plataformas, por exemplo, Flutter e React Native, você deve procurar as configurações do WebView para permitir a reprodução de mídia sem exigir gestos do usuário e para reproduzir o vídeo da câmera inline, não no controlador nativo de tela cheia.

Tabelas para apoio

Regras Campos

Tabela de erros

Customização

Considerações finais

Homologação

As instruções para realizar a homologação deste produto estão centralizadas neste link