Para desenvolvedores

Integração com APIs de terceiros

Conecte seu ERP, e-commerce ou sistema interno ao Venda no Chat. Você pode expor endpoints REST para carregamento inicial de dados (GET) e enviar atualizações em tempo real via webhook (push).

Configure credenciais em Integrações → APIs de terceiros no painel administrativo. Cada integração recebe um slug único usado como import_source e na URL do webhook.

Autenticação

Todas as requisições de saída (quando o Venda no Chat consulta suas APIs) e de entrada (webhook) usam o token configurado no painel.

Envie o header:

Texto

Authentication: bearer SEU_TOKEN

O formato é o mesmo da integração Nuvemshop. Também aceitamos Authorization: Bearer … no webhook.

Carregamento de dados

Para importar dados do seu sistema, informe no painel um endereço (URL) para cada tipo: produtos, clientes e vendas. O Venda no Chat consulta cada URL com requisições GET paginadas, usando o token de autenticação configurado na integração.

Cada endpoint deve responder com JSON. O corpo pode ser uma lista direta de registros (legado, página única) ou um objeto com a lista em uma das chaves data, results ou items, acompanhada de metadados de paginação. Campos adicionais nos objetos são ignorados.

Paginação

Durante o sync, o Venda no Chat chama sua URL repetidamente, enviando os parâmetros de query page e page_size=10. Cada resposta deve trazer no máximo 10 registros.

Exemplo de chamadas feitas pelo consumidor:

Texto

GET https://api.exemplo.com/produtos?page=1&page_size=10
GET https://api.exemplo.com/produtos?page=2&page_size=10
GET https://api.exemplo.com/produtos?page=3&page_size=10
… até a última página

Se a URL já tiver query string, os parâmetros de paginação são acrescentados (ou substituídos) automaticamente:

Texto

URL configurada: https://api.exemplo.com/v1/sales?status=closed
Chamada página 2: https://api.exemplo.com/v1/sales?status=closed&page=2&page_size=10

Formato recomendado da resposta paginada:

JSON

{
  "page": 1,
  "page_size": 10,
  "total": 47,
  "total_pages": 5,
  "has_more": true,
  "data": [
    {
      "name": "Produto A",
      "sku": "SKU-001",
      "price": 99.9
    }
  ]
}

Metadados reconhecidos para decidir se há próxima página:

Campo	Tipo	Obrigatório	Descrição
has_more	boolean	Não	Quando presente, true indica que existem páginas seguintes.
total_pages	number	Não	Total de páginas. Comparado com page para saber se deve continuar.
total / count	number	Não	Total de registros. Usado com page e page_size para calcular fim.
next_page / next	number \| string \| URL	Não	Próxima página ou URL. Valor vazio encerra a paginação.
(fallback)	—	Não	Se nenhum metadado existir, o consumidor continua enquanto a página retornar exatamente 10 itens.

A última página normalmente traz menos de 10 itens (ou uma lista vazia), o que encerra o sync daquele recurso.

Formato aceito — lista direta (legado, uma única requisição):

JSON

[
  {
    "name": "Produto A",
    "sku": "SKU-001",
    "price": 99.9
  }
]

Formato aceito — objeto com chave de lista:

JSON

{
  "data": [
    {
      "name": "Produto A",
      "sku": "SKU-001",
      "price": 99.9
    }
  ]
}

Abaixo estão os contratos de cada tipo. Cada subseção descreve o payload aceito para o respectivo endereço configurado no painel.

Produtos

Configure a URL da API de produtos em Integrações → APIs de terceiros. Esse endereço será consultado com paginação de 10 em 10 (veja Paginação). Cada item da lista segue o contrato abaixo.

Campos reconhecidos em cada item:

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do produto exibido no catálogo.
sku	string	Não	Código único usado para identificar e atualizar o produto.
price	number	Não	Preço de venda.
promotional_price	number	Não	Preço promocional. Se maior que zero, marca o produto em promoção.
stock	string \| number	Não	Quantidade em estoque.
brand	string	Não	Marca do produto.
categories	string \| array	Não	Categorias separadas por vírgula ou lista de objetos com name.
description	string	Não	Descrição completa.
link	string (URL)	Não	Link público do produto no seu sistema.
image_url	string (URL)	Não	Imagem principal.
image_urls	array	Não	Lista de URLs de imagens adicionais.
visible_in_store	boolean	Não	Se o produto aparece na loja. Padrão: true.
is_on_sale	boolean	Não	Indica promoção ativa. Padrão: promotional_price > 0.
metadata	object	Não	Metadados livres em JSON (chaves alfanuméricas/underscore, valores string, number, boolean ou null). Em atualizações, as chaves enviadas são mescladas ao metadata existente. As chaves passam a ficar disponíveis como filtros opcionais no relatório de produtos.

Exemplo de item válido:

JSON

{
  "name": "Camiseta Premium",
  "sku": "CAM-PRE-001",
  "price": 129.9,
  "promotional_price": 99.9,
  "stock": "42",
  "brand": "Marca X",
  "categories": "Roupas, Camisetas",
  "description": "Camiseta 100% algodão.",
  "link": "https://loja.exemplo.com/produtos/camiseta-premium",
  "image_url": "https://cdn.exemplo.com/camiseta.jpg",
  "image_urls": [
    "https://cdn.exemplo.com/camiseta.jpg",
    "https://cdn.exemplo.com/camiseta-detalhe.jpg"
  ],
  "visible_in_store": true,
  "is_on_sale": true,
  "metadata": {
    "cor": "preto",
    "tamanho": "M",
    "material": "algodao",
    "garantia_meses": 12
  }
}

O campo metadata é um objeto JSON livre. Em updates (webhook ou sync), as chaves enviadas são mescladas ao metadata já gravado — chaves omitidas são preservadas. No painel, os metadados aparecem na ficha do produto e as chaves existentes no catálogo podem ser incluídas como filtros no relatório de produtos (Loja → Produtos).

Clientes

Configure a URL da API de clientes no painel. Esse endereço será consultado com paginação de 10 em 10. Cada item da lista segue o contrato abaixo.

Campos reconhecidos em cada item:

Campo	Tipo	Obrigatório	Descrição
full_name	string	Sim	Nome completo. Alternativa: first_name + last_name.
first_name	string	Não	Primeiro nome.
last_name	string	Não	Sobrenome.
email	string	Não	E-mail usado como chave principal de identificação.
phone	string	Não	Telefone com DDD.
cpf	string	Não	CPF ou CNPJ (apenas dígitos).
address	string	Não	Logradouro.
number	string	Não	Número.
complement	string	Não	Complemento.
neighborhood	string	Não	Bairro.
city	string	Não	Cidade.
state	string	Não	Estado (UF).
zip_code	string	Não	CEP.
total_spent	number	Não	Total já gasto pelo cliente.
purchases_count	number	Não	Quantidade de compras.
last_purchase	string	Não	Data da última compra (ISO 8601 ou timestamp).
metadata	object	Não	Metadados livres em JSON (chaves alfanuméricas/underscore, valores string, number, boolean ou null). Em atualizações, as chaves enviadas são mescladas ao metadata existente. As chaves passam a ficar disponíveis como filtros opcionais no relatório de clientes.

Exemplo de item válido:

JSON

{
  "full_name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "47999998888",
  "cpf": "12345678901",
  "address": "Rua das Flores",
  "number": "100",
  "complement": "Apto 12",
  "neighborhood": "Centro",
  "city": "Itajaí",
  "state": "SC",
  "zip_code": "88301-000",
  "total_spent": 1549.8,
  "purchases_count": 7,
  "last_purchase": "2026-06-15T14:30:00-03:00",
  "metadata": {
    "segmento": "vip",
    "origem_lead": "instagram",
    "score": 92
  }
}

O campo metadata segue o mesmo padrão dos produtos: objeto JSON livre, merge parcial em updates, exibição na ficha do cliente e filtros opcionais no relatório (Loja → Clientes).

Vendas

Configure a URL da API de vendas no painel. Esse endereço será consultado com paginação de 10 em 10. Cada item da lista segue o contrato abaixo.

Campos reconhecidos em cada item:

Campo	Tipo	Obrigatório	Descrição
order_number	string	Sim	Número ou ID único do pedido.
email	string	Não	E-mail do comprador.
buyer	string	Não	Nome do comprador.
phone	string	Não	Telefone do comprador.
date	string	Não	Data do pedido (ISO 8601).
subtotal	number	Não	Subtotal antes de descontos e frete.
discount	number	Não	Valor de desconto.
shipping	number	Não	Valor do frete.
total	number	Não	Valor total do pedido.
order_status	string	Não	Status do pedido (ex.: open, closed, cancelled).
payment_status	string	Não	Status do pagamento (ex.: paid, pending).
shipping_status	string	Não	Status de envio.
payment_method	string	Não	Forma de pagamento.
shipping_method	string	Não	Forma de envio.
city	string	Não	Cidade de entrega.
state	string	Não	Estado de entrega.
delivery_address	string	Não	Endereço completo de entrega.
sales_channel	string	Não	Canal de venda (site, whatsapp, instagram, etc.). Padrão: site.
line_items	array	Não	Itens do pedido para vincular produtos do catálogo.
metadata	object	Não	Metadados livres em JSON (chaves alfanuméricas/underscore, valores string, number, boolean ou null). Em atualizações, as chaves enviadas são mescladas ao metadata existente. As chaves passam a ficar disponíveis como filtros opcionais no relatório de vendas.

Itens do pedido (line_items):

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do produto na linha do pedido.
sku	string	Não	SKU para vincular ao produto do catálogo.
quantity	number	Não	Quantidade comprada.
price	number	Não	Preço unitário do item.

Exemplo de item válido:

JSON

{
  "order_number": "PED-2026-1042",
  "email": "maria@exemplo.com",
  "buyer": "Maria Silva",
  "phone": "47999998888",
  "date": "2026-06-28T10:15:00-03:00",
  "subtotal": 229.8,
  "discount": 10,
  "shipping": 15,
  "total": 234.8,
  "order_status": "open",
  "payment_status": "paid",
  "shipping_status": "shipped",
  "payment_method": "pix",
  "shipping_method": "express",
  "city": "Itajaí",
  "state": "SC",
  "delivery_address": "Rua das Flores, 100",
  "sales_channel": "site",
  "line_items": [
    {
      "name": "Camiseta Premium",
      "sku": "CAM-PRE-001",
      "quantity": 2,
      "price": 99.9
    }
  ],
  "metadata": {
    "cupom": "BEMVINDO10",
    "utm_source": "google",
    "parcelas": 1
  }
}

O sistema tenta vincular cada item do pedido a um produto existente pelo SKU ou pelo nome.

O campo metadata segue o mesmo padrão de produtos e clientes: merge parcial em updates, exibição na ficha da venda e filtros opcionais no relatório (Loja → Vendas).

Webhook (atualizações em tempo real)

Além do carregamento por GET, seu sistema pode enviar eventos para o Venda no Chat sempre que houver criação, alteração ou exclusão de registros.

URL do webhook

Substitua {workspace_slug} pelo slug do workspace e {integration_slug} pelo slug da integração:

Texto

POST https://vendanochat.com.br/api/integrations/{workspace_slug}/third-party/{integration_slug}

O slug e a URL completa aparecem em Integrações → APIs de terceiros no painel.

Headers

Texto

Content-Type: application/json
Authentication: bearer SEU_TOKEN

Corpo da requisição

Todas as requisições seguem o formato:

JSON

{
  "event": "product.upsert",
  "data": {}
}

Eventos suportados

Campo	Tipo	Obrigatório	Descrição
product.upsert	event	Sim	Cria ou atualiza um produto (data = objeto).
product.created / product.updated	event	Sim	Alias de product.upsert.
product.delete	event	Sim	Remove produto por sku ou name.
customer.upsert	event	Sim	Cria ou atualiza um cliente (data = objeto).
customer.created / customer.updated	event	Sim	Alias de customer.upsert.
customer.delete	event	Sim	Remove cliente por email ou full_name.
sale.upsert	event	Sim	Cria ou atualiza uma venda (data = objeto).
sale.created / sale.updated	event	Sim	Alias de sale.upsert.
sale.delete / order.delete	event	Sim	Remove venda por order_number.
products.sync	event	Sim	Lote de produtos (data = array).
customers.sync	event	Sim	Lote de clientes (data = array).
sales.sync	event	Sim	Lote de vendas (data = array).

Exemplos

Criar ou atualizar produto:

JSON

{
  "event": "product.upsert",
  "data": {
    "name": "Camiseta Premium",
    "sku": "CAM-PRE-001",
    "price": 129.9,
    "stock": "40",
    "metadata": {
      "cor": "preto",
      "tamanho": "M"
    }
  }
}

Atualizar cliente:

JSON

{
  "event": "customer.upsert",
  "data": {
    "full_name": "Maria Silva",
    "email": "maria@exemplo.com",
    "phone": "47999998888",
    "city": "Itajaí",
    "state": "SC",
    "metadata": {
      "segmento": "vip",
      "origem_lead": "instagram"
    }
  }
}

Nova venda:

JSON

{
  "event": "sale.upsert",
  "data": {
    "order_number": "PED-2026-1043",
    "email": "maria@exemplo.com",
    "buyer": "Maria Silva",
    "total": 199.8,
    "payment_status": "paid",
    "line_items": [
      {
        "sku": "CAM-PRE-001",
        "name": "Camiseta Premium",
        "quantity": 2,
        "price": 99.9
      }
    ],
    "metadata": {
      "cupom": "BEMVINDO10",
      "utm_source": "google"
    }
  }
}

Lote de produtos:

JSON

{
  "event": "products.sync",
  "data": [
    {
      "name": "Produto A",
      "sku": "A-001",
      "price": 10
    },
    {
      "name": "Produto B",
      "sku": "B-002",
      "price": 20
    }
  ]
}

Excluir venda:

JSON

{
  "event": "sale.delete",
  "data": {
    "order_number": "PED-2026-0999"
  }
}

Respostas

Em caso de sucesso:

JSON

{
  "ok": true,
  "action": "created",
  "id": 123
}

Em caso de erro de validação:

JSON

{
  "ok": false,
  "message": "Produto inválido: informe ao menos o campo name."
}

Códigos HTTP: 200 sucesso, 400 payload inválido, 403 não autorizado ou integração desativada, 404 workspace não encontrado.

Precisa de ajuda?

Consulte a central de ajuda ou fale com o suporte em atendimento.

Integração com APIs de terceiros

Autenticação

Carregamento de dados

Paginação

Produtos

Clientes

Vendas

Webhook (atualizações em tempo real)

URL do webhook

Headers

Corpo da requisição

Eventos suportados

Exemplos

Respostas

Precisa de ajuda?

Produto

Empresa

Suporte

Legal