Histórico da Página

...

Deck of Cards

id	3. Subscrição

Card

label	API Subscrição

Nota

title	API Subscrição

Na API de subscrição é possível realizar a assinatura dos planos com itens associados e assinatura customizada vinculado somente os itens.

Card

label	API Subscrição Pause

Nota

title	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.

Card

label	API Customer

Nota

title	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:

Image Added

Card

label	API Subscrição Cancelado

Nota

title	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.

Card

label	API Subscrição com dados de pagamento

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. Cartão Tokenizado.

Pré-requisitos:

Ter realizado a criação do Customers;
Ter realizado o procedimento de Tokenização do Cartão;

Ordem das execuções:

Customers
Payment-Token
Subscriptions

Deck of Cards

id	Subscriptions

Card

label	Endpoint Customer

Esse método permite registrar as informações do cliente para que seja associado na subscrição nova ou já registrado

.

Endpoint de homologação

https://api-recorrencia.staging.totvs.app/api/v1/customers

Parâmetros de Entrada

Bloco de código

language	yml
title	POST Customers

{
  "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

Bloco de código

language	yml
title	RESPONSE Customers

{
  "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

Bloco de código

language	yml
title	GET Customers

https://api-recorrencia.staging.totvs.app/api/v1/customers/{id}

Parâmetros de Saída

Bloco de código

language	yml
title	RESPONSE POST Customers

{
  "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
}

Aviso

title	Documentação

Para uma listagem completa da saída por favor verifique a documentação Swagger.

Card

label	Subscrição com dados de pagamento

Esse método permite realizar a subscrição contendo um cartão tokenizado.

Endpoint Subscriptions

Parâmetros de Entrada

Obs.: inserir o id armazenado do cartão tokenizado no campo "paymentTokenId": "59f975c5-6c5e-43ff-8da3-07b21afbccbc"

Bloco de código

language	yml
title	POST Subscriptions

  {
  "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

Bloco de código

language	yml
title	RESPONSE Subscriptions

  "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"
    }
  ]
}

Aviso

title	Documentação

Para uma listagem completa da saída por favor verifique a documentação Swagger.

Árvore de páginas

Versões comparadas

Versão antiga 3

Nova versão Atual

Chave

Endpoint de homologação

Endpoint Subscriptions