Mocks (Sandbox)

Aviso Importante!

Não utilize dados pessoais reais (CPF, CNPJ etc.) em ambiente sandbox.

Em sandbox, duas coisas diferentes são simuladas: as chamadas à Dataprev (consulta, averbação e anuência), que a social-security-api intercepta e responde com massa de teste própria, e os retornos do CTC - CIP na portabilidade, que você dispara por rotas de mock. Cada etapa da jornada tem sua própria chave de simulação:

Etapa	O que decide o cenário
Consulta de saldo/margem	CPF — match exato ou primeiro dígito
Averbação da reserva	Primeiro dígito do CPF
Anuência (pending_confirmation)	Último dígito do número do benefício
Portabilidade — retornos do CTC - CIP	A rota de mock que você chama, por cenário

Jornada completa em sandbox

Para que a operação percorra a jornada inteira até o desembolso, o CPF e o número do benefício precisam cair, ao mesmo tempo, num cenário de sucesso de saldo, de averbação e de anuência. Combinação recomendada: CPF iniciado em 1 e benefício terminado em 0.

Consulta de saldo

A consulta de saldo/margem resolve o document_number em duas etapas:

1. Tenta um match exato do CPF contra a massa de teste.
2. Se não encontrar, usa o primeiro dígito do CPF como chave.

Se nenhuma das duas resolver, retorna o erro fixo:

{
    "erros": [
        {
            "codigo": "QIE",
            "mensagem": "CPF divergente da massa de teste informada na documentação."
        }
    ]
}

com HTTP 412.

Cenários por primeiro dígito (fallback)

Qualquer CPF de teste cujo primeiro dígito seja um dos abaixo cai num destes cenários genéricos — útil quando você não precisa de um CPF fixo:

1º dígito	Cenário	margemDisponivel	Status
1	Margem completa, elegível, sem bloqueios	431.3	200
2	Erro Dataprev D1 — dados do benefício incompletos/inconsistentes/nulos	—	412
3	Margem de cartão/RCC reduzida (R$ 75,90)	431.3	200
4	Margem completa (idêntico ao dígito 1)	431.3	200
8	Margem de cartão/RCC zerada	431.3	200

CPFs com primeiro dígito 0, 5, 6, 7 ou 9 (e que não tenham match exato) caem no erro QIE acima.

Além desses, o mocker reconhece 42 CPFs com match exato — a tabela completa está abaixo.

CPFs com match exato

Campos já mapeados para o schema público da QI: consigned_credit.balance vem de margemDisponivel, available_total_balance vem de valorDisponivelAverbacaoEmprestimo. Boa parte dos CPFs com retirement_invalidity_work_accident existe só pra cobrir uma faixa de valores de available_total_balance (de R$ 50 a R$ 900) — útil pra testar simulação de dívida contra um teto de margem específico.

CPF	Benefício (código)	Elegível	Situação	Bloqueio	consigned_credit.balance	available_total_balance	Status
18166261553	retirement_by_contribution_time (42) — margem negativa	Sim	ATIVO	-	-7.84	-7.84	200
30449750345	pension_by_death_statute (22)	Não	INATIVO	Bloqueado por TBM	1000	0	200
58992386400	pension_by_death_statute (22)	Não	ATIVO	Bloqueado por TBM	1000	0	200
15588881010	retirement_capin_extra_emploee (37)	Sim	ATIVO	-	1000	200	200
80436724154	retirement_invalidity_work_accident (92)	Não	INATIVO	Bloqueado por TBM	1000	5000	200
34166302540	pension_by_death_federal_emploee (27)	Não	ATIVO	Bloqueado por TBM	1000	5000	200
71020884851	pension_by_death_diplomat (20)	Não	ATIVO	Bloqueado por TBM	1000	5000	200
76241089684	retirement_invalidity_work_accident (92)	Não	ATIVO	Bloqueado por TBM	1000	5000	200
44559483922	pension_by_death (21)	Não	ATIVO	Bloqueado por TBM	1000	5000	200
14429281238	pension_by_death_statute (22)	Sim	ATIVO	-	1000	300	200
15843101037	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	2000	200
13686315092	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	2000	200
14937159097	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	50	200
15986213009	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	1000	200
17427272048	retirement_by_age (41)	Sim	ATIVO	-	1000	1600	200
16110575070	retirement_by_age (41)	Sim	ATIVO	-	1000	2000	200
14996024054	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	100	200
17702273003	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	150	200
12228342009	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	200	200
11709160071	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	250	200
12452312002	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	300	200
10650137019	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	350	200
17287554097	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	400	200
19815793039	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	450	200
11985375079	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	500	200
14732376029	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	750	200
10178596043	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	600	200
17859801060	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	650	200
11524380857	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	700	200
19447847056	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	800	200
10813389038	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	850	200
35776131499	retirement_invalidity_work_accident (92)	Sim	ATIVO	-	1000	900	200
17283313079	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	300	200
14552515004	retirement_by_age (41)	Sim	ATIVO	-	1000	300	200
14036419005	retirement_invalidity_social_security (32)	Sim	ATIVO	-	1000	300	200
13423241020	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	200	200
12382929090	retirement_special (46)	Sim	ATIVO	-	1000	200	200
73527133011	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	300	200
55111830081	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	300	200
83995332030	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	300	200
65954790019	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	300	200
16257311080	retirement_by_contribution_time (42)	Sim	ATIVO	-	1000	300	200

Todos os CPFs acima retornam bloqueadoParaEmprestimo: false, exceto os marcados com "Bloqueado por TBM" na coluna Bloqueio (que ainda assim respondem HTTP 200 com elegivelEmprestimo: false).

Exemplo de requisição (funciona com qualquer CPF da tabela):

ENDPOINT

/social_security/balance_request/synchronous

MÉTODO

POST

ENDPOINT

POST /social_security/balance_request/synchronous
{
    "document_number": "18166261553",
    "benefit_number": "2052711150"
}

Resposta (HTTP 200) para o CPF de margem negativa, já mapeada para o schema público:

{
    "assistance_type": "retirement_by_contribution_time",
    "available_total_balance": -7.84,
    "consigned_credit": {
        "balance": -7.84
    },
    "payroll_card": {
        "balance": 0,
        "limit": 2083.2
    },
    "benefit_card": {
        "balance": 0,
        "limit": 2083.2
    },
    "block_type": "not_blocked",
    "benefit_situation": "active"
}

Averbação

O envio da reserva à Dataprev é resolvido apenas pelo primeiro dígito do CPF — o número do benefício não influencia esta etapa:

1º dígito do CPF	Retorno mockado	Status
1	Sucesso BZ — "Averbação registrada"	200
2	Erro AN — "Conta corrente/DV do favorecido inválidos"	412
3	Depende do valor da operação: até R$ 1.000,00 sucesso BZ; acima disso, erro HW — "Margem consignável excedida"	200 / 412
4	Sucesso BZ — "Averbação registrada"	200

Qualquer outro primeiro dígito retorna o erro QIE ("CPF divergente da massa de teste informada na documentação"), com HTTP 412.

observação

Averbação bem-sucedida não conclui a reserva: em crédito novo e refinanciamento ela entra em anuência. Portabilidade não exige anuência e segue direto para reserved.

Anuência

Depois da averbação, crédito novo e refinanciamento ficam em pending_confirmation até a Dataprev informar a confirmação do beneficiário — veja Anuência (pending confirmation) para o fluxo e os webhooks.

Em sandbox, a resposta dessa consulta é determinada pelo último dígito do número do benefício informado na reserva:

Último dígito do benefício	Situação Dataprev simulada	Desfecho da reserva
0, 1, 6	0 — Ativo	✅ Confirmada → reserved, webhook de averbação e desembolso
5	5 — Averbação programada	✅ Confirmada → reserved
3	18 na 1ª página, 0 na 2ª	✅ Confirmada → reserved (exercita a paginação)
8	18 — Pendente de confirmação	⏳ Permanece em pending_confirmation
9	19 — Não confirmado pelo beneficiário	❌ Cancelada — social_security_confirmation_denied_by_beneficiary
7	20 — Confirmação expirada	❌ Nova tentativa de reserva ou cancelamento — social_security_confirmation_expired
2	Resposta sem registros	⏳ Permanece em pending_confirmation
4	Erro GR — "O período está inválido"	⏳ Permanece em pending_confirmation

Benefícios terminados em 2 e 4

Nesses dois cenários a consulta nunca devolve uma situação conclusiva, então a reserva fica em pending_confirmation indefinidamente e os webhooks de averbação e de pagamento não são emitidos. Se o objetivo é testar a jornada completa, use um benefício terminado em 0, 1, 3, 5 ou 6.

Portabilidade — retornos do CTC - CIP

Em sandbox a QI Tech não se conecta ao CTC - CIP: a solicitação de portabilidade não é enviada ao rail interbancário e, por consequência, nenhuma resposta do banco credor original chega sozinha. A proposta permanece no status em que ficou até que você simule o retorno com as rotas abaixo.

Só existem em sandbox

As rotas /mock/** respondem apenas em sandbox. Em produção elas retornam GDF000025, e o fluxo real é conduzido pelo CTC - CIP e pelo banco credor original.

Se a chamada retornar erro de endpoint não permitido para a sua ClientIntegration, as rotas de mock ainda não foram liberadas para a sua chave — solicite a liberação ao time de integração da QI Tech.

#	O que simula	Endpoint	event_type	Status exigido na proposta
1	Solicitação do saldo devedor	/v2/credit_transfer/proposal/{proposal_key} (PATCH)	—	pending_submission
2	Aprovação pelo CTC	/mock/credit_transfer/ctc	proposal_creation_accepted	pending_response
3	Rejeição pelo CTC	/mock/credit_transfer/ctc	proposal_creation_refused	pending_response
4	Envio do saldo devedor pelo banco de origem	/mock/credit_transfer/ctc	proposal_approval	pending_acceptance
5	Retenção pelo banco de origem	/mock/credit_transfer/ctc	proposal_retention	pending_acceptance
6	Devolução do pagamento	/mock/credit_transfer/str	payment_rejected	settlement_sent, pending_settlement_confirmation ou paid
7	Confirmação de pagamento pelo CTC	/mock/credit_transfer/ctc	settlement_confirmation	settlement_sent
8	Confirmação de pagamento pelo banco de origem	/mock/credit_transfer/ctc	payment_confirmation	pending_settlement_confirmation
9	Averbação da portabilidade	/mock/credit_transfer/collateral	—	pending_settlement_confirmation ou paid
10	Averbação do refinanciamento	/mock/credit_transfer/collateral	—	refin aceito, portabilidade averbada
11	Falha na averbação do refinanciamento	/mock/credit_transfer/collateral	—	refin aceito, portabilidade averbada
12	Falha no desembolso do refinanciamento	/mock/credit_transfer/disbursement	disbursement_failed	refin desembolsado

Os cenários 1 a 9 valem para a portabilidade pura. Os cenários 10 a 12 só se aplicam quando há refinanciamento do troco.

1. Solicitação do saldo devedor

Este passo não é um mock: é a chamada real de envio da proposta ao CTC - CIP.

Se o seu requester estiver configurado com envio manual, a proposta nasce em pending_submission depois da assinatura e só solicita o saldo devedor após esta chamada. Com envio automático, ela já nasce em pending_response e você pode ir direto para o cenário 2.

ENDPOINT

/v2/credit_transfer/proposal/PROPOSAL-KEY

MÉTODO

PATCH

request.json

{
    "status": "pending_response"
}

2. Aprovação pelo CTC

Simula o aceite da solicitação pelo CTC - CIP. A proposta vai para pending_acceptance e você recebe o webhook com o portability_number, a inclusion_date e a due_balance_expected_return_date.

ENDPOINT

/mock/credit_transfer/ctc

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_creation_accepted"
}

3. Rejeição pelo CTC

Simula a recusa da solicitação pelo CTC - CIP. A proposta vai para rejected e o webhook traz o erro ECTC0023 ("Contrato com portabilidade em andamento").

ENDPOINT

/mock/credit_transfer/ctc

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_creation_refused"
}

4. Envio do saldo devedor pelo banco de origem

Simula a resposta do banco credor original com o saldo devedor. O cenário 2 tem de ter sido enviado antes. A proposta vai para accepted e o webhook traz o final_due_balance, os dados do contrato de origem e a tarifa. A partir daí, para seguir com a operação, chame o aceite da proposta.

Todos os campos além de proposal_key e event_type são opcionais — sem eles, o mock devolve os valores usados na criação da proposta.

ENDPOINT

/mock/credit_transfer/ctc

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_approval",
    "due_balance": 9000,
    "installment_face_value": 300,
    "installment_number": 40,
    "opened_installment_number": 35,
    "overdue_installment_number": 5
}

due_balance number Saldo devedor devolvido. Padrão: o valor informado na criação da proposta. installment_face_value number Valor da parcela do contrato de origem. Padrão: o valor usado na criação da proposta. installment_number number Quantidade total de parcelas do contrato de origem. Padrão: o valor usado na criação da proposta. opened_installment_number number Parcelas em aberto. Padrão: igual ao installment_number. overdue_installment_number number Parcelas em atraso. Padrão: 0.

5. Retenção pelo banco de origem

Simula a retenção do crédito pelo banco credor original. O cenário 2 tem de ter sido enviado antes. A proposta vai para retained, com o motivo issuer_retention.

ENDPOINT

/mock/credit_transfer/ctc

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_retention"
}

6. Devolução do pagamento pelo banco de origem

Simula a devolução, via STR, do pagamento do saldo devedor. Só pode ser enviado depois de a proposta ser aceita e a operação de portabilidade desembolsada.

ENDPOINT

/mock/credit_transfer/str

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "payment_rejected"
}

7. Confirmação de pagamento pelo CTC

Simula a confirmação da liquidação pelo CTC - CIP. A proposta deve ter sido aceita e a operação de portabilidade desembolsada.

ENDPOINT

/mock/credit_transfer/ctc

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "settlement_confirmation"
}

8. Confirmação de pagamento pelo banco de origem

Simula a confirmação da quitação do contrato original. Deve ser chamado após o cenário 7.

ENDPOINT

/mock/credit_transfer/ctc

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "payment_confirmation"
}

9. Averbação da garantia da portabilidade

Simula a constituição da garantia da operação de portabilidade, após o cenário 7 ou 8.

ENDPOINT

/mock/credit_transfer/collateral

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "portability",
    "collateral_constituted": true
}

10. Averbação da garantia do refinanciamento

Simula a constituição da garantia do refinanciamento do troco. A proposta deve estar em paid ou pending_settlement_confirmation, com a garantia da portabilidade já averbada e o refinanciamento aceito.

ENDPOINT

/mock/credit_transfer/collateral

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "refinancing",
    "collateral_constituted": true
}

11. Falha na averbação da garantia do refinanciamento

Mesmas pré-condições do cenário 10. O webhook traz a garantia não constituída, em pending_requester_action, com os erros de averbação da Dataprev.

ENDPOINT

/mock/credit_transfer/collateral

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "refinancing",
    "collateral_constituted": false
}

12. Falha no desembolso do refinanciamento

Simula a devolução do desembolso do troco. A operação de refinanciamento tem de ter sido desembolsada.

ENDPOINT

/mock/credit_transfer/disbursement

MÉTODO

POST

request.json

{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "disbursement_failed"
}

Referências

• Consulta Offline de Saldo — schema de resposta completo
• Máquinas de Status — Port+Refin — o status e o webhook de cada etapa da portabilidade