Referência da API

Auth: Authorization: Bearer <tenant_api_key>. Lista as assinaturas do cliente (identificado por external_id OU email) que não estão canceled, cada uma com os entitlements do plano, e devolve merged_entitlements: a união das capacidades das assinaturas active, trialing e past_due (uma suspended aparece na lista mas não soma). Os entitlements vêm sempre do catálogo atual: editar o plano reflete aqui na hora. Cliente inexistente = 200 com customer_id: null (nunca 404). Informe external_id (preferido; email em query vira log). Um dos dois é obrigatório (400 sem nenhum).

Auth: Authorization: Bearer <tenant_api_key>. TODAS as assinaturas do tenant, em lotes. Filtros opcionais: status (um ou vários por vírgula) e offer_id. Pagine até next vir null: pegue next, mande em ?after=, repita. Keyset (id ULID = cronológico), aguenta bases grandes sem degradar. Mesmo shape do webhook e do GET /v1/subscriptions/{id}, sem last_payment/tracking (omitidos nas listas). Não há POST: a assinatura nasce só no checkout.

Auth: Authorization: Bearer <tenant_api_key>. O estado ATUAL da assinatura por id — em QUALQUER status (canceled/suspended inclusive), para o sistema reconciliar quando perde um webhook. Mesmo shape do webhook (subscription_event_payload). O receptor decide por status, nunca pela presença de entitlements. 404 se é de outro tenant ou não existe (indistinguíveis por design).

Auth: Authorization: Bearer <tenant_api_key> com scope write (liberado mesmo com a conta em modo só leitura). Dois modos:

• Imediato (padrão): a assinatura vai para o estado TERMINAL canceled. RECUSA (422) enquanto houver um QR Pix pagável (cancelar às cegas arriscaria o cliente pagar sobre uma assinatura terminal). Idempotente: já cancelada devolve 200.
• No fim do período (at_period_end: true): AGENDA o cancelamento — o acesso continua até o fim do período pago e o billing run não renova. É REVERSÍVEL por POST /v1/subscriptions/{id}/cancel/undo enquanto a assinatura segue viva. Só active, trialing e past_due agendam; um teste SEM cartão (sem próxima cobrança) não tem fim de período e é cancelado na hora (resposta {status: canceled}).

reason opcional (≤300) vai ao e-mail de cancelamento. 404 se é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key> com scope write. Cancela a troca de plano agendada; a assinatura volta sem pending_offer. 422 se não há troca agendada; 404 se a assinatura é de outro tenant/inexistente.

Auth: Authorization: Bearer <tenant_api_key> com scope write. Desfaz o cancelamento AGENDADO (at_period_end) — a assinatura volta a renovar normalmente. Só vale enquanto está agendado e a assinatura segue viva (NÃO ressuscita uma já canceled, nem afeta um cancelamento imediato). Emite subscription.updated. 422 se não há cancelamento agendado; 404 se é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key> com scope write. Troca a assinatura (só active ou trialing) para a offer_id alvo (offer_01...). Mesmo intervalo: mais caro = upgrade IMEDIATO com a proração cobrada no cartão salvo; mesmo preço = troca imediata sem cobrar; mais barato = AGENDADO para o fim do período (veja pending_offer). Intervalo diferente: se o valor anualizado sobe, a troca é imediata (mensal para anual cobra o anual menos o crédito do período; anual para mensal vira tempo de crédito, sem cobrar); se cai ou empata, é agendada. Trocas que cobram exigem cartão salvo: numa assinatura Pix elas são agendadas. Proração abaixo do mínimo do gateway: a troca é aplicada sem cobrar. Oferta de outro gateway: gera um link de pagamento no gateway novo (o cartão salvo não atravessa gateways). 400 sem offer_id; 404 se a sub ou a oferta são de outro tenant/inexistentes; 422 se a troca é inválida ({"error": "..."}).

Auth: Authorization: Bearer <tenant_api_key> com scope write. Roda AGORA o billing run desta assinatura, sem esperar a passada diária. Ele só cobra o que já VENCEU (next_billing_at no passado; numa assinatura Pix, emite o QR a partir de 3 dias antes): não antecipa um ciclo futuro, não encerra um teste antes da hora e não adianta a próxima tentativa da régua. Quando cobra, é no cartão salvo (Pix: emite o QR). Diferente do painel, que nunca cobra o cartão (gera link de pagamento), a API cobra direto. A anti-cobrança-dupla/idempotência é do próprio billing run: chamar duas vezes NÃO cobra duas vezes. Responde 202 (enfileirado; não quer dizer que houve cobrança, acompanhe pelos webhooks invoice.paid/invoice.payment_failed). 404 se é de outro tenant ou não existe. 409 se a assinatura não está numa situação cobrável (só active, trialing e past_due são; o corpo traz o status atual) ou se as renovações da conta estão pausadas.

Auth: Authorization: Bearer <tenant_api_key>. Os eventos que o GATEWAY respondeu nas cobranças desta assinatura (aprovação/recusa/estorno/chargeback) — feature B. Sem PII nem segredo. Teto de 200 eventos (apps/gateways/queries.py); sem paginação (uma sub tem poucos eventos). 404 se é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key>. O link público de pagamento da fatura EM ABERTO desta assinatura (feature C), para o sistema distribuir ao cliente. NUNCA expõe id de invoice/assinatura. 404 se é de outro tenant ou não existe; 409 se não há fatura em aberto ({"error": "nenhuma fatura em aberto"}).

Auth: Authorization: Bearer <tenant_api_key>. Gera um link OPACO que o cliente abre para trocar o CARTÃO (ou Pix↔cartão, se a oferta permitir) — SEM cobrança. Use no botão 'alterar forma de pagamento' da área de assinatura do seu app. Expira em 7 dias, SINGLE-USE. Scope write. No Asaas o cartão só é capturado na página hospedada de um pagamento: a troca para um cartão novo acontece ao pagar uma fatura. 404 se é de outro tenant ou não existe; 409 se a assinatura está canceled/pending_first_payment ou em teste sem cartão.

Auth: Authorization: Bearer <tenant_api_key> com scope write. Os ciclos FUTUROS deixam de ser descontados; o registro da venda permanece (só para de afetar a renovação). Devolve quantos resgates foram desativados. 404 se é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key>. Gera um link de renovação da assinatura (o cliente abre e paga, e o período é ESTENDIDO). Renova sempre a PRÓPRIA oferta da assinatura: offer_id é opcional e, se enviado, tem de ser a oferta atual (para mudar de plano use change-plan). price_cents opcional (inteiro ≥ 1; cortesia/100% off NÃO é suportada); sem ele, o preço é o do próximo ciclo já com o cupom ativo. Expira em 7 dias. Scope write. 404 se é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key> com scope write. Move a próxima cobrança (= fim do ciclo atual) para next_billing_at (ISO 8601, no FUTURO). NÃO cobra — só muda QUANDO cobra; a cadência passa a seguir a nova data. Emite subscription.updated. 400 se a data é inválida (code: data_invalida) ou passada (data_passada); 404 se é de outro tenant; 422 se o status não permite (status); 409 se há uma cobrança/QR Pix em aberto neste ciclo (fatura_em_voo).

Auth: Authorization: Bearer <tenant_api_key> com scope write. Edita os campos INFORMADOS (nome/e-mail/telefone; null/ausente = não mexe) do cliente (por external_id): local + sync no gateway (e-mail, nome e telefone) + AuditLog. doc e external_id NÃO são editáveis (identidade fiscal / chave da integração). O cadastro precisa terminar com um celular válido: phone em formato internacional E.164 (ex.: +5511999999999; número brasileiro sem + vira +55). Cliente antigo sem telefone: qualquer edição exige informar um. 404 se é de outro tenant ou não existe; 422 se o e-mail é inválido/em uso, o telefone é inválido ou falta o celular.

Auth: Authorization: Bearer <tenant_api_key> com scope write. Atualiza o e-mail do cliente (por external_id): local + sync no gateway + AuditLog (a MESMA regra do painel). 404 se é de outro tenant ou não existe; 422 se o e-mail é inválido ({"error": "..."}).

Auth: Authorization: Bearer <tenant_api_key>. Os pagamentos do cliente (por external_id), recorrentes e avulsos, em lotes. Pagine até next vir null: pegue next, mande em ?after=, repita. Keyset (ordenado por id ULID = cronológico) — aguenta históricos longos sem degradar. 404 se o cliente não existe.

Auth: Authorization: Bearer <tenant_api_key>. Todas as assinaturas do cliente (por external_id), em QUALQUER status (inclusive canceled) — o receptor decide por status, nunca pela presença de entitlements. Mesmo shape do webhook e do GET /v1/subscriptions/{id}, sem last_payment/tracking (omitidos nas listas). 404 se o cliente é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key>. O pagamento por id, com a decomposição em itens (plano/bump/juros) e o estado de estorno. 404 se é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key> com scope write (liberado mesmo com a conta em modo só leitura). Estorna o Payment (por id). reason é OBRIGATÓRIO (≤300). amount_cents em centavos (parcial = menor que o pago; Pix só aceita estorno TOTAL, e um segundo estorno parcial na mesma cobrança só vale nos gateways que somam estornos: Stone/Pagar.me e Stripe). revoke: subscription (cancela a assinatura) | grant (revoga a concessão do pedido) | none (só devolve o dinheiro). Se OMITIDO, o padrão é REVOGAR o acesso apropriado ao pagamento (fatura → cancela a assinatura; pedido → revoga a concessão) — mande revoke:"none" para só devolver sem revogar. Se o estorno desfizer uma extensão/renovação, o tempo concedido é REVERTIDO automaticamente. Anti-2x embutido (o serviço nunca estorna duas vezes). 404 se o pagamento é de outro tenant ou não existe.

Auth: Authorization: Bearer <tenant_api_key>. A 2ª via / re-acesso ao QR Pix de um pedido pendente — compra avulsa OU adiantamento de renovação —, para o sistema reenviar ao cliente pagar. Reusa Order.access_token; NUNCA expõe o id do pedido. 404 se é de outro tenant ou não existe; 409 se não há Pix pendente para reabrir ({"error": "pedido sem Pix pendente para reabrir"}).

Auth: Authorization: Bearer <tenant_api_key>. Get-ou-create do código estável do cliente-indicador + a recompensa configurada e o progresso das indicações. Informe external_id OU email (400 sem nenhum). {active:false} se o tenant não tem programa de indicação ativo; 404 se o cliente não existe.

Auth: Authorization: Bearer <tenant_api_key> com scope write (cria o link, um documento pagável). Devolve (cria-ou-obtém, idempotente) o link de renovação daquele cliente na campanha — use no botão 'antecipar renovação' do seu app. 400 sem external_id; 404 se a campanha não existe ou está inativa, se o cliente não existe ou se ele não está no público da campanha.

Auth: Authorization: Bearer <tenant_api_key>. Puxa os links já gerados, em lotes. Pagine até next vir null: pegue next, mande em ?after=, repita. Keyset (não offset) — aguenta centenas de milhares sem degradar. Leitura (qualquer scope). 400 se o cursor after é inválido; 404 se a campanha não existe.