Sumário
Cadastrando um Convênio
Assim como a conta, o cadastro do convênio irá fornecer informações para outros fluxos da aplicação. É nele que vamos configurar dados como carteira, CNAB, forma de registro, etc. Lembre-se que vamos precisar do campo id da conta que foi retornado na requisição anterior. Isso acontece pois um cedente pode ter várias contas, e é através desse ID que vinculamos esse novo convênio à conta correta.
POST
Homologação:
https://homologacao.plugboleto.com.br/api/v1/cedentes/contas/convenios
Produção:
https://plugboleto.com.br/api/v1/cedentes/contas/convenios
Headers
Nome | Descrição | Exemplo |
Content-Type | Indica o tipo de arquivo | application/json |
cnpj-sh | CNPJ ou CPF da Software House | 01001001000113 |
token-sh | Token da Software House | f22b97c0c9a3d41ac0a3875aba69e5aa |
cnpj-cedente | CNPJ ou CPF do cedente | 01001001000113 |
Headers (Opcional)
Utilizar esses headers em caso de autenticação direto com as credenciais do cedente:
Nome | Descrição | Exemplo |
Content-Type | Indica o tipo de arquivo | application/json |
cnpj-cedente | CNPJ do Cedente | 01001001000113 |
token-cedente | Token do Cedente | f22b97c0c9a3d41ac0a3875aba69e5aa1 |
Body
Campo | Tipo | Descrição |
ConvenioNumero | string | Número do convênio |
ConvenioDescricao | string | Descrição do convênio |
ConvenioCarteira | string | Número da carteira |
carteira_codigo | string |
Campo opcional. Valores aceitos: 1 = Cobrança Simples |
ConvenioEspecie | string | Espécie do convênio |
ConvenioPadraoCNAB | string | Padrão CNAB. Informar 240 ou 400 |
ConvenioReiniciarDiariamente | boolean | Define se o número atual da remessa será reiniciado diariamente. |
ConvenioNumeroRemessa | string | Número atual da remessa. Campo obrigatório para Sicredi |
Conta | integer | Identificador da conta na nossa base de dados. O campo "id" será disponibilizado a você no json de retorno da rota de cadastro da conta. |
ConvenioDensidaDeRemessa | string | Código de Densidade da remessa (verificar a necessidade de preenchimento na seção "Dicas de preenchimento"). Preencher com 1600 ou 6250, conforme orientação do banco. |
ConvenioRegistroInstantaneo | boolean | Define se o convênio irá ou não utilizar a transmissão instantânea. |
ConvenioApiId | string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioApiKey | string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioApiSecret | string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioEstacao | string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioNossoNumeroBanco | boolean | true (verdadeiro) ou false (falso). Define se o Nosso Numero será controlado pelo banco. (Carteira Escritural) |
ConvenioNossoNumeroConciliarBanco | boolean |
true (verdadeiro) ou false (falso). Define a forma como os retornos serão conciliados de acordo com o preenchimento do TituloNossoNumero no arquivo de retorno. Ex: Ex: Se o retorno não contiver o TituloNossoNumero informado pelo banco, você pode desabilitar a conciliação configurando a opção "ConvenioNossoNumeroConciliarBanco" como false ou desabilitando-a por meio da interface do PlugBoleto. |
Conveniotipowebservice | string |
Campo utilizado para registro instantâneo (Web Service), para que seja possível escolher a versão da API a ser utilizada pelo banco. Valores aceitos v1, v2, v2.2* e v3**.
Caso o convênio seja do Bradesco, as opções aceitas são: NORMAL ou SHOP FACIL. O tipo do WS é definido pelo banco, no momento da liberação do serviço. |
ConvenioConsultaws | Boolean |
Define se estará realizando as consultas dos boletos emitidos via WS (Será possível desativar apenas para os bancos: Bradesco(237), Caixa(104), Itaú(341) e Sicoob(756)).
*Quando o campo está definido como true, a API desconsidera qualquer tipo de Ocorrência passada por Arquivo de Retorno, tendo em vista que a opção habilita a recepção dos dados via WS. |
ConvenioNumeroContrato | string |
Campo utilizado para informar o "número de contrato" da conta caso o banco Banrisul exija este campo presente na remessa.
Disponível apenas no CNAB 240. |
ConvenioVersaoLayoutArquivo
|
string |
Versão do layout que deseja utilizar do banco (opcional)
|
ConvenioAlteracaoWebservice
|
Boolean |
Campo utilizado para informar se irá utilizar o serviço de alteração de boletos via WebService
Disponível apenas para o banco ( Itaú v2 )
|
Dica: Para auxiliar no cadastro do convênio, possuímos uma seção de dicas, onde você encontra um detalhamento sobre as informações que devem ser preenchidas para cada banco.
Segue o link desta documentação: https://atendimento.tecnospeed.com.br/hc/pt-br/sections/360002897054-Dicas-para-cadastro-de-contas-e-conv%C3%AAnios
Exemplo:
{
"ConvenioNumero": "7889604745",
"ConvenioDescricao": "Convenio da tecnospeed",
"ConvenioCarteira": "109",
"ConvenioEspecie": "R$",
"ConvenioPadraoCNAB": "400",
"ConvenioNumeroRemessa": "1",
"ConvenioReiniciarDiariamente": false,
"Conta": 168
}
Retorno
Exemplo de retorno:
{
"_status": "sucesso",
"_dados": {
"id": 154,
"numero_convenio": "7889604745",
"descricao_convenio": "Convenio da tecnospeed",
"carteira": "109",
"especie": "R$",
"id_conta": 168,
"criado": "2017-03-30T18:01:19.000Z",
"atualizado": "2017-03-30T18:01:19.000Z",
"padraoCNAB": "400",
"utiliza_van": false,
"numero_remessa": 1
}
}
Obs.: É importantíssimo persistir em seu banco de dados o ID do Convênio retornado na resposta da requisição. Ele será usado caso seja preciso fazer alterações no cadastro do convênio futuramente.
Exemplo de retorno com erro:
{
"_status": "erro",
"_mensagem": "Acesso negado.",
"_dados": [
{
"_erro": "Conta do Cedente não encontrada"
}
]
}
Alterando um Convênio
Assim como em Alterando um cedente e na Alteração de uma conta, a Alteração de um Convênio se resume em preenchermos um modelo de integração (JSON) com os dados do convênio a serem alterados e enviarmos para o nosso servidor.
PUT
Homologação:
https://homologacao.plugboleto.com.br/api/v1/cedentes/contas/convenios/:id
Produção:
https://plugboleto.com.br/api/v1/cedentes/contas/convenios/:id
*Deve ser informado o id do convênio que deseja alterar na URL da requisição. É o mesmo ID retornado na rotina de cadastro do convênio.
Headers
Nome | Descrição | Exemplo |
Content-Type | Indica o tipo de arquivo | application/json |
cnpj-sh | CNPJ ou CPF da Software House | 01001001000113 |
token-sh | Token da Software House | f22b97c0c9a3d41ac0a3875aba69e5aa |
cnpj-cedente | CNPJ ou CPF do cedente | 01001001000113 |
Headers (Opcional)
Utilizar esses headers em caso de autenticação direto com as credenciais do cedente:
Nome | Descrição | Exemplo |
Content-Type | Indica o tipo de arquivo | application/json |
cnpj-cedente | CNPJ do Cedente | 01001001000113 |
token-cedente | Token do Cedente | f22b97c0c9a3d41ac0a3875aba69e5aa1 |
Body
Campo | Tipo | Descrição |
ConvenioNumero | string | Número do convênio |
ConvenioDescricao | string | Descrição do convênio |
ConvenioCarteira | string | Número da carteira |
carteiracodigo |
Campo opcional. Valores aceitos: null = campo vazio 1 = Cobrança Simples |
|
ConvenioEspecie | string | Espécie do convênio |
ConvenioPadraoCNAB | string | Padrão CNAB. Informar 240 ou 400 |
ConvenioReiniciarDiariamente | boolean | Define se o número atual da remessa será reiniciado diariamente. |
ConvenioNumeroRemessa | string | Número atual da remessa. Campo obrigatório para Sicredi |
Conta | integer | Identificador da conta na nossa base de dados |
ConvenioDensidadeRemessa | string | Código de Densidade da remessa (verificar a necessidade de preenchimento na seção "Dicas de preenchimento"). Preencher com 1600 ou 6250, conforme orientação do banco. |
ConvenioRegistroInstantaneo |
boolean | Define se o convênio irá ou não utilizar a transmissão instantânea. |
ConvenioApiId |
string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioApiKey |
string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioApiSecret |
string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioEstacao |
string | Campo utilizado para a transmissão instantânea, dúvida de como preencher clique aqui |
ConvenioNossoNumeroBanco |
boolean | true (verdadeiro) ou false (falso). Define se o Nosso Numero será controlado pelo banco. (Carteira Escritural) |
ConvenioNossoNumeroConciliarBanco |
boolean |
true (verdadeiro) ou false (falso). Define a forma como os retornos serão conciliados de acordo com o preenchimento do TituloNossoNumero no arquivo de retorno. Ex: Ex: Se o retorno não contiver o TituloNossoNumero informado pelo banco, você pode desabilitar a conciliação configurando a opção "ConvenioNossoNumeroConciliarBanco" como false ou desabilitando-a por meio da interface do PlugBoleto. Documentação: Carteira Escritural |
Conveniotipowebservice |
string |
Campo utilizado para registro instantâneo (Web Service), para que seja possível escolher a versão da API a ser utilizada pelo banco. Valores aceitos v1, v2, v2.2* e v3**.
Caso o convênio seja do Bradesco, as opções aceitas são: NORMAL ou SHOP FACIL. O tipo do WS é definido pelo banco, no momento da liberação do serviço. |
ConvenioConsultaws | Boolean | Define se estará realizando as consultas dos boletos emitidos via WS (Será possível desativar apenas para os bancos: Bradesco(237), Caixa(104), Itaú(341) e Sicoob(756)) |
ConvenioNumeroContrato | string |
Campo utilizado para informar o "número de contrato" da conta caso o banco Banrisul exija este campo presente na remessa.
Disponível apenas no CNAB 240. |
ConvenioVersaoLayoutArquivo |
string |
Versão do layout que deseja utilizar do banco (opcional) |
ConvenioAlteracaoWebservice
|
Boolean |
Campo utilizado para informar se irá utilizar o serviço de alteração de boletos via WebService
Disponível apenas para o banco (Itaú v2)
|
Exemplo:
{
"ConvenioNumero": "7889604745",
"ConvenioDescricao": "Convenio da tecnospeed",
"ConvenioCarteira": "109",
"ConvenioEspecie": "R$",
"ConvenioPadraoCNAB": "400",
"ConvenioNumeroRemessa": "1",
"Conta": 168
}
Retorno
Exemplo de retorno:
{
"_status": "sucesso",
"_dados": {
"id": 154,
"numero_convenio": "7889604745",
"descricao_convenio": "Convenio da tecnospeed",
"carteira": "109",
"especie": "Boleto",
"id_conta": 168,
"criado": "2017-03-30T18:01:19.000Z",
"atualizado": "2017-03-30T18:01:19.000Z",
"padraoCNAB": "400",
"utiliza_van": false,
"numero_remessa": 1
}
}
Exemplo de retorno com erro:
{
"_status": "erro",
"_mensagem": "Acesso negado.",
"_dados": [
{
"_erro": "Conta do Cedente não encontrada"
}
]
}
Consultando Convênios
Para consultar convênios, basta utilizar a mesma rota utilizada no cadastro (POST), alterando para GET e informando uma QueryString
para aplicar um filtro, abaixo temos exemplos de como realizar tais consultas:
Como base devem ser utilizada as seguintes URl's
Homologação:
https://homologacao.plugboleto.com.br/api/v1/cedentes/contas/convenios
Produção:
https://plugboleto.com.br/api/v1/cedentes/contas/convenios
Para consultar um convênio por ID
utilizando com exemplo a url de homologação devemos utilizar a seguinte url:
https://homologacao.plugboleto.com.br/api/v1/cedentes/contas/convenios?id=137
No resultado desta busca será retornado, o convênio que possui o ID igual á 137
.
Retorno
Exemplo de retorno:
{
"_status": "sucesso",
"_dados": [
{
"id": X,
"razaosocial": "TESTE",
"nomefantasia": "TESTE",
"cpf_cnpj": "11111111111111",
"logradouro": "RUA TESTE",
"numero": "100",
"complemento": "QD3 LT 19",
"bairro": "BAIRRO TESTE",
"cep": "87000000",
"id_cidade": 979,
"telefone": "44999999999",
"email": "TESTE@TESTE.COM",
"criado": "2024-01-14T18:26:49.000Z",
"atualizado": "2024-01-21T02:30:03.000Z",
"token_cedente": "---------------",
"token_esales": "0",
"situacao": "ATIVO",
"id_software_house": X,
"config_email": null,
"config_notificacao": {
"baixou": {
"sms": {},
"email": {}
},
"liquidou": {
"sms": {},
"email": {}
},
"registrou": {
"sms": {},
"email": {}
}
},
"motivo_inativacao": null,
"data_ativacao": "2024-01-21T02:30:03.000Z",
"data_inativacao": null,
"certificado": null,
"dtvencimentocertificado": null,
"config_webhook": null,
"linha_digitavel_recibo": false,
"santander_carteira_impressao": false,
"token_intermediadora": null,
"uf": "PR",
"contas": [
{
"id": X,
"codigo_banco": "001",
"codigo_banco_correspondente": null,
"agencia": "111",
"agencia_dv": null,
"conta": "22222",
"conta_dv": "3",
"tipo_conta": "CORRENTE",
"cod_beneficiario": "44444",
"id_cedente": X,
"criado": "2024-01-14T18:27:27.000Z",
"atualizado": "2024-01-14T18:27:27.000Z",
"cod_empresa": null,
"ativo": true,
"validacao_ativa": false,
"impressao_atualizada": false,
"carteira_correspondente": null,
"agencia_correspondente": null,
"conta_correspondente": null,
"codigo_cip_correspondente": null,
"conta_dv_correspondente": null,
"impressao_atualizada_alteracao": false,
"impressao_atualizada_liquidado": true,
"config_notificacao": null,
"convenios": [
{
"id": X,
"numero_convenio": "5555",
"descricao_convenio": "TESTE",
"carteira": "17",
"especie": "R$",
"id_conta": X,
"criado": "2021-01-14T18:27:55.000Z",
"atualizado": "2021-01-14T18:27:55.000Z",
"padraoCNAB": "240",
"utiliza_van": false,
"numero_remessa": null,
"densidade_remessa": null,
"codigo_cobranca": null,
"reiniciar_diariamente": true,
"registro_automatico": false,
"numero_remessa_manual": false,
"estacao": null,
"ativo": true,
"nossonumero_controle_banco": null,
"api_id": null,
"api_key": null,
"api_secret": null,
"tipo_webservice": null,
"carteira_codigo": null,
"versao_layout": null,
"numero_contrato": null,
"codigo_identificador": null,
"consultaws": true,
"alteracao_webservice": false,
"van_provider": null,
"van_client": null,
"van_password": null,
"van_mailbox": null,
"certificado_s3_key": null,
"certificado": null,
"dtvencimentocertificado": null,
"nossonumero_conciliar_banco": true,
"bolecode": false,
"pix_chave": null,
"pix_client_id": null,
"pix_client_secret": null,
"pix_certificado_s3_key": null,
"pix_certificado": null,
"pix_dtvencimentocertificado": null,
"consulta_francesa": false
}
]
}
],
"cidadeibge": 4115200,
"cidade": "Maringa"
}
Deletando Convênios
Para deletar convênios, basta utilizar a mesma rota utilizada no cadastro (POST), alterando para DELETE e adicionar o ID do convênio.
Como base devem ser utilizada as seguintes URl's
Homologação:
https://homologacao.plugboleto.com.br/api/v1/cedentes/contas/convenios/ID_CONVENIO
Produção:
https://plugboleto.com.br/api/v1/cedentes/contas/convenios/ID_CONVENIO
Exemplo de resposta:
Sucesso:
Falha:
Comentários
0 comentário
Por favor, entre para comentar.