Integre o Gira Bem com qualquer API, webhook, agente de WhatsApp ou sistema externo.

O Gira Bem centraliza produtos, variações, estoque, clientes, vendas, fiscal, pagamentos, loja online e webhooks. A integração ideal usa três blocos: API de catálogo, criação de pedidos e webhooks para eventos em tempo real.

Os três blocos

Vocabulário

• Workspace: empresa/conta dentro do Gira Bem.
• Loja online: vitrine pública nativa do Gira Bem, com slug e domínio próprio.
• Produto: item principal, com imagens, categorias e preço base.
• Variação: tamanho/cor/sabor/voltagem, com SKU, foto, preço e estoque próprios.
• Estoque: pode vir do ERP base ou de loja/depósito separado.
• Token de conexão: identifica a loja ou workspace para APIs públicas controladas.

No painel, acesse Webhooks & API para criar endpoints de saída, ver segredos HMAC e configurar recebimento. Para integrações de catálogo/pedido, use sempre tokens e assinatura.

Cabeçalhos comuns

Content-Type: application/json
Authorization: Bearer <token-ou-segredo-da-conexao>
X-Connect-Signature: sha256=<hmac>
X-Connect-Timestamp: 1710000000

Todo produto publicado na loja online tem URL pública, SEO automático, Open Graph, canonical, schema.org Product e feed JSON para agentes. Isso permite que IAs e sistemas externos encontrem nome, descrição, preço, fotos, disponibilidade e link de compra.

Feed ACP

GET https://girabem.com.br/api/public/acp/{connection_token}

Resposta:
{
  "protocol": "agentic-commerce-product-feed",
  "store": { "name": "Minha Loja", "url": "https://..." },
  "products": [
    {
      "id": "uuid",
      "sku": "CAMISETA-P",
      "title": "Camiseta Preta",
      "description": "...",
      "link": "https://.../produto/camiseta-preta",
      "image_link": "https://.../foto.jpg",
      "availability": "in_stock",
      "price": "99.90 BRL",
      "brand": "Minha Loja"
    }
  ]
}

Quando usar o assinado

Para agentes de WhatsApp, prefira o catálogo assinado quando precisar de variações e estoque em tempo real. Para descoberta por IA, use o feed ACP e as páginas públicas dos produtos.

Use este fluxo quando um agente de WhatsApp, chatbot, CRM ou sistema externo fechar uma venda. O Gira Bem recalcula preço e estoque internamente; o integrador envia apenas IDs e quantidades.

A requisição

POST https://girabem.com.br/api/public/orders
Content-Type: application/json
X-Connect-Timestamp: 1710000000
X-Connect-Signature: sha256=<hmac_do_timestamp_e_body>

{
  "external_id": "whatsapp-5511999990000-1700000000",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@email.com",
    "phone": "+5511999990000",
    "document": "12345678909"
  },
  "items": [
    { "product_id": "uuid-do-produto", "variant_id": "uuid-da-variacao", "quantity": 2 }
  ],
  "payment": {
    "method": "pix",
    "provider": "mercadopago"
  },
  "metadata": {
    "source": "agente-whatsapp",
    "conversation_id": "abc123"
  }
}

A resposta

Resposta esperada:

{
  "ok": true,
  "order_id": "uuid-da-venda",
  "status": "pending",
  "payment_url": "https://checkout...",
  "pix_code": "000201...",
  "next_action": "send_pix_code"
}

O que fazer com a resposta

• payment_url: envie ao cliente quando a forma for link/cartão/boleto.
• pix_code: envie como copia-e-cola quando o pagamento for PIX.
• next_action: indica se o agente deve mandar link, PIX ou orientar pagamento no caixa.

Cadastre uma URL no painel para receber eventos. O Gira Bem envia POST com corpo JSON e assinatura HMAC.

Cabeçalhos e envelope

Headers enviados:
X-Listralize-Event: sale.paid
X-Listralize-Delivery: uuid-da-entrega
X-Listralize-Timestamp: 1710000000
X-Listralize-Signature: sha256=<hmac>

Envelope:
{
  "id": "uuid-da-entrega",
  "event": "sale.paid",
  "created_at": "2026-06-30T00:00:00.000Z",
  "data": { "id": "uuid-do-recurso", "status": "approved" }
}

Eventos disponíveis

Se outro sistema já tem webhooks, envie para a URL de recebimento do workspace. Isso registra eventos externos e permite criar automações internas depois.

A URL de recebimento

POST https://girabem.com.br/api/public/webhooks/in/{token_do_workspace}?source=meu-sistema&event=stock.changed
Content-Type: application/json

{ "product_id": "uuid", "variant_id": "uuid", "quantity": 12 }

A loja online aceita configuração por workspace/loja para Meta Pixel, Google Analytics 4, Google Ads, conversões aprimoradas e OpenAI Ads Pixel. Os scripts são injetados no layout da loja e eventos como visualização, carrinho, checkout e compra são disparados no navegador e no backend quando aplicável.

O que configurar

• Configure na edição da loja: Marketing e Pixels.
• Use domínio próprio verificado para melhorar confiança, SEO e mensuração.
• Produtos publicados geram metadata e JSON-LD automaticamente.

As mesmas quatro peças da referência — catálogo, pedido, webhook de saída e webhook de entrada — montam integrações bem diferentes. Seis que já rodam:

Seis integrações

Passe por esta lista antes de considerar a integração pronta. Ela é curta de propósito: cada item é uma coisa que, faltando, aparece como chamado no suporte.

Os oito passos

1. Crie ou selecione o workspace correto.

2. Publique produtos na loja online.

   Confira se as variações têm foto, SKU e estoque.

3. Configure domínio próprio da loja, quando houver.

4. Configure os pixels de Meta/Google/OpenAI na loja.

   Só é necessário se você usa mídia paga ou IA comercial.

5. Crie endpoint de webhook e valide a assinatura HMAC.

6. Teste a criação de pedido com um produto real e uma variação real.

7. Confirme a resposta do pedido.

   Ela precisa trazer payment_url ou pix_code.

8. Monitore entregas e retentativas no painel de Webhooks & API.

Daqui para frente