@ar-agents/agentic-commerce-bridge

@ar-agents/agentic-commerce-bridge

The first open-source merchant facilitator for the Agentic Commerce Protocol (ACP) in LATAM. Bridges ChatGPT Instant Checkout, Claude, Gemini, and other agentic-commerce clients to MercadoPago + MercadoLibre, with AR-fiscal compliance (auto-issued AFIP/ARCA Factura A/B/C/E) baked in.

pnpm add @ar-agents/agentic-commerce-bridge zod

What it is

ACP, maintained by OpenAI + Stripe, defines how AI agents talk to merchants on behalf of users: discover products, build a cart, finalize a checkout, settle payment, and confirm fulfillment — all over a small REST surface (5 endpoints + /.well-known/acp.json discovery) with HMAC-signed webhooks.

Today, when ChatGPT or Claude wants to buy something from a LATAM seller, there is no on-ramp: MercadoLibre and MercadoPago don't ship ACP endpoints; the official MELI/MP MCP servers expose only documentation search. This package fills that gap. It's a drop-in facilitator that:

• Implements all 5 ACP 2026-04-17 endpoints + discovery
• Signs and verifies webhooks per spec (HMAC-SHA256, Merchant-Signature)
• Enforces idempotency (Idempotency-Key, replay detection, conflict)
• Negotiates ACP versions (rejects unsupported, surfaces supported_versions)
• Plugs into MercadoPago checkout (preference creation + payment lookup
  • webhook bridge)
• Plugs into MercadoLibre catalog (item lookup + UCP-style feed)
• Auto-issues AR-fiscal Factura A/B/C/E via AFIP WSFE on order confirmation, embedding the CAE in the order metadata
• Runs on Edge Runtime (WebCrypto-only, no Node-only imports)
• Pluggable state adapter — InMemoryStateAdapter for dev, VercelKVStateAdapter for production, BYO for anything else

Why now

Standard	Status (2026-05)	LATAM coverage
ACP (OpenAI + Stripe)	Production at ChatGPT Instant Checkout	None
UCP (Google + Shopify + Amazon + Microsoft + Stripe)	NRF 2026 launch	None
AP2 (Google → FIDO Alliance)	v0.2 + FIDO donation Apr 2026	None
Visa Trusted Agent Protocol	Pilots in AR/BR/CL/MX/UY	MercadoPago absent
Mastercard Agent Pay LATAM	Live transactions Mar 2026	MercadoPago absent
x402 (Coinbase + Stripe + Cloudflare)	169M txns	None

When ChatGPT Shopping expands into LATAM (Q3-Q4 2026 per OpenAI partner trajectory), MELI sellers without an ACP bridge will be invisible to agent-driven commerce. Stripe is positioning to ship LATAM ACP in 12-18 months; this package gives you a head start, on open-source terms.

Quickstart

import {
  createFacilitator,
  InMemoryStateAdapter,
  createMercadoPagoPaymentProvider,
  mercadoPagoPaymentHandler,
  createMeliCatalogProvider,
  createFacturacionHook,
} from "@ar-agents/agentic-commerce-bridge";
// You bring your own MELI + MP + AFIP clients (or use ar-agents siblings):
import { mlClient } from "./meli-client";
import { mpClient } from "./mp-client";
import { wsfeClient, arcaPadron } from "./afip-client";

const mp = createMercadoPagoPaymentProvider({
  createPreference: (p) => mpClient.preferences.create({ body: p }),
  lookupPayment:    (id) => mpClient.payments.get({ id }),
});

const facilitator = createFacilitator({
  state: new InMemoryStateAdapter(),
  catalog: createMeliCatalogProvider({
    getItem: (id) => mlClient.items.get(id),
  }),
  paymentProviders: { [mp.handlerId]: mp },
  paymentHandlers: [mercadoPagoPaymentHandler({})],
  webhookSecret: process.env.ACP_WEBHOOK_SECRET,
  hooks: createFacturacionHook({
    seller: {
      cuit: "20123456786",
      punto_venta: 1,
      regime: "monotributo",
      legal_name: "Naza Clemente",
    },
    wsfe: wsfeClient,
    arcaPadronLookup: arcaPadron.lookup,
  }),
});

// Next.js App Router catch-all route:
//   app/api/acp/[...slug]/route.ts
export async function POST(req: Request, ctx: { params: { slug: string[] } }) {
  const acpResponse = await facilitator.dispatch({
    method: "POST",
    path: "/" + ctx.params.slug.join("/"),
    headers: Object.fromEntries(req.headers.entries()),
    rawBody: await req.text(),
  });
  return new Response(JSON.stringify(acpResponse.body), {
    status: acpResponse.status,
    headers: acpResponse.headers,
  });
}

That's it. Your store is now ACP-discoverable from any agent that follows the spec. ChatGPT, Claude, Gemini, Walmart Sparky, Microsoft Copilot, and any Vercel AI SDK agent can transact against you.

What ships

Module	Purpose
schemas/*	Zod schemas for every ACP 2026-04-17 shape — CheckoutSession, LineItem, Buyer, Address, FulfillmentOption (4 variants), PaymentData, Order, Cart, Capabilities, Discount, Webhook, Error
webhook	signWebhook / verifyWebhook — HMAC-SHA256, Merchant-Signature: t=<unix>,v1=<64hex>, 300s tolerance per spec
idempotency	Idempotency-Key validation + body-hash + state interface
state	InMemoryStateAdapter (dev) + StateAdapter interface
vercel-kv (subpath)	VercelKVStateAdapter — Redis-shape adapter (Vercel KV / Upstash / ioredis duck-typed)
version	API version negotiation (API-Version header)
handlers/*	The 5 ACP endpoint handlers + discovery + dispatcher + facilitator factory
integrations/mp	createMercadoPagoPaymentProvider + sessionToPreferencePayload + payment-handler declaration
integrations/mp-webhook	parseMpPaymentIdFromWebhook, mpStatusToAcpOrderStatus, buildAcpEventFromMpWebhook — translate MP notifications → ACP webhooks
integrations/meli	createMeliCatalogProvider + buildMeliFeed (UCP-compatible) + meliItemToFeedProduct
integrations/facturacion	createFacturacionHook — auto-emit Factura A/B/C/E via AFIP WSFE on order confirmation
totals	buildLineItemTotals, buildOrderTotals, helpers for fulfillment + tax + discount rollups
ids	generateSessionId, generateOrderId, generateCartId (UUID-backed)

ACP endpoints implemented

Method	Path	Status
POST	/checkout_sessions	✅
POST	/checkout_sessions/{id}	✅ (update)
GET	/checkout_sessions/{id}	✅
POST	/checkout_sessions/{id}/complete	✅
POST	/checkout_sessions/{id}/cancel	✅
GET	/.well-known/acp.json	✅ (discovery, RFC 8615)

Per-spec features:

• Idempotency-Key mandatory on POSTs, replay detection (Idempotent-Replayed: "true"), in-flight (409 + Retry-After), and body-hash conflict (422 idempotency_conflict).
• API-Version header negotiation; rejects unsupported with supported_versions echo.
• Cached responses for replay across restarts (when using VercelKVStateAdapter).
• Catalog / payment / fulfillment hooks — fully framework-agnostic.

AR-fiscal compliance — the moat

createFacturacionHook is the unique-to-LATAM piece. When an ACP order completes:

• The buyer's IVA condition is resolved either explicitly (host-supplied resolveBuyer) or automatically via ARCA padrón lookup (@ar-agents/identity's ws_sr_constancia_inscripcion).

• The factura type is selected from a normative matrix:

  Seller regime	Buyer condition	Factura
  monotributo	any	C
  responsable_inscripto	responsable_inscripto / monotributista	A
  responsable_inscripto	consumidor_final / other	B
  any	extranjero (cross-border)	E

• WSFE solicitarCAE is invoked with the correct totals + IVA breakdown (21% default for RI, 0% for monotributo Factura C).

• The CAE, vencimiento, número, and IVA breakdown are embedded in Order.metadata:

  {
    "factura_type": "C",
    "factura_cae": "70123456789012",
    "factura_cae_vencimiento": "20260520",
    "factura_numero": 42,
    "factura_punto_venta": 1,
    "factura_cuit_emisor": "20123456786",
    "factura_importe_total": 1210,
    "factura_importe_iva": 0,
    "factura_importe_neto": 1210
  }
  

• If WSFE rejects or padron lookup fails, the order still persists (payment was already authorized) — the error is captured in metadata.factura_error so the seller can re-emit out-of-band.

No competitor in the LATAM ACP/UCP/AP2 space ships this. Stripe Tax doesn't cover Argentine fiscal nuance and won't.

How it compares

	This package	Stripe ACP	Shopify Storefront ACP	MELI/MP MCP (official)
ACP 2026-04-17 schemas	✅	✅	partial	n/a (docs-only)
Hosted-agent on Edge Runtime	✅	✅	✅	n/a
Webhook HMAC + replay protection	✅	✅	✅	n/a
MercadoPago bridge	✅	❌	❌	partial
MercadoLibre catalog	✅	❌	❌	partial
AR-fiscal Factura A/B/C/E	✅	❌	❌	❌
Argentine padrón lookup	✅ (via @ar-agents/identity)	❌	❌	❌
MIT, open source	✅	✅ (since Apr 2026)	partial	✅ (docs only)

Hosting

Works in:

• Vercel (Edge or Node runtime) — pair with VercelKVStateAdapter for state
• Cloudflare Workers — pair with KV / Upstash Redis
• Deno Deploy / Bun
• Node 20+ (HTTP server, Express, Hono, Fastify, Next.js)

WebCrypto-only (no node:crypto imports). The bundle is < 30KB gzip.

Phase 2 (planned)

• AP2 mandate verifier/signer — ES256 SD-JWT VC, mandate chains (~~-separated), constraint evaluation (payment.amount_range, checkout.allowed_merchants, payment.budget), receipts (Checkout + Payment) signed per FIDO Alliance Agentic Auth WG profile.
• MELI Q&A + claims tools as ACP extension types — agent-driven pre-sale answer-fetch + post-sale evidence upload.
• PIX / Transferencias 3.0 / SPEI bridges — AP2 mandates settling to LATAM bank rails when card networks aren't the right fit.

Tests

pnpm test          # 160 tests across schemas, webhook, idempotency, state,
                   # version, handlers, MP, MELI, facturacion, vercel-kv
pnpm test:coverage # full coverage report
pnpm typecheck     # strict TS, no `any`, exactOptionalPropertyTypes

Specs we follow

• ACP — agentic-commerce-protocol/agentic-commerce-protocol (2026-04-17 is the targeted version; older versions are recognized in version negotiation but new sessions emit 2026-04-17)
• AP2 — ap2-protocol.org (Phase 2)
• AFIP/ARCA WSFE — wsfev1 SOAP spec, factura A/B/C/E

License

MIT. Built by Naza Clemente / Hello Astro for the LATAM agent ecosystem.

Related packages

• @ar-agents/mercadopago — Mercado Pago Agent Toolkit (89 tools)
• @ar-agents/identity — CUIT/CUIL + ARCA padrón
• @ar-agents/facturacion — AFIP WSFE factura electrónica
• @ar-agents/banking — CBU/CVU + BCRA Central de Deudores
• @ar-agents/whatsapp — WhatsApp Business Cloud
• @ar-agents/shipping — Andreani / OCA / Correo Argentino
• @ar-agents/mcp — MCP server bundling all the above