Recupera Contratos

Descrição

Esse endpoint permite consultar os contratos/planos disponíveis, com opções de filtro por nome, filial, data de atualização, entre outros. Também é possível incluir informações adicionais, como grupos de atividades, observações de venda online, filiais com acesso, contratos adicionais e mais.

OBS. Disponível para uso com chave de acesso de filial e também com chave de acesso de ADM Geral.

🔑 Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
`idMembership`	int	Não	Filtra pelo ID do membership específico.
`name`	string	Não	Filtra pelo nome do contrato.
`idBranch`	int	Não	Filtra pelo ID da filial. Ignorado se a chave de API não for multifilial.
`take`	int	Não	Número total de registros a serem retornados (máximo: 200). Padrão: 25.
`skip`	int	Não	Quantidade de registros a serem ignorados (para paginação). Padrão: 0.
`active`	boolean	Não	Filtra por contratos ativos ou inativos.
`showAccessBranches`	boolean	Não	Exibe as filiais em que o contrato garante acesso. Padrão: `false`.
`showOnlineSalesObservation`	boolean	Não	Exibe observações referentes à venda online. Padrão: `false`.
`updateDate`	string (ISO)	Não	Filtra contratos atualizados a partir desta data (`yyyy-mm-dd`).
`showActivitiesGroups`	boolean	Não	Exibe os grupos de atividades vinculados ao plano/contrato. Padrão: `false`.
`externalSaleAvailable`	boolean	Não	Permite venda externa. Padrão: `false`.
`showSuspensionRules`	boolean	Não	Exibe as regras de suspensão na resposta.. Padrão: `false`.
`showCancellationRules`	boolean	Não	Exibe as regras de cancelamento na resposta. Padrão: `false`.
`showContract`	boolean	Não	Exibe a estrutura do contrato na resposta. Padrão: `false`.
`showTurnstiles`	boolean	Não	Exibe as catracas vinculadas ao plano/contrato, direamente ou por meio de um grupo de catracas, na resposta. Padrão: `false`.
`showAdditionalMemberships`	boolean	Não	Quando `true`, traz os contratos adicionais vinculados e a configuração `additionalValueProportionalToDuration` do contrato principal. Padrão: `false`.

📤 Estrutura da Resposta

A resposta retorna os dados completos de um plano, incluindo informações comerciais, regras de cobrança, serviços adicionais, grupos de atividades, filiais associadas, entradas, páginas de venda e configurações de elegibilidade.

Campo	Tipo	Descrição
`idMembership`	int32	Identificador único do plano.
`idBranch`	int32	ID da filial associada ao plano.
`nameMembership`	string	Nome do plano.
`membershipType`	string	Tipo do plano. Ver mais abaixo.
`durationType`	string	Tipo de duração do plano (ex.: Dias ou Meses).
`duration`	int32	Duração do plano conforme o tipo definido.
`updateDate`	date-time	Data da última atualização do plano.
`value`	number (double)	Valor do plano. Inclui a soma dos adicionais vinculados ao plano, fixos e opcionais.
`maxAmountInstallments`	int32	Quantidade máxima de parcelas permitidas.
`description`	string	Descrição detalhada do plano.
`urlSale`	string (read-only)	URL pública para venda do plano.
`onlineSalesObservations`	string	Observações exibidas no fluxo de vendas online.
`diferentials`	arrayobject	Lista de diferenciais associados ao plano. Ver mais abaixo.
`accessBranches`	arrayobject	Lista de unidades onde o plano é válido. Ver mais abaixo.
`additionalService`	arrayobject	Serviço adicional vinculado ao plano. Ver mais abaixo.
`serviceYearly`	arrayobject	Serviço anual associado ao plano. Ver mais abaixo.
`typePromotionalPeriod`	int32	Tipo de período promocional aplicado ao plano ou serviço, definindo a regra de duração da promoção.
`valuePromotionalPeriod`	number	Valor aplicado durante o período promocional. Inclui a soma dos adicionais vinculados ao plano, fixos e opcionais.
`monthsPromotionalPeriod`	int32	Quantidade de meses de duração do período promocional, quando aplicável.
`daysPromotionalPeriod`	int32	Quantidade de dias de duração do período promocional, quando aplicável.
`minPeriodStayMembership`	int32	Período mínimo de permanência no plano.
`installmentsPromotionalPeriod`	int32	Quantidade de parcelas permitidas durante o período promocional.
`activitiesGroups`	arrayobject	Grupos de atividades vinculados ao plano. Ver mais abaixo.
`inactive`	boolean	Indica se o plano está inativo.
`displayName`	string	Nome de exibição formatado do plano.
`entries`	arrayobject	Configuração de entradas permitidas pelo plano. Ver mais abaixo.
`salesPage`	arrayobject	Páginas de venda associadas ao plano. Ver mais abaixo.
`allowsCancellationByApp`	boolean	Indica se o plano pode ser cancelado pelo aplicativo.
`externalSaleAvailable`	boolean	Indica se o plano pode ser vendido externamente.
`acceptEnrollment`	boolean	Indica se aceita inscrição direta.
`enrollmentRequired`	boolean	Indica se exige inscrição obrigatória.
`contractSuspension`	arrayobject	Regras de suspensão vinculados ao plano. Ver mais abaixo.
`contractCancellation`	arrayobject	Regras de cancelamento vinculados ao plano. Ver mais abaixo.
`htmlContract`	string	Estrutura do contrato vinculado ao plano.
`turnstiles`	array	Lista das catracas associadas ao plano/contrato.
`additionalValueProportionalToDuration`	boolean	Indica se o valor dos contratos adicionais deve ser proporcional à vigência do contrato principal.
`additionalMemberships`	arrayobject	Contratos adicionais vinculados ao contrato principal. Ver mais abaixo.

🧩 Valores de `membershipType`

O campo membershipType representa a modalidade do contrato configurada em Administrativo > Contratos.

Contrato comum

Contrato mensal com renovação automática

Extensão de plano

Extensão de trancamento

Débito recorrente mensal

Débito recorrente com vigência

Dependentes adicionais

Contrato anual com fim determinado

Contrato adicional

Pix agendado recorrente com vigência

Pix automático mensal

OBS. O campo membershipType não indica se um contrato adicional possui vínculo fixo ou opcional. Para contratos adicionais, essa informação é representada pelo campo additionalType dentro de additionalMemberships.

🧩 Estrutura de `diferentials`

Campo	Tipo	Descrição
`title`	string	Título do diferencial.
`order`	int32	Ordem de prioridade.

🧩 Estrutura de `accessBranches`

Campo	Tipo	Descrição
`idBranch`	int32	Identificador da unidade à qual o membro possui acesso.
`name`	string	Nome da unidade à qual o membro possui acesso.

🧩 Estrutura de `additionalService`

Campo	Tipo	Descrição
`idService`	int32	Identificador do serviço adicional.
`name`	string	Nome do serviço adicional.
`value`	number	Valor do serviço adicional.

🧩 Estrutura de `serviceYearly`

Campo	Tipo	Descrição
`idService`	int32	ID do serviço anual.
`name`	string	Nome do serviço anual.
`value`	number (double)	Valor do serviço anual.
`type`	int32	Tipo de cobrança do serviço.
`billingMonth`	int32	Mês de cobrança.
`billingDay`	int32	Dia de cobrança.
`billingAfterMonths`	int32	Meses após a contratação para cobrança.
`installments`	int32	Quantidade de parcelas.
`typePromotionalPeriod`	int32	Tipo de período promocional.
`valuePromotionalPeriod`	number (double)	Valor promocional.
`monthsPromotionalPeriod`	int32	Quantidade de meses promocionais.
`daysPromotionalPeriod`	int32	Quantidade de dias promocionais.
`installmentsPromotionalPeriod`	int32	Parcelas no período promocional.

🧩 Estrutura de `activitiesGroups`

Campo	Tipo	Descrição
`idGroupActivity`	int32	ID do grupo de atividade.
`name`	string	Nome do grupo de atividade.
`idBranch`	int32	ID da filial associada ao grupo.

🧩 Estrutura de `entries`

Campo	Tipo	Descrição
`entriesQuantity`	int32	Quantidade de entradas permitidas.
`idEntriesType`	int32	Tipo de entrada configurada.
`entriesTypeDescription`	string	Descrição do tipo de entrada.

🧩 Estrutura de `salesPage`

Campo	Tipo	Descrição
`idSalesPage`	int32	ID da página de vendas.
`order`	int32	Ordem de exibição do plano na página.
`salesPageDescription`	string	Descrição da página de vendas.

🧩 Estrutura de `contractSuspension`

Campo	Tipo	Descrição
`maxSuspensionsAllowed`	int32	Quantidade máxima de suspensões permitidas para o contrato.
`totalSuspensionDays`	int32	Quantidade total de dias de suspensão permitidos para o contrato.
`minimumPeriodBeforeSuspensionDays`	int32	Período mínimo, em dias, antes de permitir a suspensão do contrato.
`firstSuspensionGracePeriodMonths`	int32	Período de carência, em meses, para a primeira suspensão do contrato.
`nextSuspensionsGracePeriodMonths`	int32	Período de carência, em meses, para as próximas suspensões do contrato.

🧩 Estrutura de `contractCancellation`

Campo	Tipo	Descrição
`considerClosedCompetencyOnCancellation`	boolean	Indica se a competência fechada deve ser considerada no cancelamento.
`priorNoticeDays`	int32	Quantidade de dias de aviso prévio exigidos para o cancelamento.
`applyPenaltyAutomatically`	boolean	Indica se a multa deve ser aplicada automaticamente no cancelamento.
`penaltyOverRemainingContractValue`	boolean	Indica se a multa deve ser calculada sobre o valor restante do contrato.
`minimumGracePeriodMonths`	int32	Período mínimo de carência, em meses, para aplicação das regras de cancelamento.
`penaltyPercentage`	number	Percentual de multa aplicado no cancelamento do contrato.

🧩 Estrutura de `additionalMemberships`

Campo	Tipo	Descrição
`idMembership`	int32	Identificador do contrato adicional.
`nameMembership`	string	Nome do contrato adicional.
`membershipType`	string	Modalidade do contrato adicional.
`value`	number (double)	Valor configurado no cadastro do contrato adicional.
`inactive`	boolean	Indica se o contrato adicional está inativo.
`additionalType`	string	Tipo de vínculo entre o contrato principal e o adicional. Pode assumir os valores `Fixed` ou `Optional`.
`defaultSaleValue`	number (double)	Valor padrão que será utilizado pelos fluxos de Sales e Carts quando `membershipValue` não for informado para o adicional. Pode variar de acordo com a flag `additionalValueProportionalToDuration`.

🚧 Regras dos contratos adicionais
Fixed: identifica um adicional obrigatório, incluído automaticamente quando o contrato principal é vendido e que não pode ser vendido isoladamente.
Optional: identifica um adicional que pode ser selecionado pela integração, vendido junto com o contrato principal ou separadamente quando o membro já possuir um contrato principal elegível.
O tipo do vínculo pertence à combinação entre contrato principal + contrato adicional. Por isso, um mesmo contrato adicional pode ser Fixed para um contrato principal e Optional para outro.
Quando additionalValueProportionalToDuration for false, defaultSaleValue corresponde ao valor configurado no contrato adicional.
Quando additionalValueProportionalToDuration for true, defaultSaleValue corresponde ao valor configurado do adicional multiplicado pela quantidade de meses de vigência do contrato principal. Para contratos principais com vigência de 1 mês, o valor não é alterado.
Quando a integração informar membershipValue durante a venda, o valor informado será considerado o valor final do adicional e não será multiplicado novamente pela vigência.

Basic Auth

Envie suas requisições HTTP com um cabeçalho

Authorization

que contenha a palavra Basic seguida por um espaço e uma string codificada em base64 username:password

Exemplo:

Authorization: Basic *****************

Exemplos de Requisição

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Respostas

🟢200

application/json

Success

Body

Exemplo

[
    {
        "idMembership": 0,
        "idBranch": 0,
        "nameMembership": "string",
        "membershipType": "string",
        "durationType": "string",
        "duration": 0,
        "updateDate": "2019-08-24T14:15:22.123Z",
        "value": 0,
        "maxAmountInstallments": 0,
        "description": "string",
        "urlSale": "string",
        "onlineSalesObservations": "string",
        "differentials": [
            {
                "title": "string",
                "order": 0
            }
        ],
        "accessBranches": [
            {
                "idBranch": 0,
                "name": "string"
            }
        ],
        "additionalService": {
            "idService": 0,
            "name": "string",
            "value": 0
        },
        "serviceYearly": {
            "idService": 0,
            "name": "string",
            "value": 0,
            "type": 0,
            "billingMonth": 0,
            "billingDay": 0,
            "billingAfterMonths": 0,
            "installments": 0
        },
        "typePromotionalPeriod": 0,
        "valuePromotionalPeriod": 0,
        "monthsPromotionalPeriod": 0,
        "daysPromotionalPeriod": 0,
        "minPeriodStayMembership": 0,
        "installmentsPromotionalPeriod": 0,
        "activitiesGroups": [
            {
                "idGroupActivity": 0,
                "name": "string",
                "idBranch": 0
            }
        ],
        "inactive": true,
        "displayName": "string",
        "entries": {
            "entriesQuantity": 0,
            "idEntriesType": 0,
            "entriesTypeDescription": "string"
        },
        "salesPage": [
            {
                "idSalesPage": 0,
                "order": 0,
                "salesPageDescription": "string"
            }
        ],
        "allowsCancellationByApp": true,
        "externalSaleAvailable": true,
        "acceptEnrollment": true,
        "enrollmentRequired": true,
        "contractSuspension": {
            "maxSuspensionsAllowed": 0,
            "totalSuspensionDays": 0,
            "minimumPeriodBeforeSuspensionDays": 0,
            "firstSuspensionGracePeriodMonths": 0,
            "nextSuspensionsGracePeriodMonths": 0
        },
        "contractCancellation": {
            "considerClosedCompetencyOnCancellation": true,
            "priorNoticeDays": 0,
            "applyPenaltyAutomatically": true,
            "penaltyOverRemainingContractValue": true,
            "minimumGracePeriodMonths": 0,
            "penaltyPercentage": 0
        },
        "htmlContract": "string",
        "turnstiles": [
            0
        ],
        "additionalValueProportionalToDuration": true,
        "additionalMemberships": [
            {
                "idMembership": 0,
                "nameMembership": "string",
                "membershipType": "string",
                "value": 0,
                "inactive": true,
                "additionalType": "string",
                "defaultSaleValue": 0
            }
        ]
    }
]

🟠400

Get memberships

Recupera Contratos#

Descrição#

🔑 Parâmetros de Consulta#

📤 Estrutura da Resposta#

🧩 Valores de membershipType#

🧩 Estrutura de diferentials#

🧩 Estrutura de accessBranches#

🧩 Estrutura de additionalService#

🧩 Estrutura de serviceYearly#

🧩 Estrutura de activitiesGroups#

🧩 Estrutura de entries#

🧩 Estrutura de salesPage#

🧩 Estrutura de contractSuspension#

🧩 Estrutura de contractCancellation#

🧩 Estrutura de additionalMemberships#

Requisição