Saltar al contenido principal

Suscripciones (SDK)

Los SDK de Node.js y PHP de OrcaRail permiten crear y gestionar suscripciones con los mismos contratos de la API REST (incluidos los campos de petición en snake_case cuando aplica). Los ejemplos siguientes usan el SDK de Node.js; consulta SDK de PHP para los equivalentes en PHP.

APIs del comercio frente a APIs del pagador​

El SDK cubre las operaciones autenticadas por el comercio: crear, obtener, actualizar, cancelar, reanudar, listar y listar enlaces de pago (igual que en Gestionar suscripciones).

Las llamadas de cara al pagador no están en @orcarail/node ni en orcarail/orcarail-php. Impleméntalas por HTTP desde tu app de pago alojada o desde el navegador (sin clave de API), igual que la interfaz de pago de OrcaRail:

  • POST /api/v1/subscriptions/:id/approve-auto-charge
  • POST /api/v1/subscriptions/:id/revoke-auto-charge
  • POST /api/v1/subscriptions/:id/set-collection-method

Consulta Cobro automático para ver los cuerpos de petición y el comportamiento.

Instalación​

Igual que el SDK principal:

npm install @orcarail/node
composer require orcarail/orcarail-php

Configuración del cliente​

Usa el mismo cliente que para los Payment Intents; las suscripciones usan la misma autenticación (clave de API o Bearer) y las llamadas a la colección de suscripciones del comercio deducen la organización de la clave de API autenticada.

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!,
  process.env.ORCARAIL_API_SECRET!,
  { baseUrl: 'https://api.orcarail.com/api/v1' }
)

Crear una suscripción​

const subscription = await orcarail.subscriptions.create({
  description: 'Monthly Pro Plan',
  amount: '10.00',
  currency: 'usd',
  token_id: tokenId,
  network_id: networkId,
  interval: 'month',
  interval_count: 1,
  collection_method: 'send_payment_link',
  total_cycles: 12,
  payer_email: '[email protected]',
  metadata: { plan_id: 'pro_monthly' },
})

console.log(subscription.id)
console.log(subscription.current_period_end)
console.log(subscription.latest_payment_link?.link)

Obtener una suscripción​

const subscription = await orcarail.subscriptions.retrieve(
  'sub_550e8400e29b41d4a716446655440000'
)
console.log(subscription.status, subscription.completed_cycles)

Listar suscripciones​

const { data, has_more } = await orcarail.subscriptions.list({
  status: 'active',
  limit: 20,
  starting_after: 'sub_previous_id', // optional cursor
})

for (const sub of data) {
  console.log(sub.id, sub.description, sub.current_period_end)
}

Actualizar una suscripción​

const updated = await orcarail.subscriptions.update(
  'sub_550e8400e29b41d4a716446655440000',
  {
    cancel_at_period_end: true,
    metadata: { reason: 'customer_requested' },
  }
)

Cancelar una suscripción​

await orcarail.subscriptions.cancel('sub_550e8400e29b41d4a716446655440000', {
  cancellation_details: {
    comment: 'Switching to annual',
    feedback: 'other',
  },
})

Reanudar una suscripción​

await orcarail.subscriptions.resume('sub_550e8400e29b41d4a716446655440000')
const { data } = await orcarail.subscriptions.listPaymentLinks(
  'sub_550e8400e29b41d4a716446655440000',
  { limit: 10 }
)

Gestión de webhooks​

Los eventos de suscripción usan el mismo endpoint de webhook y el mismo constructEvent que los Payment Intents:

const event = orcarail.webhooks.constructEvent(
  rawBody,
  req.headers['x-webhook-signature'],
  process.env.ORCARAIL_WEBHOOK_SECRET!
)

switch (event.type) {
  case 'subscription.created':
    console.log('Subscription created:', event.data.object.id)
    break
  case 'subscription.payment_link.paid':
    console.log('Cycle paid:', event.data.object.id)
    break
  case 'subscription.canceled':
    console.log('Canceled:', event.data.object.id)
    break
  case 'subscription.past_due':
    console.log('Past due:', event.data.object.id)
    break
  // ... other subscription.* types
}

SDK de PHP​

El SDK de PHP expone las mismas operaciones en $orcarail->subscriptions, con parámetros como arrays asociativos y respuestas OrcaRailObject. Para listar se usa all() en lugar de list(), porque list es una palabra reservada de PHP.

use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

$subscription = $orcarail->subscriptions->create([
    'description' => 'Monthly Pro Plan',
    'amount' => '10.00',
    'currency' => 'usd',
    'token_id' => $tokenId,
    'network_id' => $networkId,
    'interval' => 'month',
    'interval_count' => 1,
    'collection_method' => 'send_payment_link',
    'total_cycles' => 12,
    'payer_email' => '[email protected]',
    'metadata' => ['plan_id' => 'pro_monthly'],
]);

echo $subscription->id;
echo $subscription->latest_payment_link?->link;

$page = $orcarail->subscriptions->all(['status' => 'active', 'limit' => 20]);
foreach ($page->data as $sub) {
    echo $sub->id . ' ' . $sub->current_period_end . PHP_EOL;
}

$orcarail->subscriptions->retrieve($subscription->id);
$orcarail->subscriptions->update($subscription->id, ['cancel_at_period_end' => true]);
$orcarail->subscriptions->cancel($subscription->id, [
    'cancellation_details' => ['comment' => 'Switching to annual', 'feedback' => 'other'],
]);
$orcarail->subscriptions->resume($subscription->id);
$orcarail->subscriptions->listPaymentLinks($subscription->id, ['limit' => 10]);

Los webhooks de suscripción usan el mismo helper estático que los Payment Intents:

$event = \OrcaRail\Webhook::constructEvent(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
    getenv('ORCARAIL_WEBHOOK_SECRET'),
);

if ($event->type === 'subscription.payment_link.paid') {
    // credit the cycle for $event->data->object->id
}

Consulta la referencia de la API del SDK de PHP para ver todos los parámetros y formas de retorno.

Tipos (TypeScript)​

El SDK exporta tipos de suscripción alineados con la API:

  • Subscription: objeto de suscripción completo
  • SubscriptionCreateParams: payload de creación
  • SubscriptionUpdateParams: payload de actualización
  • SubscriptionCancelParams: payload de cancelación
  • SubscriptionStatus, SubscriptionInterval, SubscriptionCollectionMethod: enums

Consulta la referencia de la API del SDK de Node para ver las definiciones de tipos completas.

Próximos pasos​