Guia de Assinaturas

Confira o guia de assinaturas para mais informações.

Endpoint responsável por recuperar os dados de uma assinatura específica cadastrada no Asaas.

Esse recurso permite consultar as informações atuais da assinatura, como forma de pagamento, periodicidade, valor, status, datas e demais configurações utilizadas para gerar as cobranças recorrentes.

A consulta é realizada utilizando o identificador único (id) retornado no momento da criação da assinatura.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• consultar os detalhes de uma assinatura específica;
• verificar o status atual de uma recorrência;
• validar informações antes de atualizar ou remover uma assinatura;
• sincronizar dados entre o Asaas e seu sistema;
• exibir informações detalhadas da assinatura em telas administrativas.

Caso seja necessário consultar várias assinaturas simultaneamente, utilize o endpoint Listar assinaturas.

Parâmetro importante

Este endpoint utiliza apenas um parâmetro obrigatório:

• id — identificador único da assinatura no Asaas.

Esse identificador é retornado pela API durante a criação da assinatura e deve ser armazenado pela sua aplicação para consultas futuras.

Como funciona

Após receber uma requisição válida, o Asaas localiza a assinatura correspondente ao identificador informado e retorna seu estado mais recente.

A consulta não altera nenhuma informação da assinatura nem gera novas cobranças.

Fluxo simplificado:

Criar assinatura
        ↓
Armazenar ID da assinatura
        ↓
Consultar assinatura
        ↓
Recuperar dados atualizados

Comportamentos importantes

Ao utilizar este endpoint, considere que:

• apenas assinaturas pertencentes à conta autenticada poderão ser consultadas;
• a consulta retorna o estado atual da assinatura no momento da requisição;
• este endpoint não retorna a lista de cobranças geradas pela assinatura;
• alterações realizadas anteriormente serão refletidas na resposta da consulta.

Boas práticas

Erros comuns

400 Bad Request

Pode ocorrer quando o identificador informado possui formato inválido.

401 Unauthorized

Ocorre quando a API Key é inválida ou não foi informada.

403 Forbidden

Pode ocorrer quando uma requisição GET é enviada com body preenchido.

404 Not Found

Ocorre quando o identificador informado não existe ou não pertence à conta autenticada pela API Key utilizada.

Impactos operacionais

A recuperação de uma assinatura é uma operação exclusivamente de consulta.

Ela não altera cobranças existentes, não modifica o ciclo da recorrência e não gera novos pagamentos, sendo indicada para sincronização de dados, validações e consultas administrativas.

Conteúdos relacionados

• Criar assinatura
• Listar assinaturas
• Atualizar assinatura
• Remover assinatura
• Listar cobranças de uma assinatura
• Webhooks de assinatura