Mocks (Sandbox)

Sandbox militar usa Zetra real de homologação

Ao contrário do SIAPE, o military-payroll-api em sandbox NÃO usa mocks locais. Em sandbox a integração aponta para o endpoint Host-a-Host de homologação da Zetra (eConsig):

Sandbox: https://www.econsig.com.br/central_homologa/services/HostaHostService-v8_0?wsdl
Produção: https://api.econsig.com.br/central/services/HostaHostService

Os dados de teste (CPFs, matrículas, tokens) são fornecidos pela própria Zetra via planilha de homologação oficial. Suporte Zetra: suporte@econsig.com.br.

Convênio QI Sociedade — Exército Brasileiro

Item	Valor
Cliente	`QI_SOCIEDADE`
Convênio	`QI_SOCIEDADE-EB`
Usuário API	`qi_sociedade_xml`
Senha API	`qi12345`
Código Serviço	`001`
Descrição Serviço	`EMPRÉSTIMO`
Código Verba	`ZQD`

Servidores de Teste

Servidores fictícios cadastrados na Zetra homologação. Todos com senha do servidor = abc123.

Cenário: Margem Negativa

Servidor sem margem disponível — toda tentativa de reserva retorna falha.

#	Matrícula	CPF	Data Nascimento
1	`132722899`	`279.315.128-98`	1983-04-01
2	`143320397`	`213.628.178-05`	1978-02-17

Cenário: Margem Limite R$ 500,00

Margem reduzida — útil para testar limites e validação INSUFFICIENT_MARGIN.

#	Matrícula	CPF	Data Nascimento
3	`346578694`	`432.108.069-00`	1997-04-21
4	`982435311`	`432.108.069-00`	1993-03-20

[!info] Matrículas 3 e 4 compartilham o mesmo CPF — útil para testar cenário "mesmo militar, múltiplas matrículas/órgãos".

Cenário: Margem Limite R$ 10.000,00

Margem confortável — usar para testar fluxos completos de margem livre, refinanciamento e portabilidade.

#	Matrícula	CPF	Data Nascimento
5	`346578694`	`540.770.447-15`	1997-04-21
6	`961683333`	`734.119.817-68`	1963-04-09

Cenário: BLOQUEADO

Servidor com bloqueio em folha — Zetra retorna military_blocked (código 352).

#	Matrícula	CPF	Data Nascimento
7	`234674321`	`045.672.387-02`	1975-01-01
8	`342542124`	`472.635.472-87`	1964-03-06

Como mapear nos payloads QI

Quando construir o payload de POST /military_payroll/balance:

{
  "document_number": "27931512898",
  "registration_code": "132722899",
  "authorization_document_key": "<document_key do POST /upload>",
  "token": "abc123"
}

document_number — CPF sem máscara (remova . e - da tabela acima).
registration_code — matrícula direto da tabela.
token — senha do servidor (abc123 para todos os testes).
authorization_document_key — upload de qualquer PDF/PNG; em sandbox a Zetra não valida o conteúdo do termo.

Webhook esperado por cenário

Cenário	Webhook `military_payroll.balance.status_change`
Margem Negativa (1, 2)	`status: failed`, `failure_reason: invalid_balance` ou `consignable_margin_exceeded`
Margem Limite R$ 500 (3, 4)	`status: succeeded`, `balance: 500.00`, `allowed_installment_numbers: [...]`
Margem Limite R$ 10.000 (5, 6)	`status: succeeded`, `balance: 10000.00`, `allowed_installment_numbers: [...]`
BLOQUEADO (7, 8)	`status: failed`, `failure_reason: military_blocked` (Zetra 352)
CPF/matrícula fora da tabela	`status: failed`, `failure_reason: military_not_found` (Zetra 293) ou `invalid_registration_code` (Zetra 210)

Fluxo end-to-end recomendado

Para validar margem livre, use teste 5 ou teste 6 (margem alta):

POST /upload com PDF qualquer → document_key.
POST /military_payroll/balance com 27931512898 (margem negativa, pra testar failure) ou 54077044715 (margem 10k).
Aguardar webhook military_payroll.balance.status_change.
Em caso de sucesso, POST /debt_simulation com installment_face_value ≤ balance retornado.
POST /debt com reservation_method: creation (margem livre) ou refinancing (port/refin).
Aguardar webhook credit_operation.collateral (successfully_accepted → successfully_reserved).
POST /debt/{KEY}/signed com QI Sign ou data-signature opt-in.
Aguardar webhook debt (disbursed).
(opcional cancelamento) PATCH /debt/{KEY}/cancel dentro de 7 dias úteis → recebe PIX QR → simular pagamento → webhook reversal.

Para testar portabilidade com contrato externo, combine teste 5 ou 6 com um original_contract_number fictício (Zetra homologação aceita strings arbitrárias nesse campo durante port em sandbox).

Códigos Zetra observados em sandbox

Código	Mensagem	Mapeamento na QI
`000`	Operação realizada com sucesso	`succeeded`
`210`	Matrícula inválida	`invalid_registration_code`
`241`	Erro de comunicação	`communication_error` (QI retenta automaticamente)
`293`	Militar não encontrado	`military_not_found`
`352`	Militar bloqueado em folha	`military_blocked`
`359`	Margem consignável excedida	`consignable_margin_exceeded`
`360`	Margem disponível verificada	retorno de `consultarMargem`

Operação 24/7 em sandbox

A Zetra em homologação opera 24h/dia, todos os dias — sem janela operacional restrita (mesmo comportamento da produção).

Reset de reservas

Reservas Zetra em homologação persistem indefinidamente salvo cancelamento explícito. Limpe seu ambiente cancelando as reservas que não forem necessárias (PATCH /debt/{KEY}/cancel).

Não há mocks locais ativos

O arquivo src/connectors/zetra_mocker.py no repo military-payroll-api existe mas não é invocado no fluxo de runtime — EconsigConnector chama diretamente o ECONSIG_SERVICE_ADDRESS configurado por ambiente. Se algum dia for necessário introduzir mocks locais (ex: Zetra fora do ar bloqueando QA), o ZetraMocker está disponível para ser ativado, mas hoje toda integração de teste passa pela Zetra real de homologação.

Convênio QI Sociedade — Exército Brasileiro​

Servidores de Teste​

Cenário: Margem Negativa​

Cenário: Margem Limite R$ 500,00​

Cenário: Margem Limite R$ 10.000,00​

Cenário: BLOQUEADO​

Como mapear nos payloads QI​

Webhook esperado por cenário​

Fluxo end-to-end recomendado​

Códigos Zetra observados em sandbox​

Operação 24/7 em sandbox​

Reset de reservas​

Não há mocks locais ativos​