Transferir para múltiplas carteiras FaciPay

Transfere valores da carteira de uma empresa parceira, como a FaciConnect, para até 500 carteiras de clientes FaciPay (particulares ou empresas). Cada destinatário recebe uma transacção. O processamento é síncrono e atómico: todas as transferências são confirmadas e os saldos movimentados antes da resposta de sucesso, ou nenhuma é executada. Não existe sucesso parcial nem identificador de lote.

Carteira de origem e disponibilidade

A origem é a carteira do parceiro associada à aplicação indicada em applicationUUID. A carteira de origem não é indicada no pedido nem pode ser alterada pelo parceiro. A aplicação tem de pertencer ao parceiro autenticado e ter uma integração activa. O serviço não exige nenhuma permissão adicional.

Pedido e validação

applicationUUID e accountValues são obrigatórios. accountValues é uma string que contém um array JSON, e não um array directamente no body. O array deve conter entre 1 e 500 objectos. Campos extra de cada item são ignorados.

Campo de cada item	Tipo	Regras
account	string	Obrigatório, até 50 caracteres. É aplicado TRIM; null e vazio são rejeitados.
value	number	Obrigatório, em AOA e estritamente maior que zero. Aceita decimais; null, zero e negativos são rejeitados.

O serviço valida o comprimento de account, sem impor prefixo ou quantidade de dígitos. A carteira de destino tem de estar activa, pertencer a uma pessoa com identidade validada e ser do tipo particular ou empresa. Outros tipos de carteira, incluindo carteiras de parceiros, são rejeitados. A carteira de origem não pode ser destinatária. Uma carteira repetida no lote rejeita o lote inteiro; os valores não são somados.

Montantes e comissões

O destinatário recebe exactamente value, sem comissões ou taxas. O saldo necessário é a soma de todos os valores. Cada value tem de ser superior a zero e o total do lote não pode exceder o saldo disponível.

Todas as carteiras e o saldo são validados antes de criar transacções. Qualquer falha, incluindo um erro inesperado durante o processamento, provoca rollback do lote inteiro.

Resposta e repetição de pedidos

body.data.items conserva a ordem do pedido e devolve account, value e transactionId por transferência. transactionId é o identificador interno da transacção FaciPay, não um identificador de lote.

Atenção: é importante que o parceiro faça a gestão dos pedidos já enviados (por exemplo, guardando localmente o lote submetido e os transactionId devolvidos) para impedir que uma mesma operação seja submetida mais do que uma vez. Em caso de timeout ou ausência de resposta, consulte o resultado antes de repetir o envio.

Erros

Os erros de negócio são Bad Request; erros inesperados são Internal Server Error. Ambos usam o envelope code/body, com body.message igual a Something went wrong, body.data e body.pagination nulos e body.error.errorMessage/body.error.detail para a mensagem e o detalhe. Os códigos HTTP e os valores numéricos de code destes dois casos estão a confirmar com a equipa FaciPay. A resposta de autenticação 401 reutiliza o formato comum já documentado. O exemplo automático de erro é parcial: omite os campos code ainda por confirmar, que continuam definidos no esquema completo.

Os números abaixo são códigos internos de mensagem, não códigos HTTP nem os valores de code do envelope. Qualquer destes erros deixa zero transferências executadas.

Situação	Código interno / mensagem	Detalhe
applicationUUID inválido ou de outro parceiro	5652: Application UUID Inválido	Application UUID inválido
Integração inactiva	5833	Integração encontra-se inactiva.
Integração sem carteira titular associada	Bad Request genérico	Conta de destino da integração não possui conta titular associada
accountValues ausente, não é array JSON ou é vazio	Bad Request genérico	Sem detalhe
Mais de 500 itens	Bad Request genérico	Máximo de 500 contas por lote
Item não é objecto; account null, vazio ou > 50 caracteres; value ausente, null ou ≤ 0	Bad Request genérico	O item em JSON
account repetido	5620: Identificamos contas duplicadas na lista. Por favor, revise e submeta apenas registos distintos.	O account
Destino inexistente, inactivo, sem validação ou de tipo não permitido	2875: Não possível validar a existência da conta destino	O account
Destino igual à origem	2830: A conta-origem não pode ser a mesma que a conta-destino.	O account
Soma dos valores superior ao saldo disponível	2831: Saldo insuficiente para realizar operação.	Sem detalhe
Erro inesperado	Internal Server Error padrão; código a confirmar	Sem detalhe

Notificações e testes

Este serviço não emite webhooks por lote ou transferência e não envia SMS nem push. Notificações genéricas da aplicação FaciPay estão a confirmar. O serviço foi testado em HML; não existe um campo de modo sandbox ou de simulação no pedido. Os testes de erro usam os dados e o saldo das carteiras desse ambiente.

Os exemplos cURL usam API_URL, ACCESS_TOKEN e o placeholder APPLICATION_UUID. Substitua-os pelos valores do ambiente de teste autorizado. Para saldo insuficiente, use carteiras de destino válidas e uma origem com saldo inferior a 2250 AOA.

A confirmar com a equipa FaciPay

• Códigos HTTP e valores numéricos de code padrão para Bad Request e Internal Server Error.
• Disponibilidade do serviço em produção.
• Aceitação de um array directo em accountValues pelo gateway HTTP; o contrato documentado recebe uma string.
• Formato oficial de account a publicar (prefixo FP e dígitos); o serviço apenas faz TRIM e valida o comprimento.
• Limites regulatórios ou de conta aplicados fora deste serviço.
• Endpoint de parceiro, se existir, para consultar uma transacção por transactionId.
• Notificações genéricas de movimentos na aplicação FaciPay para o destinatário.
• Carteiras de teste em HML disponíveis para os parceiros.