Para realizar Registro de Boletos, Consulta de Boletos e Comando de instruções, se faz necessário:

• consumir o Endpoint para recepção do Access Token (JWT - JSON Web Token)
• cadastrar uma Workspace de Cobrança.

A Workspace é um pré-requisito para ter o acesso ao Hub de Cobrança via API e neste ambiente, você cadastrará os convênios de Cobrança a serem operados via API.

Poderão ser associados numa mesma Workspace, convênios de cobrança contratados na mesma raiz do CNPJ vinculado as credenciais obtidas em nosso Portal do Desenvolvedor (ClientID e ClientSecret).

Todos os acessos para criação do workspace devem ser feitos na ferramenta POSTMAN

Para a realização das configurações de integração com as APIs, sugerimos a utilização da ferramenta Postman. Esta ferramenta auxilia desenvolvedores a validar APIs e para obter uma collection. Mas, o que é uma collection? Uma Collection é um conjunto de solicitações de API que podem ser organizadas e executadas. Ela inclui todas as informações necessárias para realizar uma chamada via API, como URL/Endpoints, parâmetros, cabeçalhos, corpo da solicitação etc.

Link para a Collection que será utilizada no Postman: collection_api_emissao_boletos_prod.zip

Para criar uma Workspace no Hub de Cobrança, é necessário consumir o endpoint POST/workspaces

Produção: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces

A primeira coisa a se fazer é obter o token de acesso

Com o Postman aberto Importe a Collection baixada anteriormente.

Importação dos certificados

Para que a comunicação funciona devemos inserir os certificados gerados (CRT e KEY)

Passo 1: Importação do certificado Clicar no ícone da ferramenta no Postman e em seguida em “Settings”:


Acessar a aba “Certificates” e clicar em “Add Certificate”:



Preencher o campo “Host” com: trust-open.api.santander.com.br (Ambiente de Produção) importar o CRT file e o KEY file clicando em “Select File”, em seguida clicar em “Add”.

Passo 2: Geração do JWT No método POST inserir a URL de Produção <trust-open.api.santander.com.br/auth/oauth/v2/token>. Clicar na aba “Body” e no item “x-www-form-urlencoded” e preencher com as informações “client_id: Inserir o Client ID”, “client_secret: Inserir o Client Secret” e “grant_type : client_credentials”. Ao clicar em “Send” será gerado o JWT no campo “access_token”

Passo 3: Inclusão de JWT nas chamadas da API
Clicar na aba “Authorization”, selecionar o Type “OAuth 2.0” e colar o JWT no campo “Token”:

Passo 4: Inclusão do X-Application-Key nas chamadas da API
Clicar na aba “Headers” e incluir o headera “X-Application-Key:(client_id)”:

Após esses passos, é só prosseguir normalmente as chamadas no Hub Workspaces. Caso comece a retornar erro 401, gerar um novo JWT e substituí-lo na aba “Authorization”, conforme mostrado no passo 2 e 3.

===== Criar Workspace ===== Para criar uma Workspace no Hub de Cobrança, é necessário consumir o endpoint POST/workspaces preenchendo os campos conforme solicitados na collection do postman

Importante:
Para utilizar a API de registro de boletos do HUB de Cobrança é obrigatório que os convênios a serem utilizados para o registro estejam previamente cadastrados em uma Workspace;
Os convênios deverão obrigatoriamente pertencer a mesma raiz de CNPJ associada a credencial de acesso, obtida após o cadastro do certificado de segurança no Portal do Desenvolvedor;
Caso na lista de convênios, seja enviado um código inválido ou não pertencente a raiz de CNPJ associada a credencial de acesso, será retornado o erro “10057 – Erro ao tentar validar os convênios”;
Caso seja enviada uma lista de convênios vazia, será retornado o erro “10058 – Convênio está inválido”.
Apesar de em alguns contextos o código do convênio de Cobrança mantido em Banco e Cliente ser informado com 20 caracteres (no Internet Banking, por exemplo), no momento de registrar a Workspace, registrar boletos, comandar instruções e realizar consultas, deve-se utilizar apenas os 7 algarismos que representam o código do beneficiário:
Ex1: Convênio completo: 00332271001912345674 Convenio a ser informado na Workspace: 1234567
Ex2: Convênio completo: 00333689001901123447 Convenio a ser informado na Workspace: 0112344
Ex3: Convênio completo: 00330001001900556778 Convenio a ser informado na Workspace: 0055677
Obs.: para os casos em que existam zeros à esquerda do convênio (como ocorre nos exemplos 2 e 3) o dado pode ser cadastrado na Workspace de duas maneiras (com e sem os zeros à esquerda):
“code”: “0112344” ou “code”: “112344” | “code”: “0055677” ou “code”: “55677”