Informações do Plano

Rotas para consultar a assinatura do usuário autenticado e o consumo do plano de uma organização. Quando a requisição usa uma chave de API, o usuário é quem criou a chave.

---

Assinatura ativa

Retorna a assinatura ativa do usuário autenticado.

Requisição

GET /v1/subscriptions/me/active

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Bearer {token}

Parâmetros

Nenhum parâmetro necessário.

Exemplo de requisição

curl -X GET \
  https://api.tapsign.com.br/v1/subscriptions/me/active \
  -H "Authorization: Bearer {token}"

Resposta

200 - Sucesso

{
  "id": 321,
  "userId": 1001,
  "stripeSubscriptionId": "sub_1Q2w3E4r5T6y7U8i",
  "stripeCustomerId": "cus_Q2w3E4r5T6y7U8",
  "planType": "TEAM_160",
  "billingInterval": "MONTHLY",
  "status": "ACTIVE",
  "currentPeriodStart": "2026-09-01T00:00:00Z",
  "currentPeriodEnd": "2026-10-01T00:00:00Z",
  "cancelAtPeriodEnd": false,
  "canceledAt": null,
  "cancellationReason": null,
  "trialStart": null,
  "trialEnd": null,
  "isActive": true,
  "isOnTrial": false,
  "isExpiringSoon": false,
  "daysUntilRenewal": 18,
  "createdAt": "2026-08-01T10:30:00Z",
  "pendingPlanType": null,
  "pendingBillingInterval": null
}

Campos da resposta

Campo	Tipo	Descrição
id	integer	ID da assinatura
userId	integer	ID do usuário dono da assinatura
stripeSubscriptionId	string | null	ID da assinatura no provedor de pagamento
stripeCustomerId	string | null	ID do cliente no provedor de pagamento
planType	string	Plano: FREE, PRO, PRO_80, PRO_160, PRO_UNLIMITED, TEAM_80, TEAM_160, TEAM_400 ou ENTERPRISE
billingInterval	string	Ciclo de cobrança: MONTHLY ou YEARLY
status	string	ACTIVE, TRIALING, PAST_DUE, UNPAID, CANCELED, INCOMPLETE, INCOMPLETE_EXPIRED ou EXPIRED
currentPeriodStart	string | null	Início do período atual (ISO 8601, UTC)
currentPeriodEnd	string | null	Fim do período atual (ISO 8601, UTC)
cancelAtPeriodEnd	boolean	Se o cancelamento está agendado para o fim do período
canceledAt	string | null	Data do cancelamento
cancellationReason	string | null	Motivo informado no cancelamento
trialStart	string | null	Início do período de teste
trialEnd	string | null	Fim do período de teste
isActive	boolean	true quando o status é ACTIVE ou TRIALING
isOnTrial	boolean	true quando o status é TRIALING e trialEnd ainda não passou
isExpiringSoon	boolean	true quando currentPeriodEnd cai nos próximos 7 dias
daysUntilRenewal	integer	Dias inteiros até currentPeriodEnd
createdAt	string	Data de criação da assinatura (ISO 8601, UTC)
pendingPlanType	string | null	Sempre null nesta rota. Veja GET /v1/subscriptions/me abaixo.
pendingBillingInterval	string | null	Sempre null nesta rota. Veja GET /v1/subscriptions/me abaixo.

Sem assinatura ativa

Esta rota só considera assinaturas com status ACTIVE ou TRIALING sem cancelamento agendado. Quando não encontra nenhuma, responde 200 OK com o corpo vazio. Corpo vazio indica apenas que não há assinatura de cobrança nessas condições.

Assinatura atual

GET /v1/subscriptions/me

Retorna o mesmo objeto, buscando nesta ordem: a assinatura ativa sem cancelamento agendado; se não houver, a assinatura ACTIVE ou TRIALING mesmo com cancelamento agendado; se não houver, a assinatura mais recente do usuário, em qualquer status. Nesta rota, pendingPlanType e pendingBillingInterval trazem o plano e o ciclo de uma troca de plano pendente, quando existir. Sem nenhuma assinatura, responde 200 OK com o corpo vazio.

---

Uso do plano da organização

Retorna os limites do plano e o consumo do mês corrente de uma organização. Os limites vêm do plano do proprietário da organização.

Permissão necessária: MEMBERS:READ (veja Papéis e Permissões)

Requisição

GET /v1/organizations/{orgId}/plan-usage

Parâmetro	Tipo	Obrigatório	Descrição
orgId	integer	Sim	ID da organização (obtido em Listar Organizações)

Exemplo de requisição

curl -X GET \
  https://api.tapsign.com.br/v1/organizations/42/plan-usage \
  -H "Authorization: Bearer {token}"

200 - Sucesso

{
  "maxSignatures": -1,
  "signaturesUsed": 37,
  "maxEnvelopes": 160,
  "envelopesUsed": 42
}

Campo	Tipo	Descrição
maxSignatures	integer | null	Limite de assinaturas do plano. null ou valor negativo indica sem limite.
signaturesUsed	integer	Assinaturas feitas em documentos da organização no mês corrente
maxEnvelopes	integer | null	Limite de documentos (envelopes) por mês do plano. null ou valor negativo indica sem limite.
envelopesUsed	integer	Envelopes criados pela organização no mês corrente. O contador não diminui quando um envelope vai para a lixeira ou é excluído.

Plano e API

A criação de chaves de API e a emissão de tokens pela API exigem plano Equipe ou Enterprise. Veja Autenticação.

---

Erros comuns

Código	Quando acontece
401	Token ausente, inválido ou chave de API desativada
403	Em plan-usage: o usuário não é membro ativo da organização ou não tem MEMBERS:READ

O formato do corpo de erro está em Status de Erros.