Skip to main content

Manual Cartão Consignado: Changelog

Mudanças de contrato do cartão consignado, para quem já integra. As rotas de cliente não mudaram em nenhum momento — apenas o corpo das requisições e alguns códigos de erro.

API em desenvolvimento

A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.

Suporte a múltiplas fontes de consignação​

O cartão passou a atender mais de uma folha de pagamento. Para isso, o que antes era uma única string fundida virou dois campos independentes: a fonte de consignação na rota e o produto no payload. Ver Visão Geral.

collateral.collateral_type foi removido; product_type é obrigatório​

O campo collateral.collateral_type, que combinava fonte e produto em uma string (social_security_benefit_card), não é mais aceito em nenhum corpo de requisição. Em seu lugar, informe product_type no primeiro nível.

Antes

{
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "collateral_type": "social_security_benefit_card",
    "subcorban_document_number": "12123456000101",
    "assistance_type": "pension_by_death_rural_worker"
  }
}

Agora

{
  "product_type": "benefit_card",
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "subcorban_document_number": "12123456000101",
    "assistance_type": "pension_by_death_rural_worker"
  }
}

Vale para a criação (POST /payroll_card_reservation/{collateral_type}) e para a simulação (POST /payroll_card_reservation/{collateral_type}/simulation). Na simulação, a seção collateral passou a ser opcional e o INSS não a envia.

As respostas não mudaram: o campo payroll_card_type continua devolvendo a string combinada, como antes.

GET /eligibility exige product_type​

A consulta de elegibilidade passou a exigir o parâmetro product_type, porque a faixa etária elegível é definida por tipo de cartão.

GET /payroll_card_reservation/social_security/eligibility?document_number=...&birth_date=...&product_type=benefit_card

Limites passaram a ser validados por tipo de cartão​

Tetos comerciais — número de parcelas, taxa de juros mensal, withdrawal_ratio e limit_days_to_disburse — deixaram de ser limites fixos do schema e passaram a ser configuração do seu tipo de cartão.

⚠️ Mudança de código de erro. Um valor acima do teto era recusado pela validação de schema, com QIT000001. Agora é recusado pela regra de negócio, com PCR000001. O status HTTP continua 400, mas o code e a description mudaram — a nova mensagem informa o campo, o valor recebido e o máximo permitido. Se a sua integração trata códigos de erro individualmente, este é o ponto a ajustar.

Novos códigos de erro​

CódigoStatusQuando ocorre
PCR000001400Um valor da requisição excede o teto do tipo de cartão
PCR000004400A combinação de fonte de consignação (rota) e product_type (payload) não corresponde a um tipo de cartão contratado
PCR000005400A entrada financeira enviada não é aceita pelo tipo de cartão — salary_amount e available_margin são mutuamente exclusivos e cada tipo aceita um deles

Consulta por request_control_key removida da documentação​

A rota GET /payroll_card_reservation/{collateral_type}/request_control_key/{request_control_key} estava documentada mas nunca existiu na API. A referência foi removida. Para localizar uma reserva, use a chave da reserva ou a consulta por CPF do portador.

O campo request_control_key continua existindo normalmente no corpo da criação e nas respostas.