Consultar assinatura

A Allya Payments expõe duas formas de consultar uma assinatura já criada:

• GET /v1/subscriptions/:id: busca pelo ID interno retornado em POST /v1/subscriptions.
• GET /v1/subscriptions?externalId=...: busca pelo identificador do seu sistema (idempotência).

Ambas usam a mesma autenticação por API key e ficam escopadas ao ambiente da chave: uma chave sk_test_ só lê assinaturas de sandbox, e sk_live_ só lê assinaturas de produção.

A resposta tem o mesmo formato de POST /v1/subscriptions: veja Criar assinatura para o esquema completo.

O bloco customer retorna name, email e documentLast4. A Allya não retorna CPF/CNPJ completo porque o documento é persistido apenas como hash + últimos 4 dígitos.

Buscar por ID interno

const response = await fetch(
  `https://payments-api.allyasolutions.com/v1/subscriptions/${subscriptionId}`,
  {
    headers: { Authorization: `Bearer ${process.env.ALLYA_API_KEY}` },
  },
);

if (response.status === 404) {
  // Assinatura não existe nesse ambiente.
}

const subscription = await response.json();
console.log(subscription.status); // "trialing", "active", "past_due", "canceled"

Buscar por externalId

Útil para reconciliação quando seu sistema só persistiu o externalId e não o id interno da Allya, ou para conferir se uma assinatura já foi criada antes de tentar de novo.

const response = await fetch(
  `https://payments-api.allyasolutions.com/v1/subscriptions?externalId=${encodeURIComponent("plano-pro-12345")}`,
  {
    headers: { Authorization: `Bearer ${process.env.ALLYA_API_KEY}` },
  },
);

if (response.status === 404) {
  // Nenhuma assinatura com esse externalId neste ambiente.
}

const subscription = await response.json();

Códigos de resposta

Diferenças entre as duas formas

Observações

• A consulta não chama o gateway: devolve apenas o que está persistido na Allya. O estado é atualizado via webhooks (subscription.created, subscription.renewed, subscription.payment_failed, subscription.past_due, subscription.canceled). Veja Webhooks.
• Não há rota de sync para assinaturas. A reconciliação acontece pelo recebimento dos webhooks dos gateways. Se um webhook deixou de chegar e o status no painel diverge do gateway, consulte o status diretamente no painel do provedor enquanto o reenvio não chega.
• Para histórico de eventos da assinatura, use o painel em Assinaturas → detalhe.