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.
UUID aleatório gerado por você. 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 UUID, nós não duplicaremos o registro.
Corpo requisição de atualização de um pedido de venda.
Lista de produtos deste pedido.
Id único do grid que este item faz parte.
O grid_id é o ID do Product Grid
Valor unitário do item.
É a soma do valor base deste item com a soma dos adicionais e com a soma do total dos atributos.
Fórmula: unitary_value = valor base do item + sum(attributes.total_value) + sum(additionals.total_value)
Valor total do item.
É a multiplicação da quantidade pelo valor unitário deste item.
Fórmula: total_value = amount * unitary_value
Lista de atributos deste produto neste pedido.
Lista de adicionais deste produto nesta venda.
Lista de componentes do combo. Obrigatório quando este item for um combo.
Id único da lista de produto do produto.
Você pode localizar os IDs da lista de preço do produto no endpoint de listagem de produtos de uma lista de preço.
Resumo monetário da venda
Valor total da venda já considerando o desconto e o frete e o valor de outras despesas
Valor de desconto na venda. Deixar em nulo quando um desconto no item for aplicado
Lista de pagamentos.
Valor total do pagamento
Lista de parcelamento.
Id único da parcela do método do pagamento na relação
Data do vencimento da parcela.
Valor da parcela
Tipo de entrega do pedido:
deliveryentregawithdrawalretirada
Número do pedido de venda. Este número pode ser gerado por você. Caso não envie, o sistema irá gerar automaticamente para você.
Data do registro do pedido de venda.
Status do pedido de venda.
Ao mudar o status para closed, gerará uma venda e não será mais permitido a alteração do pedido
canceledpedido de venda cancelada.closedpedido de venda fechada.in_preparationpedido em preparação.in_routepedido em entrega.openpedido de venda aberta.reservedpedido de venda reservada.takeoutpedido para retirar.waitingpedido de venda em espera.
- Mock server
https://cplug.redocly.app/_mock/openapi/api/v3/sale-orders/{saleOrderId}
- Dev
http://erp.connectplug.com.br/api/v3/sale-orders/{saleOrderId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://cplug.redocly.app/_mock/openapi/api/v3/sale-orders/{saleOrderId}' \
-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 '{
"items": [
{
"item_id": 123,
"id": 123,
"grid_id": 456,
"amount": 5,
"unitary_value": {
"amount": 99.95,
"currency": "BRL"
},
"total_value": {
"amount": 99.95,
"currency": "BRL"
},
"unitary_value_ipi": {
"amount": 99.95,
"currency": "BRL"
},
"discount": {
"amount": 99.95,
"currency": "BRL"
},
"notes": "sem chocolate",
"stock_id": 1234,
"attributes": [
{
"id": 456,
"attribute_id": 789,
"min_choices": 1,
"max_choices": 2,
"total_value": {
"amount": 99.95,
"currency": "BRL"
},
"price_calculation_type": "Highest",
"charge_from_quantity": 2,
"options": [
{
"id": 123,
"option_id": 123,
"amount": 5,
"unitary_value": {},
"discount": {}
}
]
}
],
"additionals": [
{
"additional_id": 123,
"amount": 1,
"unitary_value": {
"amount": 99.95,
"currency": "BRL"
},
"discount": {
"amount": 99.95,
"currency": "BRL"
},
"total_value": {
"amount": 99.95,
"currency": "BRL"
}
}
],
"components": [
{
"item_id": 123,
"id": 123,
"combo_item_id": 123,
"grid_id": 456,
"amount": 5,
"unitary_value": {
"amount": 99.95,
"currency": "BRL"
},
"total_value": {
"amount": 99.95,
"currency": "BRL"
},
"unitary_value_ipi": {
"amount": 99.95,
"currency": "BRL"
},
"discount": {
"amount": 99.95,
"currency": "BRL"
},
"notes": "sem chocolate",
"stock_id": 1234,
"attributes": [
{
"id": 456,
"attribute_id": 789,
"min_choices": 1,
"max_choices": 2,
"total_value": {},
"price_calculation_type": "Highest",
"charge_from_quantity": 2,
"options": [
null
]
}
],
"additionals": [
{
"additional_id": 123,
"amount": 1,
"unitary_value": {},
"discount": {},
"total_value": {}
}
],
"price_list_product_id": 456
}
],
"price_list_product_id": 456
}
],
"seller_id": 123,
"total": {
"value": {
"amount": 99.95,
"currency": "BRL"
},
"total_value_ipi": {
"amount": 99.95,
"currency": "BRL"
},
"discount": {
"amount": 99.95,
"currency": "BRL"
},
"other_expenses_value": {
"amount": 99.95,
"currency": "BRL"
}
},
"source_type": "erp",
"payments": [
{
"id": 1,
"payment_method_id": 1,
"bank_account_id": 5,
"total_value": {
"amount": 99.95,
"currency": "BRL"
},
"installments": [
{
"id": 1,
"due_date": "2020-01-01T09:00:00-03:00",
"value": {
"amount": 99.95,
"currency": "BRL"
},
"observation": "pagamento à vista"
}
],
"card_brand_id": 1,
"exchange_value": {
"amount": 99.95,
"currency": "BRL"
}
}
],
"delivery_type": "delivery",
"nature_transaction_id": 123,
"carrier": {
"shippingFee": {
"amount": 99.95,
"currency": "BRL"
},
"carrier_id": 1234
},
"address_id": 123,
"customer_id": 123,
"document_number": "123.456.789-00",
"observation": "Sem copo",
"user_id": 123,
"company_id": 123,
"sale_number": 1234,
"contingency_code": 12345,
"registration_date": "2020-01-01T09:00:00-03:00",
"status": "canceled"
}'Pedido de venda atualizado.
Identificador único do pedido de venda.
Status do pedido de venda.
canceledpedido de venda cancelada.closedpedido de venda fechada.in_preparationpedido em preparação.in_routepedido em entrega.openpedido de venda aberta.reservedpedido de venda reservada.takeoutpedido para retirar.waitingpedido de venda em espera.
Data do registro da venda.
Tipo de entrega do pedido:
deliveryentregawithdrawalretirada
{ "id": 123, "number": 123, "unique_id": "cf2e0a5e-aa58-4181-9c9b-47702bd2be99", "customer": { "id": 123, "name": "Nome do Cliente", "type": "individual", "birthday": "1990-12-25", "company_name": "MyCompany", "notes": "Minhas obervações do cliente", "documents": [ … ], "created_at": "2020-01-01T09:00:00-03:00", "updated_at": "2020-01-01T09:00:00-03:00" }, "address": { "id": 220, "type": "default", "street": "Avenida Paulista", "number": "42 A", "city_id": 1234, "ibge_code": "3550308", "state": "SP", "city": "São Paulo", "neighborhood": "Bela Vista", "complement": "Apto 2550", "zip_code": "01311000" }, "observation": "Sem copo", "status": "canceled", "items": [ { … } ], "payments": [ { … } ], "seller": { "id": 123, "name": "Fulano de tal", "email": "vendedor@email.com", "created_at": "2020-01-01T09:00:00-03:00", "updated_at": "2020-01-01T09:00:00-03:00", "deleted_at": "2020-01-01T09:00:00-03:00" }, "carrier": { "shipping_fee": { … }, "carrier_id": 1 }, "total": { "value": { … }, "discount": { … }, "total_value_ipi": { … }, "other_expenses_value": { … } }, "source_type": "erp", "company_name": "CPlug", "registration_date": "2020-01-01T09:00:00-03:00", "delivery_type": "delivery", "sale_id": 789, "created_at": "2020-01-01T09:00:00-03:00", "updated_at": "2020-01-01T09:00:00-03:00" }
UUID aleatório gerado por você. 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 UUID, nós não duplicaremos o registro.
Corpo requisição de atualização do status de um pedido de venda.
Tipo de status do pedido:
canceledpedido cancelada.closedpedido fechada.in_preparationpedido em preparação.in_routepedido em entrega.openpedido aberto.reservedpedido reservado.takeoutpedido para retirar.waitingpedido em espera.
Ao mudar o status para closed, o pedido gerará uma venda e NÂO será possível mais mudar o status do pedido.
- Mock server
https://cplug.redocly.app/_mock/openapi/api/v3/sale-orders/{saleOrderId}/status
- Dev
http://erp.connectplug.com.br/api/v3/sale-orders/{saleOrderId}/status
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://cplug.redocly.app/_mock/openapi/api/v3/sale-orders/{saleOrderId}/status' \
-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 '{
"status": "canceled",
"payments": [
{
"card_contract_id": 1,
"payment_id": 1,
"payment_method_id": 1,
"card_brand_id": 1,
"card_receipt": {
"authorization": "999996",
"nsu": "009999997",
"receipt": "SITEF\n00001\nBIN\nVIA - ESTABELECIMENTO\nCPLUG COMERCIO DE SOFTWARE LTDA\nAvenida da CPlug\nCuritibaTT000181\nEC:000000033999999 TERM:TFI038B9\n************9999\nAUT=999996 CV=009999997 DOC=999998\n18/03/20 17:27:57 C\nVISA\nCREDITO A VISTA\nVALOR 8.90\nTRANSACAO AUTORIZADA COM SENHA\n\n\nARQC: 35E8DF8A3234C308\nVISA CREDITO\nAID:A0000000031010\n(SiTef)"
}
}
]
}'