Integre o seu ERP à KIPI

Visão geral

A API do Parceiro é uma API REST sobre HTTPS que devolve JSON. Tudo o que o app do parceiro faz, o seu ERP também pode fazer.

O que você pode fazer:

• Produtos — carga completa ou incremental do catálogo (preços por embalagem, estoque, imagem, quantidade mínima/máxima).
• Pedidos — baixar os pedidos feitos pelos clientes com todos os dados do cliente (razão social, CNPJ, endereço de entrega) e agir sobre eles: aceitar, recusar, marcar como entregue ou cancelar.

Autenticação

Use o mesmo e-mail e senha da sua conta de parceiro (a que você usa em parceiros.kipi.com.br).

curl -X POST https://pinn-b2b-atacadista.onrender.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "seu-email@empresa.com.br", "senha": "sua-senha"}'

Resposta:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 86400
}

Envie o access_token em todas as chamadas:

Authorization: Bearer eyJhbGciOi...

Produtos — carga em massa (recomendado)

É a rota ideal para integração com ERP: envie a lista de produtos e a KIPI faz upsert pelo campo codigo — se o código já existe, o produto é atualizado; se não existe, é criado. Pode rodar quantas vezes quiser (idempotente).

curl -X POST https://pinn-b2b-atacadista.onrender.com/produtos/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "codigo": "7891234567890",
      "descricao": "ARROZ BRANCO TIPO 1 5KG",
      "estoque": 350,
      "qtd_minima": 1,
      "qtd_maxima": 200,
      "imagem_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
      "precos": [
        {"unidade": "UN", "preco": 22.90, "quantidade_unidades": 1},
        {"unidade": "FD", "preco": 132.00, "quantidade_unidades": 6}
      ]
    },
    {
      "codigo": "7899876543210",
      "descricao": "OLEO DE SOJA 900ML",
      "imagem_base64": null,
      "estoque": 1200,
      "precos": [
        {"unidade": "CX", "preco": 118.80, "quantidade_unidades": 20}
      ]
    }
  ]'

Campos do produto

Produtos — listar e consultar

Consulta um produto pelo ID interno da KIPI (campo id retornado nas listagens).

Produtos — criar, atualizar e excluir (unitário)

Cria um produto (mesmo corpo de um item do bulk). Para integração, prefira o /produtos/bulk.

Atualização parcial: envie só os campos que quer mudar (ex.: {"estoque": 40}).

Remove o produto do catálogo.

Pedidos — status possíveis

Pedidos — listar com filtros

Cada item da lista traz: id, nome do cliente (varejista_nome_fantasia), valor_total, status, condicao_pagamento, data_criacao, nome do representante e a marcação venda_mais quando o pedido veio do programa VendeMais.

Pedidos — detalhe (com dados do cliente para o seu ERP)

Retorna o pedido completo. Os blocos importantes para o seu ERP:

{
  "id": "6a4d3821f6c928eea9ca02c0",
  "status": "pendente",
  "data_criacao": "2026-07-06T02:31:30",
  "condicao_pagamento": "21 DIAS",
  "valor_total": 246.20,

  "varejista_nome_fantasia": "MERCEARIA DA CLAU",     // dados do CLIENTE
  "varejista_razao_social": "CLAUDETE COMERCIO LTDA", // p/ cadastro no ERP
  "varejista_cnpj": "12.345.678/0001-90",
  "varejista_inscricao_estadual": "096/2782076",
  "varejista_endereco": "Av. Bento Goncalves, 4200 - Partenon - Porto Alegre/RS - CEP 90650-002",
  "varejista_email": "clau@mercearia.com.br",
  "varejista_telefone": "(51) 99999-8888",

  "endereco_entrega": {                                // onde ENTREGAR
    "logradouro": "Rua Joao Salomoni", "numero": "1365",
    "bairro": "Vila Nova", "cidade": "Porto Alegre",
    "uf": "RS", "cep": "91740-830", "complemento": null
  },

  "representante_nome": null,   // preenchido quando ha representante
  "venda_mais": false,          // true = vendido pelo representante (VendeMais)

  "itens": [
    {
      "produto_id": "665f0c...",
      "codigo": "7891234567890",         // SEU codigo de produto (do bulk)
      "descricao_produto": "ARROZ BRANCO TIPO 1 5KG",
      "unidade": "FD",                   // embalagem escolhida pelo cliente
      "quantidade": 10,
      "valor_unitario": 132.00,
      "valor_total": 1320.00
    }
  ]
}

Pedidos — ações (sem acessar o app)

Sem corpo. Marca o pedido como aceito.

{"motivo": "Estoque insuficiente para o item 7891234567890"}

Sem corpo. Marca como entregue (informe apenas após a entrega física — este evento também ativa clientes pré-cadastrados por representante).

{"motivo": "Cliente solicitou cancelamento"}

Todas respondem com {"id": "...", "status": "...", "data_criacao": "..."}.

Fluxo de integração recomendado

Exemplo prático de rotina do ERP (pode rodar a cada 5–15 minutos):

Exemplo completo (Python)

import requests

BASE = "https://pinn-b2b-atacadista.onrender.com"
EMAIL, SENHA = "seu-email@empresa.com.br", "sua-senha"

# 1) login
r = requests.post(f"{BASE}/auth/login", json={"email": EMAIL, "senha": SENHA})
r.raise_for_status()
token = r.json()["access_token"]
H = {"Authorization": f"Bearer {token}"}

# 2) carga de produtos (upsert pelo codigo)
catalogo = [
    {"codigo": "7891234567890", "descricao": "ARROZ BRANCO TIPO 1 5KG",
     "imagem_base64": None,  # ou "data:image/jpeg;base64,..."
     "estoque": 350, "precos": [{"unidade": "UN", "preco": 22.90, "quantidade_unidades": 1}]},
]
requests.post(f"{BASE}/produtos/bulk", json=catalogo, headers=H).raise_for_status()

# 3) baixar pedidos pendentes
pedidos = requests.get(f"{BASE}/pedidos/", params={"status": "pendente", "page_size": 100},
                       headers=H).json()["items"]

for p in pedidos:
    det = requests.get(f"{BASE}/pedidos/{p['id']}", headers=H).json()
    print("Pedido", det["id"], "-", det["varejista_nome_fantasia"],
          "- CNPJ", det.get("varejista_cnpj"), "- R$", det["valor_total"])
    # ... cadastre o cliente e importe os itens no seu ERP ...

    tem_estoque = True  # sua regra de negocio aqui
    if tem_estoque:
        requests.post(f"{BASE}/pedidos/{p['id']}/aceitar", headers=H).raise_for_status()
    else:
        requests.post(f"{BASE}/pedidos/{p['id']}/recusar",
                      json={"motivo": "Estoque insuficiente"}, headers=H).raise_for_status()

Erros e boas práticas

• Consulte por status=pendente em intervalos de 5 a 15 minutos — não é necessário consultar a cada segundo.
• O /produtos/bulk é idempotente: reenviar o mesmo catálogo não duplica produtos.
• Guarde o refresh_token apenas se for manter processos longos; para rotinas curtas, faça login a cada execução.
• Dúvidas ou credenciais: fale com a KIPI pelo WhatsApp (51) 9852-7906.