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.

Explorar Endpoints Swagger UI

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.

Base URL (PROD)

https://api-v2.gauderp.com

Base URL (DEV)

https://api-dev.gauderp.com

Autenticação

API Token (mcp_...)

Rate Limit

300 req/min (auth) · 120 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:

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

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.

Collection pronta para importar no Postman, com exemplos de payload simplificados para os principais endpoints de leitura e escrita.

Baixar Collection Postman

Autenticação e acesso

Outros(38)

Vendas e PDV

Outros(66)

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

Request

{
  "status": "APPROVED",
  "customer": { "id": 42 },
  "products": [
    {
      "product": { "id": 101 },
      "quantity": 2,
      "price": 89.90,
      "discount": 5,
      "discountType": "PERCENTAGE"
    },
    {
      "product": { "id": 205 },
      "quantity": 1,
      "price": 250.00,
      "discount": 0,
      "discountType": "PERCENTAGE"
    }
  ],
  "payments": [
    {
      "paymentMethod": { "id": 1 },
      "value": 420.81
    }
  ],
  "observation": "Pedido via integração"
}

Response (201 Created)

{
  "id": 1001,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "number": 5432,
  "status": "APPROVED",
  "customer": {
    "id": 42,
    "name": "Maria Silva"
  },
  "products": [
    { "product": { "id": 101 }, "quantity": 2, "price": 89.90, "discount": 5, "discountType": "PERCENTAGE", "total": 170.81 },
    { "product": { "id": 205 }, "quantity": 1, "price": 250.00, "discount": 0, "discountType": "PERCENTAGE", "total": 250.00 }
  ],
  "totalWithoutDiscount": 429.80,
  "totalDiscounts": 8.99,
  "total": 420.81,
  "observation": "Pedido via integração",
  "createdAt": "2026-05-29T15:00:00"
}

Não envie total nem totalDiscounts

São campos calculados pelo Gaud: qualquer valor enviado neles é ignorado — o servidor sempre recalcula o total a partir de products[], totalFreight e additionalDiscount.

Campos obrigatórios: se status ≠ PROPOSAL, são exigidos customer (com id), products (com product.id e quantity) e payments (com paymentMethod.id e value). Com status: "PROPOSAL" (default), o pedido pode ser criado vazio.

Campos opcionais: price por item (se omitido, busca da lista de preços do cliente), discount/discountType por item (PERCENTAGE — default — ou REAL), additionalDiscount/additionalDiscountType no nível do pedido (REAL — default — ou PERCENTAGE), totalFreight, carrier, observation.

Com status: "DONE", a soma dos payments[].value precisa ser ≥ ao total calculado pelo servidor (não ao total que você enviou, que é ignorado). Erro comum: 400 — "O valor pago é menor que o valor total da venda" — quase sempre é o desconto que não foi aplicado em products[].discount ou additionalDiscount. Veja os exemplos no endpoint de criação de pedido.

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.

Ordens de serviço e frota

Outros(51)

Produtos e catálogo

Outros(48)

Estoque

Outros(38)

Produtos: operações em massa

Outros(33)

Fiscal

Outros(71)

Financeiro

Outros(69)

CRM e automação

Outros(80)

Dashboards

Outros(9)

Integrações

Outros(36)

Loja online e utilitários

Outros(35)

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	Rascunho — não exige produtos/pagamentos
APPROVED	Aprovado — pagamentos são ajustados automaticamente para o total calculado
DONE	Finalizado — gera financeiro (contas a receber). Exige soma dos payments[].value ≥ ao total calculado pelo servidor
CANCELLED	Pedido cancelado
REFUND	Estornado
RETURNED	Devolução processada
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

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. Estados de devolução/estorno (REFUND, RETURNED) aparecem quando há devolução da venda.

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 cadastrado
product.updated— Produto atualizado (preço, nome, etc.)
product.deleted— Produto removido

Pedido

order.created— Novo pedido criado
order.status.changed— Status do pedido alterou
order.cancelled— Pedido cancelado
order.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:

Envelope

id — ID único do evento (evt_<uuid>)
type — nome do evento (ex.: order.created)
createdAt — data/hora ISO-8601 (UTC)
accountId — ID da conta (tenant) que originou o evento
data — objeto específico do evento
metadata — source e actorId, ambos opcionais

product.stock.changed

{
  "id": "evt_3f2a9c1b4d5e6f708192a3b4c5d6e7f8",
  "type": "product.stock.changed",
  "createdAt": "2026-05-29T15:10:00Z",
  "accountId": 123,
  "data": {
    "productId": 123,
    "warehouseId": 1,
    "qtyManagerial": 140.00,
    "qtyFiscal": 150.00,
    "qtyReserved": 12.00,
    "available": 128.00
  },
  "metadata": { "source": "SYSTEM" }
}

product.created

{
  "id": "evt_e5f60718293a4b5c6d7e8f9012345678",
  "type": "product.created",
  "createdAt": "2026-05-29T14:00:00Z",
  "accountId": 123,
  "data": {
    "productId": 789,
    "name": "Camiseta Básica Preta M",
    "sku": "CAM-BAS-PRT-M",
    "price": 89.90,
    "active": true,
    "createdAt": "2026-05-29T14:00:00"
  },
  "metadata": { "source": "MANUAL", "actorId": 42 }
}

product.updated

{
  "id": "evt_f60718293a4b5c6d7e8f901234567890",
  "type": "product.updated",
  "createdAt": "2026-05-29T14:30:00Z",
  "accountId": 123,
  "data": {
    "productId": 789,
    "changedFields": ["price", "name"],
    "updatedAt": "2026-05-29T14:30:00"
  },
  "metadata": { "source": "MANUAL", "actorId": 42 }
}

product.deleted

{
  "id": "evt_0718293a4b5c6d7e8f90123456789012",
  "type": "product.deleted",
  "createdAt": "2026-05-29T15:00:00Z",
  "accountId": 123,
  "data": {
    "productId": 789,
    "deletedAt": "2026-05-29T15:00:00"
  },
  "metadata": { "source": "MANUAL", "actorId": 42 }
}

order.created

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "order.created",
  "createdAt": "2026-05-29T15:10:00Z",
  "accountId": 123,
  "data": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": 5432,
    "status": "PROPOSAL",
    "customerId": 50,
    "total": 253.62,
    "createdAt": "2026-05-29T15:00:00"
  },
  "metadata": { "source": "MANUAL", "actorId": 42 }
}

order.status.changed

{
  "id": "evt_b2c3d4e5f6071829a3b4c5d6e7f80912",
  "type": "order.status.changed",
  "createdAt": "2026-05-29T15:15:00Z",
  "accountId": 123,
  "data": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "previousStatus": "PROPOSAL",
    "newStatus": "APPROVED",
    "updatedAt": "2026-05-29T15:15:00"
  },
  "metadata": { "source": "MANUAL", "actorId": 42 }
}

order.cancelled

{
  "id": "evt_c3d4e5f60718293a4b5c6d7e8f901234",
  "type": "order.cancelled",
  "createdAt": "2026-05-29T16:00:00Z",
  "accountId": 123,
  "data": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": 5432,
    "reason": "Cliente solicitou cancelamento",
    "cancelledAt": "2026-05-29T16:00:00"
  },
  "metadata": { "source": "MANUAL", "actorId": 42 }
}

order.returned

{
  "id": "evt_d4e5f60718293a4b5c6d7e8f90123456",
  "type": "order.returned",
  "createdAt": "2026-05-29T17:00:00Z",
  "accountId": 123,
  "data": {
    "orderId": 1001,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": 5432,
    "previousStatus": "DONE",
    "returnedAt": "2026-05-29T17:00:00"
  },
  "metadata": { "source": "MANUAL", "actorId": 42 }
}

Implemente idempotência

O mesmo evento pode ser entregue mais de uma vez. Use o headerX-Idempotency-Key (ou o campoid do envelope) como chave única e retorne HTTP 2xx para confirmar o recebimento.

Headers enviados em cada entrega

Header	Conteúdo
`Content-Type`	`application/json`
`X-Gaud-Signature-256`	`sha256=<hmac_hex>` — HMAC-SHA256 do corpo bruto com o `secret`
`X-Gaud-Event`	Nome do evento (ex.: `order.created`)
`X-Gaud-Delivery`	ID da entrega (`evt_<id>`)
`X-Idempotency-Key`	`evt_<eventId>_sub_<subId>_att_<tentativa>` — use para deduplicar reentregas

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 sha256= seguido do HMAC-SHA256 do corpo bruto (raw body) da requisição em hex minúsculo. Valide a assinatura em tempo constante 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 = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const received = Buffer.from(signatureHeader || "", "utf8");
  const expectedBuf = Buffer.from(expected, "utf8");
  if (received.length !== expectedBuf.length) return false;
  return crypto.timingSafeEqual(received, expectedBuf);
}

// 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");
});

Reentrega, timeouts e auto-desativação

Timeout: 5 s para conexão, 10 s para leitura.
Retentativas: até 6 tentativas com backoff imediata → 1 min → 5 min → 30 min → 2 h → 24 h.
Sucesso: qualquer resposta HTTP 2xx.
Auto-desativação: após 50 falhas consecutivas, a assinatura é desativada automaticamente. Reabilite via POST /v1/settings/webhooks/{id}/enable.
Filtro por produto: eventos de produto podem ser filtrados por productIds no campo filters da assinatura.

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.

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); default: 0
limit: Itens por página (máximo recomendado: 500); default: 10
sort.attribute: Campo para ordenação; default: —
sort.order: ASC ou DESC; default: ASC
condition: Lógica entre filtros (AND ou OR). Recomenda-se enviar explicitamente quando o resultado depender da combinação.; default: 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

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 · janela deslizante de 60 s

Não autenticado

120 req/min

por endereço IP · janela deslizante de 60 s

Headers de resposta

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

X-RateLimit-Reset é o instante (epoch, em segundos) em que a janela deslizante de 60 s reinicia.

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

Todos os erros seguem o padrão RFC 7807 (application/problem+json).

Formato padrão (RFC 7807)

{
  "type": "https://gaud.app/errors/{slug}",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Mensagem legível para humano.",
  "instance": "/v1/store/wishlist"
}

Campo	Descrição
`type`	URI que identifica a categoria do erro. Prefixo fixo https://gaud.app/errors/ + slug (ex: validation-error, not-found, forbidden).
`title`	Frase padrão do status HTTP (ex: "Unprocessable Entity").
`status`	Código HTTP, duplicado no corpo por conveniência.
`detail`	Mensagem legível, já traduzida, específica do erro.
`instance`	Path da requisição que gerou o erro.

Categorias de erro (slug → status)

Slug	Status	Quando ocorre
`validation-error`	`422`	Campo obrigatório ausente/inválido no body (errors[] presente)
`not-found`	`404`	Recurso não encontrado
`unprocessable-entity`	`422`	Regra de negócio violada
`bad-request`	`400`	Parâmetro inválido / tipo incorreto
`forbidden`	`403`	Sem permissão para o recurso
`token-expired`	`401`	Token expirado
`invalid-refresh-token`	`401`	Refresh token inválido/reutilizado
`upload-failed`	`400`	Arquivo excede tamanho máximo ou upload malformado
`external-service-unavailable`	`503`	Dependência externa (SEFAZ, gateway, etc) fora do ar
`request-timeout`	`503`	Timeout de operação assíncrona
`internal-error`	`500`	Erro não tratado

Nota de transição

Alguns endpoints mais novos da Loja Headless (/v1/store/** — wishlist, avaliações, leads, devoluções, carrinho/cupons) ainda retornam erro via o ProblemDetail padrão do Spring em casos pontuais de 401/404/409. O corpo tem os mesmos campos, mas type vem como about:blank em vez do slug. Trate type: "about:blank" como erro genérico (leia detail) — não dependa do slug estar sempre presente.

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	Parâmetro inválido ou tipo incorreto
`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
`422`	Unprocessable Entity	Validação de campo ou regra de negócio violada
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Erro interno do servidor
`503`	Service Unavailable	Dependência externa indisponível ou timeout

Erro de validação (422) — múltiplos campos

{
  "type": "https://gaud.app/errors/validation-error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Um ou mais campos são inválidos.",
  "instance": "/v1/store/wishlist",
  "errors": [
    { "field": "productUuid", "message": "must not be blank" }
  ]
}

Regra de negócio violada (422)

{
  "type": "https://gaud.app/errors/unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Estoque insuficiente para o produto 'Camiseta Básica Preta M'.",
  "instance": "/v1/sales/orders"
}

Token expirado (401)

{
  "type": "https://gaud.app/errors/token-expired",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Token expirado.",
  "instance": "/v1/catalog/products"
}

Permissão insuficiente (403)

{
  "type": "https://gaud.app/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Token válido, mas sem permissão para acessar este recurso.",
  "instance": "/v1/sales/orders"
}

Recurso não encontrado (404)

{
  "type": "https://gaud.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Pedido não encontrado.",
  "instance": "/v1/sales/orders/9999"
}

Erros comuns e como resolver

Código	Causa comum	Solução
`401`	Token inválido, expirado ou ausente (token-expired)	Verifique o header Authorization ou gere um novo token no painel
`403`	Token sem permissão para o recurso (forbidden)	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 (not-found)	Verifique o ID do recurso na URL
`422`	Validação de campos ou regra de negócio (validation-error / unprocessable-entity)	Leia detail e, quando presente, errors[] para saber quais campos corrigir
`429`	Limite de requisições excedido	Aguarde o tempo indicado no header Retry-After antes de repetir
`503`	Dependência externa indisponível (external-service-unavailable)	Implemente retry com backoff exponencial

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

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.

GAUD ERPGuia de Integração via API

O que é o GAUD ERP?

O que você vai precisar antes de começar

Quick Start

Obter seu token de API

Fazer sua primeira requisição

Configurar webhooks (opcional)

Informações Base

Autenticação

Gerando seu API Token

Formato e uso

Permissões do Token

Boas práticas de segurança

Erros de autenticação

Endpoints

Autenticação e acesso

Outros(38)

GET/v1/settings/me/mcp-tokensLista os tokens MCP do usuário autenticado (sem o valor secreto).

POST/v1/settings/me/mcp-tokensCria um novo token MCP. O campo token (valor completo) só aparece nesta resposta.

DELETE/v1/settings/me/mcp-tokens/{id}Revoga um token MCP.

GET/v1/settings/meRetorna os dados do usuário autenticado (com empresa, perfil, papéis, features e assinatura).

PUT/v1/settings/me/personal-detailsAtualiza os dados pessoais do usuário autenticado (phone aceita null).

PUT/v1/settings/me/avatarAtualiza a foto de perfil do usuário autenticado.

PUT/v1/settings/me/passwordAltera a senha do usuário autenticado (exige a senha atual).

GET/v1/settings/usersLista usuários com paginação e filtros dinâmicos.

GET/v1/settings/users/{id}Retorna um único usuário.

POST/v1/settings/usersCria um novo usuário. profile pode ser null; password/confirmPassword são omitidos quando não informados.

PUT/v1/settings/users/{id}Atualiza um usuário existente. Omita password/confirmPassword para manter a senha atual.

DELETE/v1/settings/users/{id}Exclui um usuário.

GET/v1/settings/profilesLista perfis com paginação.

GET/v1/settings/profiles/{id}Retorna um único perfil.

POST/v1/settings/profilesCria um novo perfil. O corpo envia os ids das autoridades no campo roles.

PUT/v1/settings/profiles/{id}Atualiza um perfil existente.

DELETE/v1/settings/profiles/{id}Exclui um perfil.

GET/v1/settings/roles/allRetorna todos os papéis em formato plano (com parent); o cliente monta a árvore hierárquica localmente.

GET/v1/settings/profiles/{profileId}/work-scheduleRetorna a grade semanal de horários do perfil.

PUT/v1/settings/profiles/{profileId}/work-scheduleSubstitui a grade semanal de horários do perfil.

POST/v1/work-schedule/extensionsLibera hora extra para um usuário em uma data específica. date em yyyy-MM-dd, extendedUntil em HH:mm, reason opcional.

GET/v1/work-schedule/extensionsLista as liberações de hora extra de uma data.

GET/v1/work-schedule/settingsRetorna as configurações globais de horário de trabalho.

PUT/v1/work-schedule/settingsAtualiza as configurações globais. toleranceMinutes aceita null.

GET/v1/settings/webhooksLista as assinaturas de webhook com paginação.

GET/v1/settings/webhooks/{id}Retorna o detalhe de uma assinatura.

POST/v1/settings/webhooksCria uma assinatura de webhook. filters é opcional (pode ser null); quando informado, só entrega eventos dos productIds/categoryIds listados.

PUT/v1/settings/webhooks/{id}Atualiza uma assinatura existente.

DELETE/v1/settings/webhooks/{id}Exclui uma assinatura.

POST/v1/settings/webhooks/{id}/enableReativa uma assinatura desabilitada.

POST/v1/settings/webhooks/{id}/disableDesabilita uma assinatura.

POST/v1/settings/webhooks/{id}/testDispara uma entrega de teste para a URL da assinatura.

GET/v1/settings/webhooks/eventsLista os tipos de evento disponíveis para assinatura.

GET/v1/settings/webhooks/{subscriptionId}/deliveriesLista o histórico de entregas de uma assinatura.

POST/v1/settings/webhooks/{subscriptionId}/deliveries/{deliveryId}/retryReenvia manualmente uma entrega que falhou.

POST/v1/settings/account-backup/generateSolicita a geração de um novo backup. Retorna o status inicial do processamento. status assume PENDING, PROCESSING, COMPLETED, FAILED.

GET/v1/settings/account-backup/statusRetorna o status do último backup. Responde 204 (sem corpo) quando não há backup.

GET/v1/settings/account-backup/download-urlRetorna a URL temporária para baixar o arquivo de backup gerado. O download em si é um arquivo binário (ZIP) servido pela URL retornada.

Vendas e PDV

Outros(66)

GET/v1/sales/ordersLista pedidos paginados, ordenados por number DESC.

GET/v1/sales/orders/{id}Retorna um pedido pelo ID.

POST/v1/sales/ordersCria um pedido.

PUT/v1/sales/orders/{id}Atualiza um pedido. Aceita o corpo completo (mesmo body do POST) ou parcial (ex.: apenas payments, usado antes da impressão térmica).

DELETE/v1/sales/orders/{id}Exclui um pedido.

PATCH/v1/sales/orders/{orderId}/items/{itemId}/price-listTroca a lista de preço de um único item do pedido. priceListId null limpa o override e volta à lista geral do cabeçalho.

PUT/v1/sales/orders/{id}/reopenReabre um pedido (devolve produtos ao estoque, remove crédito).

PUT/v1/sales/orders/{id}/returnRealiza a devolução do pedido.

GET/v1/sales/orders/report/{uuid}Baixa o relatório (orçamento) do pedido. Retorna binário (PDF), sem JSON. O cupom térmico fica em GET /v1/report/sales-thermal/order/{uuid} (binário).

GET/v1/sales/customersLista clientes paginados. Sem fantasyName, search/name fazem autocomplete (OR sobre name/fantasyName/code).

GET/v1/sales/customers/{id}Retorna um cliente pelo ID.

GET/v1/sales/customers/by-documentBusca cliente por CPF/CNPJ.

POST/v1/sales/customersCria um cliente.

PUT/v1/sales/customers/{id}Atualiza um cliente.

DELETE/v1/sales/customers/{id}Exclui um cliente.

GET/v1/sales/carriersLista transportadoras paginadas. search/name buscam em nome e nome fantasia (OR).

GET/v1/sales/carriers/{id}Retorna uma transportadora pelo ID.

POST/v1/sales/carriersCria uma transportadora.

PUT/v1/sales/carriers/{id}Atualiza uma transportadora.

DELETE/v1/sales/carriers/{id}Exclui uma transportadora.

GET/v1/sales/payment-methodsLista formas de pagamento paginadas, ordenadas por name.

GET/v1/sales/payment-methods/{id}Retorna uma forma de pagamento pelo ID.

POST/v1/sales/payment-methodsCria uma forma de pagamento.

GAUD ERP
Guia de Integração via API

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

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