> ## Documentation Index > Fetch the complete documentation index at: https://bmpdocs.moneyp.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Retenção - Incluir Assinante > Inicia a retenção de uma portabilidade, notificando o cliente para assinatura do Termo de Retenção. > Inclui o cliente como assinante do Termo de Retenção de Portabilidade e dispara, automaticamente, toda a jornada de retenção digital: geração do termo, notificação do cliente, coleta da assinatura e envio da evidência à Núclea. ## Quando usar Utilize este endpoint quando decidir formalizar a retenção do cliente por assinatura digital do Termo de Retenção. ## O que acontece depois da chamada A chamada só cria a assinatura; o restante da jornada é automático: 1. **Validação síncrona** — a BMP confirma que `nuPortabilidade` existe, pertence à carteira do parceiro autenticado e ainda está dentro do prazo regulatório (D+2). Fora disso, a requisição é rejeitada e nenhuma assinatura é criada. 2. **Geração do Termo** — PDF pré-preenchido com os dados do cliente, contrato e portabilidade, a partir do modelo padronizado pela Autorregulação. 3. **Envio do link de assinatura** — pelos canais marcados como `true` (`notificarPorEmail`, `notificarPorWhatsApp`, `notificarPorSMS`); quando mais de um canal é indicado, o envio ocorre **simultaneamente** em todos. O link é único, seguro e **expira ao final do prazo D+1** (`dataLimiteAssinatura`) — após isso, o cliente não consegue mais acessá-lo. 4. **Coleta da assinatura** — o cliente assina digitalmente; a BMP registra IP/geolocalização e gera o código de autenticação (Hash) exigido pela Núclea, consolidando o PDF final. 5. **Envio ao Repositório de Evidências da Núclea** — dentro da janela de operação do repositório (5h–18h) e ainda dentro do D+2. 6. **Montagem e envio da estrutura de retenção** à CTC, encerrando a jornada com aceite ou recusa da retenção. O parceiro acompanha cada uma dessas etapas pelos eventos cadastrados em [Cadastrar Callback](/e-consignado/portabilidade/cadastrar-callback) ou pelo campo `statusAssinatura` em [Consultar Portabilidades](/e-consignado/portabilidade/consultar-portabilidades). ## Parâmetros da Requisição Número CTC da portabilidade em retenção (mesmo valor retornado como `nuPortabilidade` na consulta gerencial). Deve existir e pertencer à carteira do parceiro autenticado. Número da Cédula de Crédito Bancário do contrato retido. Identificador da proposta no CaaS (equivalente ao `codigoProposta` retornado na consulta gerencial). CPF do cliente titular do contrato. E-mail do cliente, usado quando `notificarPorEmail` for `true`. Telefone celular do cliente, usado quando `notificarPorWhatsApp` e/ou `notificarPorSMS` forem `true`. Se `true`, envia o link de assinatura do Termo de Retenção por e-mail. Se `true`, envia o link de assinatura do Termo de Retenção por WhatsApp. Se `true`, envia o link de assinatura do Termo de Retenção por SMS. Identificador de controle do próprio parceiro para esta solicitação de retenção (referência/rastreabilidade do lado do parceiro). Ao menos um canal de notificação deve ser indicado (`notificarPorEmail`, `notificarPorWhatsApp` ou `notificarPorSMS`), com o respectivo dado de contato preenchido — sem isso o cliente não recebe o link de assinatura. Regra de validação exata a confirmar com o time responsável. ## Campos da Resposta | Campo | Tipo | Descrição | | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `assinaturaId` | guid | Identificador único da jornada de assinatura do Termo de Retenção, criado para essa `nuPortabilidade`. Não é enviado como campo separado nos eventos de callback — aparece embutido na URL `linkAssinatura` do evento `DOCUMENTO_ENVIADO`. | | `status` | string | Situação textual da assinatura no momento da criação (`Criada`) — o ciclo de vida completo é o mesmo descrito em `statusAssinatura` na consulta gerencial | | `dataLimiteAssinatura` | datetime | Prazo final (D+1, calculado em dias úteis) para o cliente assinar o Termo — após esse horário o link de assinatura expira | O restante da jornada é acompanhado pelo campo `statusAssinatura` do endpoint [Consultar Portabilidades](/e-consignado/portabilidade/consultar-portabilidades#campos-do-item-retornado), ou pelos eventos recebidos na URL cadastrada em [Cadastrar Callback](/e-consignado/portabilidade/cadastrar-callback#eventos) — `PORTABILIDADE_SOLICITADA`, `DOCUMENTO_ENVIADO`, `ASSINATURA_COLETADA` e `TIMEOUT_ASSINATURA`. Correlação sempre por `nuPortabilidade`; ver detalhes em [Eventos de Callback](/e-consignado/portabilidade/eventos-de-callback). ## OpenAPI ````yaml POST /api/v1/Portabilidade/Retencao/incluirassinante openapi: 3.0.1 info: title: BMPDigitalCore.Portabilidade API version: '1.0' servers: - url: https://api.portabilidade.moneyp.dev.br security: - Bearer: [] paths: /api/v1/Portabilidade/Retencao/incluirassinante: post: tags: - Portabilidade requestBody: content: application/json: schema: $ref: '#/components/schemas/RetencaoincluirassinanteRequest' text/json: schema: $ref: '#/components/schemas/RetencaoincluirassinanteRequest' application/*+json: schema: $ref: '#/components/schemas/RetencaoincluirassinanteRequest' responses: '200': description: OK content: text/plain: schema: $ref: >- #/components/schemas/RetencaoincluirassinanteResponseResultResponse application/json: schema: $ref: >- #/components/schemas/RetencaoincluirassinanteResponseResultResponse text/json: schema: $ref: >- #/components/schemas/RetencaoincluirassinanteResponseResultResponse '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' '422': description: Unprocessable Content content: text/plain: schema: $ref: >- #/components/schemas/RetencaoincluirassinanteResponseResultResponse application/json: schema: $ref: >- #/components/schemas/RetencaoincluirassinanteResponseResultResponse text/json: schema: $ref: >- #/components/schemas/RetencaoincluirassinanteResponseResultResponse components: schemas: RetencaoincluirassinanteRequest: type: object properties: nuPortabilidade: type: string nullable: true numeroCCB: type: string nullable: true codigoProposta: type: string nullable: true documento: type: string nullable: true email: type: string nullable: true telefoneCelular: type: string nullable: true notificarPorEmail: type: boolean notificarPorWhatsApp: type: boolean notificarPorSMS: type: boolean codigoIdentificador: type: string nullable: true additionalProperties: false RetencaoincluirassinanteResponseResultResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/RetencaoincluirassinanteResponse' errors: type: array items: $ref: '#/components/schemas/ErrorResponse' nullable: true additionalProperties: false ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} RetencaoincluirassinanteResponse: type: object properties: assinaturaId: type: string format: uuid status: type: string nullable: true dataLimiteAssinatura: type: string format: date-time additionalProperties: false ErrorResponse: type: object properties: code: type: string nullable: true message: type: string nullable: true additionalProperties: false securitySchemes: Bearer: type: apiKey description: Informe o token name: Authorization in: header ````