Gestão Financeira
A API de Gestão Financeira do aiqfome foi desenvolvida para centralizar, automatizar e simplificar a prestação de contas e a conciliação bancária das lojas integradas. Desenhada especificamente para atender desde lojistas individuais até grandes redes e franquias, a API opera de forma consolidada a nível corporativo (por CNPJ). Isso significa que, se um mesmo documento possuir múltiplas unidades ativas na plataforma, o parceiro integrador conseguirá extrair dados unificados de todo o grupo econômico através de uma única camada de integração.
Listar Transferências
Este endpoint retorna o histórico de transferências financeiras (repasses) realizadas para o documento cadastrado, dentro do período especificado pelo integrador.
Importante: A consulta funciona por agrupamento de CNPJ. Caso o documento possua mais de uma loja ativa na plataforma, o retorno trará consolidado os dados de todas as lojas correspondentes.
GET
/financial/transfersParâmetros da Requisição (Query Parameters)
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
start_date | ✅ | Data inicial para a busca do período (Formato: AAAA-MM-DD). Deve ser uma data anterior a end_date. |
end_date | ✅ | Data final para a busca do período (Formato: AAAA-MM-DD). Deve ser uma data posterior a start_date. |
page | ❌ | O número da página que deseja consultar (Padrão: 1). Mínimo: 1. |
size | ❌ | Quantidade de registros por página (Padrão: 10). Mínimo: 1. Máximo: 100. |
Exemplo de Resposta
{
"items": [
{
"id": 1,
"funding_date": "2026-03-03T03:00:00Z",
"account_period": {
"starts_at": "2026-03-02",
"ends_at": "2026-03-02",
"accumulated": false,
"has_d32_orders": false
},
"status": "pending",
"amount": 4.95,
"recipient_document_number": "12345678910112",
"recipient_id": "77e680c559897705b58394fdc0450ell"
},
{
"id": 2,
"funding_date": "2026-03-09T03:00:00Z",
"account_period": {
"starts_at": "2026-03-06",
"ends_at": "2026-03-06",
"accumulated": false,
"has_d32_orders": false
},
"status": "rejected",
"amount": 116.53,
"recipient_document_number": "12345678910112",
"recipient_id": "77e680c552197705b58394fdc0450ell"
},
{
"id": 3,
"funding_date": "2026-02-06T03:00:00Z",
"account_period": {
"starts_at": "2025-10-17",
"ends_at": "2025-10-17",
"accumulated": false,
"has_d32_orders": false
},
"status": "done",
"amount": 8.9,
"recipient_document_number": "31544033000126",
"recipient_id": "77e680c87ed97705b58394fdc0450ell"
},
{
"id": 4,
"funding_date": "2026-02-06T03:00:00Z",
"account_period": {
"starts_at": "2025-05-14",
"ends_at": "2025-05-14",
"accumulated": false,
"has_d32_orders": false
},
"status": "done",
"amount": 29,
"recipient_document_number": "31544033000126",
"recipient_id": "77e647c55ed97705b58394fdc0450ell"
},
{
"id": 5,
"funding_date": "2026-02-06T03:00:00Z",
"account_period": {
"starts_at": "2024-05-09",
"ends_at": "2025-10-16",
"accumulated": true,
"has_d32_orders": false
},
"status": "done",
"amount": 640513.92,
"recipient_document_number": "31544033000126",
"recipient_id": "77e110c55ed97705b58394fdc0450ell"
},
{
"id": 6,
"funding_date": "2026-02-06T03:00:00Z",
"account_period": {
"starts_at": "2025-07-13",
"ends_at": "2025-07-19",
"accumulated": false,
"has_d32_orders": false
},
"status": "done",
"amount": 600,
"recipient_document_number": "31544033000126",
"recipient_id": "77e680c55ed97705b51294fdc0450ell"
},
{
"id": 7,
"funding_date": "2026-02-06T03:00:00Z",
"account_period": {
"starts_at": "2025-10-17",
"ends_at": "2025-10-17",
"accumulated": false,
"has_d32_orders": false
},
"status": "done",
"amount": 6.2,
"recipient_document_number": "31544033000126",
"recipient_id": "77e680c55ed97705b58344fdc0350ell"
},
{
"id": 8,
"funding_date": "2026-02-06T03:00:00Z",
"account_period": {
"starts_at": "2025-06-16",
"ends_at": "2025-06-16",
"accumulated": false,
"has_d32_orders": false
},
"status": "done",
"amount": 26,
"recipient_document_number": "31544033000126",
"recipient_id": "77e680c55ed91105b58394fdc0450ell"
},
{
"id": 9,
"funding_date": "2026-01-26T03:00:00Z",
"account_period": {
"starts_at": "2026-01-18",
"ends_at": "2026-01-24",
"accumulated": false,
"has_d32_orders": true
},
"status": "done",
"amount": 525.83,
"recipient_document_number": "31544033000126",
"recipient_id": "77e680c55ed97705118394fdc0450ell"
},
{
"id": 10,
"funding_date": "2026-01-26T03:00:00Z",
"account_period": {
"starts_at": "2026-01-18",
"ends_at": "2026-01-24",
"accumulated": false,
"has_d32_orders": false
},
"status": "done",
"amount": 135.14,
"recipient_document_number": "31544033000126",
"recipient_id": "77e680c55ed97705b52294fdc0450ell"
}
],
"total": 16,
"page": 1,
"size": 10,
"pages": 2
}
Detalhamento dos Campos (Payload)
| Campo | Descrição |
|---|---|
items | Lista contendo os registros de transferências localizados. |
id | ID único identificador do repasse/transferência. |
funding_date | Data e hora programada para o depósito/pagamento (padrão ISO 8601). |
account_period.starts_at | Data de início do período de apuração das vendas deste repasse. |
account_period.ends_at | Data de término do período de apuração das vendas deste repasse. |
account_period.accumulated | Indica se há valores acumulados de ciclos anteriores não pagos. |
account_period.has_d32_orders | Identifica se o lote possui pedidos com regime de liquidação D+32. |
status | Status atual do repasse (veja a lista de estados possíveis abaixo). |
amount | Valor líquido total a ser transferido. |
recipient_document_number | Documento (CNPJ) do favorecido que receberá os valores. |
recipient_id | Identificador interno da conta do recebedor na plataforma de pagamento. |
Estados Possíveis do Repasse (status)
O campo status pode retornar um dos seguintes mapeamentos de negócio:
| Status | Descrição |
|---|---|
scheduled | Repasse agendado para execução financeira na data programada. |
pending | Repasse aguardando processamento inicial. |
approved | Transferência aprovada e aguardando execução financeira. |
rejected | Repasse rejeitado por inconsistência de dados ou regras internas. |
processing_done | Processamento interno concluído com sucesso. |
done | Transferência realizada e finalizada com sucesso. |
undone | Repasse desfeito ou estornado após tentativa de envio. |
simulation | Registro gerado apenas para fins de simulação de valores. |
blocked | Valores retidos ou bloqueados judicialmente/administrativamente. |
standby | Repasse retido temporariamente aguardando liberação. |
standby_ted | Aguardando janela de execução de TED bancária. |
standby_swift | Aguardando processamento de transferência internacional via SWIFT. |
unmapped | Estado de processamento não mapeado pelo fluxo padrão. |
calculating | Sistema realizando o fechamento e cálculo dos valores do lote. |
Resumo Detalhado do Repasse
Este endpoint fornece a visão resumida de todas as movimentações financeiras contidas em um lote de transferência específico. Ele apresenta os totais de créditos, débitos e a conta bancária para onde o valor foi enviado, preparando o cenário antes da auditoria detalhada item a item.
GET
/financial/transfers/{transferId}/detailsExemplo de Resposta
{
"id": 0,
"recipient_document_number": "99999999000199",
"status": "scheduled",
"description": "string",
"funding_date": "2026-05-20",
"account_period": {
"starts_at": "2026-05-20",
"ends_at": "2026-05-20",
"accumulated": true,
"has_d32_orders": true
},
"bank_account": {
"bank": "string",
"agency": "string",
"account": "string",
"account_digit": "string"
},
"payables": [
{
"name": "string",
"description": "string",
"amount": 0,
"type": "credit",
"redirect_to_orders_report": true,
"redirect_orders": [
{
"id": 0,
"date": "2026-05-20",
"store": {
"id": 0
}
}
],
"sequence": 999
}
],
"orders": {
"total": 0,
"count": 0
},
"total_credits": 0,
"total_debits": 0,
"remaining_balance_total_debit": 0,
"subtotal": 0,
"remaining_balance_total_credit": 0,
"total": 0
}
Detalhamento dos Campos (Payload)
Campos Principais e Período
| Campo | Descrição |
|---|---|
id | ID do repasse consultado. |
recipient_document_number | Documento (CNPJ) do favorecido que receberá os valores. |
status | Status do lote (Segue a mesma lista de estados do endpoint anterior). |
description | Descrição ou identificação textual interna do repasse. |
funding_date | Data prevista ou realizada para o depósito/pagamento (AAAA-MM-DD). |
account_period.starts_at | Data de início do período de vendas que compõe este lote. |
account_period.ends_at | Data de fim do período de vendas que compõe este lote. |
account_period.accumulated | Flag indicando se há saldo acumulado de períodos passados neste lote. |
account_period.has_d32_orders | Flag indicando a presença de pedidos com liquidação em D+32. |
Destino Financeiro e Resumo de Pedidos
| Campo | Descrição |
|---|---|
bank_account.bank | Nome ou código do banco de destino do repasse. |
bank_account.agency | Agência bancária configurada. |
bank_account.account | Número da conta corrente ou poupança. |
bank_account.account_digit | Dígito verificador da conta. |
orders.total | Valor total bruto originado apenas pelos pedidos processados. |
orders.count | Quantidade total de pedidos presentes neste repasse. |
Bloco de Lançamentos (payables[])
Este array detalha as linhas de crédito e débito aplicadas ao lote (como taxas de marketplace, estornos, mensalidades ou incentivos).
| Campo | Descrição |
|---|---|
payables[].name | Nome resumido do lançamento financeiro (Ex: "Taxa de Entrega", "Mensalidade"). |
payables[].description | Descrição detalhada sobre a origem daquele valor. |
payables[].amount | Valor do lançamento específico. |
payables[].type | Indica se o lançamento soma ou subtrai do lojista (credit ou debit). |
payables[].redirect_to_orders_report | Se true, indica que esse valor é detalhável no relatório pedido a pedido. |
payables[].redirect_orders[] | Array simplificado de referência que aponta quais lojas/pedidos geraram a linha. |
payables[].sequence | Ordem de exibição do lançamento na composição do extrato. |
Totais e Balanço Final
| Campo | Descrição |
|---|---|
total_credits | Soma absoluta de todos os lançamentos do tipo credit (entradas). |
total_debits | Soma absoluta de todos os lançamentos do tipo debit (saídas/taxas). |
subtotal | Cálculo intermediário do saldo (total_credits - total_debits). |
remaining_balance_total_debit | Saldo devedor restante que não pôde ser quitado neste lote e ficou para o próximo. |
remaining_balance_total_credit | Saldo credor restante acumulado retido no lote. |
total | Valor Líquido Final: Montante exato enviado à conta bancária do lojista. |
Conciliação de Pedidos por Repasse
Este endpoint retorna a listagem de todos os pedidos cujos valores foram consolidados no lote de transferência (transfer_id) informado. Ele suporta paginação por cursor, filtros de inclusão e a possibilidade de detalhamento profundo dos custos de cada pedido através do recurso de hidratação.
GET
/financial/transfers/{transferId}/ordersParâmetros da Requisição (Query Parameters)
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
limit | ❌ | Limite de pedidos por página (Padrão: 50). Mínimo: 1. Máximo: 100. |
cursor | ❌ | Ponteiro (token) para buscar a próxima página de registros. |
include_cancelled | ❌ | Se true, inclui pedidos que foram cancelados ou estornados no lote (Padrão: false). |
include_all_payment_types | ❌ | Se true, inclui todas as formas de pagamento (Padrão: false). |
hydrate | ❌ | Controla o nível de detalhamento dos pedidos no retorno (Padrão: false). |
Exemplo de Resposta - Pedidos por Repasse resumido
{
"recipient_document_number": "99999999000199",
"orders": [
{
"id": 68676331,
"date": "2026-02-23",
"total": 29,
"payment_type": "nupay",
"payment_term": "WEEKLY"
},
{
"id": 68676332,
"date": "2026-02-23",
"total": 57.5,
"payment_type": "pix",
"payment_term": "WEEKLY"
},
{
"id": 68676333,
"date": "2026-02-24",
"total": 112.9,
"payment_type": "credit",
"payment_term": "D32"
}
],
"nextCursor": 4
}
Exemplo de Resposta - Pedidos por Repasse detalhado
{
"recipient_document_number": "99999999000199",
"orders": [
{
"id": 68676200,
"date": "2026-02-13",
"total": 20.8,
"payment_type": "pix",
"payment_term": "WEEKLY",
"delivery_fee_chargeback": 0,
"service_fee_chargeback": 0,
"coupon_reimbursement": 0,
"platform_fee": 0,
"received_in_store": 0,
"competence_status": "Venda da competência atual",
"status": 1,
"status_label": "Concluído",
"store_name": "Aiqfome Api Teste",
"subtotal": 18,
"delivery_fee": 4.5,
"service_fee": 0,
"coupon": 0,
"commission_pct": 9.5,
"commission_value": 1.71,
"commission_includes_delivery": 0,
"free_delivery": 0,
"online_payment_tax": 2.99,
"cancelled_at": null
},
{
"id": 68676201,
"date": "2026-02-14",
"total": 45.15,
"payment_type": "credit",
"payment_term": "WEEKLY",
"delivery_fee_chargeback": 0,
"service_fee_chargeback": 0,
"coupon_reimbursement": 10,
"platform_fee": 1.5,
"received_in_store": 0,
"competence_status": "Venda da competência atual",
"status": 1,
"status_label": "Concluído",
"store_name": "Aiqfome Api Teste",
"subtotal": 50,
"delivery_fee": 6,
"service_fee": 0,
"coupon": 10,
"commission_pct": 12,
"commission_value": 6.72,
"commission_includes_delivery": 1,
"free_delivery": 0,
"online_payment_tax": 2.63,
"cancelled_at": null
},
{
"id": 68676202,
"date": "2026-02-14",
"total": 0,
"payment_type": "nupay",
"payment_term": "D32",
"delivery_fee_chargeback": 5,
"service_fee_chargeback": 0,
"coupon_reimbursement": 0,
"platform_fee": 0,
"received_in_store": 0,
"competence_status": "Venda cancelada/estornada",
"status": 2,
"status_label": "Cancelado",
"store_name": "Aiqfome Api Teste",
"subtotal": 35,
"delivery_fee": 5,
"service_fee": 0,
"coupon": 0,
"commission_pct": 9.5,
"commission_value": 0,
"commission_includes_delivery": 0,
"free_delivery": 0,
"online_payment_tax": 0,
"cancelled_at": "2026-02-14T19:22:10.000Z"
}
],
"nextCursor": 18283
}
Regra de Resposta (hydrate)
O volume de dados retornado no array de pedidos depende diretamente do valor enviado no parâmetro hydrate:
Cenário 1: hydrate = false (Dados Resumidos)
Retorna apenas as informações essenciais de identificação e valores macro de cada pedido.
Tabela de Campos (hydrate = false)
| Campo | Descrição |
|---|---|
recipient_document_number | Documento (CNPJ) do favorecido do repasse. |
orders | Array contendo a lista simplificada de pedidos. |
orders[].id | ID único do pedido na plataforma. |
orders[].date | Data de criação do pedido (AAAA-MM-DD). |
orders[].total | Valor total líquido ou repassado referente a este pedido. |
orders[].payment_type | Tipo de pagamento (offline, credit, independent, pix, nupay). |
orders[].payment_term | Prazo de recebimento/liquidação do pedido (D32, WEEKLY). |
nextCursor | Identificador da próxima página de registros. |
Cenário 2: hydrate = true (Dados Detalhados)
Enriquece o array de pedidos com a abertura completa de taxas, comissões, estornos, cupons e indicadores operacionais de cada transação.
Tabela de Campos (hydrate = true)
| Campo | Descrição |
|---|---|
recipient_document_number | Documento (CNPJ) do favorecido do repasse. |
orders[].id | ID único do pedido na plataforma. |
orders[].date | Data de criação do pedido (AAAA-MM-DD). |
orders[].total | Valor final líquido do pedido. |
orders[].payment_type | Tipo de pagamento (offline, credit, independent, pix, nupay). |
orders[].payment_term | Prazo de recebimento/liquidação do pedido (D32, WEEKLY). |
orders[].delivery_fee_chargeback | Valor de estorno/chargeback de taxa de entrega aplicada. |
orders[].service_fee_chargeback | Valor de estorno/chargeback de taxa de serviço aplicada. |
orders[].coupon_reimbursement | Valor reembolsado à loja devido ao uso de cupons da plataforma. |
orders[].platform_fee | Taxas fixas ou adicionais cobradas pela plataforma sobre o pedido. |
orders[].received_in_store | Indica o valor que foi recebido diretamente no estabelecimento físico. |
orders[].competence_status | Identificador do período de competência (Ex: "Venda da competência atual"). |
orders[].status | ID numérico do status do pedido. |
orders[].status_label | Descrição amigável do status do pedido (Ex: "Concluído"). |
orders[].store_name | Nome fantasia da loja onde o pedido foi feito. |
orders[].subtotal | Valor bruto dos itens do pedido (sem taxas ou frete). |
orders[].delivery_fee | Valor cobrado do cliente pelo frete/taxa de entrega. |
orders[].service_fee | Valor cobrado referente a taxas de serviço. |
orders[].coupon | Valor total de desconto aplicado por cupom neste pedido. |
orders[].commission_pct | Percentual (%) de comissão retido pelo marketplace sobre a venda. |
orders[].commission_value | Valor monetário correspondente à comissão retida. |
orders[].commission_includes_delivery | Indica se a comissão incide também sobre o valor da entrega (1 = Sim, 0 = Não). |
orders[].free_delivery | Indica se o pedido teve entrega grátis (1 = Sim, 0 = Não). |
orders[].online_payment_tax | Percentual ou taxa retida pelo processamento do pagamento online. |
orders[].cancelled_at | Data e hora do cancelamento (retorna null se o pedido foi concluído). |
nextCursor | Identificador da próxima página de registros. |