Transferências Internas (Sicredi -> Sicoob)

Documentação técnica e de regras de negócio para o fluxo de transferências de saída Sicredi para entrada Sicoob.

Visão Geral

Este módulo permite que contas originárias do banco Sicredi enviem valores via Pix para contas do banco Sicoob dentro da plataforma, realizando o processamento bancário real enquanto mantém o sincronismo do livro razão (ledger) interno.

Regras de Negócio

1. Restrições de Bancos

• Origem (Sender): A conta autenticada que inicia a transferência deve estar vinculada ao banco Sicredi (slug: sicredi).
• Destino (Receiver): A conta receptora deve estar vinculada ao banco Sicoob (slug: sicoob).
• Bloqueio: Transferências entre outros bancos (ex: Sicredi -> Sicredi ou Sicoob -> Sicoob) não são permitidas por este endpoint específico.

2. Identificação e Segurança

• O destino é identificado pelo token da conta (UUID de 36 caracteres).
• A conta de destino deve possuir uma Chave Pix (key_pix) válida e configurada.
• O documento do destinatário (document) deve estar devidamente cadastrado no Sicoob.

3. Política de Taxas e Saldo

• Isenção: Operação isenta de taxas (tax_pix_out e tax_pix_in).
• Saldo: No momento do envio, a conta de origem deve ter saldo livre igual ou superior ao amount solicitado no ledger (balanço lógico).

4. Processamento Bancário

• O sistema utiliza a API Multipag do Sicredi.
• Identificador Fixo: O documento do pagador na API Sicredi é sempre 05796581000133.
• Atomicidade: Os registros de Débito (Sicredi) e Crédito (Sicoob) são criados apenas após a API Sicredi retornar status RECEBIDO.

---

Integração Frontend

Detalhes do Endpoint

• URL: POST /api/v1/transfers/internal
• Auth: Requer Header Authorization: Bearer \{token\} e a conta injetada via middleware.

Parâmetros da Requisição (Body JSON)

Campo	Tipo	Obrigatório	Descrição
token	String	Sim	O token único da conta Sicoob de destino.
amount	Numeric	Sim	Valor da transferência (ex: 150.50). Mínimo 0.01.
description	String	Não	Mensagem que aparecerá no extrato de ambos os usuários.

Possíveis Erros e Respostas

HTTP Status	Causa Comum	Mensagem de Exemplo
403 Forbidden	Conta de origem não é Sicredi.	"Apenas contas Sicredi podem realizar transferências através deste endpoint."
400 Bad Request	Conta de destino não é Sicoob.	"A conta de destino deve ser Sicoob para esta transferência."
400 Bad Request	Saldo insuficiente.	"Saldo insuficiente. Necessário R$ 100.00."
400 Bad Request	Destino sem chave Pix.	"A conta de destino não possui uma chave Pix configurada."
422 Unprocessable	Erro de validação de campos.	"O token da conta de destino é obrigatório."
400 Bad Request	Erro na API do Sicredi.	"Erro Sicredi: Limite diário excedido."
500 Internal Error	Falha de comunicação/token.	"Falha de comunicação com o banco de origem."

Exemplo de Fluxo de Erro (Saldo)

{
    "success": false,
    "message": "Saldo insuficiente. Necessário R$ 500.00.",
    "data": null
}

Exemplo de Sucesso

{
    "success": true,
    "message": "Transferência Realizada com sucesso via Pix (Isenta de Taxas).",
    "data": {
        "txid": "E1234567890123456789012345678901",
        "amount": 150.50,
        "status": "REALIZED"
    }
}

---

Observações para o Desenvolvedor Frontend

1. Feedback Visual: Devido à chamada externa para a API do Sicredi, este endpoint pode demorar entre 2 a 5 segundos para responder. Recomenda-se o uso de um loading state no botão de confirmação.
2. Confirmação de Destino: Antes de chamar este endpoint, sugere-se uma chamada de consulta (se disponível) para mostrar o nome do beneficiário ao usuário baseado no token, evitando envios para contas erradas.
3. Limite de Descrição: O campo description é limitado a 255 caracteres por segurança e padronização dos bancos.