Débitos (boletos)
Quando falamos de débitos, falamos de documentos que o cliente precisa conhecer e avaliar, para que possa realizar pagamentos, conferir baixas ou mesmo enviar fichas de compensação para outras pessoas efetuarem os pagamentos dos títulos.
A integração de débitos possui diversos métodos que permitem que sua empresa disponibilize documentos de cobrança (boletos, por exemplo) para seus clientes.
Para viabilizar essa integração, será necessária a criação dos seguintes artefatos de banco de dados:
Caso seu SGDB esteja configurado para ser CASE SENSITIVE, crie todos os objetos de bancos de dados em MINÚSCULAS.
Importante: todos os objetos desta documentação são obrigatórios. Não criar um ou mais objetos impossibilitará que a integração via banco de dados OMNILINK seja corretamente realizada.
Tipo do objeto: View
Nome do objeto: omni_debito
Objeto obrigatório: SIM
Informação adicional: esta view tem como objetivo listar todos os débitos (documentos de cobrança como por exemplo boletos) atribuídos aos clientes, independentemente do período. Insira nessa view todos os documentos que sua empresa deseja exibir aos clientes com acesso ao app. Portanto não insira, por exemplo, documentos de cobrança que são de “controle interno” se existirem.
Estrutura de campos:
Nome | Tipo | Obrigatório | Informações |
|---|---|---|---|
id_omni_debito | Número | Sim | Atributo do tipo primary key. Este atributo deve ser um número único por registro. |
id_operadora | Número | Sim | Atributo fixo o valor = 1, quanto view for implementado pela operadora. |
instancia_aplicacao | Texto | Sim | Atributo fixo no valor = '1', quanto view ou tabela for implementado pela operadora. |
id_config_cliente_app | Número | Sim | Atributo fixo no valor = 1, quanto view ou tabela for implementado pela operadora. |
chave_unica | Texto | Sim | Chave de identificação única por beneficiário. Não deve se repetir em nenhuma hipótese. |
numero_contrato | Texto | Sim | Número do contrato vinculado a este debito. Este código deve ter relação com o código do contrato do usuário logado. |
cnpj | Texto | Sim | Informar CNPJ da operadora (somente números). Este atributo é utilizado para identificar os dados da operadora, bem como seus dados bancários. |
conta_corrente | Texto | Sim | Informar a conta corrente completa que será exibida no boleto gerado pelo OMNILINK (ou seja, da sua empresa). Exemplo: 349454-4 |
agencia | Texto | Sim | Informar a agência completa que será exibida no boleto gerado pelo OMNILINK (ou seja, da sua empresa). Exemplo: 3154-8 |
banco | Texto | Sim | Código do banco do título (informar somente código) que será exibido no boleto gerado pelo OMNILINK (ou seja, da sua empresa). Exemplo: 001 - Quando refere-se ao Banco do Brasil 237 - Quando refere-se ao Bradesco E assim por diante. Atributo servirá para buscar dados bancários. |
id_titulo | Número | Sim | Id de banco de dados do título no seu sistema interno, não pode se repetir. Se o seu sistema exigir o id do título como chave para localizar o mesmo nos demais métodos, este campo deverá ser considerado obrigatório. Somente números (Não podem existir letras, espaços em branco, ou pontos decimais). |
codigo_titulo | Texto | Sim | Código do título no seu sistema interno, exemplo “MS00579”, não pode se repetir. Formato: Texto livre. |
data_emissao | Texto | Sim | Formato: YYYY-MM-DD Informe a data de emissão do documento de cobrança. |
data_processamento | Texto | Sim | Formato: YYYY-MM-DD |
data_pagamento | Texto | Condicional | Formato: YYYY-MM-DD Informe a data do pagamento do débito. Este campo deve ser informado caso a propriedade ‘situacao_id’ for igual a B, de baixado. |
situacao_id | Texto | Sim | Tipos FIXOS. Serão permitidos APENAS os seguintes: P - A Vencer (em aberto porém ainda não está vencido). A = Atrasado (em aberto, porém já vencido). B = Baixado (já foi pago). Caso envie algo diferente desse conteúdo, o status do boleto não será exibido. |
situacao_descricao | Texto | Sim | O que for informado neste campo será exibido como descrição. Exemplos: A vencer Atrasado Baixado |
situacao_cor | Texto | Sim | Hexadecimal. Informe o código da cor que deseja exibir este débito. Importante: enviar com o # Exemplo: Caso não informado o aplicativo utilizará a tabela de cor padrão. |
tipo_cobranca_id | Texto | Sim | C = Consignação B = Boleto. D = Débito em conta. IMPORTANTE: A linha digitável só será exibida caso o tipo_cobranca_id for “B” |
tipo_cobranca_descricao | Texto | Sim | Descrição da situação do débito Consignação / desconto em folha. Boleto Débito em conta |
tipo_cobranca_cor | Texto | Sim | Hexadecimal. Informe o código da cor que deseja exibir este débito. Importante: enviar com o # Exemplo: Caso não informado o aplicativo utilizará a tabela de cor padrão. |
descricao | Texto | Não | Utilize este campo para adicionar uma descrição do título na lista de boletos. Este campo é ideal para identificar, na listagem de títulos, se trata-se de um documento de cobrança relacionado a coparticipação, titulo de mensalidade ou de renegociação. |
fatura_digital | Número | Não | Utilize este campo para informar se o contratante fez adesão à fatura digital para este contrato. Conteúdos aceitos: 0 = Não 1 = Sim |
debito_automatico | Número | Não | Utilize este campo para informar se a forma de pagamento deste contrato é Débito Automático. Conteúdos aceitos: 0 = Não 1 = Sim |
observacao | Texto | Não | Informe um texto de observação para ser apresentado na tela de detalhes do boleto. Este texto será apresentado abaixo da linha digitável, em destaque. |
informacoes | Texto | Não | Utilize este campo para apresentar informações ao pagador. Você pode utilizar este espaço para justificar eventuais alterações de valores por motivo de atraso no pagamento. |
valor_original | Número | Não | Informe o valor original do título antes de sofrer eventuais ajustes de multas por atraso. Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) |
valor_atualizado | Número | Não | Informe o valor atualizado do título após sofrer eventuais ajustes de multas por atraso. |
vencimento_original | Texto | Não | Formato: YYYY-MM-DD Informe a data de vencimento original do título antes de sofrer alteração em função de acordos. |
vencimento_atualizado | Texto | Não | Data de vencimento atualizada do débito. Formato: YYYY-MM-DD |
alerta_mensagem | Texto | Opcional | Esta mensagem será exibida no documento de cobrança, em destaque. Utilize para destacar uma informação relevante na listagem de débitos. |
alerta_cor | Texto | Condicional | Caso o campo alerta_mensagem contenha algum conteúdo (diferente de vazio), esse campo torna-se obrigatório. A cor precisa estar no formato hexadecimal. Importante: enviar com o # Exemplo: Caso não seja informada a cor, o validador de integração vai rejeitar sua integração. |
alerta_icone | Texto | Opcional | Indique o ícone de sua preferência. Caso não seja indicado, o app vai escolher o ícone padrão. |
instrucao_boleto | Texto | Condicional | Texto para preencher o espaço de “Instruções” da ficha de compensação do Boleto. |
desconto_abatimento | Número | Condicional | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) Obrigatório quando a forma de cobrança for do tipo Boleto, ou seja, tipo_cobranca_id = 'B' e caso tenha descontos a lançar. |
outras_deducoes | Número | Condicional | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) Obrigatório quando a forma de cobrança for do tipo Boleto, ou seja, tipo_cobranca_id = 'B' e caso tenha outras deduções a lançar. |
mora_multa | Número | Condicional | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) Obrigatório quando a forma de cobrança for do tipo Boleto, ou seja, tipo_cobranca_id = 'B' e caso tenha mora ou multa a lançar. |
outros_acrescimos | Número | Condicional | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) Obrigatório quando a forma de cobrança for do tipo Boleto, ou seja, tipo_cobranca_id = 'B' e caso tenha outros acréscimos a lançar. |
local_pagamento | Texto | Condicional | Informação sobre local de pagamento. Obrigatório quando a forma de cobrança for do tipo Boleto, ou seja, tipo_cobranca_id = 'B' e caso tenha outros acréscimos a lançar. |
especie_documento | Texto | Sim | Retornar a sigla da especie do documento. |
numero_documento | Texto | Condicional | Número do documento criado pelo sistema da operadora. Obrigatório quando a forma de cobrança for do tipo Boleto, ou seja, tipo_cobranca_id = 'B' e caso tenha outros acréscimos a lançar. |
solicita_confirmacao | Texto | Sim | Informe FALSE. Motivo: Reservado para implementação futura |
texto_confirmacao | Texto | Condicional | Deixar em branco |
btn_comp_pag_ativo | Texto | Sim | INFORME SEMPRE FALSE. Motivo: Reservado para implementação futura |
btn_comp_pag_label | Texto | Condicional | Deixar em branco |
btn_res_cobr_ativo | Texto | Sim | Informe TRUE caso deseje exibir o botão de “Resumo de cobrança” para o débito em questão. Caso não deseje exibir esse botão, informe FALSE. |
btn_res_cobr_label | Texto | Condicional | Texto que será exibido no botão que exibe o resumo da cobrança na tela de detalhes do débito. Caso campo btn_res_cobr_ativo seja TRUE, esse campo torna-se obrigatório. Caso contrário, deixe o atributo em branco. |
btn_boleto_pdf_ativo | Texto | Sim | Informe TRUE caso deseje exibir o botão de “Boleto em PDF” para o débito em questão. Caso não deseje exibir esse botão, informe FALSE. Exemplo: em débitos já quitados, é comum não exibir o boleto, evitando pagamento em duplicidade. Portanto, sugerimos que quando o débito esteja com status PAGO, esse campo esteja com conteúdo FALSE. |
btn_boleto_pdf_label | Texto | Condicional | Texto que será exibido no botão que exibe o boleto em PDF na tela de detalhes do débito. Caso campo btn_boleto_pdf_ativo seja TRUE, esse campo torna-se obrigatório. Caso contrário, deixe o atributo em branco. |
nosso_numero | Texto | Não | Preencher com o “Nosso Número”. Em boletos registrados, essa informação deve existir. |
digito_nosso_numero | Texto | Não | Preencher com o Dígito do Nosso Número. Em boletos registrados, essa informação deve existir. |
carteira | Texto | Não | Indique a carteira de cobrança dessa cobrança. Em boletos registrados, essa informação deve existir. |
moeda | Texto | Não | Caso seja um boleto, geralmente é indicado preencher "REAL”. |
Tipo do objeto: View
Nome do objeto: omni_dados_cedente
Objeto obrigatório: SIM
Informação adicional: view obrigatória, que tem correlação com a view de omni_debito. Nesta view, informe os dados do cedente para geração da ficha de compensação.
Importante: Essa view também será utilizada por outras integrações (Declarações, por exemplo).
Estrutura de campos:
Nome Atributo | Tipo Atributo | Obrigatório | Descrição |
|---|---|---|---|
id_omni_cedente | Número | Sim | Atributo do tipo primary key. Este atributo deve ser um número único por registro. |
id_operadora | Número | Sim | Atributo fixo o valor = 1, quanto view for implementado pela operadora. |
instancia_aplicacao | Texto | Sim | Atributo fixo no valor = '1', quanto view ou tabela for implementado pela operadora. |
id_config_cliente_app | Número | Sim | Atributo fixo no valor = 1, quanto view ou tabela for implementado pela operadora. |
cnpj | Texto | Sim | CNPJ do emissor do título. |
nome | Texto | Sim | Nome do cedente. |
logradouro | Texto | Sim | Informar endereço completo, incluindo número ou complemento. |
bairro | Texto | Sim | Informar Bairro do Cedente. |
cidade | Texto | Sim | Informar Cidade do Cedente |
uf | Texto | Sim | Informar UF do Cedente. Exemplos: SP ES RJ |
cep | Texto | Sim | Informar CEP do Cedente sem pontuação. Exemplo: 88020393 |
Tipo do objeto: View
Nome do objeto: omni_dados_bancario
Objeto obrigatório: SIM
Informação adicional: responsável por fornecer informações de dados bancários para os boletos.
Estrutura de campos:
Nome Atributo | Tipo Atributo | Obrigatório | Descrição |
|---|---|---|---|
id_omni_dados_bancario | Número | Sim | Atributo do tipo primary key. Este atributo deve ser um número único por registro. |
id_operadora | Número | Sim | Atributo fixo o valor = 1, quanto view for implementado pela operadora. |
instancia_aplicacao | Texto | Sim | Atributo fixo no valor = '1', quanto view ou tabela for implementado pela operadora. |
id_config_cliente_app | Número | Sim | Atributo fixo no valor = 1, quanto view ou tabela for implementado pela operadora. |
banco | Texto | Sim | Código do banco do título (informar somente código) Exemplo: 001 - Quando refere-se ao Banco do Brasil 237 - Quando refere-se ao Bradesco E assim por diante. Atributo servirá para buscar dados bancários, bem como para obter a imagem (logo) do banco para o boleto em PDF (ficha de compensação). |
digito_verificador | Texto | Não | Insira o dígito verificador do banco, quando existir. Ele será concatenado ao campo de “banco” no boleto em PDF, quando necessário. |
agencia | Texto | Sim | Número (sem o dígito) da Agência Bancária do emissor do título.
|
conta_corrente | Texto | Sim | Informar a conta corrente completa. Exemplo: 349454-4 |
numero_convenio | Texto | Sim | Número do convênio bancário utilizado pelo registro do boleto. |
aceite | Texto | Sim | Informar S, para aceite do boleto pós vencimento. N para não aceitar boleto pós vencimento |
digito_verificador | Número |
| Dígito verificador do número do banco, é exibido como sufixo do número do banco no boleto |
Tipo do objeto: Stored Procedure
Nome do objeto: omni_sp_linha_digitavel
Objeto obrigatório: SIM
Informação adicional: stored procedure responsável por obter a linha digitável, valores atualizados e dados de vencimento.
Estrutura de parâmetros:
Ordem | Nome | Tipo | Parâmetro IN/OUT | Descrição do Atributo |
|---|---|---|---|---|
1 | p_id_operadora | Número | IN | Seta Valor Default na tabela de login |
2 | p_id_config_cliente_app | Número | IN | Seta Valor Default na tabela de login |
3 | p_ambiente | Texto | IN | Seta Valor Default na tabela de login |
4 | p_chave_unica | Texto | IN | Chave de identificação única por beneficiário. Não deve se repetir em nenhuma hipótese. |
5 | p_codigo_titulo | Texto | IN | Código do título no seu sistema interno, exemplo “MS00579”. Formato: Texto livre. |
6 | p_id_titulo | Número | IN | Id de banco de dados do título no seu sistema interno. Se o seu sistema exigir o id do título como chave para localizar o mesmo nos demais métodos, este campo deverá ser considerado obrigatório. Somente números inteiros (Não podem existir letras, espaços em branco, ou pontos decimais). |
7 | p_valor_atualizado | Número | OUT | Caso não tenha atualização de titulo/boleto valor deve vir “null”. Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) |
8 | p_data_vencimento_atualizada | Texto | OUT | Envie a data de vencimento atualizada deste débito. Campo obrigatório. Caso a data de vencimento não necessite ser atualizada, envie a mesma data de vencimento original. Formato: YYYY-MM-DD |
9 | p_linha_digitavel | Texto | OUT | Deve retornar em texto a linha digitável. |
Tipo do objeto: View
Nome do objeto: omni_debito_resumo_cobranca
Objeto obrigatório: SIM
Informação adicional: Responsável por mostrar o resumo da cobrança.
Estrutura de campos:
Nome Atributo | Tipo Atributo | Obrigatório | Descrição |
|---|---|---|---|
id_omni_resumo | Número | Sim | A ideia desse é ser um atributo do tipo primary key, ou seja, se a implementação for tabela ou wien este atributo deve ser um número único por registro. |
id_operadora | Número | Sim | Criar atributo e deixar fixo o valor = 1, quanto view for implementado pela operadora. |
ambiente | Texto | Sim | Criar atributo e deixar fixo o valor = '1' , quanto view for implementado pela operadora. |
id_config_cliente_app | Número | Sim | Criar atributo e deixar fixo o valor = 1 , quanto view for implementado pela operadora. |
instancia_aplicacao | Texto | Sim | Criar atributo e deixar fixo o valor = '1' , quanto view for implementado pela operadora. |
chave_unica | Texto | Sim | Está chave é a identificação única por beneficiário, é a identificação da Pessoa. Este chave não deve se repetir em nenhuma hipótese, para uma outra Pessoa ou Beneficiário. |
nome_beneficiario | Texto | Sim | Informe o nome do beneficiário relacionado ao evento de cobrança. |
numero_contrato | Texto | Sim | Número do contrato |
data_vencimento | Text | Sim | Formato: yyyy-MM-dd |
id_titulo | Número | Sim | Id de banco de dados do título no seu sistema interno. Se o seu sistema exigir o id do título como chave para localizar o mesmo nos demais métodos, este campo deverá ser considerado obrigatório. Somente números inteiros (Não podem existir letras, espaços em branco, ou pontos decimais). |
codigo_titulo | Texto | Sim | Código do título no seu sistema interno, exemplo “MS00579”. Formato: Texto livre. |
codigo_lancamento | Texto | Sim | Código do lançamento que está sendo cobrado, por exemplo: |
descricao_lancamento | Texto | Sim | Descrição do lançamento que está sendo cobrado, por exemplo: “Mensalidade” “Opcional” “Coparticipação” |
tipo_lancamento | Texto | Sim | Define se o lançamento é de débito ou crédito: Valores permitidos: 0 = Débito 1 = Crédito |
valor_lancamento | Numero | Sim | Informe o valor do lançamento. Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) |
Mobile Saúde - Mosia Omnichannel