API v2 · Estável

GAUD ERP
Guia de Integração via API

Tudo que você precisa para integrar sua loja online com o GAUD ERP/PDV. Endpoints REST, webhooks em tempo real e exemplos prontos para produção.

O que é o GAUD ERP?

O GAUD é um sistema de gestão empresarial (ERP) com PDV integrado. Ele gerencia produtos, estoque, pedidos, clientes e financeiro. Esta API permite que sistemas externos (lojas online, marketplaces, ERPs) se conectem ao GAUD para sincronizar dados em tempo real.

O que você vai precisar antes de começar

Acesso ao painel administrativo

Solicite ao responsável da empresa o acesso ao painel do GAUD ERP.

Token de API

Gerado no painel clicando no seu avatar (canto superior direito) → Perfil → aba Tokens MCP.

Conhecimento básico

Familiaridade com REST APIs, JSON e chamadas HTTP autenticadas.

Quick Start

Comece a integrar em 3 passos.

01

Obter seu token de API

No painel administrativo do GAUD, clique no seu nome/avatar no canto superior direito → Perfil → aba Tokens MCP e gere um novo token.

  • Formato mcp_xxxxxxx
  • Exibido apenas uma vez — copie e guarde com segurança
  • Já contém a identificação da sua empresa
  • Pode ter validade definida ou ser permanente
02

Fazer sua primeira requisição

Liste os primeiros 5 produtos do catálogo para validar seu token:

curl -X GET "https://api-v2.gauderp.com/v1/catalog/products?page=0&limit=5" \
  -H "Authorization: Bearer mcp_seu_token_aqui" \
  -H "Content-Type: application/json"
03

Configurar webhooks (opcional)

Webhooks enviam notificações automáticas quando algo muda no GAUD (estoque atualizado, pedido criado, etc). Veja a seção Webhooks para configurar.

Informações Base

O essencial para começar a fazer requisições.

Isolamento de dados

Todas as requisições retornam apenas dados da sua empresa. Não é possível acessar dados de outras empresas, mesmo com tentativas de manipulação de parâmetros. O isolamento é garantido pelo token.

Base URL

https://api-v2.gauderp.com

Autenticação

API Token (mcp_...)

Rate Limit

300 req/min (auth) · 60 req/min (IP)

Content-Type

application/json

Docs

Swagger UI + OpenAPI

Autenticação

Todas as requisições são autenticadas via API Token no header Authorization.

Gerando seu API Token

  • Faça login no painel administrativo do GAUD ERP
  • Clique no seu nome ou avatar no canto superior direito
  • No drawer de perfil, acesse a aba Tokens MCP
  • Digite um nome para o token (ex: "Loja Online", "Marketplace") e clique em +
  • O token será exibido apenas uma vez — copie e guarde em local seguro
  • O token identifica automaticamente sua empresa — todos os dados retornados são filtrados para sua conta. Não é necessário enviar nenhum ID adicional (Company ID, Store ID, Account ID, etc.) em nenhuma requisição.
  • Use sempre HTTPS — a API rejeita requisições HTTP em texto puro.

Token exibido uma única vez

Após a criação, o token não poderá ser visualizado novamente. Guarde-o em um cofre de senhas ou variável de ambiente segura.

Formato e uso

O token é uma string com prefixo mcp_ (ex: mcp_a1b2c3d4e5f6...). Envie-o em todas as requisições autenticadas via header Authorization:

Authorization: Bearer mcp_xxxxx

Exemplo completo

curl -X GET "https://api-v2.gauderp.com/v1/catalog/products" \
  -H "Authorization: Bearer mcp_seu_token_aqui" \
  -H "Content-Type: application/json"

Permissões do Token

O token de API herda as permissões do usuário ao qual está vinculado. Para que o parceiro acesse todos os endpoints documentados, o administrador deve garantir que o usuário do token possua as seguintes permissões configuradas no painel:

RecursoPermissão de leituraPermissão de escrita
Clientescustomer:readcustomer:write
Pedidosorder:readorder:write
Produtosproduct:readproduct:write
Estoqueinventory:read, warehouse:readinventory:write, warehouse:write
Webhookswebhook:readwebhook:write

Importante

Se o token não possuir a permissão necessária, a API retornará 403 Forbidden. Solicite ao administrador do GAUD que configure as permissões corretas para o usuário vinculado ao token de integração.

Boas práticas de segurança

Nunca exponha o token

Não compartilhe o token em repositórios públicos, código client-side (frontend) ou documentação aberta.

Use variáveis de ambiente

Armazene o token em variáveis de ambiente (ex: TOKEN_GAUD) e nunca deixe-o hardcoded no código.

Token por integração

Crie tokens separados para cada integração (loja online, marketplace, ERP parceiro). Assim você pode revogar individualmente.

Rotação proativa

Revogue tokens que não são mais utilizados. Em caso de vazamento, revogue imediatamente e gere um novo.

Em caso de vazamento

Se você suspeitar que o token foi exposto, revogue-o imediatamente no painel GAUD e gere um novo. Não é necessário alterar senhas de usuário — apenas o token da integração.

Erros de autenticação

401 Unauthorized

Ocorre quando o token está ausente, inválido, expirado ou foi revogado.

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Token inválido, expirado ou revogado",
  "timestamp": "2026-05-29T14:30:00"
}

403 Forbidden

O token é válido, mas o recurso requer uma permissão que não está associada a este token.

{
  "status": 403,
  "error": "Forbidden",
  "message": "Token válido, mas sem permissão para acessar este recurso",
  "timestamp": "2026-05-29T14:30:00"
}

Endpoints

Todos os recursos REST disponíveis, agrupados por categoria.

Estoque / Inventário

Produtos / Catálogo

Pedidos

Exemplo: Criar Pedido (POST /v1/sales/orders)

Request
{
  "customer": {
    "id": 50
  },
  "products": [
    {
      "product": { "id": 123 },
      "quantity": 2,
      "price": 89.90,
      "discount": 10.00,
      "discountType": "PERCENTAGE"
    },
    {
      "product": { "id": 456 },
      "quantity": 1,
      "price": 73.82
    }
  ],
  "payments": [
    {
      "paymentMethod": { "id": 1 },
      "value": 235.64
    }
  ],
  "totalFreight": 18.00,
  "observation": "Pedido via loja online - #EXT-5432"
}
Response (201 Created)
{
  "id": 1001,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "number": 5432,
  "status": "PROPOSAL",
  "customer": {
    "id": 50,
    "name": "Maria Silva"
  },
  "total": 235.64,
  "totalFreight": 18.00,
  "observation": "Pedido via loja online - #EXT-5432",
  "createdAt": "2026-05-29T15:00:00"
}

Campos obrigatórios: products (com product.id, quantity e price) e payments (com paymentMethod.id e value).

Campos opcionais: customer (se omitido, vira venda sem cliente identificado), totalFreight, observation, discount e discountType por item, carrier.

O campo discountType aceita PERCENTAGE (desconto percentual) ou REAL (desconto em valor fixo R$).

Clientes

Exemplo: Criar Cliente (POST /v1/sales/customers)

Pessoa Física
{
  "name": "Maria da Silva",
  "type": "INDIVIDUAL",
  "documentNumber": "123.456.789-00",
  "email": "maria@email.com",
  "phone": "(51) 99999-0000",
  "dateOfBirth": "1990-05-15",
  "address": {
    "zipCode": "93000-000",
    "address": "Rua das Flores",
    "number": "123",
    "neighborhood": "Centro",
    "city": { "id": 4314902 },
    "state": "RS"
  }
}
Pessoa Jurídica
{
  "name": "Tech Solutions Ltda",
  "fantasyName": "Tech Solutions",
  "type": "COMPANY",
  "documentNumber": "12.345.678/0001-90",
  "stateRegistration": "123456789",
  "email": "contato@techsolutions.com.br",
  "phone": "(51) 3333-4444",
  "address": {
    "zipCode": "93000-000",
    "address": "Av. Brasil",
    "number": "500",
    "addressComplement": "Sala 201",
    "neighborhood": "Industrial",
    "city": { "id": 4314902 },
    "state": "RS"
  }
}

Campos obrigatórios: name, type (INDIVIDUAL ou COMPANY) e documentNumber (CPF ou CNPJ).

Campos opcionais: email, phone, dateOfBirth (só pessoa física), fantasyName e stateRegistration (só pessoa jurídica), address, observation.

O campo city.id é o código IBGE do município (ex: 4314902 = São Leopoldo/RS). Consulte a tabela IBGE para obter o código correto.

Ciclo de Vida do Pedido

Estados possíveis de um pedido e o fluxo típico de uma integração e-commerce.

StatusDescrição
PROPOSALPedido criado, aguardando aprovação
APPROVEDPedido aprovado, pronto para faturamento
DONEPedido finalizado e pago
NFE_ISSUEDNF-e emitida para o pedido
NFCE_ISSUEDNFC-e emitida (cupom fiscal)
NFCE_AND_NFE_ISSUEDAmbos os documentos fiscais emitidos
FISCALDocumento fiscal processado
CANCELLEDPedido cancelado
RETURNEDDevolução processada

Fluxo típico para loja online

A maioria das integrações e-commerce percorre apenas o caminho feliz abaixo.

PROPOSALAPPROVEDDONENFE_ISSUED
PROPOSAL / APPROVEDCANCELLED

Para integrações e-commerce

O fluxo mais comum é PROPOSAL → APPROVED → DONE. Os estados fiscais (NFE_ISSUED, NFCE_ISSUED) são gerenciados internamente pelo GAUD e notificados via webhook order.status.changed. Sua integração normalmente só precisa se preocupar com PROPOSAL, APPROVED, DONE e CANCELLED.

Webhooks

Receba eventos em tempo real direto no seu backend.

O que são webhooks?

Webhooks são notificações automáticas que o GAUD envia para uma URL sua sempre que algo importante acontece (ex: um produto teve o estoque alterado, um pedido foi criado). Em vez de ficar consultando a API repetidamente para verificar mudanças, você recebe um aviso instantâneo.

Eventos disponíveis

Você pode assinar qualquer combinação dos 8 eventos abaixo ao criar um webhook.

Estoque

  • product.stock.changedEstoque de um produto foi alterado

Produto

  • product.createdNovo produto cadastrado
  • product.updatedProduto atualizado (preço, nome, etc.)
  • product.deletedProduto removido

Pedido

  • order.createdNovo pedido criado
  • order.status.changedStatus do pedido alterou
  • order.cancelledPedido cancelado
  • order.returnedDevolução processada

Payload entregue no seu endpoint

Quando um evento ocorre, o GAUD envia um POST para a URL cadastrada com o seguinte formato:

product.stock.changed

{
  "eventType": "product.stock.changed",
  "timestamp": "2026-05-29T15:10:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "productId": 123,
    "warehouseId": 1,
    "qtyManagerial": 140.00,
    "qtyFiscal": 150.00,
    "qtyReserved": 12.00,
    "available": 128.00
  }
}

product.created

{
  "eventType": "product.created",
  "timestamp": "2026-05-29T14:00:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "productId": 789,
    "name": "Camiseta Básica Preta M",
    "sku": "CAM-BAS-PRT-M",
    "price": 89.90,
    "active": true,
    "createdAt": "2026-05-29T14:00:00"
  }
}

product.updated

{
  "eventType": "product.updated",
  "timestamp": "2026-05-29T14:30:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "productId": 789,
    "changedFields": ["price", "name"],
    "updatedAt": "2026-05-29T14:30:00"
  }
}

product.deleted

{
  "eventType": "product.deleted",
  "timestamp": "2026-05-29T15:00:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "productId": 789,
    "deletedAt": "2026-05-29T15:00:00"
  }
}

order.created

{
  "eventType": "order.created",
  "timestamp": "2026-05-29T15:10:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": 5432,
    "status": "PROPOSAL",
    "customerId": 50,
    "total": 253.62,
    "createdAt": "2026-05-29T15:00:00"
  }
}

order.status.changed

{
  "eventType": "order.status.changed",
  "timestamp": "2026-05-29T15:15:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "previousStatus": "PROPOSAL",
    "newStatus": "APPROVED",
    "updatedAt": "2026-05-29T15:15:00"
  }
}

order.cancelled

{
  "eventType": "order.cancelled",
  "timestamp": "2026-05-29T16:00:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": 5432,
    "reason": "Cliente solicitou cancelamento",
    "cancelledAt": "2026-05-29T16:00:00"
  }
}

order.returned

{
  "eventType": "order.returned",
  "timestamp": "2026-05-29T17:00:00",
  "attempt": 1,
  "test": false,
  "payload": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": 5432,
    "previousStatus": "DONE",
    "returnedAt": "2026-05-29T17:00:00"
  }
}

Implemente idempotência

O mesmo evento pode ser entregue mais de uma vez. Use o campopayload.orderId (ou similar) como chave única e retorne HTTP 200 para confirmar o recebimento.

Validação de assinatura (HMAC-SHA256)

Ao cadastrar um webhook, o GAUD usa o secret informado para assinar cada notificação. O header X-Gaud-Signature-256 contém o HMAC-SHA256 do corpo da requisição. Valide a assinatura antes de processar o payload para garantir que a notificação veio do GAUD.

import crypto from "crypto";

function isValidGaudSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

// Express
app.post("/webhooks/gaud", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-Gaud-Signature-256");
  if (!sig || !isValidGaudSignature(req.body, sig, process.env.GAUD_WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString());
  // processa event...
  res.status(200).send("ok");
});

Como testar webhooks em desenvolvimento

  • webhook.site — gera uma URL pública instantânea para inspecionar payloads recebidos sem precisar de servidor.
  • ngrok — expõe seu servidor local (ex: localhost:3000) em uma URL HTTPS pública, permitindo que o GAUD entregue eventos diretamente no seu ambiente de dev.
  • Use o endpoint POST /v1/settings/webhooks/{id}/test para disparar um evento de teste sob demanda.

Filtros Dinâmicos

Use o padrão ?field$operation=value para filtrar qualquer endpoint paginado.

OperadorDescriçãoExemplo
eqIgual astatus$eq=ACTIVE
neqDiferente destatus$neq=INACTIVE
gtMaior quetotal$gt=100
ltMenor questock$lt=10
gteMaior ou igualcreatedAt$gte=2026-01-01
lteMenor ou igualprice$lte=99.90
matchContém (like)name$match=camiseta
matchAbbrContém abreviaçãoname$matchAbbr=cam
inEstá na listastatus$in=OPEN,CLOSED
betweenEntre dois valorestotal$between=50,200
isNullÉ nuloemail$isNull=true
isNotNullNão é nulophone$isNotNull=true

Parâmetros de paginação

page
Página (começa em 0)
limit
Itens por página (padrão: 10, máximo recomendado: 500)
sort.attribute
Campo para ordenação
sort.order
ASC ou DESC
condition
AND ou OR (padrão: OR)

Exemplo completo

GET /v1/sales/customers?name$match=silva&type$eq=PF&createdAt$gte=2026-01-01&page=0&limit=10&sort.attribute=name&sort.order=ASC

Arquitetura da Integração

Como GAUD ERP, seu backend e sua loja online se comunicam.

GAUD ERP

Estoque mestre · PDV

Partner Backend

Integração · Webhooks

Loja Online

Catálogo · Checkout

01

Venda no PDV

  1. Venda no PDV (GAUD)
  2. Webhook product.stock.changed
  3. Parceiro atualiza estoque online
02

Venda Online

  1. Pedido na loja online
  2. POST /v1/sales/orders
  3. GAUD baixa estoque físico
  4. Webhook order.created confirma
03

Sync Periódico

  1. Cron job no parceiro
  2. GET stock-balances
  3. Reconciliação de estoque

Rate Limiting

Limites de requisições para garantir estabilidade da API.

Por que existe limite?

Para garantir estabilidade para todos os parceiros integrados, a API limita o número de requisições por minuto. Planeje sua integração para respeitar esses limites — prefira webhooks para ser notificado de mudanças em vez de fazer polling frequente nos endpoints.

Autenticado

300 req/min

por conta

Não autenticado

60 req/min

por endereço IP

Headers de resposta

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1716998460

Resposta HTTP 429

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Limite de requisições excedido. Tente novamente em 23 segundos.",
  "timestamp": "2026-05-29T15:20:00"
}

Header adicional: Retry-After: 23

Dica de implementação

Monitore o header X-RateLimit-Remaining para implementar throttling proativo no seu backend antes de bater o limite.

Tratamento de Erros

Formato padrão de erros e códigos HTTP utilizados.

Formato padrão

{
  "status": 400,
  "error": "Bad Request",
  "message": "Descrição do erro",
  "timestamp": "2026-05-29T14:30:00",
  "errors": {
    "campo": "mensagem de validação"
  }
}
CódigoSignificadoQuando ocorre
200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso
204No ContentOperação realizada sem retorno
400Bad RequestValidação falhou ou regra de negócio violada
401UnauthorizedToken ausente, inválido ou expirado
403ForbiddenUsuário sem permissão para a ação
404Not FoundRecurso não encontrado
429Too Many RequestsRate limit excedido
500Internal Server ErrorErro interno do servidor

Erro de validação (400)

{
  "status": 400,
  "error": "Bad Request",
  "timestamp": "2026-05-29T14:30:00",
  "errors": {
    "name": "must not be blank",
    "email": "must be a well-formed email address",
    "items": "must not be empty"
  }
}

Erro de regra de negócio (400)

{
  "status": 400,
  "error": "Bad Request",
  "message": "Estoque insuficiente para o produto 'Camiseta Básica Preta M'",
  "timestamp": "2026-05-29T14:30:00"
}

Token inválido ou revogado (401)

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Token inválido, expirado ou revogado",
  "timestamp": "2026-05-29T14:30:00"
}

Permissão insuficiente (403)

{
  "status": 403,
  "error": "Forbidden",
  "message": "Token não possui permissão para este recurso. Verifique as permissões do usuário vinculado ao token.",
  "timestamp": "2026-05-29T14:30:00"
}

Recurso não encontrado (404)

{
  "status": 404,
  "error": "Not Found",
  "message": "Pedido não encontrado",
  "timestamp": "2026-05-29T14:30:00"
}

Erros comuns e como resolver

CódigoCausa comumSolução
401Token inválido, expirado ou ausenteVerifique o header Authorization ou gere um novo token no painel
403Token sem permissão para o recursoSolicite ao administrador que adicione as permissões necessárias ao usuário do token (ex: customer:read, order:write)
404Recurso não encontradoVerifique o ID do recurso na URL
409Conflito (ex: estoque insuficiente)Consulte o estado atual do recurso antes de tentar novamente
429Limite de requisições excedidoAguarde o tempo indicado no header Retry-After antes de repetir

Glossário

Termos do GAUD que você vai encontrar na documentação e nas respostas da API.

Account

Sua empresa/conta dentro do GAUD. Cada token de API está vinculado a uma única account, garantindo isolamento de dados.

Warehouse

Depósito ou local de estoque. Uma empresa pode ter vários depósitos (matriz, filiais, centro de distribuição).

PDV

Ponto de Venda — o sistema de caixa físico (frente de loja) integrado ao ERP.

Catalog

Catálogo de produtos com preços, atributos, marcas e variações (SKUs).

Stock Balance

Saldo de estoque de um produto em um depósito específico, com quantidade gerencial, fiscal, reservada e disponível.

Como o estoque disponível é calculado

Detalhamento dos campos retornados por endpoints de Stock Balance.

available = max(0, qtyManagerial − qtyReserved)
CampoDescrição
qtyManagerialQuantidade real em estoque (controlada por ajustes e vendas).
qtyFiscalQuantidade registrada fiscalmente (pode divergir temporariamente do gerencial).
qtyReservedQuantidade reservada por pedidos em aberto (ainda não faturados).
availableQuantidade disponível para venda: max(0, qtyManagerial − qtyReserved).

Use sempre o campo available

Exiba a disponibilidade na loja online a partir do campo available retornado pela API. Não calcule manualmente — o GAUD já considera reservas, divergências e regras internas.