Documentação
Orientações sobre uso, autenticação e melhores práticas
O que é o Portal de APIs?
O Portal de APIs tem por objetivo fornecer um extenso catálogo de APIs, que podem ser integradas a sua solução de maneira simples e eficiente. Adotamos o modelo de pré-pago, onde após efetivação do seu cadastro você recebera um token exclusivo para poder utilizar nossos micro-serviços.
Preparamos uma documentação para você usar a nossa API de uma maneira simples e rápida.
A API é o principal meio para os desenvolvedores acessarem uma coleção de recursos de micro-serviços da Cellere e realizar a integração com o seu sistema.
Antes de começar, aqui está o que você precisa:
- Um token Cellere para acesso a API, ao criar uma conta no nosso portal você terá acesso ai um token.
- Uma aplicação para interação com a API.
- Conhecimento de programação.
Veja a seguir alguns pontos importantes:
- API RESTful – Todas as nossas APIs são organizadas em torno da arquitetura REST e são acessadas via HTTP. Então, se você já interagiu com uma API RESTful, muitos dos conceitos serão familiares.
- Respostas da API – Um JSON será retornado em todas as respostas da API, incluindo casos de erro.
- URLs previsíveis – As APIs são projetadas para ter URLs previsíveis para acessar recursos e utilizam os códigos de resposta HTTP para indicar erros da API.
- Token de acesso – Todas as requisições para API são autenticadas através de um token de acesso enviado na requisição, que deverá ser obtido seguindo os passos descritos no fluxo de Autenticação.
Autenticação
Para que uma API possa ser acionada é preciso realizar uma autenticação para garantir que os dados transacionados estejam protegidos. A tecnologia adotada para nossos tokens é a JWT.
Cada cliente deve possuir um Token único, pois a mesma servirá para identificar o cliente e a quantidade de requisições que ele tem disponível. Em nossos sistemas o Token deve ser passada através de um header de autorization do tipo Bearer Token.
Se você já tem um cadastro no nosso Portal de APIs, o seu token está disponível na seção ADMINISTRAÇÃO >> Conta | Token.
EXEMPLO DE TOKEN:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwia WF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMe KKF2QT4fwpMeJf36POk6yJV_adQssw5c
Entidades de Documentos
Leitura e contextualização de documentos com auxílio do ChatGPT. Através destas APIs é possível acelerar a digitalização de documentos com campos identificados.
Quais documentos são lidos?
RG, CNH, Comprovante de Endereço (Claro, Elektro, Tim e Vivo), Certidão de Casamento, Certidão de Nascimento, ART, CNPJ, TRT, Cadastro Único, Cadesp, Passaporte, INSS, RNE, CCIR, ITR, entre outros.
FORMATO DAS RESPOSTAS: Todos os recursos suportam o envio de respostas no formato JSON, sendo JSON o formato padrão. Para obter a resposta basta enviar na requisição HTTP um cabeçalho Accept:
Accept: application/json
Resposta padrão:
Toda resposta possui um bloco response padrão com os campos:
fields – referentes aos campos retornados. deskewImage – se você deseja receber a imagem em baese64 retornada. docQualityScoreCampo com o Score sobre a qualidade do documento docType -Tipo do documento que foi processado. pageIndex – quantidade de paginas. tags – marcação sobre o documento. queryId – ID unico sobre sua mensagem. status – com codigo e mensagem sobre a resposta do seu processamento.
RETORNO DE CHAMADAS Informações de mensagens de sucesso e erro. Esses códigos são reportados diretamente como status da requisição, mas também em um campo de saída, chamado response, que detalha o motivo.
CÓDIGO RESPOSTA (RESPONSE)
- 200 – Success
- 400 – The request has no data.
- 400 – The image field is required
- 400 – The image field should be a base64 encoded string.
- 400 – Bearer Token is required to perform this operation
- 400 – The token is not in JWT format
- 400 – Bad Request
- 401 – Client is not registered
- 403 – Insufficient credits to perform this operation
- 404 – URL not found
- 500 – Service API is not working
- 500 – Could not process the service response
BACKGROUND CHECK
Verificação de antecedentes, confirma se o CPF ou CNPJ estão ativos, validando informações como o nome da pessoa ou da empresa.
FORMATO DAS RESPOSTAS: Todos os recursos suportam o envio de respostas no formato JSON, sendo JSON o formato padrão. Para obter a resposta basta enviar na requisição HTTP um cabeçalho Accept:
Accept: application/json
Resposta padrão:
Resposta CPF
- TaxIdStatus Situação do CPF
- TaxIdOriginOrigem da informação
- HasObitIndication Se existe óbito registrado
Resposta CNPJ
- BaseStatus Situação do CNPJ
- AdditionalOutputDataInformações sobre CNAE e Atividade economica
RETORNO DE CHAMADAS Informações de mensagens de sucesso e erro. Esses códigos são reportados diretamente como status da requisição, mas também em um campo de saída, chamado response, que detalha o motivo.
CÓDIGO RESPOSTA (RESPONSE)
- 200 – Success
- 400 – The request has no data.
- 400 – The image field is required
- 400 – The image field should be a base64 encoded string.
- 400 – Bearer Token is required to perform this operation
- 400 – The token is not in JWT format
- 400 – Bad Request
- 401 – Client is not registered
- 403 – Insufficient credits to perform this operation
- 404 – URL not found
- 500 – Service API is not working
- 500 – Could not process the service response
AUTOLEITURA DE MEDIDORES DE CONSUMO
Identificação de caracteres em medidores de água, luz e gás. Traz informações com mais de 90% de precisão, aumentado a agilidade e segurança para seu cliente.
Quais tipos de medidores o AUTOLEITURA lê?
- Energia
- Água
- Gás
A API funciona via requisição POST com junto com o autorization Bearer Token.
A imagem pode ser enviada de três formas seguindo os seguintes parâmetros:
- image – imagem a ser processada (Formatos aceitos: .jpeg, .png, .gif, .heic).
- base64 – imagem com encode em base64.
- link – Link(url) com a imagem a ser processada
Todos os recursos suportam o envio de respostas no formato JSON, sendo JSON o formato padrão. Para obter a resposta basta enviar na requisição HTTP um cabeçalho Accept:
Accept: application/json
Resposta padrão
Toda resposta possui um bloco response padrão com os campos:
image – nome da imagem enviada. service – tipo de medidor solicitado pelo cliente. user_ip – ip do dispositivo que fez a requisição. response – código e mensagem de sucesso ou erro da requisição. duration – tempo de resposta da API. Em adição a esses campos, podem ser retornados outras informações, de acordo com a disponibilidade das informações contidas nas imagens enviadas.
Resposta com envio de medidor válido
Quando a imagem processada contém informações completas ou parciais do medidor os seguintes campos aparecem na resposta:
- display_type – tipo de medidor (ciclométrico, digital ou analógico).
- read_result – resultado da leitura do medidor obtido pela IA.
- confidence_read – confiabilidade da IA para o resultado do medidor.
- read_id_result – resultado da leitura do ID obtido pela IA.
- id_confidence – confiabilidade da IA para o resultado do ID.
- model_meter – modelo do medidor obtido pela IA.
- meter_confidence – confiabilidade da IA para o modelo do medidor.
- power_code – Código de potência do medidor (Somente para medidores de energia digital).
- unbalanced_analogical – Indicador de desbalanceamento do medidor (somente para medidores de energia analógicos).
- Resposta com envio da leitura
Quando a imagem processada contém informações completas ou parciais do medidor os seguintes campos aparecem na resposta:
- status – batimento entre os valores do cliente e da IA (conciliated ou not conciliated).
RETORNO DE CHAMADAS Informações de mensagens de sucesso e erro. Esses códigos são reportados diretamente como status da requisição, mas também em um campo de saída, chamado response, que detalha o motivo.
CÓDIGO RESPOSTA (RESPONSE)
- 200 – Success
- 400 – The request has no data.
- 400 – The image field is required
- 400 – The image field should be a base64 encoded string.
- 400 – Bearer Token is required to perform this operation
- 400 – The token is not in JWT format
- 400 – Bad Request
- 401 – Client is not registered
- 403 – Insufficient credits to perform this operation
- 404 – URL not found
- 500 – Service API is not working
- 500 – Could not process the service response
FACEMATCH
Reconhecimento facial para verificar a equivalência de rostos em imagens. Ótima ferramenta para combate de fraude digital.
A API funciona via requisição POST com junto com o autorization Bearer Token. Para utilizar o FaceMatch, você irá precisar de um imagem de documento com foto e uma fotografia a qual o objetivo é certificar. A imagem ou documento, antes de ser enviada pela API, devera ser convertida em base64. Esse procedimento da mais segurança no envio de seus documentos.
- base64 – imagem ou documento pode ser processada (Formatos aceitos: .jpeg, .png, .bmp, .pdf).
FORMATO DAS RESPOSTAS Todos os recursos suportam o envio de respostas no formato JSON, sendo JSON o formato padrão. Para obter a resposta basta enviar na requisição HTTP um cabeçalho Accept:
Accept: application/json
Toda resposta possui um bloco response padrão com os campos:
- confiability – confiança do processamento.
- distanceCampo que trás um numero de referencia sobre a distancia do caso A para o caso B
- img_stats Trás o numero de faces reconhecidas e score
- result – Trás o resultado do processamento: True para o encontro confirmado entre as imagens. False para os resultados negativos.
- elapsedMilliseconds Tempo do processamento
- status – com codigo e mensagem sobre a resposta do seu processamento.
RETORNO DE CHAMADAS Informações de mensagens de sucesso e erro. Esses códigos são reportados diretamente como status da requisição, mas também em um campo de saída, chamado response, que detalha o motivo.
CÓDIGO RESPOSTA (RESPONSE)
- 200 – Success
- 400 – The request has no data.
- 400 – The image field is required
- 400 – The image field should be a base64 encoded string.
- 400 – Bearer Token is required to perform this operation
- 400 – The token is not in JWT format
- 400 – Bad Request
- 401 – Client is not registered
- 403 – Insufficient credits to perform this operation
- 404 – URL not found
- 500 – Service API is not working
- 500 – Could not process the service response
