Primeros pasos

En esta guía creás una app de Commercy, la instalás en una tienda de prueba y hacés tu primer request a la API en unos minutos. Al final la enviás a revisión.

Todo lo que probás antes de publicar funciona en tu propia tienda y en tus tiendas demo, sin necesidad de un plan pago.

¿Vas a armar la app con Claude, Codex o Cursor? Mirá Desarrollá con IA: la documentación completa está en https://docs.commercy.com.ar/llms-full.txt, lista para pasarle como contexto.

Creá tu cuenta y el alta de developer

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

Creá la app

En el portal elegí Nueva app y completá el 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 necesita tu app. Pedí sólo los que vas a usar: cada permiso extra se revisa y se le muestra al comerciante (ver Scopes y permisos).

Generá el client secret

En Credenciales generá un client secret. Empieza con cs_ y se muestra una sola vez: copialo y guardalo en un lugar seguro (variable de entorno o gestor de secretos). Si lo perdés, generás otro y borrás el anterior. Cada app puede tener hasta 2 secretos a la vez para rotarlos sin cortar el servicio.El client_id (empieza con app_) no es secreto y lo ves siempre en el portal.

Instalá la app en una tienda

En borrador, la app sólo se instala en tu propia tienda o en una tienda demo. Abrí esta URL en el navegador, con la sesión de la tienda donde querés instalarla:

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

Commercy te lleva a la pantalla de consentimiento. Al aceptar, te redirige a tu redirect_uri con ?code=...&state=.... El code dura 60 segundos y sirve una sola vez. Cómo generar el code_challenge y canjear el code está en Autenticación OAuth.Canjeá el code por un access token:

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

La respuesta trae el access_token (dura 1 hora) y un refresh_token:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "9f2c...",
  "scope": "read_shops read_products",
  "installation_id": "6710b3c2e4a1f20012ab34cd",
  "store": { "id": "6710b3c2e4a1f20012ab34ce", "name": "Mi Tienda" }
}

Tu primer request

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

{
  "data": {
    "id": "6710b3c2e4a1f20012ab34ce",
    "name": "Mi Tienda",
    "currency": "ARS",
    "plan_tier": "professional",
    "shops": [{ "id": "6710b3c2e4a1f20012ab34cf", "name": "Sucursal Centro" }]
  }
}

Si recibís 200 con ese formato, ya estás autenticado. Seguí con la referencia de la API.

Configurá un webhook

En Webhooks cargá la URL donde querés recibir los eventos. Tiene que ser https y pública: no funciona con localhost. Para desarrollar usá un túnel como ngrok o cloudflared:

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

Desde el portal enviá un ping de prueba para verificar que tu endpoint responde 2xx. Después implementá la verificación de la firma.Tu app tiene que responder 2xx a los 4 webhooks obligatorios (app.uninstalled, store.redact, customers.redact y customers.data_request); sin eso no se publica.

Enviá la app a revisión

Cuando todo funciona en tu tienda demo, completá la ficha (descripción, política de privacidad, soporte, video de demo) y usá Enviar a revisión. Respondemos en hasta 10 días hábiles. El detalle del checklist está en Revisión y publicación.

Empezar

Autenticación y permisos

API

Webhooks

Publicación

Creá tu cuenta y el alta de developer

Creá la app

Generá el client secret

Instalá la app en una tienda

Tu primer request

Configurá un webhook

Enviá la app a revisión