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.

• 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. Nunca coloque segredos no frontend do seu agente.

Headers 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.

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

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.

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

Resposta esperada:

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

• 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. Responda 2xx em até 10 segundos; caso contrário haverá retentativas.

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

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.

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, TikTok Pixel 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.

• 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.

1. Crie ou selecione o workspace correto.
2. Publique produtos na loja online e confira se variações têm foto, SKU e estoque.
3. Configure domínio próprio da loja, quando houver.
4. Configure pixels de Meta/Google/OpenAI na loja, se usar mídia paga ou IA comercial.
5. Crie endpoint de webhook e valide assinatura HMAC.
6. Teste criação de pedido com um produto real e uma variação real.
7. Confirme que a resposta retorna payment_url ou pix_code.
8. Monitore entregas e retentativas no painel de Webhooks & API.