Como Funciona o COMEX

Este documento descreve os fluxos necessários para a integração de cobranças corporativas (BolePix e BoleCripto) e detalha as notificações assíncronas (Webhooks) geradas ao final de cada processo financeiro.

A operação é estruturada em dois passos fundamentais para garantir assertividade: o estágio inicial de rascunho (onde os valores, impostos e devedores são definidos) e o estágio final de emissão que gera os QR Codes e inicia a espera da liquidação de forma assíncrona. Além disso, disponibiliza gerenciamento paralelo para agilizar envios.

1. Moedas e Comportamentos Aceitos

Na criação e na execução de cobranças, a API permite mesclar faturamento nacional com tecnologias de ativos digitais. O sistema suporta nativamente a conversão entre o listado abaixo.

• BRL (Real): Liquidação primária padrão por PIX.

• USDT (Tether) e USDC (USD Coin): Utilizados para precificação dolarizada. Na emissão, a taxa de conversão cambial é congelada para a geração do QR Code ou carteira.

Existem duas naturezas de faturamento que regem o comportamento da cobrança:

• STATIC: Valor fechado e inegociável. A liquidação ocorre de imediato quando o montante integral é alcançado pelo sistema bancário.

• DYNAMIC: Valor aberto, sujeito à alteração no momento que o cliente final insere o montante na sua agência/aplicativo. A aprovação referencial fica pendente até aceitação.

2. Criação da Cobrança (Draft)

O faturamento exige a construção do corpo da nota descrevendo o montante do destino, produtos ou custos logotísticos. O serviço integrado precisa obrigatoriamente submeter esse registro para validação, resultando num esqueleto de cobrança que ainda não aciona redes financeiras.

Endpoint: POST /charges

Autenticação Obrigatória: Sim (Header Authorization)

2.1 Parâmetros Obrigatórios e Opcionais (Body Params)

2.2 Exemplo de Submissão

{
  "chargeType": "STATIC",
  "issueDate": "2026-04-20",
  "dueDate": "2026-05-20",
  "description": "Consultoria Técnica Mensal",
  "documentCurrency": "BRL",
  "language": "PT",
  "customerId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "items": [
    {
      "name": "Serviços de Desenvolvimento e Suporte",
      "quantity": 1,
      "unitPrice": 150000, 
      "currency": "BRL"
    }
  ]
}

2.3 Exemplo do Rascunho Criado

{
  "id": "e21b72e0-25fc-4217-a9a3-a71dd2392700",
  "status": "DRAFT",
  "amount": 150000,
  "issueDate": "2026-04-20T00:00:00.000Z",
  "dueDate": "2026-05-20T00:00:00.000Z",
  "items": [...]
}

3. Emissão dos Dados Bancários (Execução)

A aprovação definitiva e a geração dos meios físicos de recebimento processam-se através deste endpoint. Após invocado, valores não podem ser ajustados e as plataformas Cripto/Baas são instruídas ativamente.

Endpoint: POST /charges/{id}/emit

Autenticação Obrigatória: Sim (Header Authorization)

3.1 Corpo da Requisição Base (JSON)

Se desejar acionar as carteiras Cripto simultaneamente ao fluxo natural do BolePix (BRL), declare os blocos. Sem o bloco cryptoOption, apenas PIX nativo é alocado.

{
  "cryptoOption": {
    "token": "USDT",
    "network": "Polygon",
    "blockchain": "Polygon"
  }
}

3.2 Exemplo de Finalização Pendente de Recebimento

A requisição finaliza na entrega segura (status PENDING). No payload encontra-se o fator de trava "invoiceNumber", o Payload PIX copia/cola a repassar via frontend.

{
  "id": "e21b72e0-25fc-4217-a9a3-a71dd2392700",
  "status": "PENDING",
  "amount": 150000,
  "invoiceNumber": "INV2026-9A43AE-00001",
  "pixCopyPaste": "00020101021226101br.gov.bcb.pix...",
  "pixQrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "cryptoOptions": [
    {
       "token": "USDT",
       "network": "Polygon",
       "walletAddress": "0xABC1234FDEF..."
    }
  ]
}

4. Gerenciamento e Consultas de Cobrança

Para garantir transparência, múltiplos endpoints de gestão em tempo real foram agrupados para facilitar o dia a dia.

4.1. Consultar Múltiplas Ordens de Cobrança

Endpoint: GET /charges

Autenticação Obrigatória: Sim (Header Authorization)

Query Params Aceitos: page, limit, status (PAID, PENDING, etc), chargeType, e search (Procura tanto pelo invoiceNumber quanto description).

4.2. Consultar Detalhes Específicos

Endpoint: GET /charges/{id}

Autenticação Obrigatória: Sim (Header Authorization)

Retorna os arrays internos por completo (items, taxas, customer info) de uma determinada fatura solicitada em tempo real (Polling seguro).

4.3. Cancelar a Ocorrência

Endpoint: PATCH /charges/{id}/cancel

Autenticação Obrigatória: Sim (Header Authorization)

Substituirá forçadamente transações ativas (DRAFT, PENDING ou PARTIAL) tornando pagamentos retroativos inválidos nos baas. Não requer carga de Body.

4.4. Forçar Liquidação de Charge Dinâmica

Endpoint: PATCH /charges/{id}/confirm-payment

Autenticação Obrigatória: Sim (Header Authorization)

Exclusivo para Charges DYNAMIC onde liquidações precisam vir da aceitação humana da operação, convertendo-a a PAID. Exemplo de Submissão:

{
  "paidAmount": 120000,
  "paymentMethod": "PIX",
  "notes": "Acordo firmado pelo setor CS."
}

5. Endpoints de Apoio Periférico

Evitam redundâncias garantindo que seu painel reutilize cadastros e produtos de maneira ágil injetando identificadores ao invés de represar dados estáticos a cada invoice.

5.1. Gestão de Clientes / Pagadores

Endpoint: POST /charge-customers (Utiliza GET ou PATCH no mesmo prefixo). Ao criar uma corporação/lead, a plataforma emite um UUID associativo aceito na raiz do endpoint /charges (customerId).

{
  "name": "Corporação Alpha LTDA",
  "document": "45.000.000/0001-99",
  "email": "finance@alpha.com"
}

5.2. Catálogo Fixado de Itens (SKUs)

Endpoint: POST /charge-item-catalog (Utiliza GET ou PATCH no mesmo prefixo). Produtos de rotatividade alta não requerem listarem tributos em todas requisações de emissão. Crie-os como padrão e direcione apenas sua referência na fatura.

{
  "name": "Manutenção Padrão de Servidor",
  "defaultPrice": 500000,
  "defaultCurrency": "BRL",
  "ncmHsCode": "8471.00.00"
}

6. Retornos Assíncronos via Webhook

Para impedir que a sua aplicação faça varreduras de gargalo na plataforma em busca dos status concluídos (polling), toda operação confirmada aciona o canal ativo de Push Webhook a cada alteração severa. O payload subirá diretamente de volta ao URL provisionado nas configurações da conta de API.

6.1 Captador Evento Inicial: pix.deposit.confirmed

Você receberá atualizações constantes com base em como o núcleo validador avança para a liberação final de saldo de entrada. A proteção da carga é dada pelo Cabeçalho da Ordem assediada com o parâmetro integrador de assinatura. Ao bater no seu endpoint, avalie em paralelo se providerReferenceId está atrelado ao invoiceNumber esperado na sua plataforma.

6.2 Exemplo do Payload Transmitido (JSON)

{
  "id": "e0a0210e-8f2c-47ea-bd2e-50f1bb765b20",
  "eventType": "pix.deposit.confirmed",
  "timestamp": 1776211200000,
  "data": {
    "event": "pix.deposit.confirmed",
    "timestamp": "2026-04-20T19:00:00.000Z",
    "data": {
      "pix": {
        "id": "f5e957cb-1234-5678-abcd-ef0987654321",
        "amount": 150000,
        "status": "CONFIRMED",
        "providerReferenceId": "INV2026-9A43AE-00001",
        "e2e": "E33923751202604201900pA1B2C3D4E5",
        "executedAt": "2026-04-20T19:00:05.123Z",
        "senderInfo": {
          "name": "ACME CORP BRASIL LIMITADA",
          "document": "45.000.***-99"
        }
      }
    }
  }
}

6.3 Fases Evolutivas da Ocorrência

• DRAFT: Limitar-se a operações lógicas de precificação. Não repasse status aos clientes finais.

• PENDING / PROCESSING: Estágio nativo de espera transitória. Acionamento de rede aguardando compensação das chaves bancárias fornecidas pós Emissão.

• PARTIAL: Anomalias numéricas. Valor recebido atendeu parcialmente as normativas da precificação originária. Limitado à renegociação de dinâmica aberta ou devolução.

• PAID / COMPLETED: Ciclo consolidado de sucesso. Saldo contábil repousa no caixa interno pós-impostos (Net) e pode ser reutilizado perante o gateway.

• CANCELLED: Interrupção terminal, invalidando qualquer Pix Copia-Cola exibido na tela do consumidor.