AntivioenIniciar sesión

Crear una app (OAuth)

Una app es una integración que muchas empresas o comercios pueden instalar, cada uno aprobando lo que puede hacer. Si solo conectas tu propia tienda con tu propia cuenta no necesitas una: usa un token de API.

Las apps usan el flujo de código de autorización de OAuth 2.1 con PKCE. No hay SDK que aprender: cada paso es una petición HTTPS normal.

1. Abre una cuenta de desarrollador y registra una app

Entra al panel, acepta los términos para desarrolladores y registra tu app. Eliges:

Recibes un client id (app_…). Es público.

Lo mismo está disponible por API en /v1/developer/… para personas con sesión (no para tokens).

2. Envía a la persona a aprobar

Abre el navegador de la persona en la página de consentimiento de la aplicación web, con un reto PKCE y un state que verificarás al volver:

https://cloud.antivio.app/oauth/authorize
  ?response_type=code
  &client_id=app_Ab3xK9mQ2wL7pZ4nR8tY1vC5
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=shipments%3Aread%20shipments%3Awrite
  &state=<texto aleatorio que guardas>
  &code_challenge=<base64url(sha256(code_verifier))>
  &code_challenge_method=S256

Crea un code_verifier nuevo (de 43 a 128 caracteres de A-Z a-z 0-9 - . _ ~) en cada intento y guárdalo en tu servidor (o en la sesión). state y PKCE son obligatorios.

La persona inicia sesión, elige la empresa (o la cuenta de comercio) y aprueba los permisos. Solo quienes pueden gestionar integraciones ahí pueden instalar una app, y solo pueden dar permisos que su propio rol tiene. Antivio redirige el navegador a tu URI:

https://acme.example/oauth/callback?code=atc_…&state=<tu state>

Si rechaza, la redirección trae error=access_denied y tu state. Verifica state antes de usar el código. El código sirve una vez y durante 60 segundos.

3. Cambia el código por tokens

curl -X POST https://api.antivio.app/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://acme.example/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"

Las apps confidenciales se autentican con HTTP Basic (arriba) o con client_id y client_secret en el cuerpo del formulario; las públicas envían solo client_id.

{
  "access_token": "atk_live_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "atr_…",
  "scope": "shipments:read shipments:write"
}

El token de acceso es el mismo bearer que un token de API: envíalo como Authorization: Bearer … a la API pública. Actúa como la persona que aprobó, limitado a los permisos otorgados, así que deja de funcionar si esa persona sale de la empresa. Dura una hora.

4. Renueva

curl -X POST https://api.antivio.app/oauth/token -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token -d refresh_token="$REFRESH_TOKEN"

Cada renovación devuelve un token de renovación nuevo y gasta el anterior. Guarda el nuevo antes de usar el nuevo token de acceso. Los tokens de renovación duran 30 días.

Si un token de renovación o un código se usa dos veces, Antivio asume que se filtró y revoca todos los tokens de esa instalación; la persona debe aprobar de nuevo. No reintentes una renovación en paralelo.

5. Revoca

curl -X POST https://api.antivio.app/oauth/revoke -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN"

Revocar un token de acceso termina solo ese token; revocar un token de renovación termina todos los de la instalación. La respuesta es 200 incluso para un token que no conocemos.

6. Recibe webhooks

Con webhooks:write, tu token de acceso agrega endpoints de webhooks como cualquier token de API (POST /v1/webhook-endpoints). Pertenecen a la instalación:

7. Eventos de la app y solicitudes de privacidad

Configura la URL de eventos de tu app en el portal de desarrolladores (o PUT /v1/developer/apps/{id}/events con {"url": "https://…"}). Antivio envía ahí, por cada empresa que instaló tu app, mensajes firmados con el secreto de eventos de tu app (whsec_…, visible en el portal) igual que los webhooks: verifica webhook-signature con el mismo código, responde 2xx y usa webhook-id para ignorar repeticiones. Los mensajes fallidos se reintentan durante unos tres días.

TipoCuándodata
app.uninstalledla empresa quitó tu app; sus tokens y endpoints de webhooks ya no existeninstallation_id, customer_account_id, uninstalled_at
customer.data_requestun destinatario pidió a la empresa los datos que se guardan sobre élprivacy_request_id, installation_id, customer_account_id, recipient (email, phone), shipment_ids, requested_at
customer.redactun destinatario pidió que se borren sus datoslo mismo que customer.data_request

8. Publica en la App Store

Una app privada se instala desde un enlace que compartes, sin revisión. Para que cualquier empresa la encuentre e instale, envíala a revisión; cuando Antivio la aprueba, aparece en la App Store dentro del panel de cada empresa.

Antes de enviarla, la app necesita una URL de política de privacidad, una URL de soporte y una URL de eventos (debe recibir app.uninstalled y las solicitudes de privacidad). Luego:

curl -X POST https://api.antivio.app/v1/developer/apps/$APP_ID/submissions \
  -H "Authorization: Bearer $USER_TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{
    "listing": {
      "tagline": "Mantén los pedidos y envíos de tu tienda sincronizados",
      "description_en": "Sends every order to Antivio and brings the tracking back.",
      "description_es": "Envía cada pedido a Antivio y trae el seguimiento.",
      "category": "ecommerce",
      "app_url": "https://acme.example/install",
      "scope_justifications": [
        { "scope": "shipments:read", "justification": "Muestra el estado de cada pedido al comprador." }
      ]
    },
    "note": "Primera versión."
  }'

Errores

El endpoint de tokens responde con errores de RFC 6749, no con problemas RFC 9457:

errorEstadoSignificado
invalid_request400Falta un parámetro o es inválido (forma del code_verifier, cuerpo del formulario)
invalid_client401App desconocida, suspendida o mal autenticada
invalid_grant400El código o el token de renovación es desconocido, ya usado, vencido o de otra app o URI; o la app fue desinstalada
unsupported_grant_type400Solo existen authorization_code y refresh_token. No hay concesión por contraseña, implícita ni de credenciales de cliente

Metadatos del servidor

GET /.well-known/oauth-authorization-server (RFC 8414) lista los endpoints, S256 y los permisos soportados.

Buenas prácticas

Todas las guías