Assinaturas

Dados da API

API Gateway
Esta API é utilizada para operações do gateway de pagamento:

• Produção: https://api.sopague.com.br/gateway
• Homologação: https://api-hmg.sopague.com.br/gateway
• Arquitetura: Representational State Transfer (REST)

Introdução

A assinatura de serviços e/ou produtos é uma forma muito utilizada pelas empresas para a fidelização do cliente. Por exemplo, uma revista de moda ou decoração oferece uma assinatura mensal, trimestral ou anual. Logo, o cliente irá receber o produto, no caso a revista, todos os meses ou a cada edição. E toda assinatura é associada a um plano.

---

Criar Assinatura

Para criar uma assinatura é necessário enviar uma requisição utilizando o método POST para o recurso conforme o exemplo:

POST /v1/recurrence/subscription

Observações

• É possível que o cliente tenha credenciais distintas para Gateway e Recorrência. Verifique se suas credenciais são distintas.
• Para criação do vaultId favor acessar a documentação do gateway sobre Cofre no link Cofre.

Via request Representational State Transfer (REST) com o body:

Requisição

{
  "vaultId": "e7fa5a01-90a9-4abc-9bac-d9dbfa7db587",
  "orderNumber": "1234567890",
  "planId": "e776ab3b-4698-4afa-97d4-a621d70c4a11"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
VaultId	Identificador do cofre	string	body	sim	36
OrderNumber	Número da Ordem de Serviço ou Pedido	string	body	sim	10
PlanId	Identificador do plano	string	body	sim	36

🟢 200

Assinatura criada com sucesso

"937d0108-c54c-44f5-9ddc-acdb3dd94cc6"

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
SubscriptionId	Identificador da assinatura criada.	string

🔴 400

Erro na requisição

[
  {
    "tag": "VaultId",
    "description": "Cofre não encontrado"
  }
]

🔴 500

Erro interno

[
  {
    "tag": "",
    "description": "Não foi possível executar comando. Erro desconhecido."
  }
]

---

Buscar Assinaturas

Para buscar as assinaturas é necessário enviar uma requisição utilizando o método GET para o recurso conforme o exemplo:

GET /v1/recurrence/subscription?planName={planName}&status={status}&orderBy={orderBy}&page={page}&limit={limit}

Dicionário de dados - Query Parameters

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO
PlanName	Nome do Plano	string	query params	não
Status	Status do plano	string	query params	não
OrderBy	Ordenação do resultado	string	query params	não
Page	Número da página	integer	query params	não
Limit	Limite de itens por página	integer	query params	não

🟢 200

Assinaturas encontradas

{
  "items": [
    {
      "vaultId": "fc3c5589-24b1-4bca-b8ab-e57b100c44cd",
      "orderNumber": "1234567890",
      "status": "Active",
      "plan": {
        "merchantId": "01700555550000",
        "name": "PLANO CUSTOM DO SEU ZÉ",
        "description": "PLANO DE RECORRÊNCIA EM 5X",
        "amount": 31.000000,
        "planType": "Custom",
        "trialDays": 0,
        "paymentMethod": "CreditCard",
        "interval": 30,
        "installments": 5,
        "status": "Active",
        "attempts": 0,
        "id": "cef858c4-d0c6-4f27-b009-c303121f3b6e",
        "createdDate": "2020-04-14T12:21:23.337"
      },
      "id": "013c7ec4-62c1-4d78-859d-e8d2a11f681d",
      "createdDate": "2020-03-19T15:09:12.203"
    },
    {
      "vaultId": "3a203c6b-553f-4a7c-9cc4-e30897966c2e",
      "orderNumber": "1404202015",
      "status": "Blocked",
      "plan": {
        "merchantId": "017005555500000",
        "name": "plano - Mensal 1",
        "description": "plano - Mensal 1",
        "amount": 29.990000,
        "planType": "Monthly",
        "trialDays": 1,
        "paymentMethod": "CreditCard",
        "interval": 30,
        "installments": 1,
        "status": "Active",
        "attempts": 0,
        "id": "fc7f49da-0510-4884-9cad-ae3e0b2488d9",
        "createdDate": "2020-04-14T12:21:23.337"
      },
      "id": "0405507a-c8d5-440d-bb83-80e45f24b35f",
      "createdBy": "[email protected]",
      "createdDate": "2020-04-14T15:45:04.73"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 41
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
VaultId	Identificador do cofre	string
OrderNumber	Número da Ordem de Serviço ou Pedido	string
Status	Status da assinatura	string
Id	Identificador da assinatura	string
CreatedBy	Usuário responsável pela criação da assinatura.	string
CreatedDate	Data e hora da criação da assinatura	datetime
Plan.MerchantId	Identificador do estabelecimento	string
Plan.Name	Nome do Plano	string
Plan.Description	Descrição do plano	string
Plan.Amount	Valor parcelas do plano	decimal
Plan.PlanType	Tipo do plano	string
Plan.TrialDays	Número de dias em degustação	integer
Plan.PaymentMethod	Método de pagamento	string
Plan.Interval	Intervalo em dias entre as cobranças	integer
Plan.Installments	Número de parcelas	integer
Plan.Status	Status do plano	string
Plan.Attempts	Número de tentativas da teimosinha	integer
Plan.Id	Identificador do plano	string
Plan.CreatedDate	Data e hora de criação do plano	datetime
Page	Número da página atual	integer
Limit	Limite de itens por página	integer
Total	Total de itens encontrados	integer

🔴 400

Erro na requisição

[
  {
    "tag": "Query",
    "description": "Parâmetros de consulta inválidos"
  }
]

---

Buscar Assinatura por ID

Para buscar a assinatura por ID é necessário enviar uma requisição utilizando o método GET para o recurso conforme o exemplo:

GET /v1/recurrence/subscription/{subscriptionId}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
SubscriptionId	Identificador da assinatura	string	path	sim	36

🟢 200

Assinatura encontrada

{
  "vaultId": "fc3c5589-24b1-4bca-b8ab-e57b100c44cd",
  "orderNumber": "1234567890",
  "status": "Blocked",
  "plan": {
    "merchantId": "01700555550000",
    "name": "PLANO CUSTOM  DO SEU ZÉ",
    "description": "PLANO DE RECORRÊNCIA EM 5X",
    "amount": 31.000000,
    "planType": "Custom",
    "trialDays": 0,
    "paymentMethod": "CreditCard",
    "interval": 30,
    "installments": 5,
    "status": "Active",
    "attempts": 0,
    "id": "cef858c4-d0c6-4f27-b009-c303121f3b6e",
    "createdDate": "2020-04-14T12:21:23.337"
  },
  "id": "013c7ec4-62c1-4d78-859d-e8d2a11f681d",
  "createdDate": "2020-03-19T15:09:12.203"
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
VaultId	Identificador do cofre	string
OrderNumber	Número da Ordem de Serviço ou Pedido	string
Status	Status da assinatura	string
Id	Identificador da assinatura	string
CreatedDate	Data e hora da criação da assinatura	datetime
Plan.MerchantId	Identificador do estabelecimento	string
Plan.Name	Nome do Plano	string
Plan.Description	Descrição do plano	string
Plan.Amount	Valor parcelas do plano	decimal
Plan.PlanType	Tipo do plano	string
Plan.TrialDays	Número de dias em degustação	integer
Plan.PaymentMethod	Método de pagamento	string
Plan.Interval	Intervalo em dias entre as cobranças	integer
Plan.Installments	Número de parcelas	integer
Plan.Status	Status do plano	string
Plan.Attempts	Número de tentativas da teimosinha	integer
Plan.Id	Identificador do plano	string
Plan.CreatedDate	Data e hora de criação do plano	datetime

🔴 404

Assinatura não encontrada

{
  "error": "Assinatura não encontrada"
}

---

Alterar Status da Assinatura

Para alterar o status da assinatura é necessário enviar uma requisição utilizando o método PUT para o recurso conforme o exemplo:

PUT /v1/recurrence/subscription/{subscriptionId}/status

Via request Representational State Transfer (REST) com o body:

Requisição

{
  "status": "Actived"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
SubscriptionId	Identificador da assinatura a ter o status alterado.	string	path	sim	36
Status	Identificador do status (Actived, Canceled)	string	body	sim	Fixo

🟢 200

Status alterado com sucesso

"0dd23cbd-de75-45a5-b2d1-972191140593"

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
SubscriptionId	Identificador da assinatura que foi atualizada.	string

🔴 400

Erro na requisição

[
  {
    "tag": "Status",
    "description": "Status inválido"
  }
]

---

Alteração de Cofre na Assinatura

Para alterar um cofre da assinatura é necessário enviar uma requisição utilizando o método PUT para o recurso conforme o exemplo:

PUT /v1/recurrence/subscription/{subscriptionId}/vault

Via request Representational State Transfer (REST) com o body:

Requisição

{
  "vaultId": "e954a511-f081-42e1-8531-2c4dcdf9a2cf"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
SubscriptionId	Identificador da assinatura	string	path	sim	36
VaultId	ID do Cofre	string	body	sim	36

🟢 200

Cofre alterado com sucesso

"013c7ec4-62c1-4d78-859d-e8d2a11f681d"

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
SubscriptionId	Identificador da assinatura que foi atualizada.	string

🔴 400

Erro na requisição

[
  {
    "tag": "VaultId",
    "description": "Cofre não encontrado"
  }
]

---

Status das Assinaturas

Status	Descrição
Active	Assinatura ativa e funcionando normalmente
Blocked	Assinatura bloqueada devido a falhas de pagamento
Canceled	Assinatura cancelada pelo usuário ou sistema

---

Para dúvidas ou problemas, acesse a seção de suporte no Cinq.