Documentoscopy

Última atualização: 21 de Outubro de 2022

Introdução

Processos cadastrais e de autenticação de usuários são burocráticos e lentos e nós queremos te ajudar a criar fluxos com baixa fricção, onde os bons usuários são beneficiados e os fraudadores barrados. Nossa solução de documentoscopia irá te ajudar na automatização e segurança desse processo, analisando a autenticidade dos documentos neste processo e lhe fornecendo uma sugestão de decisão rápida juntamente com outros dados extraídos do documento para garantir melhor experiência para o seu cliente.

Autenticação

Todas as requisições submetidas à nossa API devem ser realizadas através de um token, gerado por usuário e senha fornecidos pela ClearSale. Entre em contato com o seu consultor de vendas para mais informações.

Na autenticação, além do token, retornamos seu tempo de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração. Só gere um novo token após a expiração do seu token atual.

Requisição
POST https://documentoscopy.clearsale.com.br/api/v1/authentication HTTP/1.1
Content-Type: application/json
{
    "username": "*******",
    "password": "*******"
}

POST https://documentoscopy-hml.clearsale.com.br/api/v1/authentication HTTP/1.1
Content-Type: application/json
{
    "username": "*******",
    "password": "*******"
}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "token": "string",
  "expiresInSeconds": 18000
}

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
  "detail": "Invalid username and/or password. Check the field and try again",
  "title": "Unauthorized access.",
  "status": 401,
  "instance": "/api/v1/authentication"
}

HTTP/1.1 404 NotFound
                                
HTTP/1.1 500 InternalServerError

Análise de documento

Através desse endpoint, será criada uma requisição de documentoscopia das imagens fornecidas. Esta requisição será executada conforme pacote contratado pela entidade junto a ClearSale, podendo conter extração de dados, análise automatizada e análise forense de mesa.

Requisição
POST https://documentoscopy.clearsale.com.br/api/v1/documents HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}
{
  "identifierID": "string",
  "imagesDocument": [
    {
      "base64": "string",
      "url": "string",
      "type": "string"
    }
  ],
  "services": [
    0
  ],
  "cpf": "string"
}

POST https://documentoscopy-hml.clearsale.com.br/api/v1/documents HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}
{
  "identifierID": "string",
  "imagesDocument": [
    {
      "base64": "string",
      "url": "string",
      "type": "string"
    }
  ],
  "services": [
    0
  ],
  "cpf": "string"
}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "identifierID": "7867",
  "transactionID": "9d12912a-f44c-4dbf-b58b-ace31741b460",
  "date": "2021-09-20T20:41:58.2317859Z"
}

HTTP/1.1 400 BadRequest
Content-Type: application/json; charset=utf-8
{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "/api/v1/documents",
  "errors": {
    "IdentifierId": [
      "{\"code\":1,\"message\":\"The identifierID is a mandatory field.\"}"
    ],
    "ImagesDocument": [
      "{\"code\":6,\"message\":\"At least one image is required for processing.\"}"
    ]
  }
}

HTTP/1.1 404 NotFound
                                
HTTP/1.1 500 InternalServerError

Dicionário de variáveis


Requisição
Nome Descrição Tipo Tamanho Obrigatório
IdentifierID ID do pedido controlado pela entidade String 100 Sim
ImagesDocument Imagens do documento Array - Sim
Services Serviços atribuídos à atividade Array - Não *
CPF Cadastro de Pessoa Física String 11 Não **
* Se o campo Services não for preenchido, os dois possíveis serviços são atribuídos à atividade. Null, [] ou um serviço inválido disparam um erro. ** Informar apenas números. Pontos, hífen ou espaços em branco disparam um erro.
ImagesDocument
Nome Descrição Tipo Tamanho Obrigatório
Base64 Imagem em formato BASE64 String - Sim *
Url URL da imagem String - Sim *
Type Tipo da imagem String - Sim
* Base64 é obrigatório apenas se o campo Url não for preenchido. Url é obrigatório apenas se o campo Base64 não for preenchido.
Resposta
Nome Descrição Tipo Tamanho
IdentifierID O valor enviado na transação será retornado na resposta String -
TransactionID Identificador gerado pela ClearSale String 36
Date Data da geração da transaction. DateTime 10
Errors Objeto que apresenta mensagens de erro que indicam o motivo da não geração do score na requisição String[] -

Notificação via Webhook

Sempre que ocorrer uma alteração de uma transação, o Webhook da Clearsale irá enviar uma notificação para uma URL que deverá ser implementada no lado do integrador.

Para cadastrar a URL do seu webhook, enviar um e-mail para documentoscopia@clear.sale, copiando o seu gerente de contas, informando os dados da tabela abaixo:

Nome Descrição
Nome Cliente Nome fantasia do cliente
URL URL que será chamada quando houver uma alteração na transação
Token O token informado deverá ser uma chave secreta enviada nas chamadas de Webhook, no Header "Authorization: Bearer {Token}"
Requisição
POST {URL cadastrada} HTTP/1.1
Content-Type: application/json; charset=utf-8
{
    "type": 1,
    "transactionId": "d5aac162-4c22-4514-9414-ebc5a8d84ef8",
    "identifierId": "transaction-1",
    "processStatusCode": 2,
    "processStatus": "Concluído",
    "statusCode": 1,
    "status": "Não é possível analisar",
    "subStatus": "Decisão de documentoscopia não contratada",
    "receivedDate": "2022-02-22T10:57:02.56",
    "endDate": "2022-02-22T10:57:02.56",
    "ocr": [
      {
        "tag": "docNumber",
        "value": "123"
      },
      {
        "tag": "name",
        "value": "João"
      },
      {
        "tag": "fatherName",
        "value": "Pedro"
      },
      {
        "tag": "motherName",
        "value": "Maria"
      }
    ]
  }

Importante: Se a URL do integrador retornar qualquer Status HTTP diferente de 200 (Ok), serão feitas outras 5 tentativas de notificar a transação em um período maximo de 10 minutos.

Dicionário de variáveis


Requisição
Nome Descrição Tipo Tamanho
TransactionID Identificador gerado pela ClearSale String 36
IdentifierID Identificador enviado pela entidade String -
ProcessStatusCode Código da etapa atual do processamento da análise Integer -
ProcessStatus Descrição da etapa atual do processamento da análise String -
StatusCode Status code da análise forense do documento Integer -
Status Descrição do status da análise forense do documento String -
Substatus Descrição substus da análise forense do documento String -
ReceivedDate Data de recebimento da análise DateTime -
EndDate Da fim do processamento da análise DateTime -
Ocr Dados extraidos do documento. Retorno null quando não for possível obter os dados Array -

Consulta de análise

Com o transactionID retornado na solicitação de análise do documento, você poderá consultar o resultado de uma análise de documentoscopia.

Requisição
GET https://documentoscopy.clearsale.com.br/api/v1/documents/{"transactionID"} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

GET https://documentoscopy-hml.clearsale.com.br/api/v1/documents/{"transactionID"} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "type": 1,
    "transactionId": "d5aac162-4c22-4514-9414-ebc5a8d84ef8",
    "identifierId": "transaction-1",
    "processStatusCode": 2,
    "processStatus": "Concluído",
    "statusCode": 1,
    "status": "Não é possível analisar",
    "subStatus": "Decisão de documentoscopia não contratada",
    "receivedDate": "2022-02-22T10:57:02.56",
    "endDate": "2022-02-22T10:57:02.56",
    "ocr": [
      {
        "tag": "docNumber",
        "value": "123"
      },
      {
        "tag": "name",
        "value": "João"
      },
      {
        "tag": "fatherName",
        "value": "Pedro"
      },
      {
        "tag": "motherName",
        "value": "Maria"
      }
    ]
  }

HTTP/1.1 404 NotFound
                                
HTTP/1.1 500 InternalServerError

Dicionário de variáveis


Requisição
Nome Descrição Tipo Tamanho Obrigatório
TransactionID Identificador gerado pela ClearSale String - Sim
Resposta
Nome Descrição Tipo Tamanho
TransactionID Identificador gerado pela ClearSale String 36
IdentifierID Identificador enviado pela entidade String -
ProcessStatusCode Código da etapa atual do processamento da análise Integer -
ProcessStatus Descrição da etapa atual do processamento da análise String -
StatusCode Status code da análise forense do documento Integer -
Status Descrição do status da análise forense do documento String -
Substatus Descrição substus da análise forense do documento String -
ReceivedDate Data de recebimento da análise DateTime -
EndDate Da fim do processamento da análise DateTime -
Ocr Dados extraidos do documento. Retorno null quando não for possível obter os dados Array -

Tabelas código e descrição

Status codes
Valor Descrição
0 Em processamento
1 Não é possível analisar
2 Alto risco de fraude
3 Sem risco aparente
4 Análise não realizada
Process status codes
Valor Descrição
1 Em processamento
2 Concluído
3 Erro
Tipo documento
Valor Descrição
1 RG
2 CNH
Tipo imagem
Valor Descrição
front Frente do documento
back Verso do documento
Tipo de serviço
Valor Descrição
1 OCR
2 Análise forense
Images
Nome Descrição Tipo Tamanho
Base64 Imagem tratada em base 64 String -
Type Tipo da imagem String -
Ocr
Nome Descrição Tipo Tamanho
Tag Nome da tag String -
Value Valor da tag String -
Ocr Tags
Nome Descrição Tipo Tamanho
docNumber Número do documento String -
name Nome no documento String -
fatherName Nome do pai String -
motherName Nome da mãe String -
birthDay Data de nascimento String -
observation Observação String -
cpf Cpf String -
releaseDate Data de emissão String -
expirationDate Data de validade String -
rg RG String -
issuerAgency Orgão emissor String -
mirrorNumber Número do espelho String -
documentState Estado de emissão String -
local Local onde o emissor vive / tirou o documento String -
drivingCat Categoria de habilitação String -
firstLicense Data da primeira habilitação String -
acc Autorização para conduzir ciclomotor String -
securityCode Código de segurança String -
renachNumber Renach String -
origin Origem do documento String -
birthPlace Naturalidade String -