Ativação - Documentação da API Fire Banking

Visão Geral

O modo PIX Bacen inclui duas funcionalidades que precisam ser ativadas:

Endpoints BACEN: Acesso aos endpoints compatíveis com a especificação do Banco Central
Webhooks V2: Novo formato de notificações com envelope {type, data}

A ativação do modo PIX Bacen é uma breaking change. Os webhooks passam a usar um formato completamente diferente. Certifique-se de atualizar sua integração antes de solicitar a ativação.

Como Solicitar Ativação

1. Entre em contato com o suporte

Envie um email para suporte@firebanking.com.br com:

Nome da empresa
CNPJ
Client ID da aplicação
Confirmação de que já implementou suporte ao Webhook V2

2. Aguarde a configuração

Nossa equipe irá:

Ativar o modo PIX Bacen na sua conta
Habilitar os endpoints e o formato de webhook V2
Confirmar a ativação por email

3. Teste a integração

Após a ativação:

Faça uma cobrança teste via PUT /cob/:txid
Verifique se o webhook V2 chegou corretamente
Confirme que sua aplicação processou o novo formato

O que muda com a ativação?

Endpoints

Você passa a ter acesso aos endpoints BACEN:

Antes	Depois
`POST /pix/cash-in`	`PUT /cob/:txid`
`POST /pix/cash-out`	`POST /dict/pix`
`POST /pix/:id/refund`	`PUT /pix/:e2eid/devolucao/:id`
`GET /balance`	`GET /accounts/balances`

Os endpoints antigos continuam funcionando. Você pode usar ambas as APIs simultaneamente.

Webhooks

O formato de webhook muda completamente:

V1 (Antes)
V2 (Depois)

{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionId": "12345",
  "movementType": "CREDIT",
  "originalAmount": 100.00,
  "finalAmount": 100.00,
  "counterpart": {
    "name": "João Silva",
    "document": "123.xxx.xxx-xx"
  }
}

{
  "type": "RECEIVE",
  "data": {
    "id": 123,
    "txId": "abc123",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "100.00",
      "currency": "BRL"
    },
    "creditDebitType": "CREDIT",
    "debtorAccount": {
      "name": "João Silva",
      "document": "123.xxx.xxx-xx"
    },
    "creditorAccount": {...}
  }
}

Principais diferenças nos Webhooks

Aspecto	V1	V2
Estrutura	Campos na raiz	Envelope `{type, data}`
Tipo de evento	`event: "CashIn"`	`type: "RECEIVE"`
Status sucesso	`CONFIRMED`	`LIQUIDATED`
Status refund	`CONFIRMED`	`REFUNDED`
Valores	`number` (100.00)	`string` (“100.00”)
Contraparte	`counterpart`	`debtorAccount` / `creditorAccount`

Preparando sua integração

1. Atualize o handler de webhooks

// ANTES (V1)
function handleWebhookV1(payload: any) {
  if (payload.event === 'CashIn' && payload.status === 'CONFIRMED') {
    processPayment(payload.transactionId, payload.finalAmount);
  }
}

// DEPOIS (V2)
function handleWebhookV2(payload: any) {
  if (payload.type === 'RECEIVE' && payload.data.status === 'LIQUIDATED') {
    const amount = parseFloat(payload.data.payment.amount);
    processPayment(payload.data.id, amount);
  }
}

2. Atualize os tipos/interfaces

// V2 Types
interface WebhookV2Payload {
  type: 'RECEIVE' | 'TRANSFER' | 'REFUND';
  data: WebhookV2Data;
}

interface WebhookV2Data {
  id: number;
  txId: string | null;
  status: 'PENDING' | 'LIQUIDATED' | 'REFUNDED' | 'ERROR';
  payment: {
    amount: string;  // Note: string, não number!
    currency: string;
  };
  creditDebitType: 'CREDIT' | 'DEBIT';
  debtorAccount: AccountInfo;
  creditorAccount: AccountInfo;
  endToEndId: string | null;
  refunds: RefundInfo[];
  // ... outros campos
}

3. Teste em ambiente de desenvolvimento

Antes de solicitar a ativação em produção:

Solicite ativação no ambiente de sandbox
Execute testes completos de Cash-In, Cash-Out e Refund
Valide que todos os webhooks são processados corretamente

Rollback

Após a ativação, não é possível voltar para V1 automaticamente. Se precisar reverter, entre em contato com o suporte.

Recomendamos manter suporte a ambas as versões durante a transição:

function handleWebhook(payload: any) {
  // Detecta versão pelo formato
  if (payload.type && payload.data) {
    return handleWebhookV2(payload);
  } else if (payload.event) {
    return handleWebhookV1(payload);
  }
  throw new Error('Formato de webhook desconhecido');
}

Checklist de Ativação

Implementar handler V2

Atualize seu código para processar o formato envelope {type, data}

Testar em sandbox

Solicite ativação em sandbox e execute testes completos

Validar todos os eventos

Teste: RECEIVE, TRANSFER, REFUND com status LIQUIDATED, REFUNDED e ERROR

Solicitar ativação em produção

Envie email para suporte@firebanking.com.br com as informações necessárias

Monitorar primeiras transações

Acompanhe as primeiras transações após a ativação para garantir funcionamento

Dúvidas Frequentes

Posso usar V1 e V2 simultaneamente?

Os endpoints podem ser usados simultaneamente (ex: POST /pix/cash-in e PUT /cob/:txid).Os webhooks são sempre na versão configurada na conta. Não é possível receber V1 e V2 ao mesmo tempo.

O que acontece com transações em andamento?

Transações criadas antes da ativação continuarão enviando webhooks no formato antigo até serem concluídas. Novas transações usarão o formato V2.

Preciso mudar a URL do webhook?

Não. A URL permanece a mesma. Apenas o formato do payload muda.

Próximos Passos

Webhooks V2

Entenda o novo formato de webhooks

Criar Cobrança

Use o endpoint BACEN para criar cobranças

​Visão Geral

​Como Solicitar Ativação

​1. Entre em contato com o suporte

​2. Aguarde a configuração

​3. Teste a integração

​O que muda com a ativação?

​Endpoints

​Webhooks

​Principais diferenças nos Webhooks

​Preparando sua integração

​1. Atualize o handler de webhooks

​2. Atualize os tipos/interfaces

​3. Teste em ambiente de desenvolvimento

​Rollback

​Checklist de Ativação

​Dúvidas Frequentes

​Próximos Passos

Webhooks V2

Criar Cobrança

Visão Geral

Como Solicitar Ativação

1. Entre em contato com o suporte

2. Aguarde a configuração

3. Teste a integração

O que muda com a ativação?

Endpoints

Webhooks

Principais diferenças nos Webhooks

Preparando sua integração

1. Atualize o handler de webhooks

2. Atualize os tipos/interfaces

3. Teste em ambiente de desenvolvimento

Rollback

Checklist de Ativação

Dúvidas Frequentes

Próximos Passos