# QI Tech — Investment-as-a-Service › Visibilidade de caixa Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 6 página(s). Índice: - Recuperando Informações da Conta (/documentation/iaas/visibildade_de_caixa/get_accounts) - Recuperando Transações de uma Conta (/documentation/iaas/visibildade_de_caixa/get_transactions) - Introdução (/documentation/iaas/visibildade_de_caixa/inicio) - Transferência entre contas do fundo (/documentation/iaas/visibildade_de_caixa/post_internal_transfer) - Criando Pedido de Estorno (/documentation/iaas/visibildade_de_caixa/post_transaction_reversal) - Webhooks (/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal) --- # Recuperando Informações da Conta URL: /documentation/iaas/visibildade_de_caixa/get_accounts Lista as contas do fundo, com saldo, status e os tipos de transferência que cada uma aceita. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler contas | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /cash_account/fund_class/FUND_CLASS_KEY/accounts MÉTODO GET ### Query Params | Campo | Tipo | Descrição | |---------|------|-----------| | `limit` | int | Itens por página. Padrão: `10`. Máximo: `50`. | | `page` | int | Número da página (começando por zero). Padrão: `0`. | ### Response STATUS 200 ```json title='Response Body' { "data":[ { "account_key":"fdbe66e9-4b1d-4254-8473-523b8d3587be", "account_type":"checking_account", "financial_institution":{ "ispb":"32402502", "code":"329", "name":"QI Sociedade de Crédito Direto" }, "account_status":"open", "account_number":"999999", "account_digit":"9", "account_branch":"0001", "accounting_identification":1, "balance":0, "blocked_balance":0, "owner":{ "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS", "document_number":"11.222.333/0001-81" }, "owner_document_number":"11.222.333/0001-81", "account_configuration":{ "pix":true, "wire_transfer":true, "statement":true }, "billings":[] }, { "account_key":"e40dd24e-4341-4736-a868-f3e767dd6c31", "account_type":"checking_account", "financial_institution":{ "ispb":"32402502", "code":"329", "name":"QI Sociedade de Crédito Direto" }, "account_status":"open", "account_number":"77777", "account_digit":"7", "account_branch":"0001", "accounting_identification":2, "balance":0, "blocked_balance":0, "owner":{ "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS", "document_number":"11.222.333/0001-81" }, "owner_document_number":"11.222.333/0001-81", "account_configuration":{ "pix":true, "wire_transfer":true, "statement":true }, "billings":[] } ], "limit":10, "page":0, "is_last_page":true } ``` ### Response Fields | Campo | Tipo | Descrição | |---------------|--------|--------------------------------------------------------| | `data` | array | Lista de objetos de **[Account](#account)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última| ### Account | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|------------------------------------------------|------------| | `account_key` | string | Chave única identificadora da conta no sistema | 36 | | `account_type` | string | Tipo de conta | Até 50 | | `financial_institution` | JSON | Objeto de instituição financeira | - | | `account_status` | string | Status da conta | Até 50 | | `account_number` | string | Número da conta | Até 50 | | `account_digit` | string | Digito da conta | 1 | | `account_branch` | string | Agência da conta | Até 50 | | `accounting_identification` | int | Identificador ordinal da conta | - | | `balance` | int | Saldo da conta no momento | - | | `owner` | JSON | Objeto de proprietário | - | | `owner_document_number` | string | Documento do proprietário | 14 ou 18 | | `blocked_balance` | int | Saldo bloqueado, em centavos | - | | `account_configuration` | JSON | Funcionalidades habilitadas na conta: `pix`, `wire_transfer` (TED) e `statement` (extrato), cada uma `true`/`false` | - | | `billings` | array | Tarifas da conta. Nesta listagem vem sempre vazia | - | | `authorized_agents` | JSON | Agentes autorizados a operar a conta. Presente quando houver | - | :::caution **Atenção** O saldo é disponibilizado em centavos, ex.: 1234 = R$ 12,34. ::: ### Financial institution | Campo | Tipo | Descrição | Caracteres | |--------|--------|--------------------------------------------------|------------| | `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro| 8 | | `code` | string | Código da instituição financeira | 3 | | `name` | string | Nome da instituição financeira | Até 255 | ### Owner | Campo | Tipo | Descrição | Caracteres | |-------------------|--------|---------------------------|------------| | `name` | string | Nome do proprietário | até 255 | | `document_number` | string | Documento do proprietário | 14 ou 18 | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `CSH000005` | A `fund_class_key` não existe. | | 403 | `CSH000048` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperando Transações de uma Conta URL: /documentation/iaas/visibildade_de_caixa/get_transactions Lista as transações (extrato) de uma conta do fundo. Também é a forma de confirmar uma [transferência entre contas do fundo](/documentation/iaas/visibildade_de_caixa/post_internal_transfer). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler contas | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /cash_account/fund_class/FUND_CLASS_KEY/account/ACCOUNT_KEY/transactions MÉTODO GET :::info Gestora e consultoria A rota acima vale para os dois agentes: a conta precisa estar vinculada ao fundo informado em `FUND_CLASS_KEY`. A consultoria precisa ter, nesse fundo, permissão de consulta às contas, concedida pela gestora. A gestora também pode consultar sem o fundo, em `/cash_account/account/ACCOUNT_KEY/transactions`. Essa forma não está disponível para a consultoria. ::: ### Path Params | Parâmetro | Descrição | |------------------|------------------------------------------------------------------------| | `FUND_CLASS_KEY` | Chave da classe de fundo à qual a conta está vinculada | | `ACCOUNT_KEY` | Chave da conta, como retornada em **[Recuperando Informações da Conta](/documentation/iaas/visibildade_de_caixa/get_accounts)** | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "transaction_key": "ed585534-8c05-431d-b829-0dc7883b24ba", "transaction_type": "outgoing_wire_transfer", "transaction_status": "pending_conciliation", "transaction_description": "Descrição do pagamento", "amount": -70000, "transaction_datetime": "2025-01-01T14:00:00Z", "account_balance": 500000, "transaction_data": { "counter_part_account": { "owner": { "name": "Nome da Contraparte", "document_number": "***.805.49*-**" }, "account_digit": "8", "account_branch": "1", "account_number": "1234567", "financial_institution": { "code": "329", "ispb": "32402502" } } }, "account": { "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44", "account_type": "checking_account", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" }, "account_status": "open", "account_number": "3289018", "account_digit": "7", "account_branch": "0001", "accounting_identification": 1, "balance": 500000, "owner": { "name": "FUNDO TESTE", "document_number": "11.222.333/0001-81" }, "owner_document_number": "11.222.333/0001-81", "account_configuration": { "pix": true, "wire_transfer": true }, "billings": [] } }, { "transaction_key": "16c9c463-266e-4e73-b87d-efc32aa6727a", "transaction_type": "incoming_wire_transfer", "transaction_status": "reconciled", "transaction_description": "Descrição", "amount": 300000, "transaction_datetime": "2025-06-04T13:00:00Z", "account_balance": 570000, "transaction_data": { "counter_part_account": { "owner": { "name": "FUNDO TESTE", "document_number": "11.222.333/0001-81" }, "account_digit": "8", "account_branch": "73", "account_number": "567567", "financial_institution": { "code": "341", "ispb": "60701190" } } }, "account": { "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44", "account_type": "checking_account", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" }, "account_status": "open", "account_number": "3289018", "account_digit": "7", "account_branch": "0001", "accounting_identification": 1, "balance": 500000, "owner": { "name": "FUNDO TESTE", "document_number": "11.222.333/0001-81" }, "owner_document_number": "11.222.333/0001-81", "account_configuration": { "pix": true, "wire_transfer": true }, "billings": [] }, "conciliation_group": { "description": "TRANSFERÊNCIA: CONTA COBRANÇA -> CONTA PRINCIPAL", "conciliation_group_key": "1ac2921c-6c81-481b-8472-6c4126bba4bf", "conciliation_group_datetime": "2025-01-01T13:28:58Z" } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Query Params | Campo | Tipo | Descrição | |---------------|--------|----------------------------| | `status` | string | Status da transação | | `start_date` | string | Data inicial de consulta | | `end_date` | string | Data final de consulta | | `counter_part_document_number` | string | Documento da contraparte | | `limit` | int | Itens por página. Padrão: `10`. Máximo: `50`. | | `page` | int | Número da página recuperada (começando por zero) | ### Response Fields | Campo | Tipo | Descrição | |---------------|--------|--------------------------------------------------------| | `data` | array | Lista de objetos de **[Transaction](#transaction)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última| ### Transaction | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `transaction_key` | string | Chave única identificadora da transação | 36 | | `transaction_type` | string | Tipo de transação | Até 50 | | `transaction_status` | string | status da transação | Até 50 | | `transaction_description` | string | Descrição da transação fornecida pelo banco | Até 255 | | `amount` | bigint | Valor da transação vezes 100 (ex: R$1,00 == 100) | - | | `transaction_datetime` | string | Data e hora da transação | ISO 8601 | | `account_balance` | bigint | Saldo da conta após a transação | - | | `transaction_data` | JSON | Objeto com informações adicionais da transação | - | | `account` | JSON | Objeto da conta contendo a transação | - | ### Account | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|-------------------------------------|------------| | `account_key` | string | Chave única identificadora da conta | 36 | | `account_type` | string | Tipo de conta | Até 50 | | `financial_institution` | JSON | Objeto de instituição financeira | - | | `account_status` | string | Status da conta | Até 50 | | `account_number` | string | Número da conta | Até 50 | | `account_digit` | string | Digito da conta | 1 | | `account_branch` | string | Agência da conta | Até 50 | | `accounting_identification` | int | Identificador ordinal da conta | - | | `balance` | int | Saldo da conta no momento | - | | `owner` | JSON | Objeto de proprietário | - | | `owner_document_number` | string | Documento do proprietário | 14 ou 18 | :::caution **Atenção** O saldo é disponibilizado em centavos, ex.: 1234 = R$ 12,34. ::: ### Financial institution | Campo | Tipo | Descrição | Caracteres | |--------|--------|---------------------------------------------------|------------| | `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8 | | `code` | string | Código da instituição financeira | 3 | | `name` | string | Nome da instituição financeira | Até 255 | ### Owner | Campo | Tipo | Descrição | Caracteres | |-------------------|--------|---------------------------|------------| | `name` | string | Nome do proprietário | até 255 | | `document_number` | string | Documento do proprietário | 14 ou 18 | ### Conciliation Group | Campo | Tipo | Descrição | Caracteres | |-------------------------------|--------|------------------------------------------|------------| | `description` | string | Descrição da conciliação da transação | Até 255 | | `conciliation_group_key` | string | Chave única identificadora da conciliação| 36 | | `conciliation_group_datetime` | string | data e horário da conciliação | ISO 8601 | ## Erros | Código | HTTP | Causa | Como resolver | |-----------|------|-------|---------------| | CIT000018 | 401 | A consultoria não tem vínculo ativo com o fundo informado, ou não tem permissão de consulta às contas nele. | Solicitar à gestora a permissão no fundo. | | CSH000048 | 403 | A conta não está vinculada ao fundo informado, ou o fundo não pertence ao agente. | Usar o `FUND_CLASS_KEY` do fundo dono da conta, conforme a listagem de contas do fundo. | | CSH000006 | 404 | Conta não encontrada para o `ACCOUNT_KEY` informado. | Verificar se o `ACCOUNT_KEY` está correto. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Introdução URL: /documentation/iaas/visibildade_de_caixa/inicio A visibilidade das movimentações de caixa é extremamente importante para a gestão de um fundo de investimento. Nesta seção iremos explicar as ferramentas disponibilizadas para consultar as informações de contas. Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que sejam feitas as devidas liberações, tanto em sandbox quanto em produção. ## Informações de conta Nessa ferramenta é possível resgatar uma lista de informações das contas de um fundo, conforme descrito em: [5.7.2.1 Recuperando Informações da Conta](/documentation/iaas/visibildade_de_caixa/get_accounts). --- # Transferência entre contas do fundo URL: /documentation/iaas/visibildade_de_caixa/post_internal_transfer Esse recurso permite realizar uma transferência de valores entre duas contas pertencentes ao mesmo fundo, debitando a conta de origem e creditando a conta de destino. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /transfer/fund_class/{fund_class_key}/internal_transfer MÉTODO POST ### Path Params | Campo | Tipo | Descrição | |------------------|--------|------------------------------------------------| | `fund_class_key` | string | Chave única identificadora do fundo na QI DTVM | ```json title='Request Body' { "amount": 15000, "description": "Transferência para a conta de cobrança", "origin_key": "3f2b8c1d-4e5a-4b6c-8d7e-9f0a1b2c3d4e", "origin_type": "manual_transfer", "source_account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44", "target_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b", "transfer_type": "pix" } ``` ### Body Params | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `amount` | integer | obrigatório | Valor a ser transferido, em centavos (ex.: `15000` = R$ 150,00). Deve ser maior que zero. | | `description` | string | obrigatório | Descrição da transferência. Até 255 caracteres. | | `origin_key` | string | obrigatório | Seu identificador (UUID) desta transferência. Uma segunda transferência com o mesmo `origin_key` é recusada (`TSF000022`) enquanto a primeira não estiver cancelada. | | `origin_type` | string | obrigatório | Envie `manual_transfer`. | | `target_account_key` | string | obrigatório | Chave da conta a ser creditada (destino). | | `source_account_key` | string | opcional | Chave da conta a ser debitada (origem). Quando omitida, é usada a conta principal do fundo. | | `transfer_type` | string | opcional | `pix` ou `wire_transfer` (TED), limitado ao que a conta de origem suporta (veja `account_configuration` em [Recuperando Informações da Conta](/documentation/iaas/visibildade_de_caixa/get_accounts)). Padrão: `wire_transfer`. | As duas contas precisam pertencer ao fundo, estar abertas e ser diferentes entre si. ## Response STATUS 201 ```json title='Response Body' { "internal_transfer_key": "1d4c2b7a-8e9f-4a0b-b1c2-d3e4f5a6b7c8", "internal_transfer_status": "pending_validation" } ``` | Campo | Tipo | Descrição | |---|---|---| | `internal_transfer_key` | string | Identificador da transferência na QI Tech. | | `internal_transfer_status` | string | Status da transferência no momento da criação: `pending_validation`. | ## Como confirmar a transferência Esta transferência **não envia webhook** e não há endpoint para consultar seu status. Para confirmar que ela foi efetivada, consulte o extrato das contas em [Recuperando Transações de uma Conta](/documentation/iaas/visibildade_de_caixa/get_transactions): o débito aparece na conta de origem e o crédito na conta de destino, com a `description` que você enviou. Em caso de erro, reenvie a requisição: uma transferência já criada é recusada com `TSF000022`, e assim você não transfere duas vezes. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ## Erros | Status | Código | Quando acontece | |---|---|---| | 409 | `TSF000022` | Já existe transferência com este `origin_key`. Não reenvie. | | 400 | `TSF000008` | `amount` igual ou menor que zero. | | 400 | `TSF000012` | `origin_type` inválido. | | 400 | `TSF000030` | `transfer_type` inválido. | | 400 | `TSF000035` | A conta de origem não aceita este `transfer_type`. | | 400 | `TSF000049` | O caixa do fundo já foi fechado no dia. | | 400 | `TSF000020` | Uma das contas não pertence ao fundo. | | 400 | `TSF000018` | Uma das contas não está aberta. | | 400 | `TSF000036` | Conta de origem igual à de destino. | | 404 | `TSF000005` | A `fund_class_key` não existe. | | 403 | `TSF000034` | O fundo não pertence à sua gestora. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, tipo errado ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Criando Pedido de Estorno URL: /documentation/iaas/visibildade_de_caixa/post_transaction_reversal Cria um pedido de estorno (devolução) de um valor recebido na conta do fundo. O pedido passa por validação da QI Tech antes do pagamento, e o pagamento é notificado pelo [webhook de estorno](/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal). :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | -------------- | ----------------- | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /transaction_reversal/fund_class/{fund_class_key}/transaction_reversal MÉTODO POST ### Path Params | Campo | Tipo | Descrição | |------------------|--------|------------------------------------------------| | `fund_class_key` | string | Chave única identificadora do fundo na QI DTVM | ```json title='Request Body' { "amount": 125.25, "description": "Estorno - transferência indevida", "reversal_type": "pix", "reference_date": "2025-01-01", "source_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867", "origin_key": "0f8b6c2e-3d1a-4e5f-9a7b-2c4d6e8f0a1b" } ``` ### Body Params | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `amount` | number | obrigatório | Valor a ser estornado, em reais, com até duas casas decimais. Mínimo `0.01`. | | `description` | string | obrigatório | Descrição do estorno. Até 100 caracteres. | | `reversal_type` | string | obrigatório | Tipo de estorno: `pix`, `wire_transfer` (TED) ou `reversal_conciliation`. | | `reference_date` | string | obrigatório | Data de referência no formato `YYYY-MM-DD`. Não pode ser anterior à data contábil atual do fundo. | | `source_account_key` | string | condicional | Chave (UUID) da conta do fundo de onde sai o estorno. Informe este campo **ou** `source_account`. | | `source_account` | **[Account](#account)** | condicional | Dados da conta do fundo de onde sai o estorno. Alternativa a `source_account_key`. | | `transaction_key` | string | condicional | Chave (UUID) da transação recebida que será estornada. O valor é devolvido à conta que o enviou. A transação precisa estar pendente de conciliação. | | `target_account` | **[Account](#account)** | condicional | Conta de destino do estorno, quando não se usa `transaction_key`. | | `target_pix_key` | string | condicional | Chave Pix de destino. Aceita somente com `reversal_type: pix`. | | `origin_key` | string | opcional | Seu identificador (UUID) do pedido. Um segundo pedido com o mesmo `origin_key` é recusado (`TRV000033`). | | `reference_key` | string | opcional | Chave de referência da transferência a estornar no banco de origem (UUID). | | `conciliation_field` | string | opcional | Campo para conciliação em múltiplas expectativas. | | `end_to_end_id` | string | opcional | Identificador end-to-end do Pix a estornar. | | `external_key` | string | opcional | Chave única da transação a estornar no banco de origem (UUID). | | `bank_slip_settlement_group_key` | string | opcional | Chave única da liquidação de boleto a estornar no banco de origem (UUID). | :::caution Atenção - Origem: informe **exatamente um** entre `source_account_key` e `source_account`. - Destino: informe **exatamente um** entre `transaction_key`, `target_account` e `target_pix_key`. Nenhum ou mais de um devolve erro 400. ::: ### Account | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `account_number` | string | Número da conta | Até 20 | | `account_digit` | string | Dígito da conta | 1 | | `account_branch` | string | Agência da conta | Até 4 | | `financial_institution` | **[Financial Institution](#financial_institution)** | Instituição financeira | - | | `owner` | **[Owner](#owner)** | Titular da conta | - | ### Financial institution {#financial_institution} | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8 | | `code` | string | Código da instituição financeira | 3 | | `name` | string | Nome da instituição financeira | Até 255 | ### Owner | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `name` | string | Nome do titular | Até 255 | | `document_number` | string | CPF ou CNPJ do titular, com pontuação | 14 ou 18 | ## Response STATUS 201 A resposta ecoa os campos enviados e acrescenta os dados abaixo. ```json title='Response Body' { "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1", "amount": 125.25, "status": "pending_validation", "reversal_type": "pix", "origin_type": "manual", "reference_date": "2025-01-01", "description": "Estorno - transferência indevida", "source_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "source_account": { "owner": { "name": "Nome do Fundo", "document_number": "11.222.333/0001-81" }, "account_digit": "8", "account_branch": "0001", "account_number": "1234567", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" } }, "target_account": { "owner": { "name": "Nome do Remetente", "document_number": "969.698.790-03" }, "account_digit": "1", "account_branch": "0001", "account_number": "7654321", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" } }, "fund_class": { "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487", "name": "Nome do Fundo", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-01", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "22.333.444/0001-81" } }, "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867", "origin_key": "0f8b6c2e-3d1a-4e5f-9a7b-2c4d6e8f0a1b" } ``` | Campo | Tipo | Descrição | |---|---|---| | `transaction_reversal_key` | string | Identificador do estorno na QI Tech (UUID). | | `status` | string | `pending_validation` (aguarda validação da QI Tech) ou `pending_expectation_confirmation` (já aprovado, em processamento). O [webhook de estorno](/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal) é enviado quando o estorno é pago (`paid`) ou quando é descartado depois de aprovado. Um pedido reprovado na validação passa a `discarded` sem webhook. | | `source_account`, `target_account` | object | Contas de origem e de destino resolvidas. | | `fund_class` | object | Dados do fundo. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 409 | `TRV000033` | Já existe pedido com este `origin_key`. Não reenvie: o estorno já foi solicitado. | | 400 | `TRV000020` | `reference_date` anterior à data contábil do fundo. | | 400 | `TRV000019` | `reversal_type` inválido. | | 400 | `TRV000009` | `amount` com mais de duas casas decimais. | | 400 | `TRV000015` / `TRV000016` | Conta de origem ausente, ou informada de mais de uma forma. | | 400 | `TRV000017` / `TRV000018` | Destino ausente, ou informado de mais de uma forma. | | 404 | `TRV000013` | A conta de origem não foi encontrada. | | 404 | `TRV000021` | A `transaction_key` não foi encontrada na conta de origem. | | 400 | `TRV000022` | A transação não está pendente de conciliação (já foi conciliada ou estornada). | | 400 | `TRV000023` | A transação não tem os dados da conta de quem enviou; informe `target_account`. | | 400 | `TRV000025` | `target_pix_key` enviado com `reversal_type` diferente de `pix`. | | 404 | `TRV000026` | A chave Pix de destino não foi encontrada. | | 404 | `TRV000005` | A `fund_class_key` não existe. | | 403 | `TRV000012` | O fundo não está associado ao seu cadastro de cedente. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, tipo errado ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Webhooks URL: /documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal Webhooks do tipo `transaction_reversal.transaction_reversal_status_change`, enviados à gestora do fundo e ao cedente associado. Para validar a assinatura, veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). Só dois eventos geram webhook: o estorno pago e o estorno descartado depois de aprovado. Um pedido reprovado na validação da QI Tech passa a `discarded` sem webhook. ## Estorno pago STATUS paid Enviado quando o pagamento do estorno é confirmado. ```json title='Webhook Body' { "data":{ "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1", "amount": 123.45, "status": "paid", "description": "Valor de liquidação indevido", "reference_date": "2025-03-23", "fund_class_document_number": "11.222.333/0001-81", "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487", "source_account": { "account_digit": "7", "account_branch": "0001", "account_number": "0099999", "owner": { "name": "FUNDO DE INVESTIMENTO", "document_number": "11.222.333/0001-81" }, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" } }, "target_account":{ "owner": { "name": "Nome fictício", "document_number": "969.698.790-03" }, "account_digit": "0", "account_branch": "0001", "account_number": "1029490", "target_pix_key": "1232221", "financial_institution": { "code": "033", "ispb": "90400888", "name": "BCO SANTANDER (BRASIL) S.A." } }, "external_key":"40054daa-c3c5-49cd-add7-858b576c5887" }, "webhook_type":"transaction_reversal.transaction_reversal_status_change", "webhook_datetime":"2025-03-23T15:08:30Z" } ``` ## Estorno descartado STATUS discarded Enviado quando um estorno já aprovado é descartado antes do pagamento. O payload é o mesmo do estorno pago, com `status` igual a `discarded`. ## Campos de `data` | Campo | Tipo | Descrição | |---|---|---| | `transaction_reversal_key` | string | Identificador do estorno na QI Tech (UUID). | | `amount` | number | Valor do estorno, em reais. | | `status` | string | `paid` ou `discarded`. | | `description` | string | Descrição informada no pedido. | | `reference_date` | string | Data de referência do estorno (`YYYY-MM-DD`). | | `fund_class_document_number` | string | CNPJ do fundo. | | `fund_class_key` | string | Chave do fundo. | | `source_account` | object | Conta de origem do estorno. | | `target_account` | object | Conta de destino do estorno. | | `external_key` | string | Identificador do pagamento do estorno. Só no estorno pago, quando houver. | | `conciliation_field` | string | Campo de conciliação enviado no pedido. Presente quando houver. | | `transaction_key` | string | Transação estornada. Presente quando houver. | | `reference_key` | string | Chave de referência. Presente quando houver. | | `origin_key` | string | O `origin_key` enviado no pedido. Presente quando houver. |