Como começar

How to Start

Última atualização: 22 de Setembro de 2021
Last update: 22th September, 2021

Introdução

Para começar a utilizar nossos serviços é necessário conhecer nossas formas de integração e o que nossa plataforma oferece.

Resumidamente, para o back-end oferecemos o consumo de nossas API's e no front-end integrações para o seu website, com snippet em JavaScript, e aplicativos mobile, com SDKs para Android e iOS.

Nesta seção você entenderá como está formatada nossas soluções, ambientes e formas de autenticação.

Introduction

To start using our services, it is necessary to know our forms of integration and what our platform offers.

In short, for the backend we offer the consumption of our APIs and for the front-end we offer integrations for your website, with JavaScript snippet, and mobile applications, with SDKs for Android and iOS.

In this section you will understand how our solutions, environments, and forms of authentication are formatted.

Tecnologias e padrões

Technologies and patterns

HTTP

É um protocolo de comunicação utilizado para sistemas de informação de hipermídia, distribuídos e colaborativos.

Veja mais: https://pt.wikipedia.org/wiki/Hypertext_Transfer_Protocol

HTTP

Default transfer protocol used by the system.

See more: https://pt.wikipedia.org/wiki/Hypertext_Transfer_Protocol

REST

A Representational State Transfer (REST), em português Transferência de Estado Representacional, é uma abstração da arquitetura da World Wide Web (Web), um estilo arquitetural que consiste de um conjunto coordenado de restrições arquiteturais aplicadas a componentes, conectores e elementos de dados dentro de um sistema de hipermídia distribuído.

Veja mais: https://pt.wikipedia.org/wiki/REST

REST

Architecture for the provision of resources through distributed systems, which works over the HTTP protocol.

See more: https://pt.wikipedia.org/wiki/REST

JSON

Em computação, JSON, um acrônimo para "JavaScript Object Notation", é um formato de padrão aberto que utiliza texto legível a humanos para transmitir objetos de dados consistindo de pares atributo-valor.

Veja mais: https://pt.wikipedia.org/wiki/JSON

JSON

Standard for describing data, which is used to exchange information between systems. This standard is simpler and lighter than others market alternatives, such as XML.

See more: https://pt.wikipedia.org/wiki/JSON

UTF-8

É um tipo de codificação Unicode de comprimento variável. Pode representar qualquer caracter universal padrão do Unicode, sendo também compatível com o ASCII.

Atualmente é o conjunto de caracteres mais utilizado no mundo.

Veja mais: https://pt.wikipedia.org/wiki/UTF-8

UTF-8

Standard character set used by the system.

Currently it is the most used character set in the world.

See more: https://pt.wikipedia.org/wiki/UTF-8

ISO-8601

A ISO 8601 é uma norma internacional para representação de data e hora emitida pela Organização Internacional para Padronização (International Organization for Standardization, ISO).

Exemplo de data em JSON
{
    "date": "2015-01-01T15:30:50"
}

Veja mais: https://pt.wikipedia.org/wiki/ISO_8601

ISO-8601

Specific format pattern for date and time data.

Example of date format in JSON.
{
    "date": "2015-01-01T15:30:50"
}

See more: https://pt.wikipedia.org/wiki/ISO_8601

Ambientes

Atualmente contamos com dois ambientes disponíveis para utilização.

Homologação

É uma sandbox. Um ambiente onde você pode realizar testes e identificar se está apto a migrar sua aplicação para produção.

Por ser um ambiente de testes, ele não irá retornar informações que podem ser utilizadas para tomada de decisões, não gerará nenhum tipo de cobrança e, tampouco, possui infraestrutura adequada para suportar um volume de transações de operações reais.

Utilize este ambiente com moderação. Para não impactar demais usuários que estão realizando testes, qualquer abuso de volumetria pode resultar em um bloqueio temporário da sua conta.

Endpoint da API
https://homologacao.clearsale.com.br/api/
Endpoint da API específica para envio de arquivos
https://homologacao.clearsale.com.br/apidata/

Produção

É o ambiente final onde você deverá direcionar sua aplicação.

Ao utilizar este ambiente você estará sujeito a cobranças conforme o seu contrato.

Endpoint da API
https://api.clearsale.com.br/
Endpoint da API específica para envio de arquivos
https://apidata.clearsale.com.br/

Environments

There are two endpoints available to access the API. The production and the sandbox endpoint.

Sandbox

It´s an environment where you can perform tests and identify if your application are able to migrate to production environment.

Because it is a testing environment, it will not return information that can be used for decision making, it will not generate any type of billing, and it does not have adequate infrastructure to support a transaction volume of actual transactions.

Use this environment sparingly. In order not to impact other users who are testing, any excess of volumetry may result in a temporary blocking of your account.

Endpoint
https://homologacao.clearsale.com.br/api/
Endpoint to files
https://homologacao.clearsale.com.br/apidata/

Production

It is the final environment where you should direct your application after the completion of the tests.

By using this environment, you will be charged according to your contract.

Endpoint
https://api.clearsale.com.br/
Endpoint to files
https://apidata.clearsale.com.br/

Autenticação

Authentication

API

Todas as requisições submetidas à nossa API devem ser realizadas através de um token de 2048 caracteres.

O token é gerado através de um usuário e senha que deve ser fornecido pela ClearSale.

Entre em contato com o seu consultor de vendas para maiores informações.

Na autenticação, além do token retornamos sua data de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nessa data de expiração.

Para o recebimento desse dado é necessário que reserve um espaço de 2048 caracteres. Só gere um novo token após a expiração do seu token atual.

Requisição
POST https://api.clearsale.com.br/v1/authenticate HTTP/1.1
Content-Type: application/json

{
    "name": "{Your User}",
    "password": "{Your Password}"
}
POST https://homologacao.clearsale.com.br/api/v1/authenticate HTTP/1.1
Content-Type: application/json

{
    "name": "{Your User}",
    "password": "{Your Password}"
}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Token": "{Token value}",
  "ExpirationDate": "{Token expiration date}"
}

API

The API authentication occurs through a user and password, which allows you to obtain an access token. This process is necessary so your application does not deal directly with the user and password on requisition operations.

Request
POST https://api.clearsale.com.br/v1/authenticate HTTP/1.1
Content-Type: application/json

{
    "name": "{Your User}",
    "password": "{Your Password}"
}
POST https://homologacao.clearsale.com.br/api/v1/authenticate HTTP/1.1
Content-Type: application/json

{
    "name": "{Your User}",
    "password": "{Your Password}"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Token": "{Token value}",
  "ExpirationDate": "{Token expiration date}"
}

Websites e Mobile Apps

As integrações de websites através de JavaScript e aplicativos mobile são feitas através de uma chave de 10 caracteres alfanuméricos.

Entre em contato com o seu consultor de vendas para maiores informações.

JavaScript Snippet: https://pt.wikipedia.org/wiki/UTF-8

Mobile SDK: https://pt.wikipedia.org/wiki/UTF-8

Websites and Mobile Apps

Web site integrations through JavaScript and mobile applications are done using a 10-character alphanumeric key.

Contact your sales consultant for more information.

JavaScript Snippet: https://pt.wikipedia.org/wiki/UTF-8

Mobile SDK: https://pt.wikipedia.org/wiki/UTF-8