Uma vez realizado a subscrição o consumidor é cobrado dentro do prazo conforme a periodicidade parametrizada no plano.
Os possíveis status de uma subscrição podem variar conforme a situação:
Criada – A subscrição foi efetivada, porém seu processo de recorrência ainda não foi iniciado.
Vigente – A subscrição está ativa e seu processo de recorrência foi iniciado.
Suspensa – A subscrição foi temporariamente interrompida, geralmente por falha no pagamento desacordo comercial.
Cancelada – A subscrição foi encerrada pelo usuário ou pelo serviço, mas pode continuar válida até o fim do ciclo atual.
Expirada ou Encerrada – O período da subscrição terminou e não foi renovado.
Reativada – A subscrição foi cancelada ou suspensa anteriormente, mas foi reativada pelo usuário.
API Subscrição
Na API de subscrição é possível realizar a subscrição dos planos com itens associados e assinatura customizada vinculado somente os itens.
API Subscrição Pause
Na API de subscrição Pause é possível realizar a pausa das cobranças por um período definido conforme parametrização.
API Customer
Na API de Customer é utilizado para realizar o cadastro do cliente, podendo reutilizar o registro para outras subscrições.
Criando um Customer (POST)
Com base na rota do Customer (POST /api/v1/customers), utilizar o payload abaixo:
"code": "Informar o código",
"organizationId": "Informar o Id da Organização",
"organizationIntegrationId": "T1|D MG 01",
"reference": "Informar a referencia",
"name": "Informar o nome",
"typeDocument": "1", 1 para CPF, 2 para CNPJ
"documentNumber": "CPF ou CNPJ",
"stateRegistration": "000.000.000.000",
"cityRegistration": "000000-0",
"integrationId": "Informar a Integração associado",
"status": "1",
"addresses": [
{
"type": "1",
"street": "Campo Obrigatório",
"number": "Campo Obrigatório",
"complement": "Campo Obrigatório",
"district": "Campo Obrigatório",
"zipCode": "Campo Obrigatório",
"cityName": "Campo Obrigatório",
"stateInitials": "Campo Obrigatório",
"stateName": "Campo Obrigatório",
"countryName": "BR"
}
],
"EMAILS": [
{
"TYPE": "1",
"EMAILADDRESS": "Campo Obrigatório"
}
],
"phones": [
{
"type": "1",
"countryCode": "Campo Obrigatório",
"areaCode": "Campo Obrigatório",
"number": "Campo Obrigatório",
"extension": "2666"
}
],
"birthDate": "Campo Obrigatório"
}
Response:
API Subscrição Cancelado
Na API Subscrição Cancelado podemos utilizar a API para cancelar uma subscrição a partir de uma data especifica. Uma vez cancelado será necessário criar outra subscrição.
Subscrição com dados de pagamento
O método de de subscrição permite que seja registrada informações para a realização de uma adesão contendo informações do cliente e Cartão Tokenizado.
Pré-requisitos:
Ordem das execuções:
Esse método permite registrar as informações do cliente para que seja associado na subscrição nova ou já registrado.
Parâmetros de Entrada
{
"code": "123456", //Identificador do cliente
"reference": "00010020", //Id código externo
"name": "TOTVs", //Nome do cliente
"typeDocument": "1 = NaturalPerson", //Tipo de documento 1=NaturalPerson;2=LegalPerson
"documentNumber": "308540", //Número do documento
"status": "1 = Active",
"addresses": [
{
"type": "1 = Home", //Tipo de endereço 1=Home;2=Business;3=Billing
"street": "Rua Dom Pedro I", //Endereço
"number": "100", //Número
"complement": "Bloco B", // Complemento
"district": "Bairro Jardim", //Bairro
"zipCode": "00000-000", //CEP
"cityName": "São Paulo", //Cidade
"stateInitials": "SP", //Estado
"stateName": "São Paulo", //Nome Estado
"countryName": "Brasil" //País
}
],
"emails": [
{
"type": "1 = Personal", // Tipo de pessoa 1=Personal;2=Work;3=Home;4=Business;5=Billing
"emailAddress": "[email protected]" //email de contato
}
],
"phones": [
{
"type": "1 = Home", //Tipo 1=Home;2=Business;3=CellPhone
"countryCode": "+55", //Código do país
"areaCode": "11", //Código da area
"number": "(11)91111-1111", //Número
"extension": "2666" //Ramal
}
],
"birthDate": "01/01/2001", //Data de nascimento
}
Parâmetros de Saída
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"integrationId": "T1|D MG 01|0021878",
"code": "123456",
"organizationId": "9495d9da-33be-4634-a67e-22eced59274d",
"organizationIntegrationId": "T1|D MG 01",
"reference": "00010020",
"name": "TOTVs",
"typeDocument": "1 = NaturalPerson",
"documentNumber": "308540",
"stateRegistration": "000.000.000.000",
"cityRegistration": "000000-0",
"status": "1 = Active",
"birthDate": "01/01/2001",
"isActive": true
}
Parâmetros de Entrada
https://api-recorrencia.staging.totvs.app/api/v1/customers/{id}
Parâmetros de Saída
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"integrationId": "T1|D MG 01|0021878",
"code": "123456",
"organizationId": "9495d9da-33be-4634-a67e-22eced59274d",
"organizationIntegrationId": "T1|D MG 01",
"reference": "00010020",
"name": "TOTVs",
"typeDocument": "1 = NaturalPerson",
"documentNumber": "308540",
"stateRegistration": "000.000.000.000",
"cityRegistration": "000000-0",
"status": "1 = Active",
"birthDate": "01/01/2001",
"isActive": true
}
Documentação
Para uma listagem completa da saída por favor verifique a documentação Swagger.
Esse método permite realizar a subscrição contendo um cartão tokenizado.
Parâmetros de Entrada
Obs.: inserir o id armazenado do cartão tokenizado no campo "paymentTokenId": "59f975c5-6c5e-43ff-8da3-07b21afbccbc"
{
"OrganizationIntegrationId":"010000091777", // Código de integração de uma organization
"organizationId": "92cb23af-08cf-4063-a7a8-4218ae5fef06", //Código da organization
"customerId": "021eb296-b80e-4c5e-bdfb-4131459b3704", //Customer a ser utilizado
"reference": "RK07022023", // Código de referência
"name": "Subscrição Swagger TOTVS", //Nome da adesão
"currencyId": "bbff1352-0256-4ac9-8aaa-df0f619f3d37", //Moeda
"planId": "d0cb3401-a69a-49c5-982a-56519175573d", //Codigo do plano associado
"planVersionId": 1,
"creationDate": "2023-02-10", //Data da Criação
"subscriptionAccession": "2023-02-10", //Data da adesão
"tastingDays": 0, //Dias de degustação
"billingCycleStartAt": "2023-02-10", //Inicio do ciclo da cobrança
"subscriptionStart": "2024-02-10", //Inicio da assinatura
"subscriptionEnd": "", //Fim da assinatura
"description": "Swagger TOTVS", //Campo descrição
"paymentTokenId": "59f975c5-6c5e-43ff-8da3-07b21afbccbc" //Código tokenizado
}
Parâmetros de Saída
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"integrationId": "T1|D MG 01|0021878",
"organizationId": "9495d9da-33be-4634-a67e-22eced59274d",
"organizationIntegrationId": "T1|D MG 01",
"name": "Nome",
"customerId": "9495d9da-33be-4634-a67e-22eced59274d",
"customerIntegrationId": "A00003",
"addressId": "9495d9da-33be-4634-a67e-22eced59274d",
"emailId": "9495d9da-33be-4634-a67e-22eced59274d",
"phoneId": "9495d9da-33be-4634-a67e-22eced59274d",
"currencyId": "9495d9da-33be-4634-a67e-22eced59274d",
"planId": "9495d9da-33be-4634-a67e-22eced59274d",
"planIntegrationId": "T1|D MG 01|0021878",
"planReference": "112233",
"planVersionId": 1,
"creationDate": "2022-04-06",
"subscriptionAccession": "2022-04-06",
"tastingDays": 1,
"billingCycleStartAt": "2022-04-06",
"subscriptionStart": "2022-04-06",
"subscriptionEnd": "2022-04-06",
"description": "campo de descrição",
"paymentMethods": [
{
"paymentMethod": "0 = None",
"paymentMethodDescription": "string"
}
],
"paymentTokenId": "59f975c5-6c5e-43ff-8da3-07b21afbccbc",
"reference": "112233",
"cancellationDate": "2022-04-06",
"chargeEach": 1,
"period": "1 = Day",
"numberOfTimes": 1,
"chargeType": "1 = WithSpecificDay",
"specificDay": 1,
"quantityDay": 1,
"referenceDay": "1 = DaysBefore",
"referencePeriod": "1 = StartOfPeriod",
"origin": "Origem",
"customer": {
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"integrationId": "T1|D MG 01|0021878",
"code": "123456",
"organizationId": "9495d9da-33be-4634-a67e-22eced59274d",
"organizationIntegrationId": "T1|D MG 01",
"reference": "00010020",
"name": "TOTVs",
"typeDocument": "1 = NaturalPerson",
"documentNumber": "308540",
"stateRegistration": "000.000.000.000",
"cityRegistration": "000000-0",
"status": "1 = Active",
"birthDate": "01/01/2001",
"addresses": [
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"type": "1 = Home",
"street": "Rua Dom Pedro I",
"number": "100",
"complement": "Bloco B",
"district": "Bairro Jardim",
"zipCode": "00000-000",
"cityName": "São Paulo",
"stateInitials": "SP",
"stateName": "São Paulo",
"countryName": "Brasil",
"isActive": true
}
],
"emails": [
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"type": "1 = Personal",
"emailAddress": "[email protected]",
"isActive": true
}
],
"phones": [
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"type": "1 = Home",
"countryCode": "+55",
"areaCode": "11",
"number": "91122-3344",
"extension": "2666",
"isActive": true
}
],
"isActive": true
},
"items": [
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"subscriptionId": "9495d9da-33be-4634-a67e-22eced59274d",
"planItemId": "9495d9da-33be-4634-a67e-22eced59274d",
"itemId": "9495d9da-33be-4634-a67e-22eced59274d",
"itemIntegrationId": "T1|D MG 01|0021878",
"integrationId": "T1|D MG 01|0021878",
"itemName": "Nome do item",
"paymentType": "1 = Recurring",
"recurringType": "1 = Continuos",
"typeCalculation": "1 = FixedPrice",
"quantityCicles": 1,
"variation": "1 = Currency",
"aditonal": 1.5,
"discount": 1.5,
"cicleNumber": 1,
"quantity": 1,
"baseValue": 1,
"value": 1,
"totalAmount": 1,
"reference": "INTMOV019",
"description": "Internet movel 5G",
"quantityRange": 1,
"unitMeasurement": "Mb",
"currencyCode": "BRL",
"minMarginValue": 42.3,
"maxMarginValue": 60.5,
"minMarginPercent": 70,
"maxMarginPercent": 110,
"isActive": true,
"priceRange": [
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"subscriptionItemId": "9495d9da-33be-4634-a67e-22eced59274d",
"initialQuantity": 1,
"finalQuantity": 1,
"rangeValue": 1,
"exceedRange": true,
"exceedTypeCalculation": "1 = FixedPrice"
}
],
"metadata": [
{
"alias": "string",
"name": "string",
"key": "string",
"value": "string"
}
]
}
],
"subscriptionPause": [
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"subscriptionId": "9495d9da-33be-4634-a67e-22eced59274d",
"startDate": "2022-04-06",
"endDate": "2022-04-06",
"observation": "Observações",
"integrationId": "112233"
}
],
"billsSimulation": [
{
"subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"cicle": 0,
"initialCicleDate": "2023-02-10T14:29:48.175Z",
"finalCicleDate": "2023-02-10T14:29:48.175Z",
"billingDate": "2023-02-10T14:29:48.175Z",
"totalAmount": 0
}
],
"billingRuler": {
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"description": "Description",
"sendingCharge": "0 = ExactlyDay",
"chargeAfterDueDate": "0 = NoDayAfterDueDate",
"chargeAfterDueDateEachDay": 0,
"chargeAfterDueDatePer": 0,
"default": false
},
"bills": [
{
"id": "9495d9da-33be-4634-a67e-22eced59274d",
"integrationId": "T1|D MG 01|0021878",
"reference": "0021878",
"description": "Bill Description",
"source": "Protheus",
"origin": "Protheus",
"cicle": 1,
"type": "0 = Single",
"status": "1 = Created",
"totalAmount": 100.5,
"usageTotalAmount": 200.99,
"creationDate": "2021-01-01",
"dueDate": "2021-01-01",
"paymentDate": "2021-01-01",
"currencyId": "9495d9da-33be-4634-a67e-22eced59274d",
"currencyCode": "BRL",
"organizationId": "9495d9da-33be-4634-a67e-22eced59274d",
"paymentMethods": [
{
"paymentMethod": "0 = None",
"paymentMethodDescription": "string"
}
],
"organizationIntegrationId": "T1|D MG 01|0021878",
"customerId": "9495d9da-33be-4634-a67e-22eced59274d",
"customerIntegrationId": "01 | SP | 012454",
"customerName": "Aleixo Telles",
"customerPhoneNumber": "+55 (11) 992635498",
"customerEmail": "[email protected]",
"subscriptionId": "9495d9da-33be-4634-a67e-22eced59274d",
"subscriptionIntegrationId": "T1|D MG 01|jun030",
"subscriptionReference": "jun030",
"subscriptionName": "English Course",
"metadata": [
{
"alias": "string",
"name": "string",
"key": "string",
"value": "string"
}
]
}
],
"metadata": [
{
"alias": "string",
"name": "string",
"key": "string",
"value": "string"
}
]
}
Documentação
Para uma listagem completa da saída por favor verifique a documentação Swagger.