> ## 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. # Consultar Portabilidades > Consulta gerencial das portabilidades de crédito da carteira do parceiro autenticado. > Retorna **somente** as portabilidades da carteira do parceiro autenticado (`client_id`), com filtros por período, CPF, etapa e número de proposta. ## Endpoint ``` GET /api/v1/Portabilidade/Listar ``` ## Autenticação ``` Authorization: Bearer ``` O token é o reference token BMP e precisa conter a claim `client_id`. | Situação | HTTP | | -------------------------- | ---- | | Sem token | 401 | | Token inválido ou expirado | 401 | | Token sem `client_id` | 401 | Mensagens de erro possíveis no `401`: `Token não informado`, `Token inválido ou expirado`, `Token não contém client_id`. ## Parâmetros da Requisição Todos os parâmetros abaixo são enviados via query string e são **opcionais**. Início do período, considerando a data de solicitação da portabilidade. Fim do período, considerando a data de solicitação da portabilidade. Se enviado sem `dataInicio`, é ignorado — veja regras abaixo. CPF do cliente, com ou sem máscara. Etapa gerencial da portabilidade. Repita o parâmetro para filtrar mais de uma etapa. Case-insensitive. Valores aceitos: ``` Recepcao ConsultaRestricoes AguardandoAssinatura EmAceite EmRetencao EmLiquidacao EmRegistro Bloqueada Retida RetencaoRecusada Portada Cancelada Refinanciada ``` Também são aceitos `RETIDA` e `PORTADA` (equivalentes a `Retida` e `Portada`). Número da proposta no CaaS (`CodigoPropostaAN`). Repita o parâmetro para consultar mais de uma proposta. Página da consulta (mínimo 1). Cada página tem **20 registros**. ### Regras de negócio * Filtros informados em conjunto são cumulativos (**AND**). * Sem `dataInicio` e sem `dataFim`: retorna no máximo as **50** portabilidades mais recentes da carteira, ordenadas por `dataSolicitacao` decrescente, paginadas de 20 em 20. * Somente `dataInicio` informado (sem `dataFim`): `dataFim` assume a data corrente no horário de Brasília. * `dataFim` anterior a `dataInicio` → `400`. * Sem resultado → `200` com `items: []`. * `numeroProposta` informado como lista vazia → `400`. * CPF inválido → `400`. * `statusOperacao` fora da lista aceita → `400`, com os valores aceitos na mensagem de erro. ## Campos do item retornado Todo campo abaixo está **sempre presente** na resposta. Quando não se aplica ao registro, o valor é `null` — o campo não é omitido. | Campo | Tipo | Descrição | | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nuPortabilidade` | string | Número CTC da portabilidade | | `etapa` | string | Etapa gerencial (mesmos valores de `statusOperacao`) | | `statusPortabilidade` | int | Status interno da operação | | `taxaJurosMensal` | decimal? | Taxa mensal do contrato (CaaS) | | `cetMensal` | decimal? | CET mensal do contrato (CaaS) | | `qtdeParcelas` | int? | Quantidade de parcelas (CaaS) | | `vlrParcela` | decimal? | Valor da parcela (CaaS) | | `valorFinanciado` | decimal? | Valor financiado (CaaS) | | `dtVencimentoUltimaParcela` | date? | Vencimento da última parcela da agenda (`yyyy-MM-dd`) | | `nomeEmitente` | string? | Nome do cliente | | `documentoFederal` | string | CPF/CNPJ | | `dataSolicitacao` | datetime | Data de criação da portabilidade (UTC) | | `numeroProposta` | string? | Número da proposta no CaaS | | `codigoProposta` | guid? | Id interno da proposta | | `dtLimiteRetencao` | datetime? | Prazo X03; `null` quando não aplicável | | `motivoRetencao` | int? | Código CTC `MtvRetenContrto`; `null` quando não aplicável — ver domínio abaixo | | `motivoCancelamento` | int? | Código CTC `mtvCanceltPortldd`; `null` quando não aplicável — ver domínio abaixo | | `statusAssinatura` | int? | Situação do Termo de Retenção; `null` quando não há assinatura em curso — ver [ciclo de vida da assinatura](/e-consignado/portabilidade#ciclo-de-vida-da-assinatura-statusassinatura) | | `dtLimiteAssinatura` | datetime? | Prazo para assinar o Termo; `null` quando não há assinatura em curso | ### Respostas de erro (`400`) | Código | Mensagem | | -------------- | -------------------------------------------------------------------- | | `CONSULTA_001` | O campo 'dataFim' não pode ser anterior a 'dataInicio'. | | `CONSULTA_002` | O 'cpfEmitente' informado não é um CPF válido. | | `CONSULTA_003` | O campo 'numeroProposta' foi informado como lista vazia. | | `CONSULTA_004` | O valor '{x}' não é válido para 'statusOperacao'. Valores aceitos: … | | `CONSULTA_006` | O campo 'page' deve ser maior ou igual a 1. | ## Domínio — `motivoRetencao` Código CTC (`MtvRetenContrto`). Inteiro. `null` quando a operação não está em retenção. | Valor | Significado | | ----- | ----------------------------------------------- | | 1 | Cliente aceitou as novas condições | | 2 | Contrato não encontrado / modalidade divergente | | 6 | Garantia em execução | | 9 | CPF/CNPJ não é o titular | | 11 | Variação de saldo/parcelas acima do permitido | | 12 | Cliente com ação judicial | | 13 | Contrato cedido sem coobrigação | | 16 | Contrato já liquidado | | 17 | Cliente não solicitou a portabilidade | | 18 | IF credora original incorreta | | 25 | Portabilidade em andamento | ## Domínio — `motivoCancelamento` Código CTC (`mtvCanceltPortldd`). Inteiro. Preenchido apenas quando o cancelamento veio do ACTC104. | Valor | Significado | | ----- | ------------------------------- | | 3 | Saldo devedor | | 6 | STR não liquidado | | 7 | Cancelado pela IF proponente | | 10 | Decurso de prazo, STR devolvida | | 11 | Decurso de prazo | | 14 | Decurso de prazo, garantia | Decurso de prazo simples (`statusPortabilidade` 910) devolve `motivoCancelamento = null`. ## OpenAPI ````yaml GET /api/v1/Portabilidade/listar 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/listar: get: tags: - Portabilidade parameters: - name: DataInicio in: query schema: type: string format: date - name: DataFim in: query schema: type: string format: date - name: CpfEmitente in: query schema: type: string - name: StatusOperacao in: query schema: type: array items: type: string - name: NumeroProposta in: query schema: type: array items: type: string - name: Page in: query schema: type: integer format: int32 responses: '200': description: OK content: text/plain: schema: $ref: >- #/components/schemas/PortabilidadeGerencialResponsePagedResultResultResponse application/json: schema: $ref: >- #/components/schemas/PortabilidadeGerencialResponsePagedResultResultResponse text/json: schema: $ref: >- #/components/schemas/PortabilidadeGerencialResponsePagedResultResultResponse '400': description: Bad Request content: text/plain: schema: $ref: >- #/components/schemas/PortabilidadeGerencialResponsePagedResultResultResponse application/json: schema: $ref: >- #/components/schemas/PortabilidadeGerencialResponsePagedResultResultResponse text/json: schema: $ref: >- #/components/schemas/PortabilidadeGerencialResponsePagedResultResultResponse '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' components: schemas: PortabilidadeGerencialResponsePagedResultResultResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/PortabilidadeGerencialResponsePagedResult' 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: {} PortabilidadeGerencialResponsePagedResult: type: object properties: items: type: array items: $ref: '#/components/schemas/PortabilidadeGerencialResponse' nullable: true total: type: integer format: int32 page: type: integer format: int32 pageSize: type: integer format: int32 totalPages: type: integer format: int32 readOnly: true additionalProperties: false ErrorResponse: type: object properties: code: type: string nullable: true message: type: string nullable: true additionalProperties: false PortabilidadeGerencialResponse: type: object properties: nuPortabilidade: type: string nullable: true etapa: $ref: '#/components/schemas/EtapaPortabilidade' statusPortabilidade: type: integer format: int32 taxaJurosMensal: type: number format: double nullable: true cetMensal: type: number format: double nullable: true qtdeParcelas: type: integer format: int32 nullable: true vlrParcela: type: number format: double nullable: true valorFinanciado: type: number format: double nullable: true dtVencimentoUltimaParcela: type: string format: date nullable: true nomeEmitente: type: string nullable: true documentoFederal: type: string nullable: true dataSolicitacao: type: string format: date-time numeroProposta: type: string nullable: true codigoProposta: type: string format: uuid nullable: true dtLimiteRetencao: type: string format: date-time nullable: true motivoRetencao: type: integer format: int32 nullable: true motivoCancelamento: type: integer format: int32 nullable: true statusAssinatura: type: integer format: int32 nullable: true dtLimiteAssinatura: type: string format: date-time nullable: true additionalProperties: false EtapaPortabilidade: enum: - 10 - 20 - 30 - 40 - 50 - 60 - 70 - 80 - 90 - 91 - 95 - 99 type: integer format: int32 securitySchemes: Bearer: type: apiKey description: Informe o token name: Authorization in: header ````