← Volver al blogGuía · Tutorial

Cómo crear una app para Commercy: guía para developers

· 9 min de lectura · Equipo Commercy

Crear una app para Commercy lleva unos minutos hasta el primer request y unos días hasta la publicación, porque cada app pasa por una revisión. Commercy es un e-commerce, POS y ERP argentino con facturación ARCA nativa, y desde el 25 de octubre de 2026 abre su marketplace de apps de terceros. Esta guía recorre el camino completo de una API de e-commerce para Argentina: alta en el portal, credenciales, OAuth con PKCE, el primer request, webhooks, pruebas en una tienda demo y envío a revisión. Los snippets salen de la documentación oficial; ahí está el detalle de cada endpoint.

Antes de empezar: qué podés construir

Con la API pública (https://api.commercy.com.ar/api/public/2026-10) tu app puede leer y modificar productos, precios, stock, ventas y clientes de las tiendas donde se instale, según los permisos que el comerciante acepte. Además de eso, el programa admite:

  • Webhooks firmados para enterarte de cambios sin hacer polling.
  • Apps embebidas que se abren dentro del panel de Commercy.
  • Lugares en la tienda online, que muestran un bloque de tu app en el storefront.
  • Apps de envío y apps de cobro que se integran al checkout. Si es tu caso, mirá la guía de pasarelas y envíos.

Para ver cómo lo presentamos a quienes construyen, está la página /developers.

Paso 1: alta de developer

  1. Registrate en Commercy como cualquier comercio.
  2. Entrá al portal de developers con el mismo email y contraseña.
  3. Completá el alta de developer: nombre público y aceptación de los términos del programa.

Paso 2: creá la app, la redirect URI y los scopes

En el portal elegí Nueva app y poné un nombre. Después, en Credenciales:

  • Cargá una redirect URI. Mientras la app está en borrador podés usar http://localhost:3000/callback.
  • Elegí los scopes, que son los permisos que verá el comerciante. Pedí solo los que vas a usar: cada permiso extra se revisa en la homologación. Los de escritura incluyen los de lectura (write_stock ya permite leer stock) y el permiso de costos (read_costs) es sensible y hay que justificarlo.

Generá también un client secret. Empieza con cs_ y se muestra una sola vez: guardalo en una variable de entorno o en un gestor de secretos. El client_id (empieza con app_) no es secreto.

Paso 3: OAuth 2.0 con PKCE

Las apps usan authorization code con PKCE (S256) y un cliente confidencial: el client_secret vive en tu servidor y nunca en un navegador. Estos endpoints no tienen CORS a propósito.

El flujo, resumido:

  1. Tu servidor genera un code_verifier, calcula su code_challenge y guarda el verifier y un state en la sesión del comerciante.
  2. Mandás al comerciante a GET /oauth/apps/authorize. Él ve los permisos y acepta.
  3. Commercy redirige a tu redirect_uri con ?code=...&state=.... El code dura 60 segundos y sirve una vez.
  4. Tu servidor lo canjea en POST /oauth/apps/token. Ese canje es lo que crea la instalación.

Para instalar en tu tienda de pruebas, abrí esta URL con la sesión de la tienda donde querés instalar:

https://api.commercy.com.ar/oauth/apps/authorize
  ?client_id=TU_CLIENT_ID
  &redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback
  &response_type=code
  &state=UN_VALOR_ALEATORIO
  &code_challenge=EL_CODE_CHALLENGE
  &code_challenge_method=S256

Y canjeá el code por tokens:

curl -X POST https://api.commercy.com.ar/oauth/apps/token \
  -u "TU_CLIENT_ID:TU_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=EL_CODE_RECIBIDO \
  -d redirect_uri=http://localhost:3000/callback \
  -d code_verifier=EL_CODE_VERIFIER

El access token dura 1 hora. El refresh token dura 90 días y es de un solo uso: cada renovación te da uno nuevo y tenés que guardarlo. Si un refresh token ya usado se vuelve a presentar, Commercy lo trata como una posible filtración y revoca la instalación, así que serializá los refresh (un solo proceso renueva). El código para generar el challenge y armar la URL en Node está completo en la página de OAuth.

Paso 4: tu primer request

Con el access token ya podés consultar la API:

curl https://api.commercy.com.ar/api/public/2026-10/store \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Si recibís 200 con los datos de la tienda, estás autenticado. Algunas convenciones útiles de la referencia de la API:

  • La versión va en la URL y es una fecha (2026-10). Cada versión se mantiene al menos 12 meses después de que sale la siguiente.
  • Las colecciones se paginan con cursor (limit de 1 a 100) y aceptan updated_since para sincronizar solo lo nuevo.
  • Los parámetros desconocidos se rechazan con 400 invalid_request, no se ignoran en silencio.
  • Mandá Idempotency-Key en las escrituras; es obligatorio en los ajustes de stock.
  • Los límites de uso se calculan por app y por tienda. Si recibís 429, esperá lo que indica el header Retry-After.

Paso 5: configurá un webhook

En Webhooks cargá la URL donde querés recibir eventos. Tiene que ser https y pública: no funciona con localhost, así que durante el desarrollo usá un túnel como cloudflared:

cloudflared tunnel --url http://localhost:3000

Desde el portal podés enviar un ping de prueba. Después implementá la verificación de la firma, que se calcula sobre el cuerpo crudo y el timestamp. La función de Node de la documentación es esta:

const crypto = require("crypto");

const TOLERANCE_SECONDS = 300; // 5 minutos

// headers: nombres en minúscula (como los entrega Node/Express).
function verifyCommercyWebhook(rawBody, headers, secret, nowSec = Math.floor(Date.now() / 1000)) {
  const timestamp = headers["x-commercy-timestamp"];
  const signature = headers["x-commercy-signature"];
  if (!timestamp || !signature) return false;

  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || Math.abs(nowSec - ts) > TOLERANCE_SECONDS) return false;

  const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(String(signature));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

module.exports = { verifyCommercyWebhook };

Tres detalles que suelen fallar: leer el cuerpo antes de parsearlo como JSON, comparar en tiempo constante y deduplicar por el header X-Commercy-Event-Id, porque la entrega es al menos una vez y sin orden garantizado. La documentación incluye un vector de prueba para validar tu implementación.

Los 4 webhooks obligatorios

Tu app tiene que responder 2xx a app.uninstalled, store.redact, customers.redact y customers.data_request. Se entregan siempre, sin suscribirte, y sin ellos la app no se publica. Cubren la desinstalación y los pedidos de borrado o copia de datos de un cliente.

Paso 6: probá en una tienda demo

En borrador, la app solo se instala en tu propia tienda y en tus tiendas demo: hasta 3 tiendas de ejemplo con productos, stock, clientes y ventas ficticias que creás desde el portal. Ahí podés probar el flujo completo (instalar, llamar a la API, recibir webhooks, desinstalar y reinstalar) sin riesgo para un comercio real y sin plan pago.

Paso 7: enviá la app a revisión

Cuando todo funciona, completá la ficha (descripción, política de privacidad, soporte y video de demo) y usá Enviar a revisión. El equipo responde en hasta 10 días hábiles. Revisan, entre otras cosas, que:

  • se instale y reinstale bien, y responda los 4 webhooks obligatorios;
  • pida solo los permisos que usa y justifique los sensibles;
  • no consulte la API en exceso (se pide un diagrama de secuencia de cómo sincronizás datos, y se prefieren webhooks más updated_since antes que polling);
  • tenga política de privacidad y soporte válidos, y una ficha honesta.

Las URLs de producción tienen que ser https y públicas. Una vez publicada, la app aparece en la Tienda de apps de los comercios con un plan que las incluya. Si no querés listarla (por ejemplo, porque es para tus propios clientes), podés marcarla como no listada y compartir el link a la ficha.

Desarrollar con IA

Si trabajás con Claude, Codex o Cursor, la documentación completa está en un solo archivo pensado para pasarle como contexto: llms-full.txt. Pedile que lea el archivo antes de escribir código, indicale los scopes mínimos y probá todo en una tienda demo. Revisá lo que genera contra la referencia de la API: si la IA inventa un endpoint, la API lo rechaza con 400 invalid_request.

Una app de ejemplo para copiar

commercy-app-examples reúne varias apps de ejemplo para copiar y adaptar: un tablero de ventas (OAuth con PKCE, refresh de tokens, API pública con paginación y webhooks firmados, incluidos los 4 obligatorios), una app de envíos, una de cobros, un arranque de webhooks y scripts para la tienda online.

Scripts para la tienda

Si tu app necesita mostrar algo en la tienda online del comercio, como un chat, un aviso de cuotas o prueba social, podés declarar un script que se carga en la tienda. El archivo tiene que servirse desde el mismo dominio que la URL de tu app, con un hash SRI, y pasa por la revisión de Commercy. El comercio acepta el permiso al instalar y puede apagarlo desde el detalle de la app. Cómo declararlo y los eventos que recibe están en Scripts en la tienda.

Preguntas frecuentes

¿Cuánto cuesta crear una app para Commercy?

Crear y probar es gratis, sin necesidad de un plan pago. Para probar usás tu tienda y hasta 3 tiendas demo. Commercy no cobra comisión por las apps.

¿Qué autenticación usa la API de Commercy?

OAuth 2.0 con authorization code y PKCE (S256), con un cliente confidencial. El access token dura 1 hora y el refresh token, 90 días y de un solo uso.

¿Puedo probar sin un comercio real?

Sí. En borrador, la app se instala en tu propia tienda y en tus tiendas demo, que tienen datos ficticios y se crean desde el portal.

¿Cuánto tarda la revisión?

El equipo de Commercy responde en hasta 10 días hábiles desde que enviás la app. Si hay que corregir algo, el motivo queda en la pestaña Revisión del portal.

¿Cómo verifico la firma de los webhooks?

Calculás HMAC-SHA256 con tu secreto sobre <timestamp>.<cuerpo crudo>, en hexadecimal y con el prefijo v1=, y la comparás en tiempo constante con el header X-Commercy-Signature. Rechazá timestamps con más de 5 minutos de diferencia.

¿Puedo hacer una app solo para mis clientes?

Sí. Podés marcarla como no listada: sigue publicada pero no aparece en el listado de la Tienda de apps, y los comercios la instalan desde el link a su ficha.