Manual de Integração - API BelloCard

🚀 REDE BELLOCARD

Manual de Integração - API de Conciliação

Versão 3.0.0 Janeiro/2026

Controle de Versão

Data	Descrição	Versão	Responsável
08/01/2020	Documento inicial	1.0	Manoel Adriano
20/09/2022	Adicionando nova Conciliadora - NEXXERA	2.3	Manoel Adriano
05/12/2022	Informações de PayLoad da Conciliadora NEXXERA	2.5	Manoel Adriano
28/02/2023	Melhoria no retorno quando não há movimentações	2.7	Manoel Adriano
01/03/2023	Atualização do XML de retorno	2.8	Manoel Adriano
14/04/2025	Incluindo parâmetro `cod_rede`	2.8.1	Manoel Adriano
01/07/2025	Descrição de campos de retorno	2.8.2	Manoel Adriano
19/01/2026	Endpoint de paginação (`getMovimentacaoPaginada`)	3.0.0	Guilherme Arguelho

Visão Geral

Este manual orienta você sobre como integrar-se com a API BelloCard para consultar movimentações financeiras (vendas, antecipações e ajustes).

REST API

Integração via Web Service REST com autenticação Bearer Token

Multiplataforma

Compatível com ASP, .Net, Java, PHP, Ruby, Python e outras

Paginação

Endpoint otimizado para grandes volumes de dados

Sandbox

Ambiente de homologação público para testes

Pré-requisitos

Antes de iniciar a integração, certifique-se de ter:

Token de autenticação (Bearer Token)
CNPJ do lojista cadastrado na Rede BelloCard
Ambiente de desenvolvimento com suporte a requisições HTTPS
Conhecimento básico de APIs REST e formato JSON

URL do Endpoint:

http://api.sandbox.redebellocard.com.br/conciliador.php

Token de Teste:

BC27571MS_5244_&7124478303245331396280==

Autenticação

A API utiliza Bearer Authentication (Token Authentication). Envie o token no cabeçalho Authorization de todas as requisições.

Formato do Cabeçalho

POST /conciliador.php HTTP/1.1
Host: api.sandbox.redebellocard.com.br
Content-Type: application/json;charset=utf-8
Authorization: Bearer BC27571MS_5244_&7124478303245331396280==

Exemplo de Conexão (Python)

import http.client
import json

conn = http.client.HTTPSConnection("api.sandbox.redebellocard.com.br")

payload = json.dumps({
    "serviceId": "statusService"
})

headers = {
    'Content-Type': 'application/json;charset=utf-8',
    'Authorization': 'Bearer BC27571MS_5244_&7124478303245331396280=='
}

conn.request("POST", "/conciliador.php", payload, headers)
response = conn.getresponse()
data = response.read()

print(data.decode("utf-8"))

Serviços Disponíveis

Serviço	`serviceId`	Descrição
Teste de Conectividade	`statusService`	Verifica se a API está operacional
Consulta Movimentações	`getMovimentacao`	Consulta movimentações em um período (sem paginação)
Consulta Paginada	`getMovimentacaoPaginada`	Consulta movimentações com controle de paginação

Teste de Conectividade

Use este serviço para verificar se a API está operacional antes de iniciar suas consultas.

Requisição

{
  "serviceId": "statusService"
}

Resposta de Sucesso

{
  "erro": false,
  "msg": "CONEXÃO REALIZADA COM SUCESSO - API de Serviços de BelloCard"
}

Consulta de Movimentações

A API oferece dois endpoints para consultar movimentações. Escolha o mais adequado para sua necessidade:

Consulta Simples (`getMovimentacao`)

Retorna todas as movimentações de uma única vez. Adequado para:

Períodos curtos (até 7 dias)
Baixo volume de transações
Consultas pontuais

Parâmetros de Entrada

Parâmetro	Tipo	Obrigatório	Descrição
`serviceId`	String	Sim	Valor fixo: `"getMovimentacao"`
`dtInicial`	String	Sim	Data inicial (YYYY-MM-DD)
`dtFinal`	String	Sim	Data final (YYYY-MM-DD)
`cnpjLojista`	String	Sim	CNPJ do lojista (apenas números)
`fornecer_rede`	String	Não	`"TRUE"` para toda a rede, `"FALSE"` apenas o lojista
`tp_cartao`	String	Não	Filtro por tipo: `1` (Convênio), `2` (Benefício), `3` (Vale Gás), `4` (Alimentação), `5` (Frota)

Exemplo de Requisição

{
  "serviceId": "getMovimentacao",
  "dtInicial": "2022-01-01",
  "dtFinal": "2022-01-31",
  "cnpjLojista": "12123123000125",
  "fornecer_rede": "FALSE",
  "tp_cartao": ""
}

Consulta Paginada (`getMovimentacaoPaginada`) ⭐

Retorna as movimentações em páginas controláveis. Recomendado para:

Períodos longos (> 7 dias)
Alto volume de transações
Integrações automáticas e processos em lote
Qualquer cenário onde confiabilidade é prioridade

Parâmetros de Entrada

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`serviceId`	String	Sim	Valor fixo: `"getMovimentacaoPaginada"`	`"getMovimentacaoPaginada"`
`dtInicial`	String	Sim	Data inicial (YYYY-MM-DD)	`"2022-01-01"`
`dtFinal`	String	Sim	Data final (YYYY-MM-DD)	`"2022-01-31"`
`cnpjLojista`	String	Condicional	CNPJ do lojista	`"12123123000125"`
`cod_rede`	String	Condicional	Código da rede do lojista	`"1234"`
`fornecer_rede`	String	Não	`"TRUE"` ou `"FALSE"` (padrão)	`"FALSE"`
`tp_cartao`	String	Não	`"CREDITO"`, `"DEBITO"`, `"VR"`, `"VA"`	`"DEBITO"`
`pagina`	Integer	Sim	Número da página (inicia em 1)	`1`
`itens_por_pagina`	Integer	Sim	Registros por página	`100`

Campos Adicionais na Resposta

Campo	Tipo	Descrição
`eof`	Boolean	`true` = última página, `false` = há mais páginas

Exemplo de Requisição

{
  "serviceId": "getMovimentacaoPaginada",
  "dtInicial": "2022-01-01",
  "dtFinal": "2022-01-31",
  "cnpjLojista": "12123123000125",
  "fornecer_rede": "FALSE",
  "tp_cartao": "DEBITO",
  "pagina": 1,
  "itens_por_pagina": 100
}

Implementando a Paginação

Fluxo de Consumo

Inicie com pagina = 1

Configure sua primeira requisição com pagina: 1 e o itens_por_pagina desejado (recomendado: 100).
Faça a requisição

Envie a requisição POST com todos os parâmetros obrigatórios.
Processe os dados retornados

Armazene ou processe os arrays vendas, antecipacoes e ajustes da resposta.
Verifique o campo eof
- Se eof = false: incremente pagina e volte ao passo 2
- Se eof = true: você chegou ao fim dos dados
Finalize a consulta

Consolide todos os dados coletados de todas as páginas.

Diagrama do Fluxo

┌─────────────────────────┐
│   Início: pagina = 1    │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│  Fazer requisição com   │
│       pagina = N        │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   Processar resposta    │
│  (vendas, antecipacoes, │
│        ajustes)         │
└───────────┬─────────────┘
            │
            ▼
       ┌────────────┐
       │ eof = true │
       │     ?      │
       └─────┬──────┘
             │
     ┌───────┴───────┐
     │               │
    Sim             Não
     │               │
     ▼               ▼
┌─────────┐   ┌──────────────┐
│   FIM   │   │ pagina += 1  │
└─────────┘   └──────┬───────┘
                     │
                     └──────────────┐
                                    │
            ┌───────────────────────┘
            │
            ▼
   (volta para "Fazer requisição")

Exemplos de Código

import http.client
import json

def consultar_movimentacoes_paginadas(dt_inicial, dt_final, cnpj_lojista,
                                       fornecer_rede="FALSE", tp_cartao=None):
    """
    Consulta todas as movimentações usando paginação automática.
    """
    conn = http.client.HTTPSConnection("api.sandbox.redebellocard.com.br")
    headers = {
        'Content-Type': 'application/json;charset=utf-8',
        'Authorization': 'Bearer BC27571MS_5244_&7124478303245331396280=='
    }

    todas_vendas = []
    todas_antecipacoes = []
    todosAjustes = []
    pagina = 1
    itens_por_pagina = 100

    while True:
        # Monta o payload
        payload = {
            "serviceId": "getMovimentacaoPaginada",
            "dtInicial": dt_inicial,
            "dtFinal": dt_final,
            "cnpjLojista": cnpj_lojista,
            "fornecer_rede": fornecer_rede,
            "pagina": pagina,
            "itens_por_pagina": itens_por_pagina
        }

        if tp_cartao:
            payload["tp_cartao"] = tp_cartao

        # Faz a requisição
        conn.request("POST", "/conciliador.php", json.dumps(payload), headers)
        res = conn.getresponse()
        data = res.read()
        response = json.loads(data.decode("utf-8"))

        # Verifica erro
        if response.get('erro'):
            print(f"Erro: {response.get('msg')}")
            break

        # Acumula os dados
        vendas = response.get('vendas', [])
        antecipacoes = response.get('antecipacoes', [])
        ajustes = response.get('ajustes', [])

        todas_vendas.extend(vendas)
        todas_antecipacoes.extend(antecipacoes)
        todosAjustes.extend(ajustes)

        print(f"Página {pagina}: {len(vendas)} vendas")

        # Verifica fim dos dados
        if response.get('eof', True):
            print("Consulta concluída!")
            break

        pagina += 1

    conn.close()

    return {
        'vendas': todas_vendas,
        'antecipacoes': todas_antecipacoes,
        'ajustes': todosAjustes
    }

# Uso
resultado = consultar_movimentacoes_paginadas(
    dt_inicial="2022-01-01",
    dt_final="2022-01-31",
    cnpj_lojista="12123123000125"
)

print(f"Total de vendas: {len(resultado['vendas'])}")

<?php

function consultarMovimentacoesPaginadas($dtInicial, $dtFinal, $cnpjLojista,
                                          $fornecerRede = "FALSE", $tpCartao = null) {
    $url = 'http://api.sandbox.redebellocard.com.br/conciliador.php';
    $token = 'BC27571MS_5244_&7124478303245331396280==';

    $todasVendas = [];
    $todasAntecipacoes = [];
    $todosAjustes = [];
    $pagina = 1;
    $itensPorPagina = 100;

    while (true) {
        // Monta o payload
        $payload = [
            'serviceId' => 'getMovimentacaoPaginada',
            'dtInicial' => $dtInicial,
            'dtFinal' => $dtFinal,
            'cnpjLojista' => $cnpjLojista,
            'fornecer_rede' => $fornecerRede,
            'pagina' => $pagina,
            'itens_por_pagina' => $itensPorPagina
        ];

        if ($tpCartao) {
            $payload['tp_cartao'] = $tpCartao;
        }

        // Faz a requisição
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($payload),
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json;charset=utf-8',
                'Authorization: Bearer ' . $token
            ],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 300
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);

        // Verifica erro
        if ($data['erro'] ?? false) {
            echo "Erro: " . $data['msg'] . "\n";
            break;
        }

        // Acumula os dados
        $vendas = $data['vendas'] ?? [];
        $antecipacoes = $data['antecipacoes'] ?? [];
        $ajustes = $data['ajustes'] ?? [];

        $todasVendas = array_merge($todasVendas, $vendas);
        $todasAntecipacoes = array_merge($todasAntecipacoes, $antecipacoes);
        $todosAjustes = array_merge($todosAjustes, $ajustes);

        echo "Página $pagina: " . count($vendas) . " vendas\n";

        // Verifica fim dos dados
        if ($data['eof'] ?? true) {
            echo "Consulta concluída!\n";
            break;
        }

        $pagina++;
    }

    return [
        'vendas' => $todasVendas,
        'antecipacoes' => $todasAntecipacoes,
        'ajustes' => $todosAjustes
    ];
}

// Uso
$resultado = consultarMovimentacoesPaginadas('2022-01-01', '2022-01-31', '12123123000125');

echo "Total de vendas: " . count($resultado['vendas']) . "\n";

?>

const https = require('https');

async function consultarMovimentacoesPaginadas(dtInicial, dtFinal, cnpjLojista,
                                                fornecerRede = 'FALSE', tpCartao = null) {
    const todasVendas = [];
    const todasAntecipacoes = [];
    const todosAjustes = [];
    let pagina = 1;
    const itensPorPagina = 100;

    while (true) {
        // Monta o payload
        const payload = {
            serviceId: 'getMovimentacaoPaginada',
            dtInicial,
            dtFinal,
            cnpjLojista,
            fornecer_rede: fornecerRede,
            pagina,
            itens_por_pagina: itensPorPagina
        };

        if (tpCartao) {
            payload.tp_cartao = tpCartao;
        }

        const options = {
            hostname: 'api.sandbox.redebellocard.com.br',
            port: 443,
            path: '/conciliador.php',
            method: 'POST',
            headers: {
                'Content-Type': 'application/json;charset=utf-8',
                'Authorization': 'Bearer BC27571MS_5244_&7124478303245331396280=='
            }
        };

        // Faz a requisição
        const response = await new Promise((resolve, reject) => {
            const req = https.request(options, (res) => {
                let data = '';
                res.on('data', (chunk) => { data += chunk; });
                res.on('end', () => {
                    try {
                        resolve(JSON.parse(data));
                    } catch (e) {
                        reject(e);
                    }
                });
            });
            req.on('error', reject);
            req.write(JSON.stringify(payload));
            req.end();
        });

        // Verifica erro
        if (response.erro) {
            console.log(`Erro: ${response.msg}`);
            break;
        }

        // Acumula os dados
        const vendas = response.vendas || [];
        const antecipacoes = response.antecipacoes || [];
        const ajustes = response.ajustes || [];

        todasVendas.push(...vendas);
        todasAntecipacoes.push(...antecipacoes);
        todosAjustes.push(...ajustes);

        console.log(`Página ${pagina}: ${vendas.length} vendas`);

        // Verifica fim dos dados
        if (response.eof) {
            console.log('Consulta concluída!');
            break;
        }

        pagina++;
    }

    return {
        vendas: todasVendas,
        antecipacoes: todasAntecipacoes,
        ajustes: todosAjustes
    };
}

// Uso
(async () => {
    const resultado = await consultarMovimentacoesPaginadas(
        '2022-01-01',
        '2022-01-31',
        '12123123000125'
    );
    console.log(`Total de vendas: ${resultado.vendas.length}`);
})();

Estrutura de Dados da Resposta

A resposta da API é um objeto JSON unificado contendo arrays para cada tipo de movimentação (vendas, antecipacoes, liquidacoes, ajustes), além de metadados de paginação.

Dicionário de Dados

Array de vendas realizadas no período.

Campo	Tipo	Descrição
`cnpj_parceiro`	String	CNPJ do estabelecimento onde ocorreu a venda
`data_venda`	String	Data e hora da transação
`nome_parceiro`	String	Razão social ou nome fantasia do estabelecimento
`valor_venda`	String	Valor bruto da transação
`valor_liquido_parcela`	String	Valor líquido a receber (descontada a taxa)
`numero_parcela`	String	Número da parcela atual (ex: “1”)
`nome_bandeira`	String	Bandeira do cartão (ex: “BELLOCARD”)
`tipo_produto`	String	Tipo do benefício (`ALIMENTACAO`, `REFEICAO`, etc)
`order_id`	String	Identificador único da transação na conciliadora
`detalhes_venda.nsu`	String	Número Sequencial Único da transação
`detalhes_venda.codigo_autorizacao`	String	Código de autorização da transação

Array de antecipações de recebíveis contratadas.

Campo	Tipo	Descrição
`data_credito`	String	Data em que o valor foi creditado
`valor_venda`	String	Valor original da venda antecipada
`valor_taxa_antecipacao`	String	Valor da taxa cobrada pela antecipação
`valor_liquido`	String	Valor final recebido após desconto da taxa
`identificador_produto`	String	Identificador do produto antecipado

Lançamentos de crédito ou débito (ex: cancelamentos, aluguel de POS).

Campo	Tipo	Descrição
`detalhes_ajuste.motivo_ajuste`	String	Descrição do motivo (ex: “CANCELAMENTO”)
`detalhes_ajuste.indicador_ajuste`	String	`CREDITO` ou `DEBITO`
`valor_venda`	String	Valor do ajuste
`data_pagamento`	String	Data efetiva do ajuste financeiro

Exemplo de Resposta Completa

{
    "vendas": [
        {
            "cnpj_parceiro": "09477652001249",
            "data_venda": "02/09/2023 21:49:40",
            "nome_parceiro": "COMPER LJ71",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "28.25",
            "valor_comissao": "0.42",
            "valor_liquido_parcela": "27.83",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "896062",
            "cnpj_lojista": "09477652001249",
            "codigo_terminal": "",
            "tipo_produto": "ALIMENTACAO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652001249",
                "data_venda": "02/09/2023 21:49:40",
                "data_pagar": "07/10/2026",
                "numero_cartao": "6090********0012",
                "valor_bruto": "28.25",
                "valor_liquido": "27.83",
                "valor_comissao": "0.42",
                "codigo_autorizacao": "480517",
                "hora_venda": "21:49:40",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "954447651",
                "codigo_terminal": "",
                "nsu": "000028400160",
                "id_fepas": "000317",
                "order_id": "896062"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652001249",
                    "data_pagamento": "07/10/2026",
                    "numero_parcela": "1",
                    "valor_bruto": "28.25",
                    "valor_comissao": "0.42",
                    "valor_liquido": "27.83",
                    "order_id": "896062"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652006399",
            "data_venda": "01/09/2023 21:02:24",
            "nome_parceiro": "COMPER LJ134",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "72.97",
            "valor_comissao": "1.09",
            "valor_liquido_parcela": "71.88",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "895467",
            "cnpj_lojista": "09477652006399",
            "codigo_terminal": "",
            "tipo_produto": "CONVENIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652006399",
                "data_venda": "01/09/2023 21:02:24",
                "data_pagar": "08/01/2024",
                "numero_cartao": "6090********0085",
                "valor_bruto": "72.97",
                "valor_liquido": "71.88",
                "valor_comissao": "1.09",
                "codigo_autorizacao": "079617",
                "hora_venda": "21:02:24",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "945952937",
                "codigo_terminal": "",
                "nsu": "000018450115",
                "id_fepas": "500139",
                "order_id": "895467"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652006399",
                    "data_pagamento": "08/01/2024",
                    "numero_parcela": "1",
                    "valor_bruto": "72.97",
                    "valor_comissao": "1.09",
                    "valor_liquido": "71.88",
                    "order_id": "895467"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652004264",
            "data_venda": "01/09/2023 19:41:25",
            "nome_parceiro": "FORT LJ170",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "130.48",
            "valor_comissao": "1.95",
            "valor_liquido_parcela": "128.53",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "895438",
            "cnpj_lojista": "09477652004264",
            "codigo_terminal": "",
            "tipo_produto": "BENEFICIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652004264",
                "data_venda": "01/09/2023 19:41:25",
                "data_pagar": "07/10/2026",
                "numero_cartao": "6090********0070",
                "valor_bruto": "130.48",
                "valor_liquido": "128.53",
                "valor_comissao": "1.95",
                "codigo_autorizacao": "392208",
                "hora_venda": "19:41:25",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "157622631",
                "codigo_terminal": "",
                "nsu": "000018400121",
                "id_fepas": "500215",
                "order_id": "895438"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652004264",
                    "data_pagamento": "07/10/2026",
                    "numero_parcela": "1",
                    "valor_bruto": "130.48",
                    "valor_comissao": "1.95",
                    "valor_liquido": "128.53",
                    "order_id": "895438"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652004264",
            "data_venda": "01/09/2023 14:58:35",
            "nome_parceiro": "FORT LJ170",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "162.78",
            "valor_comissao": "2.44",
            "valor_liquido_parcela": "160.34",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "895170",
            "cnpj_lojista": "09477652004264",
            "codigo_terminal": "",
            "tipo_produto": "CONVENIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652004264",
                "data_venda": "01/09/2023 14:58:35",
                "data_pagar": "08/01/2024",
                "numero_cartao": "6090********9605",
                "valor_bruto": "162.78",
                "valor_liquido": "160.34",
                "valor_comissao": "2.44",
                "codigo_autorizacao": "365936",
                "hora_venda": "14:58:35",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "328299861",
                "codigo_terminal": "",
                "nsu": "000018450043",
                "id_fepas": "500109",
                "order_id": "895170"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652004264",
                    "data_pagamento": "08/01/2024",
                    "numero_parcela": "1",
                    "valor_bruto": "162.78",
                    "valor_comissao": "2.44",
                    "valor_liquido": "160.34",
                    "order_id": "895170"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652000510",
            "data_venda": "01/09/2023 11:47:38",
            "nome_parceiro": "FORT  LJ76",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "16.00",
            "valor_comissao": "0.24",
            "valor_liquido_parcela": "15.76",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "895070",
            "cnpj_lojista": "09477652000510",
            "codigo_terminal": "",
            "tipo_produto": "BENEFICIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652000510",
                "data_venda": "01/09/2023 11:47:38",
                "data_pagar": "07/10/2026",
                "numero_cartao": "6090********0043",
                "valor_bruto": "16.00",
                "valor_liquido": "15.76",
                "valor_comissao": "0.24",
                "codigo_autorizacao": "144887",
                "hora_venda": "11:47:38",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "404479989",
                "codigo_terminal": "",
                "nsu": "000018400030",
                "id_fepas": "500042",
                "order_id": "895070"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652000510",
                    "data_pagamento": "07/10/2026",
                    "numero_parcela": "1",
                    "valor_bruto": "16.00",
                    "valor_comissao": "0.24",
                    "valor_liquido": "15.76",
                    "order_id": "895070"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652000510",
            "data_venda": "01/09/2023 11:32:49",
            "nome_parceiro": "FORT  LJ76",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "194.00",
            "valor_comissao": "2.91",
            "valor_liquido_parcela": "191.09",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "895061",
            "cnpj_lojista": "09477652000510",
            "codigo_terminal": "",
            "tipo_produto": "BENEFICIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652000510",
                "data_venda": "01/09/2023 11:32:49",
                "data_pagar": "07/10/2026",
                "numero_cartao": "6090********0043",
                "valor_bruto": "194.00",
                "valor_liquido": "191.09",
                "valor_comissao": "2.91",
                "codigo_autorizacao": "796287",
                "hora_venda": "11:32:49",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "354944216",
                "codigo_terminal": "",
                "nsu": "000018450025",
                "id_fepas": "500040",
                "order_id": "895061"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652000510",
                    "data_pagamento": "07/10/2026",
                    "numero_parcela": "1",
                    "valor_bruto": "194.00",
                    "valor_comissao": "2.91",
                    "valor_liquido": "191.09",
                    "order_id": "895061"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652000510",
            "data_venda": "01/09/2023 11:01:03",
            "nome_parceiro": "FORT  LJ76",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "77.44",
            "valor_comissao": "1.16",
            "valor_liquido_parcela": "76.28",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "895045",
            "cnpj_lojista": "09477652000510",
            "codigo_terminal": "",
            "tipo_produto": "BENEFICIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652000510",
                "data_venda": "01/09/2023 11:01:03",
                "data_pagar": "07/10/2026",
                "numero_cartao": "6090********0250",
                "valor_bruto": "77.44",
                "valor_liquido": "76.28",
                "valor_comissao": "1.16",
                "codigo_autorizacao": "847148",
                "hora_venda": "11:01:03",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "925695557",
                "codigo_terminal": "",
                "nsu": "000018400025",
                "id_fepas": "500033",
                "order_id": "895045"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652000510",
                    "data_pagamento": "07/10/2026",
                    "numero_parcela": "1",
                    "valor_bruto": "77.44",
                    "valor_comissao": "1.16",
                    "valor_liquido": "76.28",
                    "order_id": "895045"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652013093",
            "data_venda": "01/09/2023 08:45:13",
            "nome_parceiro": "FORT LJ 315",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "8.97",
            "valor_comissao": "0.13",
            "valor_liquido_parcela": "8.84",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "894981",
            "cnpj_lojista": "09477652013093",
            "codigo_terminal": "",
            "tipo_produto": "BENEFICIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652013093",
                "data_venda": "01/09/2023 08:45:13",
                "data_pagar": "07/10/2026",
                "numero_cartao": "6090********0375",
                "valor_bruto": "8.97",
                "valor_liquido": "8.84",
                "valor_comissao": "0.13",
                "codigo_autorizacao": "621750",
                "hora_venda": "08:45:13",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "775234714",
                "codigo_terminal": "",
                "nsu": "000018450011",
                "id_fepas": "500018",
                "order_id": "894981"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652013093",
                    "data_pagamento": "07/10/2026",
                    "numero_parcela": "1",
                    "valor_bruto": "8.97",
                    "valor_comissao": "0.13",
                    "valor_liquido": "8.84",
                    "order_id": "894981"
                }
            ]
        },
        {
            "cnpj_parceiro": "09477652010906",
            "data_venda": "01/09/2023 07:11:26",
            "nome_parceiro": "FORT LJ 470",
            "codigo_banco": "237",
            "codigo_agencia": "3686",
            "codigo_conta_corrente": "1006525",
            "valor_venda": "26.00",
            "valor_comissao": "0.39",
            "valor_liquido_parcela": "25.61",
            "numero_parcela": "1",
            "nome_bandeira": "BELLOCARD ADMINISTRADORA DE CARTOES",
            "order_id": "894947",
            "cnpj_lojista": "09477652010906",
            "codigo_terminal": "",
            "tipo_produto": "CONVENIO",
            "detalhes_venda": {
                "cnpj_parceiro": "09477652010906",
                "data_venda": "01/09/2023 07:11:26",
                "data_pagar": "08/01/2024",
                "numero_cartao": "6090********8248",
                "valor_bruto": "26.00",
                "valor_liquido": "25.61",
                "valor_comissao": "0.39",
                "codigo_autorizacao": "710126",
                "hora_venda": "07:11:26",
                "quantidade_parcelas": "1",
                "origem_venda": "TEF",
                "codigo_transacao": "392591313",
                "codigo_terminal": "",
                "nsu": "000018400003",
                "id_fepas": "500002",
                "order_id": "894947"
            },
            "parcelas": [
                {
                    "cnpj_parceiro": "09477652010906",
                    "data_pagamento": "08/01/2024",
                    "numero_parcela": "1",
                    "valor_bruto": "26.00",
                    "valor_comissao": "0.39",
                    "valor_liquido": "25.61",
                    "order_id": "894947"
                }
            ]
        }
    ],
    "antecipacoes": [
        {
            "cnpj_parceiro": "",
            "data_venda": "",
            "codigo_banco": "",
            "codigo_agencia": "",
            "codigo_conta_corrente": "",
            "data_credito": "",
            "valor_venda": "",
            "valor_comissao": "",
            "valor_liquido": "",
            "tipo_movimento": "",
            "parcela": "",
            "codigo_bandeira": "",
            "order_id": "",
            "cnpj_lojista": "",
            "identificador_produto": "",
            "valor_total": "",
            "valor_taxa_antecipacao": "",
            "tipo_lancamento": "",
            "detalhes_antecipacao": {
                "cnpj_parceiro": "",
                "data_pagamento": "",
                "valor_antecipado": "",
                "codigo_banco": "",
                "codigo_agencia": "",
                "conta_corrente": "",
                "data_venda": "",
                "valor_liquido_parcela": "",
                "data_vencimento_parcela": "",
                "numero_parcela": "",
                "valor_bruto_parcela": "",
                "valor_taxa_parcela": "",
                "order_id": "",
                "nsu": ""
            }
        }
    ],
    "liquidacoes": [
        {
            "cnpj_parceiro": "",
            "data_venda": "",
            "nome_parceiro": "",
            "codigo_banco": "",
            "codigo_agencia": "",
            "codigo_conta": "",
            "data_pagamento": "",
            "valor_bruto": "",
            "valor_comissao": "",
            "valor_liquido": "",
            "numero_parcela": "",
            "nome_bandeira": "",
            "order_id": "",
            "cnpj_lojista": "",
            "codigo_terminal": "",
            "tipo_produto": "",
            "nsu": ""
        }
    ],
    "ajustes": [
        {
            "cnpj_parceiro": "09477652014731",
            "data_venda": "02/09/2023 20:00:38",
            "codigo_banco": "",
            "codigo_agencia": "",
            "conta_corrente_ajuste": "",
            "data_pagamento": "25/09/2026",
            "valor_venda": "280.00",
            "valor_comissao": "4.2",
            "valor_liquido": "275.8",
            "parcela": "1",
            "order_id": "896050",
            "cnpj_lojista": "09477652014731",
            "detalhes_ajuste": {
                "cnpj_parceiro": "09477652014731",
                "cnpj_parceiro_ajustado": "",
                "nsu": "182927153",
                "data_venda": "02/09/2023 20:00:38",
                "data_cancelamento": "02/09/2023 20:00:38",
                "valor_venda_ajustado": "280.00",
                "order_id": "896050",
                "order_id_ajustado": "896050",
                "data_venda_ajustado": "02/09/2023 20:00:38",
                "valor_venda": "280.00",
                "valor_venda_cancelada": "280.00",
                "numero_parcela": "1",
                "valor_comissao": "4.2",
                "motivo_ajuste": "CANCELAMENTO DE TRANSACAO",
                "descricao_ajuste": "CANCELAMENTO DE TRANSACAO",
                "indicador_ajuste": "CREDITO",
                "data_pagamento": "25/09/2026",
                "id_fepas": "000290"
            }
        }
    ],
    "pagina": 1,
    "eof": true,
    "total_registros": 10,
    "total_paginas": 1,
    "qtde_vendas_retornadas": 10
}

Tratamento de Erros

Tabela de Erros

Código	Mensagem	Causa	Solução
01	`Serviço não identificado!`	`serviceId` inválido ou ausente	Verifique o valor do `serviceId`
02	`Nosso serviço está fora ar!`	API temporariamente indisponível	Aguarde e tente novamente
03	`Parâmetros obrigatórios ausentes!`	Faltam parâmetros na requisição	Confira todos os campos obrigatórios
04	`Não foram encontradas Movimentações no Período Informado!`	Sem dados no período	Verifique o período consultado
05	`Rede do Lojista informada não encontrada - 060`	`cod_rede` inválido	Confirme o código da rede
06	`Acesso não autorizado - 002`	Token inválido ou ausente	Verifique o cabeçalho `Authorization`

Exemplos de Resposta de Erro

// Erro 01 - Serviço não identificado
{
  "erro": true,
  "msg": "Serviço não identificado!"
}

// Erro 06 - Acesso não autorizado
{
  "erro": true,
  "msg": "Acesso não autorizado - 002"
}

Problemas Comuns e Soluções

Loop Infinito na Paginação

Sintoma: O código consulta a mesma página indefinidamente.

Causas:

Não está incrementando a variável pagina
Não está verificando o campo eof

Solução:

# ❌ ERRADO
pagina = 1
while True:
    response = fazer_requisicao(payload)
    # Esqueceu de incrementar!

# ✅ CORRETO
pagina = 1
while True:
    payload["pagina"] = pagina
    response = fazer_requisicao(payload)

    if response.get('eof'):
        break

    pagina += 1  # Não esqueça!

Perda de Dados

Sintoma: O total de vendas é menor que o esperado.

Causas:

Parando o loop antes de eof = true
Ignorando páginas sem vendas (mas com antecipações/ajustes)

Solução:

# ❌ ERRADO - Para quando não há vendas
if not vendas:
    break  # Pode haver antecipações/ajustes!

# ✅ CORRETO - Para apenas quando eof = true
if response.get('eof'):
    break

Timeout na Requisição

Sintoma: A requisição expira antes de receber resposta.

Solução:

Configure um timeout mínimo de 300 segundos
Reduza o itens_por_pagina para 50 em conexões lentas

Configurações Recomendadas

Tamanho da Página

Cenário	`itens_por_pagina`	Motivo
Padrão	`100`	Equilíbrio entre performance e requisições
Conexão Lenta	`50`	Reduz risco de timeout
Alto Volume	`200`	Menos requisições totais

Checklist de Implementação

Token configurado no cabeçalho Authorization
Content-Type definido como application/json;charset=utf-8
pagina iniciando em 1 (não em 0)
itens_por_pagina definido (recomendado: 100)
Pelo menos um informado: cnpjLojista ou cod_rede
Datas no formato YYYY-MM-DD
Loop verificando campo eof para parar
Incremento de pagina a cada iteração
Timeout configurado (mínimo 300 segundos)

Comparativo: Tradicional vs Paginado

Aspecto	`getMovimentacao`	`getMovimentacaoPaginada`
Risco de Timeout	⚠️ Alto com muitos dados	✅ Baixo
Uso de Memória	⚠️ Pode exceder limites	✅ Controlado
Controle	❌ Tudo ou nada	✅ Página por página
Performance	⚠️ Pode degradar	✅ Consistente
Recomendação	Períodos < 7 dias	Sempre que possível

Suporte

Para dúvidas ou problemas com a integração:

Email: adm@bellocard.com.br
Telefone: (67) 3326-6510 | (67) 9 9892-9178
Horário: Segunda a Sexta, 8h às 17h

Links Úteis

Ambiente de Homologação: http://api.sandbox.redebellocard.com.br/conciliador.php
Token de Homologação: BC27571MS_5244_&7124478303245331396280==

Versão 3.0.0 | Última atualização: Janeiro/2026

Manual de Integração - API BelloCard

🚀 REDE BELLOCARD

Manual de Integração - API de Conciliação

Controle de Versão

Visão Geral

Pré-requisitos

Ambientes Disponíveis

Autenticação

Formato do Cabeçalho

Exemplo de Conexão (Python)

Serviços Disponíveis

Teste de Conectividade

Requisição

Resposta de Sucesso

Consulta de Movimentações

Consulta Simples (getMovimentacao)

Parâmetros de Entrada

Exemplo de Requisição

Consulta Paginada (getMovimentacaoPaginada) ⭐

Parâmetros de Entrada

Campos Adicionais na Resposta

Exemplo de Requisição

Implementando a Paginação

Fluxo de Consumo

Diagrama do Fluxo

Exemplos de Código

Estrutura de Dados da Resposta

Dicionário de Dados

Exemplo de Resposta Completa

Tratamento de Erros

Tabela de Erros

Exemplos de Resposta de Erro

Problemas Comuns e Soluções

Loop Infinito na Paginação

Perda de Dados

Timeout na Requisição

Configurações Recomendadas

Tamanho da Página

Checklist de Implementação

Comparativo: Tradicional vs Paginado

Suporte

Links Úteis

Consulta Simples (`getMovimentacao`)

Consulta Paginada (`getMovimentacaoPaginada`) ⭐