Visão geral

O BridgesAgents reúne produtos, preços e estoque de lojas de qualquer segmento do varejo (supermercado, eletrônicos, farmácia, moda...) num formato pronto para agentes de IA de compra.

Há três formas de consultar o catálogo, todas com a mesma chave de agente:

• MCP, para agentes de IA (Claude, ChatGPT, agentes próprios): o agente descobre e chama as tools sozinho.
• API REST, para sistemas e integrações tradicionais.
• UCP (Universal Commerce Protocol), para agentes que já falam esse padrão.

Comece por aqui: crie uma conta de desenvolvedor, gere a chave de agente em Chaves de agente no painel e envie em toda consulta no header Authorization: Bearer abd_… (detalhes em Autenticação).

Conceitos

Detalhes que o agente deve levar em conta:

• effectivePrice é o preço a pagar: o promocional quando existe, senão o normal.
• updatedAt diz quando preço e estoque foram atualizados. stale: true marca oferta sem atualização há mais de 7 dias (o preço pode ter mudado); com mais de 30 dias ela não aparece para agentes.
• soldByWeight indica venda por peso (ex.: hortifruti): o preço é por kg e o valor final só é conhecido na separação.
• Unidades (unit): UN, KG, G, L, ML.
• requiresPrescription: medicamento que exige receita. O agente não deve concluir a compra; oriente o consumidor a apresentar a receita na farmácia.
• adult: true: produto para maiores de 18 (bebida alcoólica, tabaco). A BridgesAgents só marca; quem confirma a idade é o agente.
• inStoreOnly: true: vendido só no local (combustível). Não entra em carrinho e não tem retirada nem entrega: mostre o preço, a distância e mapsUrl (rota até a loja). Para acompanhar o preço da gasolina, busque com radiusKm.
• storeVerified: a empresa da loja tem CNPJ ativo na Receita Federal. storeRating e storeRatingCount: nota média (1 a 5) e quantas avaliações de quem comprou pelo BridgesAgents.
• kind: GOOD (produto físico), FUEL (combustível), SERVICE (serviço), BOOKABLE (viagem, reserva) ou DIGITAL (curso, gift card). Só GOOD vai para carrinho; os outros se compram pelo buyUrl da loja.
• currency é a moeda dos preços (ISO 4217, ex.: BRL). priceType diz como ler o preço: FIXED (fechado), FROM (a partir de), PER_NIGHT (por noite), PER_PERSON (por pessoa).
• fulfillment diz como chega: DELIVERY, PICKUP, IN_STORE (no local), AT_CUSTOMER (a domicílio), BOOKING (reserva) ou DIGITAL. Serviço e reserva não têm estoque (stock nulo); digital pode ser ilimitado. Reserva e digital valem de qualquer lugar.
• No produto: taxonomyId (categoria da Google Product Taxonomy), mpn (código do fabricante) e attributes (dados do tipo: color, size, duration_minutes, max_guests...).

Localização do consumidor

Busca e ofertas aceitam a localização do consumidor. Com ela, só aparecem lojas que entregam ali ou que ficam perto para retirada (até 30 km), e cada oferta diz como a loja atende.

• Prefira latitude e longitude: são precisas. Só com o postalCode (CEP), a coordenada vem de um serviço de CEP e muitas vezes é apenas o centro da cidade; nesse caso a distância vem com distanceApproximate: true.
• A entrega vale se o consumidor estiver no raio da loja ou numa das faixas de CEP que ela atende. Faixas de CEP funcionam mesmo sem coordenada, então mande o CEP sempre que tiver.

Conectar via MCP

O servidor usa o transporte Streamable HTTP em https://api.sandbox.bridgesagents.com/mcp.

Claude Code

claude mcp add --transport http bridgesagents https://api.sandbox.bridgesagents.com/mcp \
  --header "Authorization: Bearer abd_SUA_CHAVE"

Clientes que só aceitam servidores locais (stdio)

Use o mcp-remote como ponte. Exemplo de configuração (Claude Desktop, Cursor e similares):

{
  "mcpServers": {
    "bridgesagents": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.sandbox.bridgesagents.com/mcp", "--header", "Authorization:Bearer ${BRIDGESAGENTS_KEY}"],
      "env": { "BRIDGESAGENTS_KEY": "abd_SUA_CHAVE" }
    }
  }
}

Testar sem agente

O MCP Inspector lista e executa as tools pelo navegador. Escolha Streamable HTTP, informe a URL acima e adicione o header Authorization com Bearer abd_….

Clientes com suporte a OAuth (como o Claude e o MCP Inspector) não precisam de header: no primeiro acesso recebem 401 com WWW-Authenticate, descobrem o servidor de autorização, se registram sozinhos e abrem a página em que o consumidor entra (ou cria a conta) e permite o acesso. Veja Autenticação.

npx @modelcontextprotocol/inspector

Tools MCP

[
  {
    "id": "00000000-0000-0000-0000-0000000000b8",
    "gtin": "7890000000103",
    "name": "Amoxicilina 500mg 21 cápsulas",
    "brand": "Marca F",
    "category": "Medicamentos",
    "unit": "UN",
    "requiresPrescription": true,
    "imageUrl": "https://img.example.com/amoxicilina.png"
  }
]

[
  {
    "storeId": "00000000-0000-0000-0000-0000000000a4",
    "storeName": "Farmácia Exemplo Savassi",
    "city": "Belo Horizonte",
    "region": "MG",
    "price": 32.90,
    "promoPrice": null,
    "effectivePrice": 32.90,
    "stock": 20.000,
    "inStock": true,
    "soldByWeight": false,
    "requiresPrescription": true,
    "updatedAt": "2026-10-25T21:51:47Z",
    "stale": false,
    "distanceKm": 0.2,
    "distanceApproximate": false,
    "pickup": true,
    "delivery": { "fee": 0.00, "etaMinutes": 40, "minOrder": null, "coveredBy": "radius" },
    "openNow": true,
    "buyUrl": "https://api.sandbox.bridgesagents.com/r/00000000-0000-0000-0000-0000000000cb"
  }
]

{
  "id": "f4e2add5-0103-4fc2-aebb-77dbabff2241",
  "status": "OPEN",
  "store": { "id": "00000000-0000-0000-0000-0000000000a4", "name": "Farmácia Exemplo Savassi", … },
  "fulfillment": "PICKUP",
  "items": [
    { "productId": "00000000-0000-0000-0000-0000000000b6", "name": "Protetor Solar FPS 50 200ml",
      "unit": "UN", "quantity": 2, "unitPrice": 52.90, "lineTotal": 105.80 }
  ],
  "subtotal": 105.80,
  "deliveryFee": null,
  "total": 105.80,
  "expiresAt": "2026-10-27T02:39:54Z",
  "confirmUrl": "https://bridgesagents.com/compras/c/abc_…",
  "order": null
}

Produto com receita não entra em carrinho. Se algum item tiver problema (sem estoque, quantidade, loja que não vende), nada é criado e a resposta lista cada problema. Na confirmação, preço e estoque são conferidos de novo: se o preço mudou, o consumidor vê o valor novo antes de confirmar.

Próximas tools: quote_delivery e pagamento pelo agente.

UCP e ACP

O mesmo catálogo também sai nos formatos de comércio para agentes do Google e da OpenAI. Cada produto (o mesmo em qualquer loja, pelo GTIN) traz as ofertas de todas as lojas. A compra continua na loja: ainda não há checkout pelo agente.

UCP (Universal Commerce Protocol)

O perfil em https://api.sandbox.bridgesagents.com/.well-known/ucp anuncia as capacidades dev.ucp.shopping.catalog.search e dev.ucp.shopping.catalog.lookup (versão 2026-08-25). Cada oferta de loja é uma variante: a loja vem em seller, o preço em centavos ({"amount": 2490, "currency": "BRL"}), url é o link de compra. Distância, retirada, entrega e horário ficam em metadata. Informe context.postal_code para ver só as lojas que atendem o consumidor.

curl -X POST "https://api.sandbox.bridgesagents.com/ucp/v1/catalog/search" -H "Authorization: Bearer abd_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"query": "pilha aa", "context": {"postal_code": "30140-010"}, "pagination": {"limit": 5}}'

ACP (Agentic Commerce Protocol, OpenAI)

Feed de produtos do ChatGPT: um JSON por linha, uma linha por oferta de loja, com price no formato 19.90 BRL e is_eligible_checkout: false. Ofertas sem marca, sem imagem ou sem canal de compra ficam de fora (o formato exige esses campos), assim como produtos com receita. O header X-BridgesAgents-Skipped diz quantas ficaram de fora.

O feed é de uso interno: o próprio BridgesAgents o gera em /feeds/acp/products.jsonl.gz e envia à OpenAI. Agentes não precisam baixá-lo; para consultar o catálogo, use MCP, REST ou UCP com a chave de agente.

Importar catálogo

O lojista envia a planilha que já usa, em Excel (.xlsx) ou CSV, pelo painel ou pela API. Importar de novo atualiza preço e estoque, sem duplicar produtos.

• A primeira linha é o cabeçalho. A ordem das colunas não importa, e colunas desconhecidas são ignoradas.
• Os nomes são comparados sem acento, maiúsculas ou pontuação: Preço de Venda e preco_venda são a mesma coluna.
• Números aceitam o formato brasileiro (1.234,56, R$ 27,90) e também 27.90.
• CSV pode usar ponto e vírgula, vírgula ou tab, em UTF-8 ou no formato padrão do Excel em português.
• Linhas com problema não impedem as outras: o resultado lista cada uma com o número da linha e o motivo.
• Combustível (gasolina, etanol, diesel, GNV) é marcado sozinho como vendido só no local: sem carrinho, aparece pela distância até o posto. Armas, munição, explosivos, cigarro eletrônico e drogas são recusados.
• Limites: 5 MB e 10.000 linhas por arquivo.

Baixar planilha modelo

Cadastro de lojas

O lojista é responsável pelo cadastro de cada loja: endereço, localização, como atende e horário. É com isso que os agentes sabem se a loja entrega para o consumidor, se dá para retirar por perto e se está aberta. O painel mostra o que falta em cada loja.

• Coordenada: informe a exata (no Google Maps, botão direito sobre a loja e clique nos números). Em branco, usamos uma aproximada pelo CEP, que pode ser só o centro da cidade.
• Entrega: por raio (km a partir da loja), por faixas de CEP ou os dois. Taxa, prazo em minutos e pedido mínimo são por loja.
• Canal de compra: WhatsApp de pedidos e/ou site. É para onde o link “comprar nesta loja” (buyUrl) leva o cliente. No site, {produto} na URL é trocado pelo nome do produto.
• Horário: por dia da semana, no fuso da UF da loja. Dois turnos com vírgula, 24h ou fechado. Fechar depois da meia-noite (22:00-02:00) também vale.

Planilha de lojas (redes)

Em Lojas → Importar planilha, a rede cadastra e atualiza todas as lojas de uma vez. O código identifica cada loja: se existir, atualiza; se não, cria.

* Cidade e UF são completadas pelo CEP quando ficam em branco. Baixar planilha modelo de lojas

Conectar o Bling

Quem usa o Bling não precisa de planilha nem de programação: em Integrações, no painel, o administrador conecta a conta Bling, autoriza o BridgesAgents (só leitura de produtos, estoque e depósitos) e escolhe qual depósito abastece cada loja.

• Preço, foto, código de barras, marca e categoria vêm do cadastro do produto no Bling.
• O estoque de cada loja é a soma do saldo disponível dos depósitos ligados a ela.
• Mudanças de preço e estoque chegam em segundos; uma sincronização completa roda todo dia de madrugada e aparece em Importações com a fonte Bling.
• Produto inativado ou excluído no Bling fica com estoque zero.
• Produtos com variação (cor, tamanho) ainda não entram: por enquanto, envie esses pela planilha.

Conectar a Nuvemshop

Quem vende numa loja virtual Nuvemshop também não precisa de planilha: em Integrações, no painel, o administrador conecta a loja, autoriza o BridgesAgents (só leitura de produtos e estoque) e escolhe qual loja do BridgesAgents recebe o estoque de cada local da Nuvemshop (com uma loja só, isso é automático).

• Cada variação vira um item, com o nome do produto e os valores da variação (ex.: "Camiseta Básica – Azul / M").
• Preço, preço promocional, foto, código de barras (quando é um GTIN válido), marca e categoria vêm da Nuvemshop.
• Variação sem controle de estoque na Nuvemshop aparece como disponível, com 999 unidades.
• Mudanças nos produtos chegam em segundos; uma sincronização completa roda todo dia de madrugada e aparece em Importações com a fonte Nuvemshop.
• Produto oculto, fora da vitrine ou excluído na Nuvemshop fica com estoque zero. Variação sem preço ("consulte") não entra.

Webhooks de pedido

Para o pedido cair direto no sistema da loja (ERP, PDV, agenda, n8n, Zapier): em Integrações, a central ou o desenvolvedor da empresa cadastra um endereço https e escolhe a loja (ou todas) e os eventos. Os administradores recebem um e-mail a cada webhook novo.

• order.created: o consumidor confirmou o pedido (o mesmo momento do e-mail para a loja).
• order.status_changed: a loja aceitou, deixou pronto, concluiu ou cancelou (com cancelReason).
• order.paid: a loja marcou o pedido como pago (ou desfez: paidAt volta vazio).
• Cada envio é um POST com o pedido completo em data.order: itens com gtin e sku da loja, cliente, endereço, agenda da reserva ou do serviço, totais e moeda. Campos novos podem aparecer; nenhum é renomeado.
• Os dados do cliente vão só para a loja do pedido. Para devolver o status, use POST /api/v1/me/orders/{id}/status com a chave da loja.
• Número do pedido: escolha no cadastro o que o seu sistema aceita. Só números: "number": 1042. Letras e números: "number": "AB1042". O campo reference ("AB1042", o mesmo identificador do Pix e do link do consumidor) vai sempre.
• Cabeçalho de acesso (opcional): se o seu sistema exige um token fixo (Authorization: Bearer …, X-Api-Key...), cadastre o nome e o valor: ele vai em todo envio, junto com a assinatura. O valor fica cifrado e o painel mostra só o final.
• Conta de desenvolvedor: em Webhooks, o desenvolvedor do agente recebe os mesmos eventos dos pedidos feitos pelas chaves dele, com data.cart (id, externalReference, agentKeyId) e o pedido sem dados pessoais do comprador (customer e deliveryAddress vazios). É assim que o bot avisa o usuário sem ficar consultando get_cart.

Exemplo

POST https://seusistema.com.br/agentbridge/pedidos
Content-Type: application/json
X-BridgesAgents-Event: order.created
X-BridgesAgents-Event-Id: 6f1c0d2e-…
X-BridgesAgents-Delivery: 0b9a7c41-…
X-BridgesAgents-Signature: t=1793000000,v1=5d2c…
X-Api-Key: (o cabeçalho de acesso, se você cadastrou um)

{
  "id": "6f1c0d2e-…",
  "event": "order.created",
  "createdAt": "2026-10-27T14:03:11Z",
  "data": {
    "order": {
      "id": "…", "number": 1042, "reference": "AB1042", "status": "NEW",
      "storeId": "…", "storeCode": "CENTRO", "storeName": "Exemplo Centro",
      "fulfillment": "DELIVERY",
      "customer": { "name": "Ana Souza", "phone": "+5511988887777", "email": "ana@exemplo.com", "note": null },
      "deliveryAddress": { "postalCode": "01310100", "street": "Av. Paulista", "number": "1000", "complement": null,
                           "district": "Bela Vista", "city": "São Paulo", "region": "SP" },
      "items": [
        { "productId": "…", "gtin": "7890000000011", "sku": "ARZ-5", "name": "Arroz Branco Tipo 1 5kg", "unit": "UN",
          "quantity": 2, "unitPrice": 24.90, "multiplier": 1, "lineTotal": 49.80, "adult": false }
      ],
      "subtotal": 49.80, "deliveryFee": 8.00, "total": 57.80, "currency": "BRL", "estimated": false,
      "schedule": { "scheduledFor": null, "checkIn": null, "checkOut": null, "guests": null },
      "paidAt": null, "cancelReason": null, "agentNote": null,
      "createdAt": "2026-10-27T14:03:10Z", "updatedAt": "2026-10-27T14:03:10Z",
      "payment": { "status": "PENDING", "method": "PIX" }
    }
  }
}

Conferir a assinatura

Ao cadastrar, o painel mostra uma única vez o segredo (whsec_…). Cada envio traz X-BridgesAgents-Signature: t=<segundos>,v1=<hex>, em que v1 é o HMAC-SHA256, com o segredo, de t + "." + corpo (o corpo exatamente como chegou). Recuse se não bater ou se t tiver mais de 5 minutos.

// Node.js (Express): use o corpo cru, antes de qualquer JSON.parse
import crypto from "node:crypto";

app.post("/agentbridge/pedidos", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-BridgesAgents-Signature") ?? "";
  const t = header.match(/t=(\d+)/)?.[1];
  const v1 = header.match(/v1=([0-9a-f]+)/)?.[1] ?? "";
  const expected = crypto.createHmac("sha256", process.env.BRIDGESAGENTS_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!fresh || v1.length !== expected.length
      || !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  // Guarde event.id: se chegar de novo (nova tentativa ou reenvio), ignore
  res.sendStatus(200);
});

# Python (Flask)
import hashlib, hmac, os, re, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/agentbridge/pedidos")
def pedidos():
    header = request.headers.get("X-BridgesAgents-Signature", "")
    t = re.search(r"t=(\d+)", header)
    v1 = re.search(r"v1=([0-9a-f]+)", header)
    if not t or not v1 or abs(time.time() - int(t[1])) > 300:
        abort(401)
    body = request.get_data(as_text=True)
    expected = hmac.new(os.environ["BRIDGESAGENTS_WEBHOOK_SECRET"].encode(), f"{t[1]}.{body}".encode(),
                        hashlib.sha256).hexdigest()
    if not hmac.compare_digest(v1[1], expected):
        abort(401)
    event = request.get_json()
    return "", 200

Respostas, novas tentativas e reenvio

• Responda 2xx em até 10 segundos e processe depois, se for demorado. Redirecionamento não é seguido.
• Sem 2xx, tentamos de novo em 1 min, 5 min, 30 min, 2 h e 12 h. Esgotadas (cerca de 15 h), o webhook é pausado e os administradores recebem e-mail; os pedidos continuam no painel.
• O mesmo evento pode chegar mais de uma vez (nova tentativa ou reenvio): use X-BridgesAgents-Event-Id (igual ao id do corpo) para ignorar repetidos. A ordem não é garantida depois de uma falha: compare data.order.updatedAt.
• No painel ficam os últimos envios (30 dias), com o erro de cada um, e os botões Enviar teste (pedido fictício, evento webhook.test), Reenviar, Pausar/Reativar e Trocar segredo.

Testar no sandbox

No sandbox você testa o fluxo inteiro do seu agente sem uma loja de verdade: as lojas, os produtos e os pedidos são fictícios, e você faz o papel da loja e do checkout de pagamento.

• Pelo painel: em Pedidos dos agentes, abra um pedido e use os botões para aceitar, marcar como pronto, concluir ou cancelar, e para avisar o pagamento (pago no Pix, cartão ou boleto, recusado, estornado, contestado).
• Pela API, com a chave de agente (para testes automatizados): POST /api/v1/carts/{id}/sandbox/status com {"status": "ACCEPTED"} (ACCEPTED, READY, COMPLETED, CANCELLED) e POST /api/v1/carts/{id}/sandbox/payment com {"status": "paid", "method": "pix"} (paid, refused, refunded, chargeback, pending; pix, card, boleto).
• Cada simulação muda o pedido de verdade: o consumidor é avisado, os seus webhooks recebem order.status_changed e order.paid, e o get_cart mostra order.status, order.paymentStatus, order.paymentMethod e order.paidAt.
• Só pedidos montados pelas suas chaves. Em produção essas rotas não existem: quem responde é a loja.

# Aceitar o pedido e avisar o pagamento aprovado (sandbox, com a chave de agente)
curl -X POST https://api.sandbox.bridgesagents.com/api/v1/carts/$CART_ID/sandbox/status \
  -H "Authorization: Bearer $BRIDGESAGENTS_KEY" -H "Content-Type: application/json" \
  -d '{"status": "ACCEPTED"}'

curl -X POST https://api.sandbox.bridgesagents.com/api/v1/carts/$CART_ID/sandbox/payment \
  -H "Authorization: Bearer $BRIDGESAGENTS_KEY" -H "Content-Type: application/json" \
  -d '{"status": "paid", "method": "pix"}'

Ferramenta completa: risco e regiões

Contas de desenvolvedor podem ver o nível de risco dos pedidos que os seus agentes geraram (GET /api/v1/me/agent-orders/{cartId}/risk) e os números por região das lojas da rede (GET /api/v1/me/insights/regions), e buscar pedidos por região (GET /api/v1/me/insights/orders?q=04001, pelo começo do CEP ou pelo nome da cidade ou do bairro): produtos e categoria, pagamento, recusas e o motivo, e o contato (nome, e-mail, telefone) só de pedidos com consentimento: o operador do bot colhe o consentimento do comprador, conforme a cláusula do contrato com a BridgesAgents. O que aparece depende do que o contrato libera, campo a campo, e cada busca fica registrada. No sandbox já está tudo liberado; em produção, mediante contrato com a BridgesAgents.

Enviar catálogo por API

Para o sistema da loja (ERP, loja virtual, script) mandar preços e estoque automaticamente, sem planilha. Mesmas regras e mensagens da importação por planilha.

1. Gere a chave

Há dois tipos:

• Chave da empresa (POST /api/v1/me/api-keys): vale para todas as lojas. Cada item informa storeCode, o código da loja no seu sistema. Ideal para redes.
• Chave de uma loja (POST /api/v1/stores/{storeId}/api-keys): tudo vai para aquela loja e storeCode é ignorado.

No painel, em Chaves de API, ou pela API com a sessão do lojista (veja Autenticação). A chave inteira só aparece nessa resposta: guarde-a com segurança.

curl -X POST "https://api.sandbox.bridgesagents.com/api/v1/stores/{storeId}/api-keys" \
  -H "Authorization: Bearer abs_…" \
  -H "Content-Type: application/json" -d '{"name": "ERP"}'

{
  "apiKey": { "id": "…", "name": "ERP", "keyPrefix": "abk_Xy12Ab34", "createdAt": "…", "lastUsedAt": null, "revokedAt": null },
  "key": "abk_Xy12Ab34…"
}

2. Envie os itens com a chave

A chave vai no header X-Api-Key. Com a chave da empresa, a loja de cada item vem do storeCode; com a chave de uma loja, é sempre aquela loja. Cada item cria ou atualiza a oferta da loja; itens que não forem enviados continuam como estão (para tirar de venda, envie estoque 0). Até 1.000 itens por requisição.

curl -X POST "https://api.sandbox.bridgesagents.com/api/v1/catalog/items" \
  -H "X-Api-Key: abk_…" -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "storeCode": "BH-SAVASSI", "gtin": "7890000000066", "name": "Pilha Alcalina AA com 4", "price": 17.50, "stock": 60 },
      { "storeCode": "BH-PAMPULHA", "gtin": "7890000000103", "name": "Amoxicilina 500mg 21 cápsulas",
        "price": 29.90, "stock": 8, "requiresPrescription": true }
    ]
  }'

A resposta diz o que entrou. Itens com problema não impedem os outros e aparecem em errors com a posição em items (começando em 0):

{
  "received": 2, "imported": 1, "failed": 1,
  "productsCreated": 0, "offersCreated": 0, "offersUpdated": 1,
  "errors": [ { "index": 1, "gtin": null, "name": "Banana Prata", "message": "Preço em branco." } ]
}

Para trocar uma chave vazada, gere outra e revogue a antiga no painel (ou com DELETE /api/v1/stores/{storeId}/api-keys/{keyId}).

API REST

Respostas em JSON. Os campos de produto e oferta são os mesmos das tools MCP.

curl -H "Authorization: Bearer abd_SUA_CHAVE" "https://api.sandbox.bridgesagents.com/api/v1/products?q=pilha%20aa"

curl -H "Authorization: Bearer abd_SUA_CHAVE" \
  "https://api.sandbox.bridgesagents.com/api/v1/products/00000000-0000-0000-0000-0000000000b7/offers?postalCode=30140-010"

curl -X POST "https://api.sandbox.bridgesagents.com/api/v1/carts" -H "Authorization: Bearer abd_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"storeId": "00000000-0000-0000-0000-0000000000a4", "fulfillment": "pickup",
       "items": [{"productId": "00000000-0000-0000-0000-0000000000b6", "quantity": 2}]}'

Com sessão do lojista (header Authorization: Bearer abs_…)

curl -H "Authorization: Bearer abs_…" -F "file=@catalogo.xlsx" \
  "https://api.sandbox.bridgesagents.com/api/v1/stores/{storeId}/catalog/import"

Com chave de API da loja (header X-Api-Key: abk_…)

{
  "rows": 120,
  "imported": 118,
  "failed": 2,
  "productsCreated": 40,
  "offersCreated": 100,
  "offersUpdated": 18,
  "ignoredColumns": ["Observações"],
  "errors": [
    { "line": 7, "message": "Preço inválido: \"abc\"." },
    { "line": 31, "message": "Nome do produto em branco." }
  ]
}

Para testar os endpoints direto no navegador, use a referência interativa (Swagger).

Erros e limites

Erros vêm no formato application/problem+json (RFC 9457). O campo detail já traz uma mensagem em português que pode ser mostrada ao lojista.

Autenticação

Chave de agente

Nenhuma consulta ao catálogo é anônima. Crie a conta de desenvolvedor (sem CNPJ) e gere as chaves em Chaves de agente, no painel. A chave aparece uma vez só; o banco guarda apenas o hash. Use uma chave por agente ou ambiente: se uma vazar, revogue só ela. O painel mostra quantas consultas cada chave fez por dia, e o limite é de 120 por minuto por chave.

curl -X POST "https://api.sandbox.bridgesagents.com/api/v1/me/agent-keys" -H "Authorization: Bearer abs_…" \
  -H "Content-Type: application/json" -d '{"name": "Agente em produção"}'
# → { "apiKey": { "id": "…", "keyPrefix": "abd_Xk3…" }, "key": "abd_…" }   (só desta vez)

Planos e franquia

Cada requisição autenticada com chave de agente conta uma consulta (busca, ofertas, carrinho ou chamada MCP). O plano Grátis inclui 10.000 consultas por mês; ao chegar nelas, a API responde 429 com a explicação em detail até o dia 1º do mês seguinte. Os planos pagos (Pro e Escala) não bloqueiam: o excedente é cobrado por bloco de 1.000 consultas na fatura do fim do mês. Avisamos por e-mail aos 80% e aos 100% da franquia, e o uso do mês aparece em Plano e cobrança, no painel. O sandbox não tem franquia.

Sandbox

Para testar sem atingir lojas de verdade, use o sandbox: site em https://sandbox.bridgesagents.com e API em https://api.sandbox.bridgesagents.com (MCP em /mcp). Ele tem a mesma versão da produção (toda mudança é publicada nos dois), mas banco próprio, com lojas e produtos de exemplo. Crie lá uma conta de desenvolvedor: as chaves começam com abd_test_ e não valem na produção (nem as de produção valem lá). Carrinhos e pedidos funcionam de ponta a ponta, só que nas lojas de exemplo; os e-mails chegam com [Sandbox] no assunto.

OAuth 2.1 (servidor MCP)

Seguimos a autorização da especificação MCP: metadados em /.well-known/oauth-protected-resource e /.well-known/oauth-authorization-server, registro dinâmico em POST /oauth/register (só clientes públicos), código com PKCE S256 obrigatório em /oauth/authorize e POST /oauth/token. O token de acesso (abo_) vale 1 hora e o de renovação (abr_) 30 dias, trocado a cada uso; reusar um token de renovação ou um código derruba a conexão. POST /oauth/revoke revoga. O consumidor vê e desconecta os apps em Minhas compras › Apps conectados.

Ficam públicos só a descoberta (/.well-known/ucp), esta documentação e o link de compra /r/…, que o consumidor abre.

Sessão do painel

A sessão vem do login e vale 30 dias:

curl -X POST "https://api.sandbox.bridgesagents.com/api/v1/auth/login" -H "Content-Type: application/json" \
  -d '{"email": "voce@sualoja.com.br", "password": "…"}'
# → { "token": "abs_…", "expiresAt": "…", "user": { … } }

O cadastro de lojista (POST /api/v1/auth/signup) cria a empresa, a primeira loja e o usuário de uma vez; o de desenvolvedor (POST /api/v1/auth/signup/developer) pede só nome da empresa ou projeto, seu nome, e-mail e senha. Os dois já devolvem a sessão. POST /api/v1/auth/logout encerra a sessão.

A chave de agente continua valendo para agentes que não usam OAuth.