Documentação da API

Última atualização: 11 de outubro de 2026

A API pública permite integrar a sua loja a sistemas e automações. Ela está disponível no plano Business. Os webhooks avisam o seu sistema quando algo acontece na loja. Dúvidas: contato@tinit.com.br.

Autenticação

Endereço base: https://{sua-loja}/api/v1/rest, no endereço da própria loja (subdomínio da VendaFácil ou domínio próprio).
Chave: crie em Admin da loja › API e webhooks. O token completo aparece uma única vez, na criação; guarde-o em local seguro.
Cabeçalho: Authorization: Bearer vf_live_…. A chave vale só para a loja em que foi criada; em outra loja, a resposta é 401.
Escopos: cada chave recebe só os escopos de que precisa.
Limite: 120 requisições por minuto nas leituras (30/min para criar e 60/min para editar produtos).
Formato: JSON no formato { "data": …, "pagination": { "total", "limit", "offset" } }. Valores em centavos (…Cents). Mudanças incompatíveis vão para /api/v2.

Rotas

Método e rota	Escopo
`GET /products?status&q&limit&offset`	`products.read`
`GET /products/:id`	`products.read`
`POST /products`	`products.write`
`PATCH /products/:id`	`products.write`
`GET /orders?status&from&to&limit&offset`	`orders.read`
`GET /orders/:id`	`orders.read`
`GET /customers?q&limit&offset`	`customers.read`
`GET /customers/:id`	`customers.read`

Exemplo:

curl -H "Authorization: Bearer vf_live_..." \
  "https://minhaloja.vendafacil.app/api/v1/rest/orders?status=PAID&from=2026-09-01"

Webhooks

Cadastre um endereço HTTPS em Admin da loja › API e webhooks e escolha os eventos: order.created, order.paid, order.canceled, order.refunded, customer.created e product.created.

Entrega: POST com corpo JSON e os cabeçalhos x-vendafacil-event, x-vendafacil-delivery (id único da entrega), x-vendafacil-timestamp (segundos Unix) e x-vendafacil-signature.
Assinatura: sha256= seguido do HMAC-SHA256, em hexadecimal, de {timestamp}.{corpo} com o segredo do endpoint. Calcule sobre o corpo bruto, compare em tempo constante e recuse timestamps antigos.
Resposta: devolva um status 2xx em até 5 segundos. Fora disso, a entrega é repetida com intervalo crescente (30 s, 1 min, 2 min…), até 6 tentativas. Use x-vendafacil-delivery para ignorar repetições.
Histórico: o admin mostra as últimas entregas e o status de cada uma.

Exemplo de verificação (Node.js):

import { createHmac, timingSafeEqual } from 'node:crypto'

function assinaturaValida(rawBody, headers, secret) {
  const ts = headers['x-vendafacil-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const esperado = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex')
  const recebido = String(headers['x-vendafacil-signature'] ?? '')
  return recebido.length === esperado.length && timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado))
}