API v1

Documentação da API PeGow para integração ERP

Integre Totvs, Linx e outros ERPs ao PeGow para publicar automaticamente produtos próximos ao vencimento.

Gerar chave de API

Introdução

A API de integração ERP da PeGow permite enviar em lote produtos próximos ao vencimento para publicação no marketplace. O fluxo foi projetado para cenários de sincronização automática entre ERPs como Totvs, Linx e sistemas proprietários.

Base URL

url
https://pegow.com.br/api/erp/v1
v1 - Estavel

Autenticação

Gere uma chave em /merchant/api-keys e envie o token em todas as requisições no header Authorization.

http
Authorization: Bearer pgw_sua_chave_aqui

Nunca exponha sua chave em código client-side. Use variáveis de ambiente no servidor do seu ERP.

Gerar minha chave de API

Endpoint de Inventário

POST/api/erp/v1/inventory/batch

Recebe um array de produtos e realiza UPSERT no inventário do tenant autenticado. O campo ean representa o codigo interno/ticket usado na loja, enquanto original_ean e opcional e guarda o codigo de barras real para enriquecimento. Limite: 500 itens por requisição.

CampoTipoObrigatórioDescrição
eanstringSimCodigo interno/ticket numerico usado como chave principal no estoque
original_eanstringNaoCodigo de barras real do fabricante (EAN-8, EAN-13 ou UPC-A) para lookup e catalogo
product_namestringSimNome do produto (2 a 255 caracteres)
descriptionstringNãoDescrição opcional (máx. 1000 caracteres)
original_pricenumberSimPreço original em reais (> 0)
discount_pricenumberSimPreço com desconto em reais (> 0 e ≤ original_price)
quantityintegerSimQuantidade disponível em estoque (≥ 0)
expiry_datestringSimData de validade no formato YYYY-MM-DD (≥ data de hoje)
store_codestringNãoCódigo da filial (opcional; roteia o item para o estoque da filial se presente)
HeaderValorObrigatório
AuthorizationBearer <sua_chave>Sim
Content-Typeapplication/jsonSim

Schema do Payload

O corpo da requisição deve ser um array JSON com 1 a 500 objetos.

json
[
  {
    "ean": "200000192837",
    "original_ean": "7891000000021",
    "product_name": "Leite Integral Itambe 1L",
    "description": "Leite integral longa vida, caixa 1 litro.",
    "original_price": 7.49,
    "discount_price": 4.99,
    "quantity": 24,
    "expiry_date": "2026-03-05"
  },
  {
    "ean": "200000192838",
    "original_ean": "7896017201019",
    "product_name": "Iogurte Natural Integral 170g",
    "description": "Iogurte natural sem adicao de acucar.",
    "original_price": 4.99,
    "discount_price": 2.99,
    "quantity": 36,
    "expiry_date": "2026-03-03"
  }
]

Endpoint de Baixa Rápida

POSTPOST /api/erp/v1/inventory/decrement

Use este endpoint para abater estoque fisico imediatamente quando uma venda acontecer fora do app. A baixa e atomica e consome os lotes em ordem FEFO.

CampoTipoObrigatórioDescrição
eanstringSimCodigo interno/ticket do produto a ser abatido
quantity_soldintegerSimQuantidade vendida na loja fisica (minimo 1)
json
{
  "ean": "200000192837",
  "quantity_sold": 1
}
200 OK
json
{
  "success": true,
  "ean": "200000192837",
  "quantity_sold": 1,
  "remaining_quantity": 23,
  "affected_lots": 1
}
409 Conflict
json
{
  "error": "Estoque insuficiente para baixa solicitada"
}

Exemplos de Resposta

200 OK
json
{
  "processed": 2,
  "errors": []
}
422 Unprocessable Entity
json
{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "original_ean": ["EAN original invalido"]
    },
    "formErrors": []
  }
}
401 Unauthorized
json
{
  "error": "Unauthorized"
}

Códigos de Erro

CódigoStatusCausaAção Recomendada
200OKSucessoItens processados com sucesso
400Bad RequestJSON malformadoVerificar o corpo da requisição
401UnauthorizedToken ausente, inválido ou revogadoVerificar o header Authorization e o status da chave
422Unprocessable EntityFalha de validação Zod ou constraint do bancoCorrigir os campos indicados em details
403ForbiddenFilial tentando criar sub-filialUsar a chave API da conta Matriz
422Unprocessable Entitystore_code não encontrado na redeCadastrar a filial via POST /api/erp/v1/stores antes de enviar inventário
500Internal Server ErrorErro interno do servidorTentar novamente ou contatar suporte

Multi-Lojas (Rede Matriz/Filial)

O modelo Matriz/Filial permite cadastrar múltiplas lojas em uma rede com uma única chave de API da conta Matriz. O fluxo possui duas etapas: primeiro cadastrar/atualizar a filial, depois enviar inventário com store_code para rotear os itens ao estoque correto.

Endpoint de Cadastro de Lojas

POSTPOST /api/erp/v1/stores
CampoTipoObrigatórioDescrição
store_codestringSimCódigo da filial no ERP (1 a 50 caracteres)
namestringSimNome da filial (2 a 255 caracteres)
cnpjstringSimCNPJ com 14 dígitos numéricos
cepstringSimCEP com 8 dígitos numéricos
addressstringSimEndereço completo da filial
latnumberNãoLatitude (fornecer junto com lng)
lngnumberNãoLongitude (fornecer junto com lat)
json
{
  "store_code": "SP-001",
  "name": "Big Box Asa Sul",
  "cnpj": "12345678000195",
  "cep": "70390900",
  "address": "CLS 304 Bloco A, Asa Sul, Brasilia - DF",
  "lat": -15.7998,
  "lng": -47.8992
}

lat/lng opcionais. Filiais sem GPS não aparecem no feed de proximidade.

201 Created
json
{
  "store_id": "8e6f4a4f-2b2d-48f8-bdb9-0b2f61b4f8cf",
  "store_code": "SP-001",
  "created": true
}
200 OK (upsert)
json
{
  "store_id": "8e6f4a4f-2b2d-48f8-bdb9-0b2f61b4f8cf",
  "store_code": "SP-001",
  "created": false
}
403 Forbidden
json
{
  "error": "Filiais não podem cadastrar sub-filiais. Use a chave API da conta Matriz."
}

Roteamento por Filial no Inventário

Adicione store_code em cada item do batch para direcionar ao estoque da filial.

CampoTipoObrigatórioDescrição
store_codestringNãoCódigo da filial (max 50 chars)
json
[
  {
    "ean": "200000192837",
    "original_ean": "7891000000021",
    "product_name": "Leite Integral Itambe 1L",
    "description": "Leite integral longa vida, caixa 1 litro.",
    "original_price": 7.49,
    "discount_price": 4.99,
    "quantity": 24,
    "expiry_date": "2026-03-05",
    "store_code": "SP-001"
  },
  {
    "ean": "200000192838",
    "original_ean": "7896017201019",
    "product_name": "Iogurte Natural Integral 170g",
    "description": "Iogurte natural sem adicao de acucar.",
    "original_price": 4.99,
    "discount_price": 2.99,
    "quantity": 36,
    "expiry_date": "2026-03-03"
  }
]
422 Unprocessable Entity
json
{
  "error": "Loja 'SP-001' não encontrada. Cadastre o endereço da filial primeiro via POST /api/erp/v1/stores"
}

Fluxo Multi-Lojas

text
Matriz API Key -> POST /api/erp/v1/stores -> Filial criada
Matriz API Key + store_code -> POST /api/erp/v1/inventory/batch -> Estoque da Filial