Conecte seu ERP à Peçafy por webhook

Como funciona

A conversa é de mão dupla e sempre por evento. Nenhum dos dois lados fica consultando o outro.

O ponto que costuma gerar dúvida: a resposta pode ser depois

Quando a gente pergunta o preço de uma peça, tem um comprador olhando a tela. Por isso o prazo é curto — 3 segundos por padrão. Se o seu ERP não responde nesse tempo, você não precisa segurar a conexão: devolva 202 e mande o resultado depois, no callback. Os dois caminhos são igualmente válidos e usam o mesmo evento.

Seu acesso e sua configuração

Você mesmo configura, no portal, em Integração.

Você tem dois ambientes

Ao ter o cadastro aprovado, você recebe dois pares de credenciais, com o mesmo identificador de fornecedor nos dois. Comece pelo de homologação: é lá que você testa à vontade, sem tocar em pedido real.

O que você configura no portal

Assinatura

Vale nos dois sentidos, com a mesma chave. A gente assina o que manda; você assina o que manda.

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Pecafy-Webhooks/1.0
X-Pecafy-Signature:        t=1756304591,v1=<hex>
X-Pecafy-Event-Id:         evt_9f2c7a1b4d6e8035
X-Pecafy-Event-Type:       product.quote.requested
X-Pecafy-Delivery-Attempt: 1

X-Pecafy-Delivery-Attempt começa em 1. Vindo 2 ou mais, é uma retentativa de um evento que já pode ter chegado — é o sinal para conferir a sua deduplicação por id antes de processar de novo.

v1 é HMAC-SHA256(chave, "<t>.<corpo_cru>") em hexadecimal. Corpo cru quer dizer os bytes exatos que chegaram — antes de qualquer parse ou reserialização. Se o seu framework já transformou o JSON em objeto, você perdeu o que precisa assinar; guarde o buffer original.

• Confira a assinatura antes de olhar o conteúdo.
• Recuse t fora de uma janela de 5 minutos — é o que impede replay.
• Compare em tempo constante (hash_equals, crypto.timingSafeEqual), nunca com ==.
• Aplicamos exatamente as mesmas regras no que vem de você.

Exemplo — Node

const [t, v1] = header.split(',').map(p => p.split('=')[1]);
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return recusar();

const esperado = crypto.createHmac('sha256', SEGREDO)
  .update(`${t}.${corpoCru}`).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1))) return recusar();

Exemplo — PHP

[$t, $v1] = array_map(fn($p) => explode('=', $p)[1], explode(',', $header));
if (abs(time() - (int)$t) > 300) return recusar();

$esperado = hash_hmac('sha256', "$t." . $corpoCru, $segredo);
if (!hash_equals($esperado, $v1)) return recusar();

Envelope

Mesma estrutura nos dois sentidos. O que muda é o type e o data.

{
  "id":            "evt_9f2c7a1b4d6e8035",
  "type":          "product.quote.requested",
  "version":       1,
  "occurred_at":   "2026-08-28T14:03:11.482Z",
  "supplier_id":   "sup_exemplo",
  "correlation_id":"cor_4b8e12aa",
  "reply": {
    "mode":         "sync_or_async",
    "callback_url": "https://app.pecafy.com.br/api/webhooks/inbound/sup_exemplo",
    "timeout_ms":   3000,
    "expires_at":   "2026-08-28T14:08:11.482Z"
  },
  "data": { }
}

Como responder

Quatro respostas possíveis, e cada uma significa uma coisa diferente para a fila.

Quanto tempo a Peçafy espera

Estourar o prazo não é erro: só significa que a resposta vai pelo callback em vez de vir no corpo. Veja o aviso acima — resposta atrasada continua valendo.

Corpo do callback assíncrono

É um evento seu como qualquer outro — assinado, com id novo — só que carrega in_reply_to apontando para o evento que estamos esperando.

{
  "id":          "evt_<um id novo, seu>",
  "type":        "product.quote.requested.reply",
  "version":     1,
  "occurred_at": "2026-08-28T14:03:16.000Z",
  "supplier_id": "sup_exemplo",
  "in_reply_to": "evt_9f2c7a1b4d6e8035",
  "status":      "ok",
  "data": { "preco_unitario": 176.30, "estoque_disponivel": 12 }
}

Passo a passo, do zero ao pedido entregue

A ordem real das chamadas, quem inicia cada uma e o que precisa estar pronto antes. Se você está implementando do zero, siga daqui.

1. Fase 0 · Ligar a conexão uma vez

   Você salva a URL e gera a chave no portal, em Integração. Para conferir que os dois lados se entendem, o botão "Testar conexão" (no mesmo lugar) dispara:

   Direção	Evento	Você faz
   → Peçafy	ping	Valida a assinatura e responde {"pong": true}

   Enquanto o ping não voltar, nada mais adianta: o problema é assinatura ou URL.

2. Fase 1 · Carga inicial: dizer quais peças você tem obrigatória

   Sem carga inicial a integração não faz nada. A Peçafy só pergunta preço de peça que sabe ser sua — e só sabe pelo que você mandou: o seu código interno (sku_id_origem), o OEM/GTIN e a descrição. Há dois caminhos, e você pode usar os dois (detalhes em Carga inicial e busca):

   Caminho	O que você manda	Quando escolher
   Catálogo catalog.items.upserted	Item completo: descrição, preço, estoque, imagem.	Quando quiser aparecer na comparação já com preço, sem depender de cotação.
   De-para catalog.refs.upserted	Só "meu código = este OEM", mais marca e aplicação se tiver.	Muito mais barato. Passa a ser cotado por peças que não publicou — o OEM vem do catálogo de qualquer fornecedor.

   O caminho do catálogo, em detalhe:

   Direção	Evento	O que acontece
   → Peçafy	catalog.sync.requested	Pedimos o catálogo. Responda 202.
   ← você	catalog.items.upserted	Você empurra os itens, em lotes de até 5000. Pode mandar vários eventos.
   ← você	price.changed stock.changed	Daí em diante, só o que mudou. É o caminho barato — use bastante.
   ← você	catalog.items.removed	Item que saiu de linha.

   Você também pode empurrar catalog.items.upserted sem a gente pedir — o catalog.sync.requested é só a carga inicial.

3. Fase 2 · O comprador busca aqui sai evento

   Alguém procura "pastilha de freio". Perguntamos o preço só das peças dessa busca — nunca do catálogo inteiro — e não esperamos a sua resposta: a tela é respondida na hora com a última cotação guardada, e o preço se atualiza quando você responde.

   Direção	Evento	Quando você recebe
   → Peçafy	products.quote.requested	Você tem a peça (por catálogo ou de-para) e a última cotação venceu. Uma busca por dois produtos é um evento com dois itens.
   → Peçafy	items.search.requested	Você não tem a peça por nenhum caminho e ativou "aceitar busca por texto". Mandamos o termo e o que sabemos da peça.

   Você controla a frequência. Enquanto a última cotação estiver dentro da validade que você define no portal, reaproveitamos a resposta em vez de bater no seu servidor. A exceção é o estoque na faixa baixa que você configurar, onde perguntamos sempre — é onde um número velho vira venda de item que não existe.

4. Fase 3 · Preço ao vivo de um item opcional

   Fora da busca, o comprador pode pedir o preço atualizado de uma opção específica — a sua. Aí sai um evento só, e só para você.

   Direção	Evento	Prazo
   → Peçafy	product.quote.requested	3s. Não deu? 202 e responda no callback.

   É a versão de um item só do evento da fase 2 — mesmo formato de resposta, sem o items[]. O preço da tabela daquele cliente entra nos dois.

5. Fase 4 · O comprador vira seu cliente

   Acontece quando ele escolhe você e ainda não tem cadastro no seu ERP.

   Direção	Evento	O que acontece
   → Peçafy	customer.lookup.requested	Esse CNPJ já é seu cliente? Se registered: false, o comprador vê o botão "Cadastrar".
   → Peçafy	customer.register.requested	Ele clicou em cadastrar. Crie o cliente e devolva o cli_cod.
   → Peçafy	customer.credit.requested	Limite e condição de pagamento, para o checkout.
   ← você	customer.credit.changed	Depois, sempre que o limite ou o bloqueio mudar no seu ERP.

   Sem cadastro confirmado, a Peçafy não deixa fechar pedido com você.

6. Fase 5 · O pedido

   Direção	Evento	O que acontece
   → Peçafy	order.created	Lance no ERP e devolva external_order_ref. Guarde o order_id.
   ← você	order.status.changed	Faturado (com a NF), enviado (com o rastreio), entregue. Um evento por mudança — o comprador é notificado a cada um.
   → Peçafy	order.cancel.requested	Se o comprador cancelar.

O mesmo caminho, em uma imagem

Mapa de chamadas

Todo o protocolo em uma tela. Você só precisa expor UM endpoint — os eventos chegam todos nele, e o type diz qual é.

Ordem sugerida de implementação

Cada etapa é útil sozinha — dá para ir ao ar antes de terminar tudo.

• 1. Endpoint + verificação de assinatura + ping. Sem isso nada funciona.
• 2. catalog.items.upserted ou catalog.refs.upserted. O catálogo já mostra a sua peça com preço; o de-para é bem mais barato e também te coloca no jogo. Fazer os dois é o ideal.
• 3. products.quote.requested. É o que a busca dispara — sem ele, a sua peça aparece com o preço da última carga e envelhece.
• 4. customer.lookup + register + credit. Aqui já dá para comprar de você.
• 5. order.created + order.status.changed. Fluxo fechado ponta a ponta.
• 6. price.changed / stock.changed incrementais, em vez de republicar tudo.
• 7. product.quote.requested (um item) e, se o seu sistema souber buscar por descrição, items.search.requested.

Carga inicial e busca: como o comprador acha a sua peça

O que você manda na carga inicial é exatamente o que a busca usa para achar você. Aqui está a regra, sem mistério — para você mandar o dado certo e ser encontrado.

O que vai na carga inicial

Mande a carga em lotes de até 5000 itens em catalog.items.upserted (ou só o de-para em catalog.refs.upserted), leia result.rejeitados de cada lote e corrija o que caiu. Depois disso, só o que mudar: price.changed, stock.changed, catalog.items.removed.

Como a busca casa o que o comprador digitou

A busca é exata por código e lexical por texto. Não existe busca "semântica" nem por similaridade: em autopeça, o parecido vende a peça errada. O que o comprador digita passa por estas regras, todas ao mesmo tempo, sobre o catálogo de todos os fornecedores:

Quando você é perguntado

A busca responde na hora com o que está no catálogo. Em paralelo, decide para quem perguntar preço — e a decisão é só esta:

Eventos que a Peçafy manda

Chegam por POST na sua URL. Todos assinados.

{ "pong": true }

{
  "delta": false,
  "since": null
}

202 Accepted

{
  "item": {
    "catalog_item_id": 52,
    "sku_id_origem": "ABC-123",
    "gtin": null,
    "oem": "FD88",
    "descricao": "lona freio"
  },
  "comprador": {
    "cnpj": "19131243000197",
    "external_ref": "19131243000197",
    "cli_cod": "1001",
    "tabela_preco": 1
  }
}

{
  "preco_unitario": 176.30,
  "estoque_disponivel": 12,
  "estoque_unidade": "un",
  "promocao_ativa": false,
  "promocao_valor": null,
  "prazo_entrega": {
    "valor": 1,
    "unidade": "dia(s)"
  }
}

{
  "items": [
    { "catalog_item_id": 52, "sku_id_origem": "ABC-123",
      "gtin": null, "oem": "FD88", "descricao": "pastilha de freio" },
    { "catalog_item_id": 77, "sku_id_origem": "VOL-9",
      "gtin": null, "oem": "VL21", "descricao": "volante celta" }
  ],
  "comprador": {
    "cnpj": "19131243000197",
    "external_ref": "19131243000197",
    "cli_cod": "1001",
    "tabela_preco": 1
  }
}

{
  "items": [
    { "sku_id_origem": "ABC-123", "preco_unitario": 176.30,
      "estoque_disponivel": 12, "promocao_ativa": false },
    { "sku_id_origem": "VOL-9", "preco_unitario": 402.00,
      "estoque_disponivel": 0, "promocao_ativa": false }
  ]
}

{
  "termo":      "pastilha de freio celta",
  "oems":       ["FD88"],
  "gtins":      [],
  "marcas":     ["Fras-le"],
  "aplicacoes": ["Celta 2006-2015"],
  "refs":       ["PF-1234"],
  "comprador":  { "cnpj": "19131243000197", "cli_cod": "1001" }
}

{
  "items": [
    { "sku_id_origem": "ABC-123",
      "descricao": "Pastilha de freio dianteira",
      "oem": "FD88",
      "preco_unitario": 176.30,
      "estoque_disponivel": 12 }
  ]
}

{
  "cnpj": "19131243000197",
  "cli_cod": null
}

{
  "registered": true,
  "external_ref": "19131243000197",
  "cli_cod": "1001",
  "tabela_preco": 1,
  "credit_limit": 250000
}

{
  "tenant_id": "tn_abc",
  "cnpj": "19131243000197",
  "razao_social": "Oficina Exemplo Ltda",
  "inscricao_estadual": "ISENTO",
  "email": "compras@oficina.com.br",
  "telefone": "5585999990000",
  "endereco": {
    "cep": "60000000",
    "logradouro": "Rua Exemplo",
    "numero": "100",
    "bairro": "Centro",
    "cidade": "Fortaleza",
    "estado": "CE"
  }
}

{
  "external_ref": "19131243000197",
  "cli_cod": "1001",
  "tabela_preco": 1
}

{
  "external_ref": "19131243000197",
  "cli_cod": "1001"
}

{
  "credit_limit": 250000,
  "credit_used": 12000,
  "credit_available": 238000,
  "blocked": false,
  "payment_term": "Boleto 28 dias",
  "due_days": 28
}

{
  "order_id": "ord_a1b2c3",
  "cliente": {
    "external_ref": "19131243000197",
    "cli_cod": "1001",
    "cnpj": "19131243000197",
    "razao_social": "Oficina Exemplo Ltda",
    "email": "compras@oficina.com.br",
    "telefone": "5585999990000"
  },
  "itens": [
    {
      "sku_id_origem": "ABC-123",
      "descricao": "lona freio Fras-le",
      "quantidade": 2,
      "preco_unitario": 186.17
    }
  ],
  "pagamento": {
    "condicao": "Boleto 28 dias",
    "prazo_dias": 28
  },
  "entrega": {
    "tipo": "entrega",
    "endereco": { }
  },
  "cobranca": { "endereco": { } }
}

{
  "external_order_ref": "PED-5001",
  "status": "confirmado"
}

{
  "order_id": "ord_a1b2c3",
  "external_order_ref": "PED-5001",
  "motivo": "…"
}

{ "cancelled": true }

Eventos que você manda

POST na sua URL de callback, assinado com a mesma chave. Não precisa de pergunta prévia — mande quando o dado mudar no seu ERP.

{
  "items": [
    { "sku_id_origem": "ABC-123",
      "oem": "FD88",
      "descricao": "Pastilha de freio dianteira",
      "marca": "Fras-le",
      "aplicacao": "Celta 2006-2015",
      "ref_fornecedor": "PF-1234" },

    { "sku_id_origem": "XYZ-9", "gtin": "7891234567895" }
  ]
}

{
  "items": [
    {
      "sku_id_origem": "ABC-123",
      "gtin": "7891234567890",
      "oem": "FD88",
      "descricao": "Lona de freio dianteira",
      "marca": "Fras-le",
      "modelo": null,
      "aplicacao": "VW 8-160",
      "categoria_nome": "Freios",
      "categoria_path": ["Freios", "Lonas"],
      "imagens": ["https://cdn.exemplo.com/abc123.jpg"],
      "preco_unitario": 186.17,
      "preco_promocao_ativa": false,
      "preco_promocao_valor": null,
      "estoque_disponivel": 12,
      "estoque_unidade": "un",
      "peso": 2.4, "altura": 10, "largura": 20, "comprimento": 30,
      "ativo": true,
      "atualizado_em": "2026-08-28T14:00:00Z"
    }
  ]
}

{
  "status": "ok",
  "event_id": "evt_…",
  "result": {
    "processed": 3, "upserted": 1, "skipped": 1, "quarantined": 1, "errors": 0,
    "rejeitados": [
      { "sku_id_origem": "XYZ-9", "erros": ["Nenhuma chave de matching: gtin e oem são ambos nulos."] }
    ]
  }
}

{ "items": [ { "sku_id_origem": "ABC-123" } ] }

{
  "items": [
    {
      "sku_id_origem": "ABC-123",
      "preco_unitario": 179.90,
      "preco_promocao_ativa": false
    }
  ]
}

{
  "items": [
    {
      "sku_id_origem": "ABC-123",
      "estoque_disponivel": 3
    }
  ]
}

{
  "order_id": "ord_a1b2c3",
  "external_order_ref": "PED-5001",
  "status": "faturado",
  "nota_fiscal": {
    "numero": "90001",
    "chave": "3526…",
    "url": "https://…"
  },
  "rastreio": {
    "codigo": "BR123456789BR",
    "url": "https://…"
  }
}

{
  "cnpj": "19131243000197",
  "external_ref": "19131243000197",
  "credit_limit": 300000,
  "blocked": false,
  "payment_term": "Boleto 30 dias",
  "due_days": 30
}

O que cada evento faz do lado de cá

Para você saber o efeito real de cada mensagem antes de mandá-la.

Falhas e retry

O que acontece quando a entrega não completa.

Backoff

Falha que dá para retentar — 5xx, timeout, conexão recusada — volta para a fila com espera crescente:

Depois da sétima, o evento vai para a dead-letter e só sai de lá por reenvio manual no backoffice. Há variação aleatória de ±20% em cada espera, para várias entregas não baterem no seu servidor no mesmo instante.

Circuit breaker

Cinco falhas seguidas e o seu fornecedor é marcado como offline. A gente para de mandar evento não-crítico até uma entrega dar certo — a primeira entrega boa fecha o circuito e volta tudo ao normal. Recusa de negócio ({"status":"error"}) não conta como falha.

Idempotência

Todo evento carrega um id estável. Reenvio por timeout de rede é comum: se você já processou aquele id, responda 200 e não faça de novo. Do nosso lado vale o mesmo — mandar o mesmo id duas vezes devolve {"status":"duplicate"} sem reprocessar.

Log de entregas

Cada tentativa fica registrada com a URL, o código HTTP, a duração e o corpo que você devolveu. Quem opera a Peçafy consegue ver exatamente o que saiu e o que voltou — se algo não está funcionando, essa é a primeira coisa a pedir.

O que a Peçafy responde para você

Rede e limites

O que a sua equipe de infraestrutura precisa saber antes de abrir o acesso.

Antes de ligar em produção

A lista que evita as falhas que a gente mais vê.

• Verifico a assinatura sobre o corpo cru, com comparação em tempo constante.
• Recuso t com mais de 5 minutos.
• Dedupo por event.id — o mesmo id chega duas vezes e não pode virar dois pedidos.
• Respondo 202 quando vou demorar, em vez de segurar a conexão.
• Uso {"status":"error"} para "não posso", e 5xx só quando estou quebrado.
• Todo POST meu para a Peçafy vai assinado.
• Guardo o order_id do order.created para mandar o status depois.
• Fiz a carga inicial completa (sku_id_origem + oem/gtin + descricao) e li result.rejeitados.
• No callback, o id é meu; o da Peçafy vai só em in_reply_to.
• Números vão como número; gtin ou oem sempre presente.
• Minha URL é https://, com certificado válido, e não redireciona.
• Trato X-Pecafy-Delivery-Attempt maior que 1 como retentativa.
• Liberei o IP 185.197.195.29 no firewall, se houver allowlist.
• Distingo estoque_disponivel: null de 0.