Campo Alfanumérico na CCB

Com a evolução da estrutura de identificação das propostas e contratos, alguns campos anteriormente tratados apenas como numéricos passaram a suportar valores alfanuméricos.

Essa alteração visa:

• Garantir maior flexibilidade de identificação;
• Suportar novos padrões operacionais;
• Evitar limitações de tamanho e formato;
• Melhorar interoperabilidade entre parceiros e sistemas.

​

Impactos Esperados

Os parceiros deverão revisar:

• Validações de tipo;
• Máscaras e regex;
• Estruturas de banco de dados;
• Conversões numéricas;
• Serializações;
• Regras de integração.

---

​

Lista Completa de APIs Impactadas

​

APIs de Crédito

Abaixo estão listadas as APIs contendo endpoints, controllers impactados, endpoint externo e payloads afetados.

#	Endpoint
1	IncluirPropostaRenegociacao
2	PropostaAtualizarCampoExtra
3	CreateUpdatePropostaLancamento
4	PropostaAtualizarContaPagamento
5	PropostaAtualizarPIXPagamento
6	PropostaAtualizarPIXPagamentoParcela
7	CreateUpdatePropostaBoleto
8	CreateUpdatePropostaBoletoParcela
9	CreateUpdatePropostaCarnet
10	CreateUpdatePropostaPIX
11	AtualizarProposta
12	BuscarProposta
13	BuscarPropostaDetalhada
14	BuscarPropostaParceiro
15	BuscarContrato
16	BuscarContratoDetalhado
17	BuscarOperacao
18	BuscarOperacaoParceiro
19	AtualizarOperacao
20	BuscarContaPagamento
21	AtualizarContaLiquidacao
22	BuscarDadosPIX
23	AtualizarDadosPIX
24	BuscarNumeroProposta
25	BuscarCodigoCCB
26	BuscarDadosLiquidacao
27	BuscarStatusContrato
28	BuscarDadosAgenda
29	BuscarDocumentoCliente
30	BuscarCodigoOperacao
31	AtualizarNumeroProposta
32	ConsultarPropostaAlfanumerica
33	CreateUpdatePropostaPIXExterno
34	CreateUpdatePropostaBoletoExterno
35	IncluirNotaComercial
36	IncluirPropostaManual
37	IncluirPropostaManualSAC
38	IncluirPropostaManualSimplificado
39	IncluirPropostaManualSimplificadoPrice
40	IncluirPropostaManualSimplificadoSAC
41	IncluirPropostaFluxoIrregular

​

APIs Manuais

Os seguintes endpoints compartilham o mesmo padrão de alteração:

• IncluirPropostaManual
• IncluirPropostaManualSAC
• IncluirPropostaManualSimplificado
• IncluirPropostaManualSimplificadoPrice
• IncluirPropostaManualSimplificadoSAC
• IncluirPropostaFluxoIrregular

​

Alteração Aplicada

Todos os endpoints acima passam a retornar:

{
  "Msg": "string",
  "Result": false,
  "Codigo": "Guid",
  "Numero": 0,
  "CodigoProposta": "string"
}

​

Campos Impactados

Campo	Alteração
CodigoProposta	Numérico → Alfanumérico
CodigoOperacao	Numérico → Alfanumérico
NumeroProposta	Numérico → Alfanumérico
CodigoCCB	Numérico → Alfanumérico
CodigoContratoOriginal	Numérico → Alfanumérico

​

APIs de Agenda

#	Endpoint
37	/AgendaRecebivel/ConsultarBoletos
38	/AgendaRecebivel/ConsultarDetalhes

---

​

APIs de Crédito

​

1. IncluirPropostaRenegociacao

​

Controllers Impactados

Controller	Impactado
BMPDigitalController	Sim
MultiploController	Não
PartnerController	Não

​

Endpoint Externo

IncluirPropostaRenegociacao

​

Request

{
  "dto": {
    "CodigoContratoOriginal": "string",
    "ValorPropostaPrincipal": 0,
    "DocumentoCliente": "string",
    "DocumentoPromotor": "string"
  }
}

​

Response

{
  "Msg": "string",
  "Result": false,
  "Codigo": "Guid",
  "Numero": 0,
  "CodigoProposta": "string"
}

​

Alterações Realizadas

Campo	Antes	Depois
CodigoContratoOriginal	Numérico	Alfanumérico
CodigoProposta	Numérico	Alfanumérico

​

Observações

• O campo CodigoContratoOriginal passa a aceitar letras e números.
• O campo CodigoProposta deve ser tratado como string em toda a integração.

---

​

2. PropostaAtualizarCampoExtra

​

Controllers Impactados

Controller	Impactado
BMPDigitalController	Sim
MultiploController	Sim
PartnerController	Não

​

Endpoint Externo

AtualizarCampoExtra

​

Request

{
  "dto": {
    "CodigoProposta": "00000000-0000-0000-0000-000000000000",
    "CodigoOperacao": "string",
    "NumeroProposta": "string"
  }
}

​

Response

Retorno simplificado:

"OK"

​

Alterações Realizadas

Campo	Antes	Depois
NumeroProposta	Numérico	Alfanumérico
CodigoOperacao	Numérico	Alfanumérico

​

Observações

• Não realizar parse numérico no campo NumeroProposta.
• O endpoint retorna apenas confirmação de processamento.

---

​

3. CreateUpdatePropostaLancamento

​

Controllers Impactados

Controller	Impactado
BMPDigitalController	Sim
MultiploController	Sim
PartnerController	Não

​

Endpoint Externo

SalvarLancamento

​

Request

{
  "dto": {
    "CodigoProposta": "00000000-0000-0000-0000-000000000000",
    "CodigoOperacao": "string",
    "NumeroProposta": "string"
  }
}

​

Response

Retorno simplificado:

"OK"

​

Alterações Realizadas

Campo	Antes	Depois
NumeroProposta	Numérico	Alfanumérico
CodigoOperacao	Numérico	Alfanumérico

---

​

4. PropostaAtualizarContaPagamento

​

Controllers Impactados

Controller	Impactado
BMPDigitalController	Sim
MultiploController	Sim
PartnerController	Não

​

Endpoint Externo

AtualizarContaPagamento

​

Request

{
  "dto": {
    "CodigoProposta": "00000000-0000-0000-0000-000000000000",
    "CodigoOperacao": "string",
    "NumeroProposta": "string"
  }
}

​

Response

Retorno simplificado:

"OK"

​

Alterações Realizadas

Campo	Antes	Depois
NumeroProposta	Numérico	Alfanumérico
CodigoOperacao	Numérico	Alfanumérico

---

​

APIs de Agenda

​

1. /AgendaRecebivel/ConsultarBoletos

​

Response

{
  "msg": "string",
  "hasError": true,
  "boletos": [
    {
      "numeroBoleto": 0,
      "numeroProposta": 0,
      "codigoCCB": "A458F32"
    }
  ]
}

​

Alterações Realizadas

Campo	Antes	Depois
codigoCCB	Numérico	Alfanumérico

​

Observações

• O campo codigoCCB passa a aceitar letras e números.
• Não utilizar validações exclusivamente numéricas.

---

​

2. /AgendaRecebivel/ConsultarDetalhes

​

Response

{
  "numeroProposta": 0,
  "codigoCCB": "A458F32",
  "numeroPropostaAlfa": "string"
}

​

Alterações Realizadas

Campo	Antes	Depois
codigoCCB	Numérico	Alfanumérico
numeroPropostaAlfa	Não existente	Novo campo

​

Observações

• Foi adicionado o novo campo numeroPropostaAlfa.
• Os parceiros devem priorizar o consumo do identificador alfanumérico quando aplicável.
• Sistemas legados que utilizam apenas numeroProposta devem ser revisados.

---

​

APIs do FGTS

​

1. Consulta Proposta

​

Endpoint

/FGTS/ConsultaProposta

​

Request

{
  "dto": {
    "CodigoProposta": "string",
    "NumeroProposta": "string",
    "CodigoOperacao": "string"
  }
}

​

Response

{
  "Codigo": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "DtInclusao": "string",
  "Situacao": 0,
  "VlrFinanciado": 0,
  "QtdeParcelas": 0,
  "VlrTAC": 0,
  "VlrSeguro": 0,
  "VlrIOF": 0,
  "VlrOutrasDespesas": 0,
  "VlrOutrosServicos": 0,
  "VlrTotalCredito": 0,
  "VlrTotalDivida": 0,
  "PercCETMensal": 0,
  "PercCETAnual": 0,
  "PercJurosMensal": 0,
  "PercJurosAnual": 0,
  "CodigoProposta": "string",
  "NumeroCCB": "string",
  "MotivoRejeicao": "string",
  "MotivoPendencia": "string",
  "MotivoCancelamento": "string",
  "TextoRetornoPagamento": "string",
  "AutenticacaoBancaria": "string",
  "ControleBancario": "string",
  "StatusProtocoloCEF": "string",
  "PropostaLancamentos": [
    {
      "CampoID": "string",
      "DescricaoCampo": "string",
      "VlrTransacao": 0,
      "DtPrevPagto": "2026-05-25T15:17:13.529Z",
      "DtPagamento": "2026-05-25T15:17:13.529Z",
      "Situacao": 0,
      "LinhaDigitavel": "string",
      "DtVenctoBoleto": "2026-05-25T15:17:13.529Z",
      "VlrBoleto": 0,
      "CodigoBanco": 0,
      "NumeroBanco": "string",
      "TipoConta": 0,
      "Agencia": "string",
      "AgenciaDig": "string",
      "Conta": "string",
      "ContaDig": "string",
      "DocumentoFederal": "string",
      "NomePagamento": "string",
      "TextoRetornoPagamento": "string",
      "AutenticacaoBancaria": "string",
      "ControleBancario": "string",
      "DescricaoOcorrencia": "string"
    }
  ],
  "CancelamentoFGTS": [
    {
      "Detalhes": "string",
      "ContextoEvento": "string",
      "TipoEvento": 0,
      "NomeEvento": "string",
      "DtEvento": "string",
      "NumCodigoBarras": "string",
      "NumLinhaDigitavel": "string",
      "PixCopiaCola": "string",
      "VlrBoleto": 0,
      "DtVencimento": "2026-05-25T15:17:13.529Z",
      "NumeroBoleto": 0,
      "UrlImpressaoBoleto": "string"
    }
  ],
  "Msg": "string",
  "HasError": true,
  "Messages": [
    {
      "MessageType": 1,
      "Code": "string",
      "Context": "string",
      "Description": "string",
      "Field": "string"
    }
  ]
}

​

2. Incluir Proposta

​

Endpoint

/FGTS/IncluirProposta

​

Request

{
  "dto": {
    "CodigoOperacao": "string",
    "VlrEmprestimo": 0,
    "Periodo": 0,
    "DtAniversario": "2026-05-27T15:20:45.490Z",
    "TaxaMensal": 0,
    "VlrTAC": 0,
    "PercTAC": 0,
    "CpfTrabalhador": "string",
    "TipoContrato": "string",
    "DocumentoParceiroCorrespondente": "string",
    "PropostaContaPagamento": {
      "CodigoBanco": 0,
      "TipoConta": 0,
      "Agencia": "string",
      "AgenciaDig": "string",
      "Conta": "string",
      "ContaDig": "string",
      "NumeroBanco": "string",
      "DocumentoFederalPagamento": "string",
      "NomePagamento": "string"
    },
    "PropostaPIXPagamento": {
      "ChavePIX": "string"
    },
    "PropostaLancamentos": [
      {
        "CampoID": "string",
        "VlrTransacao": 0,
        "DtPagamento": "2026-05-27T15:20:45.491Z",
        "LinhaDigitavel": "string",
        "CodigoBanco": 0,
        "NumeroBanco": "string",
        "TipoConta": 0,
        "Agencia": "string",
        "AgenciaDig": "string",
        "Conta": "string",
        "ContaDig": "string",
        "DocumentoFederal": "string",
        "NomePagamento": "string",
        "DocumentoFederalCedente": "string",
        "NomeCedente": "string",
        "PagamentoViaChavePix": {
          "ChavePix": "string"
        },
        "PagamentoViaEmv": {
          "Emv": "string"
        }
      }
    ],
    "ConsultaCache": true,
    "Periodos": [
      {
        "DataRepasse": "2026-05-27T15:20:45.491Z",
        "VlrRepasse": 0
      }
    ]
  }
}

​

Response

{
  "CodigoProposta": "string",
  "NumeroProposta": "string",
  "Msg": "string",
  "HasError": true,
  "Messages": [
    {
      "MessageType": 1,
      "Code": "string",
      "Context": "string",
      "Description": "string",
      "Field": "string"
    }
  ]
}

​

3. Consulta Status do Protocolo

​

Endpoint

/FGTS/ConsultaProtocolo

​

Request

{
  "dto": {
    "CodigoProposta": "string",
    "NumeroProposta": "string"
  }
}

​

Response

{
    "Msg": "string",
    "Codigo": "string",
    "HasError": false,
    "Messages": []
}

​

Alterações Realizadas

Campo	Antes	Depois
NumeroProposta	Numérico	Alfanumérico
CodigoProposta	Numérico	Alfanumérico

​

Observações

• Campo NumeroProposta deixa de ser int e se torna string.
• O campo CodigoProposta deixa de ser string e se torna GUID.

---

​

Recomendações Técnicas para Parceiros

​

Ajustes Recomendados

​

Banco de Dados

Alterar tipos de campos:

Antes	Recomendado
INT	VARCHAR
BIGINT	VARCHAR
NUMERIC	VARCHAR

---

​

Validações

Remover validações como:

^[0-9]+$

Substituir por:

^[A-Za-z0-9]+$

---

​

Serialização

Garantir que os campos sejam tratados como:

"string"

Evitar:

• ParseInt;
• Conversão automática para long/int;
• Máscaras numéricas.

---

​

Compatibilidade

​

Retrocompatibilidade

Durante o período de transição:

• Alguns endpoints poderão retornar valores exclusivamente numéricos;
• Novos contratos poderão utilizar identificadores alfanuméricos;
• As integrações devem suportar ambos os formatos.

---

​

Checklist de Adequação

Item	Obrigatório
Ajustar banco de dados	Sim
Ajustar validações	Sim
Ajustar serialização	Sim
Revisar logs e auditoria	Sim
Revisar filtros e buscas	Sim
Revisar exportações	Sim

---