Chaves API e Webhooks

Onde encontrar: Na barra lateral do painel Bizaldo, abra Definições. Use o separador Chaves API para criar chaves e o separador Webhooks para registar endpoints. A secção Geral no topo das Definições mostra o seu ID de Empresa e ID de Filial atuais, que muitas integrações precisam juntamente com a chave.

Quem pode gerir integrações

Empresa e filial

12345

Figura 1 — Separador Definições Chaves API com IDs de empresa e filial

Elementos do Ecrã

1

Separador Chaves API

Abra Definições e selecione Chaves API para gerir credenciais de integração.

2

ID da Empresa

Copie o ID da empresa para a sua integração. Corresponde à empresa selecionada no cabeçalho do painel.

3

ID da Filial

Copie o ID da filial para a sua integração. Corresponde à filial selecionada no cabeçalho do painel.

4

Criar Chave API

Inicie o fluxo de criação de chave.

5

Estatísticas de utilização

Total de chaves, chaves ativas, total de pedidos e pedidos de hoje.

Chaves API

O que uma chave API contém

Criar uma chave API

1. Inicie sessão com uma conta Administrador ou Super Administrador.
2. Selecione a empresa e filial corretas no cabeçalho do painel.
3. Vá a Definições → Chaves API.
4. Clique em Criar Chave API.
5. Introduza um nome (pelo menos 3 carateres) e descrição opcional.
6. Selecione as permissões. Conceda apenas o que a integração necessita (privilégio mínimo).
7. Clique em Criar Chave.
8. Copie a chave pública e a chave secreta imediatamente. Guarde o segredo num gestor de palavras-passe ou variável de ambiente (por exemplo, `BIZALDO_API_SECRET`). Nunca submeta segredos ao controlo de código-fonte nem os incorpore em código do lado do cliente.

1234

Figura 2 — Criar Chave API: nome, descrição e âmbitos de permissão

Elementos do Ecrã

1

Nome da Chave

Etiqueta obrigatória para a chave (mínimo de 3 carateres).

2

Descrição

Nota opcional descrevendo o que esta integração faz.

3

Permissões

Selecione âmbitos por grupo de entidade. Conceda apenas o que a integração necessita.

4

Criar Chave

Gere o par de chaves pública e secreta.

Permissões disponíveis

As empresas de restaurante também veem os grupos de permissões Mesas e Reservas. As de retalho e outras indústrias não.

Usar uma chave API

GET /api/v1/products HTTP/1.1
Host: openapi.bizaldo.com
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json

x-company-id: YOUR_COMPANY_ID
x-branch-id: YOUR_BRANCH_ID

• Sincronização de catálogo: Puxe ou envie produtos e categorias
• Automação de inventário: Reaja a alterações de nível de stock
• Relatórios personalizados: Crie relatórios a partir dos dados da sua filial
• Exportações noturnas: Puxe encomendas concluídas para ferramentas de contabilidade

Gerir chaves existentes

Webhooks

Eventos suportados

Selecione um ou mais eventos ao registar ou editar um webhook. É necessário pelo menos um evento.

Registar um webhook

1. Selecione a empresa e filial corretas no cabeçalho do painel.
2. Vá a Definições → Webhooks.
3. Clique em Registar Webhook.
4. Preencha o formulário:

5. Clique em Registar Webhook.

12345

Figura 3 — Registe um endpoint de webhook e subscreva eventos

Elementos do Ecrã

1

Separador Webhooks

Mude de Chaves API para Webhooks em Definições.

2

Empresa e filial

Contexto atual de empresa e filial para o webhook a ser registado.

3

URL do Endpoint

URL HTTPS público que recebe pedidos POST de evento.

4

Chave API

String secreta usada para verificar payloads de webhook recebidos.

5

Subscrever eventos

Escolha um ou mais tipos de evento a receber.

Após o registo, o Bizaldo apresenta um segredo de assinatura numa faixa amarela: "API Key - Save this now!" Este valor é apresentado apenas uma vez. Copie-o antes de fechar a faixa.

Verificar assinaturas de webhook

• Responder com 2xx em poucos segundos
• Ser idempotente. O mesmo evento pode ser entregue mais do que uma vez; desduplique usando o ID do evento, se fornecido no payload
• Usar HTTPS em produção

Gerir webhooks

• URL e descrição
• Eventos subscritos
• Estado Ativo/Inativo
• Data de criação

Desenvolvimento local

Melhores práticas de segurança

• Emita chaves separadas por ambiente (teste vs produção) e por integração.
• Aplique permissões de privilégio mínimo. Uma sincronização de catálogo apenas de leitura não precisa de `orders:delete`.
• Restrinja URLs de webhook a HTTPS e valide `X-Bizaldo-Signature` em cada pedido.
• Não exponha segredos de API em JavaScript de navegador, aplicações móveis ou repositórios públicos.
• Ative a autenticação de dois fatores em contas de administrador que podem gerir chaves.
• Se uma secreta for comprometida, regenere ou desative a chave imediatamente e reveja as estatísticas de utilização recentes.

Documentação relacionada

• Definições da Empresa — Perfil da empresa, filiais e faturação
• Gestão de Encomendas — Ciclo de vida da encomenda (separado do catálogo de eventos de webhook atual)
• Visão Geral da Plataforma — Arquitetura e aplicações Bizaldo
• Perguntas Frequentes — Perguntas comuns de integração