📋 Changelog

Changelog

🚀 Introdução

A API da ConnectPlug permite que parceiros utilizem diversos recursos da plataforma como gerenciar suas lojas e seus pedidos.

A ConnectPlug oferece soluções para a operação e gestão das suas vendas e permite integrar seu PDV/POS ou qualquer outro aplicativo.

🗂️ Organização da Documentação

Esta documentação está organizada em categorias para facilitar a navegação:

• 🔐 Autenticação: Endpoints para obter tokens de acesso
• 📦 Catálogo de Produtos: Gerenciamento de produtos, categorias e unidades
• 📦 Produtos - Funcionalidades Descontinuadas: ⚠️ Endpoints que serão removidos em breve
• 📱 Aplicativos: Gerenciamento de aplicativos e disponibilidade de produtos
• 💰 Financeiro: Pagamentos, contas bancárias e transações
• 🛒 Vendas: Pedidos, vendas e promoções
• 📦 Estoques: Gerenciamento de estoque e compras
• 🏢 Empresa: Configurações da empresa e periféricos
• 📊 Relatórios: Relatórios de vendas e estatísticas

🏗️ Arquitetura da API

A API está organizada utilizando os padrões REST.

Os recursos são orientados pelas URLs, aceitamos corpo de requisições (Body Requests) no formato JSON. As respostas também utilizam o formato JSON.

Sendo assim, todas as requests devem conter os Headers

Além disso, utilizamos os padrões HTTP: response codes, verbos HTTP e autenticação.

📚 Conhecimento Geral

🔐 Autenticação

A API utiliza Oauth2 com o fluxo password (Grant Type Password).

Todos os endpoints devem conter o Token de acesso no Header Authorization, exceto os endpoints /oauth/token e oauth/scopes que são utilizados para gerar os Tokens de Acesso (Access Token).

Para obter o access_token, você irá precisar das seguintes informações:

• CLIENT_ID e CLIENT_SECRET do seu aplicativo.
• email e password do usuário com acesso à API.

Exemplo de chamada para gerar o Access Token utilizando cURL:

Exemplo de chamada para renovação do Access Token via Refresh Token utilizando cURL:

Exemplo do uso do Access Token nas chamadas à API:

🔄 Verbos HTTP

Para cada endpoint, detalharemos as especificações dos parâmetros da requisição e do retorno, além dos métodos de requisição disponíveis (GET, PUT, POST e/ou DELETE). Parâmetros que exigem explicações mais detalhadas serão destacados após as informações de requisição e retorno de cada endpoint.

🔢 HTTP Status

⚠️ Códigos de Erro

⏱️ Rate Limit

O Rate limit atual da API é de 60 requisições por minuto.

🔁 Chaves de Idempotência

A API utiliza idempotência nos endpoints que ocorrem operações de criação e atualização.

O Idempotency-Key é um ID aleatório gerado por você e deve ser passado no header Idempotency-Key das solicitações POST e PUT.

Nós utilizamos esse header para evitar duplicidade de registros, ou seja, caso você não tenha recebido a resposta de alguma requisição e mandar o mesmo Idempotency-Key, nós não duplicaremos o registro. Assim, se repetir ou houver duplicidade acidental da mesma request, não corre o risco de criar um segundo objeto ou efetuar a atualização duas vezes.

A idempotência funciona salvando o código de status resultante e o corpo da primeira solicitação feita para qualquer chave de idempotência, independentemente de ser bem-sucedida ou não. Os pedidos subsequentes com a mesma chave retornam o mesmo resultado, incluindo erros 500.

No response dos métodos POST e PUT é retornado dois headers adicionais:

• Idempotency-Key: que deve conter o identificador da request que você enviou.
• Idempotency-Replayed: que indica se a request é um replay de uma chamada anterior ou não.

Não é exigido um formato específico para o Idempotency-Key, porém sugerimos que utilize UUID ou alguma outra forma de geração de IDs aleatórios com entropia suficiente para evitar colisões. As chaves de idempotência têm um comprimento máximo de 100 caracteres.

📝 Formato dos Dados

Visando facilitar a compreensão das nossas APIs para o maior número de desenvolvedores parceiros, alguns retornos tiveram seus formatos normalizados. A seguir, especificamos alguns dos formatos mais relevantes dos retornos da nossa API:

📅 Datas e horários

Nossos campos que representam datas os horários são retornados no fuso horário da loja e são representadas em UTC utilizando o padrão ISO 8601.

A informação de qual Timezone é utilizada na loja vem no próprio valor retornado.

Para os métodos em que é necessário passar uma data e horário no parâmetro, basta enviar as informações do horário local com a informação que determina o fuso horário em UTC.

Onde:

• YYYY representa os 4 dígitos do ano.
• MM representa os 2 dígitos do mês.
• DD representa os 2 dígitos do dia do mês.
• hh representa os 2 dígitos da hora.
• mm representa os 2 dígitos do minuto.
• ss representa os 2 dígitos do segundo.
• +hh:mm representa o timezone, que pode ser positivo ou negativo. Por exemplo: o timezone America/Sao_Paulo é representado por -03:00.

📅 Dias da semana

Para campos que representam dias de semana, são numeramos de 1 à 7, onde:

• O dia 1 representa o domingo, e
• o dia 7 representa o sábado.

📄 Paginação das respostas da API

Alguns de nossos endpoints possuem paginação. Implementamos paginação para endpoints que tem o potencial de retornar um grande número de resultados.

Neste caso, temos o parâmetro page para operar a paginação via query string.

No retorno de endpoints com paginação enviamos o objeto meta, para consulta e referência do desenvolvedor parceiro.

Todos os nossos endpoints com paginação seguem um formato específico. Retornamos os resultados no formato JSON, com os seguintes campos sempre presentes:

• data: Campo utilizado para envolver a resposta da requisição.
• meta: Campo utilizado para referência da paginação, para os endpoints que se utilizam de paginação.
• meta.current_page: Campo utilizado para referência da paginação, para os endpoints que se utilizam de paginação.
• meta.last_page: Campo que identifica a quantidade de páginas.
• meta.per_page: Campo que identifica a quantidade por páginas.
• meta.total: Campo que identifica a quantidade total de objetos.

📊 Tabelas

O sistema utiliza várias tabelas de dados para armazenar e organizar informações essenciais.

Tabela de Unidades de medida

A tabela de Unidades de Medida armazena informações sobre diferentes unidades de medida e suas descrições. Essa tabela é usada para garantir a padronização das unidades de medida em diversos contextos.