# Emissão Sicoob - Via API
Analista Responsável: Gustavo Henrique Braga Fernandes
Esse documento visa descrever os processos básicos para a integração com a API do Banco Sicoob. Inicialmente será implementada a emissão de boleto
# Primeiros Passos - Liberação - criação aplicativo
|
| **Projeto/Sistema:**
Emissão Sicoob - Via API
| **Versão do *Template:***
1.1 |
| **Processo:**
Primeiros Passos - Liberação - criação aplicativo e sandbox | **Versão do Documento:**
1.0 |
| **Responsável(eis):**
Gustavo Fernandes | **Data:**
02/01/2025
|
##### **1. Introdução**
**Este processo visa exemplificar o cadastro para libeação e criação do aplicativo, para emissão de boletos no banco Sicoob - via API.**
#### **Processos Relacionados**
- - - - - -
[Sandbox (homologação)](https://docs.softensistemas.com.br/books/siem-boleto/page/sandbox-homologacao "Sandbox (homologação)")
[Endpoints Produção (Exemplos JSON)](https://docs.softensistemas.com.br/books/siem-boleto/page/endpoints-producao-exemplos-json "Endpoints Produção (Exemplos JSON)")
#### **Especificação Funcional**
- - - - - -
#### **PROC001 CADASTRO NO PORTAL:**
Antes de tudo, será necessário possuir uma conta no ["Portal Developers - Sicoob".](https://developers.sicoob.com.br/portal/ ""Portal Developers - Sicoob".")
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1735830311176.png)
Será necessário preencher todos os dados para cadastro, inclusive o **CPF** do representante da empresa.
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1735830394293.png)
##### ***Gerar Aplicativo (Ambiente produção):***
Após realizar o acesso, cadastrando-se no portal, será necessário criar um novo aplicativo junto ao cliente.
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1735914442564.png)
**1.** Será necessário ser um cooperado e utilizar o AppSicoob para conseguir.
**(Fazer o procedimento junto com um cliente que já é cliente do banco Sicoob)**
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1735914763921.png)
**2.** Seguir o passo a passo conforme documentação:
[Passo a passo criação aplicativo](https://developers.sicoob.com.br/portal/documentacao?slugItem=apis-do-sicoob&slugSubItem=aplicativos-de-producao "Passo a passo criação aplicativo")
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1736168872954.png)
##### **Autenticação**
O fluxo de autenticação *Client Credentials* pode ser acessado pela URL abaixo:
**Geração do token:**
[https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token](https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token)
Você poderá visualizar o passo a passo de geração de token via Postman no vídeo disponibilizado no link a seguir.
**[Vídeo exemplo aqui.](https://developers.sicoob.com.br/portal/documentacao?slugItem=seguranca&slugSubItem=autenticacao "Vídeo exemplo aqui.")**
O fluxo de autenticação utilizado pelas APIs do Sicoob requer a utilização de **certificado digital** emitido por uma entidade certificadora **ICP Brasil** e deve ser emitido para o **CNPJ do cooperado**, quando PJ (Pessoa Jurídica) e para CPF do cooperado quando PF (Pessoa Física).
©SOFTEN SISTEMAS 2024
# Sandbox (homologação)
|
| **Projeto/Sistema:**
Emissão Sicoob - Via API
| **Versão do *Template:***
1.1 |
| **Processo:**
Sandbox (homologação) | **Versão do Documento:**
1.0 |
| **Responsável(eis):**
Gustavo Fernandes | **Data:**
08/01/2025
|
##### **1. Introdução**
**Este processo visa exemplificar a utilização do ambiente sandbox para registro de boletos no banco Sicoob - via API.**
#### **Processos Relacionados**
- - - - - -
[Primeiros Passos - Liberação - criação aplicativo](https://docs.softensistemas.com.br/books/siem-boleto/page/primeiros-passos-liberacao-criacao-aplicativo "Primeiros Passos - Liberação - criação aplicativo")
[Endpoints Produção (Exemplos JSON)](https://docs.softensistemas.com.br/books/siem-boleto/page/endpoints-producao-exemplos-json "Endpoints Produção (Exemplos JSON)")
#### **Especificação Funcional**
- - - - - -
#### **PROC002 SANDBOX (HOMOLOGAÇÃO):**
O ambiente de Sandbox foi criado especificamente para desenvolvedores que desejam testar as APIs do Sicoob.
##### **1) Acesse suas credenciais de teste:**
Antes de começar a utilizar o ambiente de sandbox, é necessário obter suas credenciais de teste. Estas:
#### Client ID
```
9b5e603e428cc477a2841e2683c92d21
```
#### Access token (Bearer)
```
1301865f-c6bc-38f3-9f49-666dbcfc59c3
```
**OBS: Vale ressaltar que estas credenciais não são válidas para produção!**
##### **2) Autenticação:**
É necessário fornecer no Header *Authorization* das requisições o Access token fornecido
##### **Endereços de Sandbox (Endpoints):**
**API Cobrança Bancária:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/cobranca-bancaria/v3](https://sandbox.sicoob.com.br/sicoob/sandbox/cobranca-bancaria/v3)
**API Cobrança Bancária Pagamentos:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/cobranca-bancaria-pagamentos/v3](https://sandbox.sicoob.com.br/sicoob/sandbox/cobranca-bancaria-pagamentos/v3)
**API Conta Corrente:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/conta-corrente/v4](https://sandbox.sicoob.com.br/sicoob/sandbox/conta-corrente/v4)
**API Convênios Pagamentos:** [https://sandbox.sicoob.com.br/sicoob/sandbox/convenios-pagamentos/v2](https://sandbox.sicoob.com.br/sicoob/sandbox/convenios-pagamentos/v2)
**API Investimentos - RDC:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/investimentos/v2](https://sandbox.sicoob.com.br/sicoob/sandbox/investimentos/v2)
**API Open Finance - Iniciação de Pagamento:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/payments/v2/itp](https://sandbox.sicoob.com.br/sicoob/sandbox/payments/v2/itp)
**API Pix Pagamentos:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/pix-pagamentos/v2](https://sandbox.sicoob.com.br/sicoob/sandbox/pix-pagamentos/v2)
**API Pix Recebimentos:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/pix/api/v2](https://sandbox.sicoob.com.br/sicoob/sandbox/pix/api/v2)
**API Poupança:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/poupanca/v3](https://sandbox.sicoob.com.br/sicoob/sandbox/poupanca/v3)
**API SPB Transferências:**
[https://sandbox.sicoob.com.br/sicoob/sandbox/spb/v2](https://sandbox.sicoob.com.br/sicoob/sandbox/spb/v2)
#### **Exemplos de requisição**
**Consultar Cobrança Imediata PIX**
```c
curl --location --request GET 'https://sandbox.sicoob.com.br/sicoob/sandbox/pix/api/v2/cob/:TXID' \
--header 'Authorization: Bearer {{Access Token}}' \
--header 'client_id: {{client_id}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```
**Obs: O TXID é um path param que deve ser preenchido com o identificador único do QR Code. Ele deve conter de 27 a 36 caracteres.**
**Consultar Boleto**
```c
curl --location -g --request GET 'https://sandbox.sicoob.com.br/sicoob/sandbox/cobranca-bancaria/v3/boletos?numeroContrato={{numContrato}}&modalidade=1&nossoNumero=integer' \
--header 'Authorization: Bearer {{Access Token}}' \
--header 'client_id: {{client_id}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```
**Obs: Os Headers seguirão um padrão para todas as APIs.**
©SOFTEN SISTEMAS 2024
# Endpoints Produção (Exemplos JSON)
|
| **Projeto/Sistema:**
Emissão Sicoob - Via API
| **Versão do *Template:***
1.1 |
| **Processo:**
Endpoints Produção (Exemplos JSON) | **Versão do Documento:**
1.0 |
| **Responsável(eis):**
Gustavo Fernandes | **Data:**
08/01/2025
|
##### **1. Introdução**
**Este processo visa exemplificar a utilização de endpoints, envio e retornos para registro de boletos no banco Sicoob - via API.**
#### **Processos Relacionados**
- - - - - -
[Primeiros Passos - Liberação - criação aplicativo](https://docs.softensistemas.com.br/books/siem-boleto/page/primeiros-passos-liberacao-criacao-aplicativo "Primeiros Passos - Liberação - criação aplicativo")
[Sandbox (homologação)](https://docs.softensistemas.com.br/books/siem-boleto/page/sandbox-homologacao "Sandbox (homologação)")
#### **Especificação Funcional**
- - - - - -
#### **PROC003 API DE COBRANÇA BANCÁRIA V3:**
Esta API disponibiliza serviços para recebimento de valores referentes às vendas de produtos e serviços da sua empresa, por meio de boletos de cobrança, pagos em toda a rede bancária.
**Funcionalidades**
- Gerenciamento de Boletos
- Alteração de informações de pagadores de boletos
- Negativação de pagadores
- Protesto de boletos
- Movimentação
**Especificações de uso da API**
[https://developers.sicoob.com.br/portal/documentacao?slugItem=apis&slugSubItem=cobranca-bancaria-v3](https://developers.sicoob.com.br/portal/documentacao?slugItem=apis&slugSubItem=cobranca-bancaria-v3)
#### ***Questões Técnicas:***
##### **1. Cobrança Bancária Pagamentos**
**BASE URL: [https://api.sicoob.com.br/pagamentos/v3](https://api.sicoob.com.br/pagamentos/v3)**
(Esta API disponibiliza funcionalidades para realização de pagamentos de boletos de Cobrança Bancária.)
##### **1.1 Pagamento** (Pagamento de Boletos de Cobrança)
**1.1.1 Serviço para consultar boleto:**
| Método HTTP
| URL
|
| GET
| /boletos/{codigoBarras}
|
**Parâmetros:**
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1736348677063.png)
**1.1.2 Resposta esperada:**
**1.1.3 Exemplo retorno:**
```json
{
"resultado": {
"numeroInstituicaoEmissora": 756,
"nomeInstituicaoEmissora": "Banco Cooperativo do Brasil",
"tipoPessoaBeneficiario": "F",
"numeroCpfCnpjBeneficiario": "12345678900",
"nomeRazaoSocialBeneficiario": "José da Silva",
"nomeFantasiaBeneficiario": "Estilo Tech",
"tipoPessoaBeneficiarioFinal": "2",
"numeroCpfCnpjBeneficiarioFinal": "12345678900",
"nomeRazaoSocialBeneficiarioFinal": "João das Flores",
"nomeFantasiaBeneficiarioFinal": "Quitanda do João",
"tipoPessoaPagador": "F",
"numeroCpfCnpjPagador": "12345678900",
"nomeRazaoSocialPagador": "Maria José",
"nomeFantasiaPagador": "Rosa Maria da Silva",
"codigoBarras": "string",
"numeroLinhaDigitavel": "string",
"dataVencimentoBoleto": "2021-04-20",
"dataLimitePagamentoBoleto": "2021-04-25",
"valorBoleto": 152.3,
"valorAbatimentoDesconto": 0,
"valorMultaMora": 0,
"valorPagamento": 152.3,
"dataPagamento": "2021-04-24",
"permiteAlterarValor": true,
"consultaEmContingencia": false,
"codigoEspecieDocumento": 25,
"codigoSituacaoBoletoPagamento": "12",
"nossoNumero": "123789",
"numeroDocumento": "123456",
"identificadorConsulta": "hash",
"descricaoInstrucaoDesconto1": "Conceder desconto de 10% até 05/04/2021",
"descricaoInstrucaoDesconto2": "Conceder desconto de 5% até 10/04/2021",
"descricaoInstrucaoDesconto3": "Conceder desconto de 2% até 05/04/2021",
"descricaoInstrucaoValorMinMax": "O Valor Mínimo é R$ 0,01. O Valor Máximo é R$ 99.999.999,99",
"bloquearPagamento": true,
"mensagemBloqueioPagamento": "Pagamento bloqueado"
}
}
```
**1.1.4 Respostas possíveis:**
| Code
| Description
|
| 204
| Requisição processada com sucesso e não há conteúdo a ser retornado.
|
| 400
| Possíveis erros de negócio.
|
| 406
| Possíveis erros de inconsistência nos dados passados.
|
| 500
| Erro interno.
|
**1.1.5 Exemplo retorno: (Mesmo padrão de retorno para o 400, 406 e 500)**
```json
{
"mensagens": [
{
"mensagem": "string",
"codigo": "string"
}
]
}
```
**1.1.6 Serviço para efetuar o pagamento ou agendamento de boleto.**
| Método HTTP
| URL
|
| POST
| /boletos/pagamentos/{codigoBarras}
|
**Parâmetros:**
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1736349536996.png)
Exemplo valor | Modelo: **(boletoPagamento)**
```json
{
"identificadorConsulta": "hash",
"valorBoleto": 152.3,
"valorDescontoAbatimento": 0,
"valorMultaMora": 0,
"descricaoObservacao": "Boleto da Escola",
"aceitaValorDivergente": true,
"numeroCpfCnpjPortador": "12345678900",
"nomePortador": "Rosa Maria da Silva",
"amount": 152.3,
"date": "2021-04-24",
"debtorAccount": {
"issuer": 1234,
"number": 1234569,
"accountType": 0,
"personType": 0
}
}
```
**1.1.7 Resposta esperada:**
**1.1.8 Exemplo retorno:**
```json
{
"resultado": {
"numeroAgencia": "0001-9",
"nomeAgencia": "Agência Sede",
"numeroConta": 1234569,
"nomeProprietarioContaCorrente": "José da Silva",
"numeroLinhaDigitavel": "string",
"numeroInstituicaoEmissora": 756,
"nomeInstituicaoEmissora": "Banco Cooperativo do Brasil",
"numeroCpfCnpjBeneficiario": "12345678900",
"nomeRazaoSocialBeneficiario": "José da Silva",
"nomeFantasiaBeneficiario": "Estilo Tech",
"numeroCpfCnpjBeneficiarioFinal": "12345678900",
"nomeRazaoSocialBeneficiarioFinal": "João das Flores",
"nomeFantasiaBeneficiarioFinal": "Quinatda dojão",
"numeroCpfCnpjPagador": "12345678900",
"nomeRazaoSocialPagador": "Maria José",
"nomeFantasiaPagador": "Rosa Maria da Silva",
"dataVencimento": "2018-09-20",
"valorBoleto": 100.36,
"valorAbatimentoDesconto": 0,
"valorMultaMora": 60.36,
"valorPagamento": 255.63,
"dataPagamento": "2019-10-20",
"situacaoPagamento": "Efetivado",
"descricaoDetalheSituacao": "Saldo no momento da rejeição em 10/03/2021 às 22:01:10: R$ 343,05.",
"dataHoraCadastro": "2019-10-20T12:30:22.000Z",
"aceitaValorDivergente": true,
"nossoNumero": "756",
"numeroDocumento": "123456",
"descricaoObservacao": "Boleto da Escola",
"descricaoOuvidoria": "OUVIDORIA AGIBANK: 08007250996",
"descricaoTituloComprovante": "PAGAMENTO DE BOLETO",
"idPagamento": 1983450,
"numeroAutenticacaoPagamento": "89C3E9FD-1A37-40BE-A85B-69AF118D336A"
}
}
```
**1.1.9 Respostas possíveis:**
| Code
| Description
|
| 204
| Requisição processada com sucesso e não há conteúdo a ser retornado.
|
| 400
| Possíveis erros de negócio.
|
| 406
| Possíveis erros de inconsistência nos dados passados.
|
| 500
| Erro interno.
|
**1.1.10 Exemplo retorno: (Mesmo padrão de retorno para o 400, 406 e 500)**
```json
{
"mensagens": [
{
"mensagem": "string",
"codigo": "string"
}
]
}
```
**1.1.11 Serviço para consultar um comprovante de um pagamento efetuado.**
| Método HTTP
| URL
|
| GET
| /boletos/pagamentos/{idPagamento}/comprovantes
|
**Parâmetros:**
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1736360421037.png)
**1.1.12 Resposta esperada:**
**1.1.13 Exemplo retorno:**
```json
{
"resultado": {
"numeroAgencia": "0001-9",
"nomeAgencia": "Agência Sede",
"numeroConta": 1234569,
"nomeProprietarioContaCorrente": "José da Silva",
"numeroLinhaDigitavel": "string",
"numeroInstituicaoEmissora": 756,
"nomeInstituicaoEmissora": "Banco Cooperativo do Brasil",
"numeroCpfCnpjBeneficiario": "12345678900",
"nomeRazaoSocialBeneficiario": "José da Silva",
"nomeFantasiaBeneficiario": "Estilo Tech",
"numeroCpfCnpjBeneficiarioFinal": "12345678900",
"nomeRazaoSocialBeneficiarioFinal": "João das Flores",
"nomeFantasiaBeneficiarioFinal": "Quinatda dojão",
"numeroCpfCnpjPagador": "12345678900",
"nomeRazaoSocialPagador": "Maria José",
"nomeFantasiaPagador": "Rosa Maria da Silva",
"dataVencimento": "2018-09-20",
"valorBoleto": 100.36,
"valorAbatimentoDesconto": 0,
"valorMultaMora": 60.36,
"valorPagamento": 255.63,
"dataPagamento": "2019-10-20",
"situacaoPagamento": "Efetivado",
"descricaoDetalheSituacao": "Saldo no momento da rejeição em 10/03/2021 às 22:01:10: R$ 343,05.",
"dataHoraCadastro": "2019-10-20T12:30:22.000Z",
"aceitaValorDivergente": true,
"nossoNumero": "756",
"numeroDocumento": "123456",
"descricaoObservacao": "Boleto da Escola",
"descricaoOuvidoria": "OUVIDORIA AGIBANK: 08007250996",
"descricaoTituloComprovante": "PAGAMENTO DE BOLETO",
"idPagamento": 1983450,
"numeroAutenticacaoPagamento": "89C3E9FD-1A37-40BE-A85B-69AF118D336A"
}
}
```
**1.1.14 Respostas possíveis:**
| Code
| Description
|
| 204
| Requisição processada com sucesso e não há conteúdo a ser retornado.
|
| 400
| Possíveis erros de negócio.
|
| 406
| Possíveis erros de inconsistência nos dados passados.
|
| 500
| Erro interno.
|
**1.1.15 Exemplo retorno: (Mesmo padrão de retorno para o 400, 406 e 500)**
```json
{
"mensagens": [
{
"mensagem": "string",
"codigo": "string"
}
]
}
```
**1.1.16 Serviço para cancelar um agendamento de pagamento.**
| Método HTTP
| URL
|
| DELETE
| /boletos/pagamentos/agendamentos/{idPagamento}
|
**Parâmetros:**
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1736361112205.png)
Exemplo valor | Modelo: **(cancelamento)**
```json
{
"numeroConta": 1234569
}
```
**1.1.17 Resposta esperada:**
| Code
| Description
|
| 204
| Requisição processada com sucesso e não há conteúdo a ser retornado.
|
**1.1.18 Respostas possíveis:**
| Code
| Description
|
| 400
| Possíveis erros de negócio.
|
| 406
| Possíveis erros de inconsistência nos dados passados.
|
| 500
| Erro interno
|
**1.1.19 Exemplo retorno: (Mesmo padrão de retorno para o 400, 406 e 500)**
```json
{
"mensagens": [
{
"mensagem": "string",
"codigo": "string"
}
]
}
```
**1.1.20 Serviço para consultar um comprovante de um pagamento efetuado atarvés do idempotency**
| Método HTTP
| URL
|
| GET
| /boletos/pagamentos/{idempotency}/idempotency/comprovantes
|
**Parâmetros:**
[](https://docs.softensistemas.com.br/uploads/images/gallery/2025-01/image-1736361549118.png)
**1.1.21 Resposta esperada:**
**1.1.22 Exemplo retorno:**
```json
{
"resultado": {
"numeroAgencia": "0001-9",
"nomeAgencia": "Agência Sede",
"numeroConta": 1234569,
"nomeProprietarioContaCorrente": "José da Silva",
"numeroLinhaDigitavel": "string",
"numeroInstituicaoEmissora": 756,
"nomeInstituicaoEmissora": "Banco Cooperativo do Brasil",
"numeroCpfCnpjBeneficiario": "12345678900",
"nomeRazaoSocialBeneficiario": "José da Silva",
"nomeFantasiaBeneficiario": "Estilo Tech",
"numeroCpfCnpjBeneficiarioFinal": "12345678900",
"nomeRazaoSocialBeneficiarioFinal": "João das Flores",
"nomeFantasiaBeneficiarioFinal": "Quinatda dojão",
"numeroCpfCnpjPagador": "12345678900",
"nomeRazaoSocialPagador": "Maria José",
"nomeFantasiaPagador": "Rosa Maria da Silva",
"dataVencimento": "2018-09-20",
"valorBoleto": 100.36,
"valorAbatimentoDesconto": 0,
"valorMultaMora": 60.36,
"valorPagamento": 255.63,
"dataPagamento": "2019-10-20",
"situacaoPagamento": "Efetivado",
"descricaoDetalheSituacao": "Saldo no momento da rejeição em 10/03/2021 às 22:01:10: R$ 343,05.",
"dataHoraCadastro": "2019-10-20T12:30:22.000Z",
"aceitaValorDivergente": true,
"nossoNumero": "756",
"numeroDocumento": "123456",
"descricaoObservacao": "Boleto da Escola",
"descricaoOuvidoria": "OUVIDORIA AGIBANK: 08007250996",
"descricaoTituloComprovante": "PAGAMENTO DE BOLETO",
"idPagamento": 1983450,
"numeroAutenticacaoPagamento": "89C3E9FD-1A37-40BE-A85B-69AF118D336A"
}
}
```
**1.1.23 Respostas possíveis:**
| Code
| Description
|
| 204
| Requisição processada com sucesso e não há conteúdo a ser retornado.
|
| 400
| Possíveis erros de negócio.
|
| 406
| Possíveis erros de inconsistência nos dados passados.
|
| 500
| Erro interno.
|
**1.1.19 Exemplo retorno: (Mesmo padrão de retorno para o 400, 406 e 500)**
```json
{
"mensagens": [
{
"mensagem": "string",
"codigo": "string"
}
]
}
```
#####
##### **AVISO IMPORTANTE**
**Desativação da API Cobrança Bancária V2**
Informamos que a API Cobrança Bancária **V2** será descontinuada em **30 de abril de 2025.** Essa medida está sendo tomada em função do lançamento da **API Cobrança Bancária V3**, que já está disponível e oferece melhorias significativas.
Orientamos que os cooperados que ainda utilizam a versão 2 realizem a migração para a versão 3 para garantir a continuidade dos serviços e o acesso às novas funcionalidades. Abaixo está o cronograma da desativação:
- **03/01/2025 Desativação da criação de credenciais para novas integrações:**Para incentivar a adoção da nova versão, não será mais possível criar credenciais para a API Cobrança Bancária V2. A criação de credenciais estará disponível apenas para a V3.
- **30/04/2025 Interrupção do funcionamento da API Cobrança Bancária V2:**A partir dessa data, a V2 da API será desativada. Todos os integradores e empresas parceiras que ainda utilizam a versão V2 devem migrar para a V3 antes desta data para evitar impactos nos serviços.
#### **Acesso para conferir o catalógo completo das API's:** [Catálogo de API's](https://developers.sicoob.com.br/portal/apis "Catálogo de API's")
©SOFTEN SISTEMAS 2024