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.
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
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"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.
https://api-v2.gauderp.com
API Token (mcp_...)
300 req/min (auth) · 60 req/min (IP)
application/json
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
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_xxxxxExemplo 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:
| Recurso | Permissão de leitura | Permissão de escrita |
|---|---|---|
| Clientes | customer:read | customer:write |
| Pedidos | order:read | order:write |
| Produtos | product:read | product:write |
| Estoque | inventory:read, warehouse:read | inventory:write, warehouse:write |
| Webhooks | webhook:read | webhook:write |
Importante
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
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)
{
"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"
}{
"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)
{
"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"
}
}{
"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.
| Status | Descrição |
|---|---|
| PROPOSAL | Pedido criado, aguardando aprovação |
| APPROVED | Pedido aprovado, pronto para faturamento |
| DONE | Pedido finalizado e pago |
| NFE_ISSUED | NF-e emitida para o pedido |
| NFCE_ISSUED | NFC-e emitida (cupom fiscal) |
| NFCE_AND_NFE_ISSUED | Ambos os documentos fiscais emitidos |
| FISCAL | Documento fiscal processado |
| CANCELLED | Pedido cancelado |
| RETURNED | Devolução processada |
Fluxo típico para loja online
A maioria das integrações e-commerce percorre apenas o caminho feliz abaixo.
Para integrações e-commerce
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.changed— Estoque de um produto foi alterado
Produto
product.created— Novo produto cadastradoproduct.updated— Produto atualizado (preço, nome, etc.)product.deleted— Produto removido
Pedido
order.created— Novo pedido criadoorder.status.changed— Status do pedido alterouorder.cancelled— Pedido canceladoorder.returned— Devoluçã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
payload.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}/testpara disparar um evento de teste sob demanda.
Filtros Dinâmicos
Use o padrão ?field$operation=value para filtrar qualquer endpoint paginado.
| Operador | Descrição | Exemplo |
|---|---|---|
eq | Igual a | status$eq=ACTIVE |
neq | Diferente de | status$neq=INACTIVE |
gt | Maior que | total$gt=100 |
lt | Menor que | stock$lt=10 |
gte | Maior ou igual | createdAt$gte=2026-01-01 |
lte | Menor ou igual | price$lte=99.90 |
match | Contém (like) | name$match=camiseta |
matchAbbr | Contém abreviação | name$matchAbbr=cam |
in | Está na lista | status$in=OPEN,CLOSED |
between | Entre dois valores | total$between=50,200 |
isNull | É nulo | email$isNull=true |
isNotNull | Não é nulo | phone$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=ASCArquitetura 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
Venda no PDV
- Venda no PDV (GAUD)
- Webhook product.stock.changed
- Parceiro atualiza estoque online
Venda Online
- Pedido na loja online
- POST /v1/sales/orders
- GAUD baixa estoque físico
- Webhook order.created confirma
Sync Periódico
- Cron job no parceiro
- GET stock-balances
- 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: 1716998460Resposta 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
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ódigo | Significado | Quando ocorre |
|---|---|---|
200 | OK | Requisição bem-sucedida |
201 | Created | Recurso criado com sucesso |
204 | No Content | Operação realizada sem retorno |
400 | Bad Request | Validação falhou ou regra de negócio violada |
401 | Unauthorized | Token ausente, inválido ou expirado |
403 | Forbidden | Usuário sem permissão para a ação |
404 | Not Found | Recurso não encontrado |
429 | Too Many Requests | Rate limit excedido |
500 | Internal Server Error | Erro 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ódigo | Causa comum | Solução |
|---|---|---|
401 | Token inválido, expirado ou ausente | Verifique o header Authorization ou gere um novo token no painel |
403 | Token sem permissão para o recurso | Solicite ao administrador que adicione as permissões necessárias ao usuário do token (ex: customer:read, order:write) |
404 | Recurso não encontrado | Verifique o ID do recurso na URL |
409 | Conflito (ex: estoque insuficiente) | Consulte o estado atual do recurso antes de tentar novamente |
429 | Limite de requisições excedido | Aguarde 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)| Campo | Descrição |
|---|---|
qtyManagerial | Quantidade real em estoque (controlada por ajustes e vendas). |
qtyFiscal | Quantidade registrada fiscalmente (pode divergir temporariamente do gerencial). |
qtyReserved | Quantidade reservada por pedidos em aberto (ainda não faturados). |
available | Quantidade disponível para venda: max(0, qtyManagerial − qtyReserved). |
Use sempre o campo available
available retornado pela API. Não calcule manualmente — o GAUD já considera reservas, divergências e regras internas.