Sicoob.PIX 0.9.4

There is a newer version of this package available.
See the version list below for details.
dotnet add package Sicoob.PIX --version 0.9.4
NuGet\Install-Package Sicoob.PIX -Version 0.9.4
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sicoob.PIX" Version="0.9.4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Sicoob.PIX --version 0.9.4
#r "nuget: Sicoob.PIX, 0.9.4"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Sicoob.PIX as a Cake Addin
#addin nuget:?package=Sicoob.PIX&version=0.9.4

// Install Sicoob.PIX as a Cake Tool
#tool nuget:?package=Sicoob.PIX&version=0.9.4

APIs Sicoob

Repositório para comunicação via API com o banco Sicoob

Link da documentação oficial: https://developers.sicoob.com.br

Para comunicação com o Sicoob é necessário um "Cadastro de Aplicativo" em developers.sicoob.com.br. Para isso é necessário ter os dados bancarios da conta a ser automatizada e de um certificado ICP-Brasil em arquivo.

Cada conta bancária a ser automatizada deve ter um cadastro como Aplicaitvo

É necessário ter o certificado em dois formatos:

  • *.PFX (padrão quando um certificado A1 é adiquirido) com a senha e;
  • *.CER (apenas a chave pública em formato Base-64)

Durante o cadastro será informado os dados da conta bancária sendo automatizada e o certificado no formato PEM. Será gerado um ClientId.

O Sicoob possui APIs para:

  • PIX
  • Cobrança Bancária (Boleto)
  • Conta Corrente
  • Conta Poupança

Badges:

.NET

API PIX: NuGet

API Cobrança: NuGet

API Conta Corrente e Poupança: NuGet

A documentação do Sicoob é falha, imcompleta e em alguns tópicos é completamente ausente. O Gerente não tem acesso à documentação, o WhatsApp das APIs manda solicitar via e-mail, e o e-mails não são respondidos. Farei o póssível para documentar aqui as funções não documentadas lá, porém sob o risco de errar alguma funcionalidade

Sicoob.PIX

APIs do Sicoob para funções PIX

Funcionalidades da API:

  • Consultar e Devolver PIX recebidos no período (com e sem txId)
  • Criar, Consultar e revisar Pix-Cobrança imediato
  • Criar, Consultar e revisar Pix-Cobrança com vencimento
  • Criar, Consultar e revisar lotes de Pix-Cobrança com vencimento
  • Criar, Consultar e revisar PayloadLocation de Pix (cria um acesso público para dados de uma cobrança)
  • Criar, consultar e cancelar Webhook

Exemplos de uso

Criação do objeto API

// Cria configuração
var cfg = new ConfiguracaoAPI()
{
    ClientId = "00000000-0000-0000-0000-000000000000", // Obtém no "Aplicativo" no developers.sicoob.com.br
    Scope =  AuthorizationScope.PIX_SomenteLeitura(),
    CertificadoSenha = "SenhaCertificado",
    UrlCertificadoPFX = "caminho/do/pfx/com/chave/privada.pfx"
};

// cria o objeto de comunicação com as APIs de PIX
var sicoob = new SicoobPIX(cfg);
// Inicializa o acesso das APIs
await sicoob.SetupAsync();

// A autenticação dura 300 segundos (5min) e é auto renovado pela biblioteca
// Cada chamada verifica e, se necessário, atualiza o token
// Chame AtualizarCredenciaisAsync() para renovar manualmente
// É possível consultar dados da vigência do Token nas propriedades:
//  * sicoob.ExpiresIn
//  * sicoob.ExpiresAtUTC
//  * sicoob.Expired

Atenção: Por segurança, o construtor da classe Sicoob (e todas suas derivações, como o SicoobPIX) apaga a propriedade CertificadoSenha do objeto de configuração

Funções Cobrança para PIX-Imediato

// Listar todas as cobranças num período
var cobs = await sicoob.ListarCobrancasAsync(new Sicoob.PIX.Models.Cobranca.ConsultaRequest
{
    inicio = DateTime.UtcNow.Date.AddDays(-1),
    fim = DateTime.UtcNow.AddDays(1).Date,
});

// Criar uma Cobrança para a chave: "12.345.678/0001-00", no valor de R$ 19,90, com limite de 1h para pagamento
var transactionId = gerarNovaTxId(); // Controle interno (string), pode ser um guid (pattern: ^[a-zA-Z0-9]{26,35}$)
var dadosCobranca = PIX.Models.Cobranca.CriarCobrancaRequest.Padrao(chave: "12345678000100", valor: 19.90M, expiracaoSegundos: 3600));
var nova = await sicoob.CriarCobrancaAsync(transactionId, dadosCobranca);
// Baixar QR Code
var pngBytes = await sicoob.ConsultarImagemCobrancaAsync(transactionId);

// Consultar cobrança
var consulta = await sicoob.ConsultarCobrancaAsync(transactionId);

// Função interna da empresa para gerar Ids de Transação
string gerarNovaTxId()
  => Guid.NewGuid().ToString();

Funções de consulta de PIX Recebidos

/* PIX */
var pixPeriodo = await sicoob.ListarPIXAsync(new Sicoob.PIX.Models.Pix.ConsultaRequest()
{
    inicio = DateTime.UtcNow.Date.AddDays(-1),
    fim = DateTime.UtcNow.AddDays(1).Date,
});

Webhook

A documentação do Webhook é um dos casos aonde só há informações parciais

Existe a documentação dos endpoints para criar e gerenciar o cadastro de Webhooks, porém não há nenhuma documentação da requisição que será feita pelo Sicoob no endpoint.

Ao consultar o suporte do sicoob no setor de APIs, fomos informados que não há documentação e devemos trabalhar por tentativa e erro (veja abaixo), portanto a documentação pode estar incompleta ou errada.

Após registrar o Webhook, todo PIX recebido que tenha TransactionId será notificado através de uma chamada Webhook, aonde os servidores do Sicoob farão uma chamada REST na aplicação com informações sobre o PIX.

Exemplo:

É registrado um Webhook para a chave: "12.345.678/0001-00":

await sicoob.CriarWebHook("12345678000100", "https://meu.site.com.br/api/");

O Sicoob vai fazer um POST para ttps://meu.site.com.br/api/pix, repare que é feito um POST para o endereço registrado adicionado de /pix no final.

Caso seja registrado como https://meu.site.com.br/api/pix, será feito um POST para https://meu.site.com.br/api/pix/pix (repare o duplo pix).

O POST não tem nenhum header especial, e contém um array de dados do PIX no payload conforme model: Sicoob.PIX.Models.Webhook.WebhookPostRequest

// Exemplo de um Endpoint em ASP
[HttpPost]
[Route("cuidado com sua rota aqui/pix")] // não esquecer do /pix
public IActionResult Webhook_Pix([FromBody] Sicoob.PIX.Models.Webhook.WebhookPostRequest payload){
    // Processa o payload
    return Ok();
}

Dump de uma requisição do sicoob capturada

{
  "method": "POST",
  "uri": "/api/pix",
  "headers": {
    "Via": "1.1 wsap501.sicoob.com.br:80 (Cisco-WSA/12.0.3-007)",
    "X-Imforwards": "20",
    "Content-Length": "164",
    "User-Agent": "axios/0.21.4",
    "Content-Type": "application/json",
    "Accept": "application/json, text/plain, */*",
    "Connection": "close"
  },
  "body": "{\"pix\":[{\"endToEndId\":\"xxxxxxxxxxx\",\"txid\":\"xxxxxxxxxxx\",\"valor\":\"xxx.xx\",\"horario\":\"2020-01-01T00:00:00.000Z\",\"devolucoes\":[]}]}",
}

Segue o Contato com a equipe do suporte ao desenvolvedor do Sicoob em JAN/2023:

Nós: 
Eu estou lendo a documentação sobre o registro, consulta e edição de WebHook
Mas não achei o protocolo da chamada que o Sicoob vai fazer
Não achei COMO o sicoob vai bater no meu endpoint
Qual método? (POST/GET?), não tem se vai mandar parâmetros, headers, qual o payload ....
Como eu faço para saber o que vou receber?

Sicoob ([NOME REMOVIDO]):
Você será notificado na URL cadastrada do Webhook e poderá identificar pelos IPs do Webhook PIX do Sicoob.

Infelizmente não temos exemplos disponíveis, será necessário testar sua aplicação.

Protocolo do Atendimento: [REMOVIDO]

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.9.7.4 287 2/3/2023
0.9.7.2 248 1/31/2023
0.9.7.1 252 1/31/2023
0.9.7 260 1/30/2023
0.9.6 253 1/30/2023
0.9.5 253 1/26/2023
0.9.4 265 1/26/2023
0.9.3 266 1/25/2023
0.9.2 245 1/24/2023
0.9.1 247 1/24/2023

See examples and documentation on the GitHub page
https://github.com/SharpSistemas/SicoobAPI