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 (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:

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"
}

Registros excluídos

Quando um registro é excluído no GAUD (pedido, ordem de serviço, título financeiro etc.), ele não é apagado de vez: fica guardado como excluído e, por padrão, deixa de aparecer nas listagens da API. O parâmetro deleted permite consultar esses registros nas listagens paginadas.

Valores do parâmetro deleted

ValorO que retorna
exclude (padrão)Só registros ativos. É o comportamento quando o parâmetro não é enviado.
includeRegistros ativos e excluídos juntos.
onlySó os registros excluídos.

Nas listagens que aceitam o parâmetro, cada item da resposta traz o campo deletedAt: a data e hora da exclusão, ou null se o registro está ativo. O campo é somente leitura: se for enviado em POST ou PUT, é ignorado.

Exemplo: listar pedidos excluídos
curl -X GET "https://api-v2.gauderp.com/v1/sales/orders?deleted=only&page=0&limit=50" -H "Authorization: Bearer mcp_seu_token_aqui" -H "Content-Type: application/json"
Resposta (trecho)
{
  "content": [
    { "id": 485, "number": 485, "status": "DONE", "total": 0.00, "deletedAt": "2026-10-02T13:45:10" }
  ],
  "totalElements": 1
}

O parâmetro pode ser combinado com os demais filtros da listagem. O filtro de excluídos é sempre aplicado junto com os outros filtros, nunca como alternativa a eles. Exemplo: verificar quais pedidos de uma lista de IDs estão excluídos:

curl -X GET "https://api-v2.gauderp.com/v1/sales/orders?deleted=only&condition=and&id$in=485,490,511&limit=100" -H "Authorization: Bearer mcp_seu_token_aqui"

Importante

Valor inválido em deleted (ex.: deleted=all) retorna 400 Bad Request com os valores aceitos. A busca por ID (ex.: GET /v1/sales/orders/{id}) continua retornando 404 para registros excluídos: use a listagem com deleted=only para consultá-los.

Paginação e filtros

O tamanho da página é limit (padrão 10) e a página é page (começa em 0). Vários filtros na mesma requisição são combinados com OU por padrão; para exigir todos, envie condition=and.

Onde o parâmetro funciona

  • Pedidos: GET /v1/sales/orders (e /v1/sales/orders/slim)
  • Ordens de serviço: GET /v1/service/maintenances e GET /v1/sales/service-orders
  • Contas a receber: GET /v1/financial/invoices/receivable (inclusive com slim=true)
  • Contas a pagar: GET /v1/financial/invoices/payable
  • Produtos de estoque: GET /v1/inventory/products
  • Veículos: GET /v1/fleet/vehicles
  • Demais listagens paginadas de cadastros simples (marcas, grupos, formas de pagamento, transportadoras, categorias financeiras, contas bancárias etc.)

Onde o parâmetro NÃO funciona

Nestas listagens o parâmetro é ignorado e só registros ativos são retornados:

  • Resumos e totais: /v1/financial/invoices/receivable/summary, /v1/financial/invoices/payable/summary, /v1/sales/orders/summaries (para que valores excluídos não entrem nas somas)
  • Kanbans: /v1/service/service-order-kanban, /v1/vendas e os quadros do CRM
  • Notas fiscais: /v1/fiscal/order e /v1/fiscal/nfse
  • Catálogo: /v1/catalog/products
  • Clientes: /v1/sales/customers

Caso de uso: limpar títulos de pedidos excluídos

  1. Liste os títulos a receber em aberto que vieram de pedidos:

    GET /v1/financial/invoices/receivable?condition=and&sourceType$eq=ORDER&status$in=PENDING,OVERDUE&page=0&limit=200

    Guarde o id e o sourceId (ID do pedido) de cada título. Avance page até o fim.

  2. Consulte quais desses pedidos estão excluídos:

    GET /v1/sales/orders?deleted=only&condition=and&id$in=<sourceIds separados por vírgula>
  3. Remova os títulos dos pedidos retornados no passo 2:

    DELETE /v1/financial/invoices/receivable/bulk
    
    { "ids": [ ... ], "confirmCancelActiveCollection": true }

    (confirmCancelActiveCollection: true cancela também boleto ou cobrança ativa vinculada ao título)

Remova apenas títulos em aberto (PENDING/OVERDUE). Títulos já pagos representam dinheiro recebido e não devem ser excluídos.

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.

Autenticação e acesso

Outros(38)

Vendas e PDV

Outros(67)

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(44)

Estoque

Outros(38)

Produtos: operações em massa

Outros(33)

Fiscal

Outros(71)

Financeiro

Outros(70)

CRM e automação

Outros(80)

Dashboards

Outros(9)

Integrações

Outros(36)

Loja online e utilitários

Outros(35)

Bloqueio por WMS (blockedByWms)

Pedidos, Ordens de Serviço e Entradas Fiscais podem ser bloqueados enquanto estão em processamento num sistema de armazém (WMS). Um registro bloqueado não aceita alterações. Isso evita que alguém mude itens, quantidades ou status enquanto o WMS separa ou confere a mercadoria.

O bloqueio é controlado pela integração. Não há botão na tela do GAUD: quem liga e desliga é o sistema parceiro, pela API.

O campo

CampoTipoPadrãoOnde aparece
blockedByWmsbooleanfalseRespostas de GET de Pedido, OS e Entrada Fiscal

Ao enviar, o campo é opcional. Se ele não for enviado, o valor gravado é mantido.

Como bloquear

Envie "blockedByWms": true na requisição de alteração do registro.

Ordem de Serviço: junto com a troca de status. O campo status é obrigatório nesta requisição.

curl -X PATCH "https://api-v2.gauderp.com/v1/service/maintenances/{id}" -H "Authorization: Bearer mcp_seu_token_aqui" -H "Content-Type: application/json" -d '{"status": {"id": 1835}, "blockedByWms": true}'

Entrada Fiscal: aceita só os campos que mudam.

curl -X PUT "https://api-v2.gauderp.com/v1/inventory/provider-entries/{id}" -H "Authorization: Bearer mcp_seu_token_aqui" -H "Content-Type: application/json" -d '{"blockedByWms": true}'

Pedido: envie só o campo blockedByWms. Funciona com o pedido em qualquer status (em aberto, aprovado, concluído, com nota emitida ou em separação) e não altera mais nada no pedido.

curl -X PATCH "https://api-v2.gauderp.com/v1/sales/orders/{id}" -H "Authorization: Bearer mcp_seu_token_aqui" -H "Content-Type: application/json" -d '{"blockedByWms": true}'

Enviar o valor que o pedido já tem não dá erro e não muda nada. Se a integração repetir a chamada, ela passa normalmente.

Como desbloquear

Envie "blockedByWms": false. A mesma requisição que desbloqueia pode alterar o registro. Exemplo: ao receber a confirmação do WMS, a OS sai do bloqueio e muda de status numa única chamada:

curl -X PATCH "https://api-v2.gauderp.com/v1/service/maintenances/{id}" -H "Authorization: Bearer mcp_seu_token_aqui" -H "Content-Type: application/json" -d '{"status": {"id": 1502}, "blockedByWms": false}'

Pedido: para só liberar, envie {"blockedByWms": false}. Para liberar e mudar o status na mesma chamada, envie os dois campos:

curl -X PATCH "https://api-v2.gauderp.com/v1/sales/orders/{id}" -H "Authorization: Bearer mcp_seu_token_aqui" -H "Content-Type: application/json" -d '{"status": "APPROVED", "blockedByWms": false}'
status aceito no PATCH do PedidoSignificado
PROPOSALEm aberto (orçamento)
APPROVEDAprovado
DONEConcluído

Importante:

quando o status vem junto, o GAUD aplica as mesmas regras de quando o pedido é salvo na tela, por exemplo a baixa de estoque, o lançamento no financeiro e a forma de pagamento obrigatória para concluir. Se alguma regra não for atendida, o status não muda e a resposta traz o motivo.

Respostas do PATCH do Pedido:

SituaçãoResposta
Deu certo200 OK, com o pedido atualizado no corpo
Corpo sem status e sem blockedByWms400 Bad Request: "Informe o status ou o bloqueio do WMS."
status diferente de PROPOSAL, APPROVED ou DONE400 Bad Request. Separação, devolução, cancelamento e emissão de nota têm ações próprias.
Pedido já concluído, com nota, cancelado ou devolvido, com status diferente do atual400 Bad Request: o pedido precisa ser reaberto antes.
Pedido bloqueado e status enviado sem "blockedByWms": false422, com type blocked-by-wms (veja abaixo)

O que fica bloqueado

Com blockedByWms = true, a API recusa:

RegistroOperações recusadas
Pedidoalterar (PUT), mudar status (PATCH com status), excluir, reabrir, devolver, trocar tabela de preço (do pedido ou de um item), enviar para separação
Ordem de Serviçoalterar (PUT), mudar status (PATCH), excluir, reabrir, aprovar para o caixa, registrar pagamento, trocar tabela de preço de produto ou serviço
Entrada Fiscalalterar ou mudar etapa (PUT), excluir, reimportar impostos

As operações que aceitam corpo (PUT, o PATCH da OS e o PATCH do Pedido) passam quando trazem "blockedByWms": false. No Pedido, um PATCH só com blockedByWms sempre passa, para a integração conseguir travar e liberar. As demais (excluir, reabrir, devolver etc.) só funcionam depois que o registro for desbloqueado.

A leitura (GET) continua liberada normalmente.

Resposta quando o registro está bloqueado

422 Unprocessable Entity

{
  "type": "https://gaud.app/errors/blocked-by-wms",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Este registro está em processamento no WMS e não pode ser alterado no momento. Aguarde a confirmação do WMS e tente de novo.",
  "instance": "/v1/service/maintenances/410772"
}

Identifique o caso pelo type (blocked-by-wms), não pelo texto do detail, que pode mudar. Reenviar a mesma requisição dá o mesmo erro até o registro ser desbloqueado.

Fluxo recomendado

  1. Ao enviar o registro ao WMS, bloqueie (blockedByWms: true).
  2. Enquanto o WMS processa, ninguém consegue alterar o registro no GAUD.
  3. Ao receber a confirmação do WMS, desbloqueie e aplique a mudança (por exemplo, o novo status) na mesma requisição (blockedByWms: false).

Se a integração falhar antes de desbloquear, o registro continua bloqueado. Para liberar, envie "blockedByWms": false pela API.

Ciclo de Vida do Pedido

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

StatusDescrição
PROPOSALRascunho — não exige produtos/pagamentos
APPROVEDAprovado — pagamentos são ajustados automaticamente para o total calculado
DONEFinalizado — gera financeiro (contas a receber). Exige soma dos payments[].value ≥ ao total calculado pelo servidor
CANCELLEDPedido cancelado
REFUNDEstornado
RETURNEDDevolução processada
NFE_ISSUEDNF-e emitida para o pedido
NFCE_ISSUEDNFC-e emitida (cupom fiscal)
NFCE_AND_NFE_ISSUEDAmbos os documentos fiscais emitidos
FISCALDocumento 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

HeaderConteúdo
Content-Typeapplication/json
X-Gaud-Signature-256sha256=<hmac_hex> — HMAC-SHA256 do corpo bruto com o secret
X-Gaud-EventNome do evento (ex.: order.created)
X-Gaud-DeliveryID da entrega (evt_<id>)
X-Idempotency-Keyevt_<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.

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)
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. Por padrão, vários filtros na mesma requisição são combinados com OU; para exigir todos, envie condition=and.
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

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 · 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"
}
CampoDescrição
typeURI que identifica a categoria do erro. Prefixo fixo https://gaud.app/errors/ + slug (ex: validation-error, not-found, forbidden).
titleFrase padrão do status HTTP (ex: "Unprocessable Entity").
statusCódigo HTTP, duplicado no corpo por conveniência.
detailMensagem legível, já traduzida, específica do erro.
instancePath da requisição que gerou o erro.

Categorias de erro (slug → status)

SlugStatusQuando ocorre
validation-error422Campo obrigatório ausente/inválido no body (errors[] presente)
not-found404Recurso não encontrado
unprocessable-entity422Regra de negócio violada
bad-request400Parâmetro inválido / tipo incorreto
forbidden403Sem permissão para o recurso
token-expired401Token expirado
invalid-refresh-token401Refresh token inválido/reutilizado
upload-failed400Arquivo excede tamanho máximo ou upload malformado
external-service-unavailable503Dependência externa (SEFAZ, gateway, etc) fora do ar
request-timeout503Timeout de operação assíncrona
internal-error500Erro 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ódigoSignificadoQuando ocorre
200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso
204No ContentOperação realizada sem retorno
400Bad RequestParâmetro inválido ou tipo incorreto
401UnauthorizedToken ausente, inválido ou expirado
403ForbiddenUsuário sem permissão para a ação
404Not FoundRecurso não encontrado
422Unprocessable EntityValidação de campo ou regra de negócio violada
429Too Many RequestsRate limit excedido
500Internal Server ErrorErro interno do servidor
503Service UnavailableDependê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ódigoCausa comumSolução
401Token inválido, expirado ou ausente (token-expired)Verifique o header Authorization ou gere um novo token no painel
403Token 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)
404Recurso não encontrado (not-found)Verifique o ID do recurso na URL
422Validação de campos ou regra de negócio (validation-error / unprocessable-entity)Leia detail e, quando presente, errors[] para saber quais campos corrigir
429Limite de requisições excedidoAguarde o tempo indicado no header Retry-After antes de repetir
503Dependê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)
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.