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 4

Nova versão Atual

Chave

Endpoint de homologação

Endpoint Subscriptions