Como debitar e creditar o saldo de uma Subconta via API?

info

Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta

O saldo de uma subconta é uma reserva dentro do saldo da conta principal. Você pode mover valores entre a subconta e a conta principal, sem sair da Woovi, com dois endpoints:

• POST /api/v1/subaccount/{id}/debit: tira o valor da subconta e devolve para a conta principal.
• POST /api/v1/subaccount/{id}/credit: tira o valor do saldo disponível da conta principal e coloca na subconta.

Você pode acessar a documentação de cada endpoint em debit e credit.

Um caso comum de uso do débito: em uma cobrança com split para subconta, o estorno parcial é descontado da conta principal. O /debit permite retirar da subconta a parte correspondente.

A chave Pix registrada na subconta deve ser passada na url da requisição como parâmetro ({id}).

Os campos da requisição são os mesmos nos dois endpoints:

• value (obrigatório): O valor em centavos a ser movimentado. Deve ser um número inteiro maior que zero (500, não "500" nem 5.00).
• description (opcional): Uma descrição da movimentação, que aparece no extrato da subconta.

Permissões

A sua aplicação (AppID) precisa ter o escopo correspondente:

• /debit: SUBACCOUNT_DEBIT_POST
• /credit: SUBACCOUNT_CREDIT_POST

Nos dois endpoints, a aplicação também pode precisar ter IPs permitidos cadastrados. Quando essa exigência está ativa para a sua conta, uma aplicação sem IP permitido recebe 401.

Exemplo

O body da sua requisição será semelhante a este exemplo:

{
  value: 500,
  description: 'Estorno parcial pedido 1234',
}

Se tudo ocorreu bem, o status code será 200 e a resposta terá este formato:

{
  "pixKey": "[email protected]",
  "value": 500,
  "description": "Estorno parcial pedido 1234",
  "success": "A retirada da subconta foi debitada com sucesso, 500"
}

Erros

As mensagens de erro e de sucesso vêm no idioma configurado na sua empresa. Na tabela, o texto em português e, entre parênteses, a mensagem em inglês. Algumas mensagens só existem em inglês.

Status	Erro	Quando acontece
400	value deve ser um integer (value must be an integer)	value ausente, em texto ou com casas decimais
400	O valor deve ser maior que 0 (The value must be greater than 0)	value zero ou negativo
400	Subconta não encontrada: {id} (Subaccount not found: {id})	Não existe subconta ativa com essa chave Pix na sua empresa
400	Transferir apenas trabalhe com a subconta com saldo (Transfer just work with subaccount with balance)	/debit em uma subconta com saldo zero
400	Account does not have enough balance to complete the operation	/debit com valor maior que o saldo da subconta
400	Saldo insuficiente (Not enough balance)	/credit com valor maior que o saldo disponível da conta principal
400	Erro ao criar crédito de subconta (Error when creating subaccount credit)	/credit sem conta principal padrão configurada na empresa
401	Um IP permitido é obrigatório nesta aplicação para enviar dinheiro (An allowed IP is required on this application to move money out)	Aplicação sem IP permitido, quando a exigência está ativa para a sua conta
403	This feature is not enabled for your company	A empresa não tem a funcionalidade Subconta

atenção

Estes endpoints não possuem chave de idempotência. Não há correlationID: cada requisição aceita gera uma nova movimentação. Se a requisição der timeout e você reenviar, o valor pode ser movimentado duas vezes.

Para evitar duplicidade, coloque um identificador único no campo description e, antes de tentar de novo, consulte o extrato da subconta em GET /api/v1/subaccount/{id}/statement (escopo SUBACCOUNT_STATEMENT_GET). Se já existir um lançamento com esse description, a movimentação anterior foi feita e não deve ser repetida.

Exemplos em código

Shell + cURL

  curl 'https://api.woovi.com/api/v1/subaccount/[email protected]/debit' -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "Authorization: AUTHORIZATION" \
      --data-binary '{
        "value": 500,
        "description": "Estorno parcial pedido 1234"
      }'

JavaScript + Fetch

fetch('https://api.woovi.com/api/v1/subaccount/[email protected]/debit', {
  method: 'POST',
  body: JSON.stringify({
    value: 500,
    description: 'Estorno parcial pedido 1234',
  }),
  headers: {
    Authorization: 'AUTHORIZATION',
    'Content-Type': 'application/json',
  },
}).then((res) => res.json());

Para creditar a subconta, use a mesma requisição trocando /debit por /credit.