Connect Plug API (3.0.0)
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.
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
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
Content-Type: application/json
Accept: application/jsonAlém disso, utilizamos os padrões HTTP: response codes, verbos HTTP e 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_IDeCLIENT_SECRETdo seu aplicativo.emailepassworddo usuário com acesso à API.
Exemplo de chamada para gerar o Access Token utilizando cURL:
curl --location --request POST 'http://erp.connectplug.com.br/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "password",
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"username": "<email>",
"password": "<password>",
"scope": "*"
}'Exemplo de chamada para renovação do Access Token via Refresh Token utilizando cURL:
curl --location --request POST 'http://erp.connectplug.com.br/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "refresh_token",
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"refresh_token": "<REFRESH_TOKEN>",
"scope": "*"
}'Exemplo do uso do Access Token nas chamadas à API:
curl --location --request POST 'http://erp.connectplug.com.br/api/v3/categories' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'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.
| Código | Nome | Descrição |
|---|---|---|
| 200 | OK | O recurso solicitado foi processado e retornado com sucesso. |
| 201 | Created | O recurso informado foi criado com sucesso. |
| 401 | Unauthorized | A chave da API está desativada, incorreta ou não foi informada corretamente. Consulte a seção sobre autenticação da documentação. |
| 403 | Forbidden | O acesso ao recurso não foi autorizado. Isso pode acontecer quando a loja não tem permissão para acessar o recurso |
| 404 | Not Found | O recurso solicitado ou o endpoint não foi encontrado. |
| 422 | Unprocessable Entity | A requisição foi recebida com sucesso, porém contém parâmetros inválidos. |
| 429 | Too Many Requests | O limite de requisições (Rate Limit) foi atingido. |
| 400 | Bad Request | Não foi possível interpretar a requisição. Verifique as informações enviadas. |
| 500 | Internal Server Error | Ocorreu uma falha na plataforma. Por favor, entre em contato com o suporte. |
| Código | Descrição |
|---|---|
| bad_request | É retornado quando o servidor não consegue entender ou processar a solicitação, pois a solicitação está malformada, incompleta ou contém parâmetros inválidos. |
| not_found | É retornado quando o recurso solicitado não pode ser encontrado no servidor. |
| method_not_allowed | É retornado quando o método HTTP não é permitido para o recurso solicitado. |
| unprocessable_entity | É retornado quando houver erros de validação com os dados enviados. |
| too_many_requests | É retornado quando houver um número excessivo de requisições à API. Verifique a sessão de Rate Limit. |
| internal_server_error | É retornado quando houver uma falha na plataforma. Por favor, entre em contato com o suporte. |
| missing_headers | É retornado quando um header obrigatório não estiver presente na requisição. |
| max_upload_size_exceeded | Ocorre um retorno quando a imagem excede o limite de tamanho estabelecido. |
| unauthorized | É retornado quando a autenticação foi expirada. |
| invalid_scope | O retorno é gerado quando o escopo especificado na autenticação é inválido ou inexistente. |
| forbidden | O retorno ocorre quando se tenta realizar uma ação para a qual não se possui permissão. |
| uneditable_entity | Isso ocorre quando há uma tentativa de edição de um recurso que não é suscetível a modificações. |
| undeleted_resource_association | Isso ocorre quando há a tentativa de excluir um recurso, contudo, tal exclusão é inviável devido à sua associação com outro recurso. |
| product_combo_empty_components | Produtos do tipo "Combo" devem ter pelo menos um componente. |
| product_combo_attributes_not_allowed | Produtos do tipo "Combo" não podem ter atributos. |
| product_combo_component_combo_not_allowed | Produtos do tipo "Combo" não podem ter componentes do tipo "Combo". |
| product_combo_invalid_price | O valor do preço passado no produto do tipo "Combo" não é compatível com o calculo do preço dos componentes. |
| product_with_grid_cannot_have_components | Produtos com grade de preços não podem ter componentes. |
| option_cannot_be_associated_with_grid | Acontece quando uma opção de um atributo não pode ser associado em uma grade de preço. |
| grid_with_options_not_exclusive_by_attribute_group | Uma grade de preços de um produto não pode ter duas ou mais opções do mesmo grupo de atributos. |
| grid_with_duplicate_set_of_options | Uma grade de preço de um produto não pode ter opções de atributos duplicados. |
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.
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:
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.
YYYY-MM-DDThh:mm:ss+hh:mmOnde:
YYYYrepresenta os 4 dígitos do ano.MMrepresenta os 2 dígitos do mês.DDrepresenta os 2 dígitos do dia do mês.hhrepresenta os 2 dígitos da hora.mmrepresenta os 2 dígitos do minuto.ssrepresenta os 2 dígitos do segundo.+hh:mmrepresenta o timezone, que pode ser positivo ou negativo. Por exemplo: o timezoneAmerica/Sao_Pauloé representado por-03:00.
2020-01-01T09:00:00-03:00Para campos que representam dias de semana, são numeramos de 1 à 7, onde:
- O dia
1representa o domingo, e - o dia
7representa o sábado.
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.
{
"data": {
...
},
"meta": {
"current_page": 1,
"last_page": 2,
"per_page": 15,
"total": 17
}
}O sistema utiliza várias tabelas de dados para armazenar e organizar informações essenciais.
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.
| Código | Descrição |
|---|---|
| AMPOLA | AMPOLA |
| BALDE | BALDE |
| BANDEJ | BANDEJA |
| BARRA | BARRA |
| BISNAG | BISNAGA |
| BLOCO | BLOCO |
| BOBINA | BOBINA |
| BOMB | BOMBONA |
| CAPS | CAPSULA |
| CART | CARTELA |
| CENTO | CENTO |
| CJ | CONJUNTO |
| CM | CENTIMETRO |
| CM2 | CENTIMETRO QUADRADO |
| CX | CAIXA |
| CX2 | CAIXA COM 2 UNIDADES |
| CX3 | CAIXA COM 3 UNIDADES |
| CX5 | CAIXA COM 5 UNIDADES |
| CX10 | CAIXA COM 10 UNIDADES |
| CX15 | CAIXA COM 15 UNIDADES |
| CX20 | CAIXA COM 20 UNIDADES |
| CX25 | CAIXA COM 25 UNIDADES |
| CX50 | CAIXA COM 50 UNIDADES |
| CX100 | CAIXA COM 100 UNIDADES |
| DISP | DISPLAY |
| DUZIA | DUZIA |
| EMBAL | EMBALAGEM |
| FARDO | FARDO |
| FOLHA | FOLHA |
| FRASCO | FRASCO |
| GALAO | GALÃO |
| GF | GARRAFA |
| GRAMAS | GRAMAS |
| JOGO | JOGO |
| KG | QUILOGRAMA |
| KIT | KIT |
| LATA | LATA |
| LITRO | LITRO |
| M | METRO |
| M2 | METRO QUADRADO |
| M3 | METRO CÚBICO |
| MILHEI | MILHEIRO |
| ML | MILILITRO |
| MWH | MEGAWATT HORA |
| PACOTE | PACOTE |
| PALETE | PALETE |
| PARES | PARES |
| PC | PEÇA |
| POTE | POTE |
| K | QUILATE |
| RESMA | RESMA |
| ROLO | ROLO |
| SACO | SACO |
| SACOLA | SACOLA |
| TAMBOR | TAMBOR |
| TANQUE | TANQUE |
| TON | TONELADA |
| TUBO | TUBO |
| UNID | UNIDADE |
| VASIL | VASILHAME |
| VIDRO | VIDRO |
https://cplug.redocly.app/_mock/openapi/
http://erp.connectplug.com.br/
Importação de XML de Entrada
Importação de XML de Entrada.
Fluxo de importação padrão:
Faz o upload da nota fiscal de entrada.
Obtém informações sobre o XML para verificase se o fornecedor está cadastrado;
a) Se o campo
data.supplier.idestiver com valornull, quer dizer que precisa cadastrar um novo fornecedor."Baixa" os itens do XML para o sistema por meio do endpoint Faz um pré-processamento dos itens da nota;
Obtém a lista de itens do XML para ver se precisa fazer alguma alteração ou associar um produto já cadastrado;
Faça as operações necessárias do item;
a) Salva os itens em massa ou
b) Salva um item ou
c) Apaga um item do XML ou
d) Reverte uma alteração para o estado inicial do XML ou
E finalmente faz a importação dos itens que foram salvos no item anterior, adicionando as formas de pagamento para poder gerar uma compra no sistema.
Filtro pelos IDs das séries de comanda. Pode passar mais de um ID numérico separado por virgula.
Filtra por dados que foram atualizadas a partir de uma data. (Formato: YYYY-MM-DDThh:mm:ss+hh:mm).
Id da Empresa (Company).
Você pode localizar os IDs das empresas no endpoint de listagem de empresas.
- Mock server
https://cplug.redocly.app/_mock/openapi/api/v3/command-series
- Dev
http://erp.connectplug.com.br/api/v3/command-series
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://cplug.redocly.app/_mock/openapi/api/v3/command-series?command_series_id=1%2C2%2C3&name=Comanda&page=1&per_page=30&updated_from=2019-08-24T14%3A15%3A22Z&deleted=not_include' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'CPlug-Company-Id: 12'{ "data": { "command_series": [ … ] }, "meta": { "current_page": 1, "last_page": 10, "per_page": 20, "total": 200 } }
Id da Empresa (Company).
Você pode localizar os IDs das empresas no endpoint de listagem de empresas.
Corpo da requisição da criação da série de comanda.
- Mock server
https://cplug.redocly.app/_mock/openapi/api/v3/command-series
- Dev
http://erp.connectplug.com.br/api/v3/command-series
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://cplug.redocly.app/_mock/openapi/api/v3/command-series \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'CPlug-Company-Id: 12' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
-d '{
"name": "Comanda",
"start_number": 1,
"end_number": 100
}'{ "data": { "id": 123, "name": "Comanda", "start_number": 1, "end_number": 100, "deleted": false, "created_at": "2020-01-01T09:00:00-03:00", "updated_at": "2020-01-01T09:00:00-03:00" } }
Id da Empresa (Company).
Você pode localizar os IDs das empresas no endpoint de listagem de empresas.
- Mock server
https://cplug.redocly.app/_mock/openapi/api/v3/command-series/{commandSeriesId}
- Dev
http://erp.connectplug.com.br/api/v3/command-series/{commandSeriesId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://cplug.redocly.app/_mock/openapi/api/v3/command-series/{commandSeriesId}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'CPlug-Company-Id: 12'{ "data": { "id": 123, "name": "Comanda", "start_number": 1, "end_number": 100, "deleted": false, "created_at": "2020-01-01T09:00:00-03:00", "updated_at": "2020-01-01T09:00:00-03:00" } }