API Sicoob - Cobrança Bancária Pagamentos

Esta documentação descreve os endpoints da API do Sicoob para realização de pagamentos de boletos de Cobrança Bancária, conforme implementado na classe Sicoob.php.

Autenticação

Para utilizar estes endpoints, é necessário obter um token com os escopos apropriados:

• pagamentos_consulta
• pagamentos_inclusao
• pagamentos_alteracao

O método getAccessToken(string $scope) gerencia a obtenção do token automaticamente.

---

Endpoints

1. Consultar Boleto

Permite consultar informações detalhadas sobre um boleto (status, valor, vencimento, beneficiário).

• Método: consultarBoleto(string $codigoBarras, ?string $dataPagamento = null)
• Parâmetros:
  • codigoBarras: Código de barras (44 dígitos) ou linha digitável (47 dígitos).
  • dataPagamento (Opcional): Data prevista para o pagamento (yyyy-MM-dd).
• Endpoint Sicoob: GET /pagamentos/v3/boletos/\{codigoBarras\}
• Retorno Detalhado (array):

  Chave	Tipo	Descrição
  resultado	object	Objeto contendo os dados do boleto.
  resultado->valorBoleto	string	Valor nominal registrado no boleto.
  resultado->dataVencimentoBoleto	string	Data de vencimento (yyyy-MM-dd).
  resultado->nomeRazaoSocialBeneficiario	string	Nome do beneficiário (credor).
  resultado->codigoSituacaoBoletoPagamento	string	Situação (1: Em Aberto, 2: Baixado, 3: Liquidado).
  resultado->identificadorConsulta	string	Importante: Hash único para autorizar o pagamento no próximo passo.

2. Pagar Boleto

Efetua o pagamento imediato ou agenda o pagamento de um boleto.

• Método: pagarBoleto(string $codigoBarras, array $data, ?string $idempotencyKey = null)
• Parâmetros:
  • codigoBarras: Código de barras (44 posições).
  • idempotencyKey (Opcional): Chave de idempotência única. Se não informada, será gerada automaticamente no formato Cooperativa-Conta-UUID.
• Parâmetros da Payload ($data):

  Atributo	Tipo	Obrigatório	Descrição
  identificadorConsulta	string	Sim	Hash retornado na consulta do boleto.
  amount	number	Sim	Valor final a ser pago (com juros/descontos aplicados).
  date	string	Sim	Data do pagamento (yyyy-MM-dd).
  debtorAccount	array	Sim	Dados da conta de débito (issuer, number, accountType).

• Endpoint Sicoob: POST /pagamentos/v3/boletos/pagamentos/\{codigoBarras\}
• Retorno Detalhado (array):

  Chave	Tipo	Descrição
  idPagamento	string	Identificador único do pagamento no SISBR.
  status	string	Status da operação (EFETIVADO, AGENDADO, PENDENTE).
  autenticacao	string	Código de autenticação eletrônica (comprovante).

3. Consultar Comprovante

Consulta o comprovante de um pagamento já efetuado.

• Método: consultarComprovante(string $idPagamento)
• Parâmetros:
  • idPagamento: Número de identificação do agendamento no SISBR.
• Endpoint Sicoob: GET /pagamentos/v3/boletos/pagamentos/\{idPagamento\}/comprovantes
• Retorno Detalhado (array):

  Chave	Tipo	Descrição
  codigoSituacao	string	Status do pagamento ("1" para Efetivado).
  dataPagamento	string	Data em que o pagamento foi processado.
  valorPagamento	number	Valor total debitado da conta.
  autenticacao	string	Autenticação eletrônica para validade jurídica.

4. Consultar Comprovante por Idempotência

Consulta o comprovante utilizando a chave de idempotência enviada no momento do pagamento.

• Método: consultarComprovanteByIdempotency(string $idempotency)
• Retorno: Estrutura idêntica ao item 3.
• Endpoint Sicoob: GET /pagamentos/v3/boletos/pagamentos/\{idempotency\}/idempotency/comprovantes

5. Cancelar Agendamento

Cancela um agendamento de pagamento ainda não processado.

• Método: cancelarAgendamento(string $idPagamento)
• Endpoint Sicoob: DELETE /pagamentos/v3/boletos/pagamentos/agendamentos/\{idPagamento\}
• Retorno: Confirmação de exclusão ou erro se já processado.

6. Consultar Boletos DDA

Consulta boletos vinculados ao CPF/CNPJ da conta (DDA).

• Método: consultarBoletosDDA(array $filters = [])
• Filtros comuns:
  • dataInicial, dataFinal (yyyy-MM-dd)
  • situacao (1: Aberto, 2: Agendado, 3: Liquidado, 4: Baixado)
  • tipoData (1: Vencimento, 2: Emissão, 3: Inclusão)
• Endpoint Sicoob: GET /pagamentos/v3/boletos
• Retorno Detalhado (array):

  Chave	Tipo	Descrição
  resultado	array	Lista de objetos de boletos.
  lista[n]->nossoNumero	string	Identificador do boleto.
  lista[n]->valor	number	Valor do título.
  lista[n]->dataVencimento	string	Vencimento do DDA.