@movelabs/pix-sicoob

Cliente TypeScript/JavaScript para integração com a API PIX do Sicoob. Oferece uma interface simples e type-safe para criar cobranças, gerenciar webhooks e consultar transações PIX.

🚀 Características

• ✅ Type-safe: Totalmente tipado com TypeScript
• ✅ Validação robusta: Schemas Zod para validação de dados
• ✅ Logs detalhados: Sistema de logging configurável
• ✅ Tratamento de erros: Erros customizados com contexto
• ✅ Interceptadores: Logs automáticos de requisições/respostas
• ✅ Health check: Verificação de conectividade
• ✅ Cache de token: Gerenciamento automático de autenticação
• ✅ Webhooks: Suporte completo para notificações
• ✅ QR Code: Geração de imagens QR Code

📦 Instalação

npm install @movelabs/pix-sicoob

yarn add @movelabs/pix-sicoob

pnpm add @movelabs/pix-sicoob

🔧 Configuração

Pré-requisitos

1. Certificado PFX: Certificado digital fornecido pelo Sicoob
2. Client ID: Identificador da aplicação no Sicoob
3. Chave PIX: Chave PIX cadastrada na sua conta

Variáveis de Ambiente (Recomendado)

SICOOB_CLIENT_ID=seu-client-id
SICOOB_CERT_PATH=/caminho/para/certificado.pfx
SICOOB_CERT_PASSWORD=senha-do-certificado
[email protected]

🚀 Uso Básico

import { SicoobPixClient } from "@movelabs/pix-sicoob";
import fs from "fs";

// Configurar cliente
const client = new SicoobPixClient({
  clientId: process.env.SICOOB_CLIENT_ID!,
  pfxBuffer: fs.readFileSync(process.env.SICOOB_CERT_PATH!),
  pfxPassword: process.env.SICOOB_CERT_PASSWORD!,
  scope: "cob.write cob.read webhook.read webhook.write",
  debug: true, // Habilitar logs (desenvolvimento)
});

// Criar cobrança PIX
const cobranca = await client.createPixCob({
  calendario: {
    expiracao: 3600, // 1 hora
  },
  valor: {
    original: "25.50",
  },
  chave: "[email protected]",
  solicitacaoPagador: "Pagamento do pedido #12345",
});

console.log("Cobrança criada:", cobranca.txid);
console.log("BR Code:", cobranca.brcode);

📚 Documentação da API

Configuração do Cliente

interface SicoobAuthConfig {
  clientId: string; // ID do cliente fornecido pelo Sicoob
  pfxBuffer: Buffer; // Buffer do certificado PFX
  pfxPassword: string; // Senha do certificado PFX
  scope: string; // Escopo de acesso
  baseUrl?: string; // URL base da API (opcional)
  debug?: boolean; // Habilitar logs de debug
  logger?: Logger; // Logger customizado
}

Métodos Disponíveis

🔐 Autenticação

// Obter token de acesso
const token = await client.getAccessToken();

// Verificar se token é válido
const isValid = client.isTokenValid();

// Obter informações do token
const tokenInfo = client.getTokenInfo();

// Invalidar token (forçar nova autenticação)
client.invalidateToken();

// Verificar conectividade
const isHealthy = await client.healthCheck();

💰 Cobranças PIX

// Criar cobrança
const cobranca = await client.createPixCob({
  calendario: { expiracao: 3600 },
  valor: { original: "10.50" },
  chave: "[email protected]",
  solicitacaoPagador: "Descrição do pagamento",
  devedor: {
    nome: "João Silva",
    cpf: "12345678901", // Opcional
  },
  infoAdicionais: [
    // Opcional
    { nome: "Produto", valor: "Curso Online" },
  ],
});

// Consultar cobrança
const cobrancaConsultada = await client.getPixCob("txid-da-cobranca");

// Obter QR Code como imagem
const imagemQR = await client.getPixCobImagem("txid-da-cobranca");
fs.writeFileSync("qrcode.png", imagemQR);

// Listar cobranças
const lista = await client.listPix({
  inicio: "2025-01-01T00:00:00Z",
  fim: "2025-01-31T23:59:59Z",
  status: "ATIVA",
  "paginacao.paginaAtual": 0,
  "paginacao.itensPorPagina": 50,
});

🔗 Webhooks

// Configurar webhook
await client.setWebhook(
  "[email protected]",
  "https://seu-site.com/webhook/pix",
);

// Consultar webhook
const webhook = await client.getWebhook("[email protected]");

// Remover webhook
await client.deleteWebhook("[email protected]");

🎯 Exemplos Avançados

Logger Customizado

import pino from "pino";

const logger = pino({
  level: "info",
  transport: {
    target: "pino-pretty",
  },
});

const client = new SicoobPixClient({
  // ... outras configurações
  debug: false,
  logger: logger,
});

Tratamento de Erros

import {
  SicoobPixError,
  SicoobAuthError,
  SicoobValidationError,
} from "@movelabs/pix-sicoob";

try {
  const cobranca = await client.createPixCob(dadosCobranca);
} catch (error) {
  if (error instanceof SicoobAuthError) {
    console.error("Erro de autenticação:", error.message);
  } else if (error instanceof SicoobValidationError) {
    console.error("Dados inválidos:", error.details);
  } else if (error instanceof SicoobPixError) {
    console.error("Erro na API PIX:", error.code, error.status);
  }
}

Processamento de Webhook

import express from "express";
import { webhookPixPayloadSchema } from "@movelabs/pix-sicoob";

const app = express();
app.use(express.json());

app.post("/webhook/pix", (req, res) => {
  try {
    // Validar payload do webhook
    const payload = webhookPixPayloadSchema.parse(req.body);

    // Processar cada PIX recebido
    payload.pix.forEach((pix) => {
      console.log("PIX recebido:", {
        txid: pix.txid,
        valor: pix.valor,
        pagador: pix.nomePagador,
        horario: pix.horario,
      });

      // Aqui você processaria o pagamento na sua aplicação
      processarPagamento(pix);
    });

    res.status(200).json({ success: true });
  } catch (error) {
    console.error("Erro no webhook:", error);
    res.status(400).json({ error: "Payload inválido" });
  }
});

🏗️ Tipos e Schemas

Principais Tipos

// Payload para criar cobrança
interface CobPayload {
  calendario: {
    expiracao: number;
    criacao?: string;
  };
  valor: {
    original: string; // Formato: "10.50"
    modalidadeAlteracao?: 0 | 1;
  };
  chave: string;
  txid?: string;
  solicitacaoPagador?: string;
  devedor?: {
    nome: string;
    cpf?: string;
    cnpj?: string;
  };
  infoAdicionais?: Array<{
    nome: string;
    valor: string;
  }>;
}

// Resposta da cobrança
interface CobResponse {
  txid: string;
  revisao: number;
  location: string;
  status:
    | "ATIVA"
    | "CONCLUIDA"
    | "REMOVIDA_PELO_USUARIO_RECEBEDOR"
    | "REMOVIDA_PELO_PSP";
  calendario: {
    criacao?: string;
    expiracao: number;
  };
  valor: {
    original: string;
  };
  chave: string;
  brcode: string;
  // ... outros campos
}

🔒 Segurança

Boas Práticas

1. Nunca commite certificados ou senhas no código
2. Use variáveis de ambiente para credenciais
3. Mantenha o certificado PFX seguro
4. Valide sempre os webhooks recebidos
5. Use HTTPS para webhooks
6. Implemente rate limiting
7. Monitore logs de erro

Exemplo de Configuração Segura

// ❌ Não faça isso
const client = new SicoobPixClient({
  clientId: "meu-client-id",
  pfxPassword: "senha123",
  // ...
});

// ✅ Faça isso
const client = new SicoobPixClient({
  clientId: process.env.SICOOB_CLIENT_ID!,
  pfxBuffer: fs.readFileSync(process.env.SICOOB_CERT_PATH!),
  pfxPassword: process.env.SICOOB_CERT_PASSWORD!,
  scope: process.env.SICOOB_SCOPE!,
  debug: process.env.NODE_ENV !== "production",
});

🐛 Troubleshooting

Problemas Comuns

Erro de Certificado

Error: unable to verify the first certificate

Solução: Verifique se o certificado PFX está correto e a senha está correta.

Erro de Autenticação

SicoobAuthError: Erro ao obter token de acesso

Soluções:

• Verifique o clientId
• Confirme o escopo (scope)
• Verifique se o certificado não expirou

Erro de Validação

SicoobValidationError: Dados inválidos para cobrança PIX

Soluções:

• Verifique o formato do valor (ex: "10.50")
• Confirme se a chave PIX está correta
• Valide CPF/CNPJ se fornecidos

Debug

Habilite logs detalhados:

const client = new SicoobPixClient({
  // ... configurações
  debug: true,
});

📝 Changelog

v1.0.0

• ✨ Versão inicial
• ✅ Suporte completo à API PIX Sicoob
• ✅ Validação com Zod
• ✅ Tipos TypeScript
• ✅ Sistema de logs
• ✅ Tratamento de erros
• ✅ Suporte a webhooks

🤝 Contribuindo

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🔗 Links Úteis

• Documentação oficial da API PIX Sicoob
• Especificação PIX do Banco Central
• Repositório no GitHub

📞 Suporte

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentação: Wiki

Feito com ❤️ pela equipe ZapTickets