Introdução

O DUNNING faz uso de dados dos clientes da empresa a fim de executar algoritmos inteligentes que geram as melhores estratégias de cobrança. O usuário pode ainda utilizar as ferramentas de envio de cobrança como e-mail, sms, mensagem de voz, carta, etc.

Com este propósito, é necessário fazer a integração com o sistema de gestão, seja ele um ERP ou planilhas eletrônicas. Considerando que o sistema de gestão está na infraestrutura da empresa, imaginamos o seguinte cenário de integração:

Integração

A empresa é responsável pela criação do integrador, que tem duas funções: (1) buscar os dados no ERP ou diretamente no banco de dados e (2) enviá-lo ao DUNNING usando serviços REST que serão detalhados posteriormente. O integrador deve ser executado diariamente para garantir que o DUNNING receba as informações de pagamento de títulos do dia anterior.

Dados

O DUNNING necessita de três tabelas de dados: (1) clientes, (2) títulos e (3) baixas.
Para importar corretamente os seus clientes no sistema, é necessário fornecer os seguinte dados:

  1. Código do Grupo Econômico: campo texto que identifica o grupo econômico do cliente no sistema de gestão
  2. Código do Cliente (*): campo texto que identifica o cliente no sistema de gestão
  3. Nome (*): campo texto (Ex: João da Silva)
  4. Tipo de Pessoa (*): informa se é uma pessoa física ou jurídica (Ex: F, Física ou FISICA para pessoas físicas; e J, Jurídica ou JURIDICA para pessoas jurídicas)
  5. CPF/CNPJ : campo numérico de 11 ou 14 dígitos válidos para cpf ou cnpj
  6. CEP: campo número (Ex: 35570000)
  7. Endereço: campo texto
  8. Número: campo texto
  9. Complemento: campo texto
  10. Bairro: campo texto
  11. Cidade: campo texto
  12. UF: campo texto de 2 letras (Ex: MG)
  13. Email 1: primeiro e-mail
  14. Email 2: segundo e-mail
  15. Telefone 1 (DDD): campo numérico de 2 dígitos
  16. Telefone 1: campo numérico de 8 ou 9 dígitos
  17. Telefone 2 (DDD): campo numérico de 2 dígitos
  18. Telefone 2: campo numérico de 8 ou 9 dígitos
  19. Celular 1 (DDD): campo numérico de 2 dígitos
  20. Celular 1: campo numérico de 8 ou 9 dígitos
  21. Celular 2 (DDD): campo numérico de 2 dígitos
  22. Celular 2: campo numérico de 8 ou 9 dígitos
  23. Celular 3 (DDD): campo numérico de 2 dígitos
  24. Celular 3: campo numérico de 8 ou 9 dígitos
  25. Situação: informa se o cliente está ativo ou inativo
  26. Campo 1: (Opcional) campo texto personalizado
  27. Campo 2: (Opcional) campo texto personalizado
  28. Campo 3: (Opcional) campo texto personalizado
  29. Campo 4: (Opcional) campo texto personalizado
  30. Campo 5: (Opcional) campo texto personalizado
  31. Observação 1: (Opcional) campo texto de observação personalizado
  32. Observação 2: (Opcional) campo texto de observação personalizado
  33. Observação 3: (Opcional) campo texto de observação personalizado

Para importar corretamente os seus títulos no sistema, é necessário ter os seguintes dados:

  1. Código da Filial (*): campo texto que identifica a filial do título no sistema de gestão (Padrão: 1)
  2. Código do Cliente (*): campo texto que identifica o cliente no sistema de gestão
  3. Código do Título (*): campo texto que identifica o título no sistema de gestão
  4. Data de Emissão (*): campo data que informa a data de emissão (Ex: 10/08/2015)
  5. Data de Vencimento (*): campo data que informa o vencimento (Ex: 10/08/2015)
  6. Valor (*): campo numérico informando o valor do título (Ex: 104,90)
  7. Tipo: campo texto que informa o tipo do título (Ex: NF, Cartão)
  8. Nosso número: campo texto do nosso número para geração de boletos
  9. Campo 1: (Opcional) campo texto personalizado
  10. Campo 2: (Opcional) campo texto personalizado
  11. Campo 3: (Opcional) campo texto personalizado
  12. Campo 4: (Opcional) campo texto personalizado
  13. Campo 5: (Opcional) campo texto personalizado
  14. Observação 1: (Opcional) campo texto de observação personalizado
  15. Observação 2: (Opcional) campo texto de observação personalizado
  16. Observação 3: (Opcional) campo texto de observação personalizado

Para importar corretamente as baixas dos seus títulos no sistema, é necessário ter os seguintes dados:

  1. Código da Filial (*): campo texto que identifica a filial do título no sistema de gestão (Padrão: 1)
  2. Código do Cliente (*): campo texto que identifica o cliente do título no sistema de gestão
  3. Código do Título (*): campo texto que identifica o título no sistema de gestão
  4. Sequência da Baixa (*): campo numérico que identifica o número de sequência da baixa (Padrão: 1)
  5. Data da Baixa (*): campo data que informa a data da baixa (Ex: 10/08/2015)
  6. Forma de Pagamento (*): campo texto que informa o código da forma de pagamento existente no dunning (Padrão: 1 para dinheiro, 2 para boleto)
  7. Valor da Baixa (*): campo numérico informando o valor da baixa (Ex: 100,00)
  8. Valor de Juros (*): campo numérico informando o valor dos juros (Ex: 1,00)
  9. Valor de Multa (*): campo numérico informando o valor da multa (Ex: 2,00)
  10. Valor da Acréscimo (*): campo numérico informando o valor de acréscimo (Ex: 0,00)
  11. Valor de Desconto (*): campo numérico informando o valor do desconto (Ex: 0,00)
  12. Valor Recebido (*): campo numérico informando o valor total recebido (Ex: 103,00)

Autenticação

A API do DUNNING possui autenticação via token de acesso que é único por empresa. Ele é criado no cadastro da nova empresa e pode ser visualizado na aba Integração localizada em Configurações do Sistema, conforme apresentado na figura abaixo.

Autenticação

Este token deve ser passado como parâmetro nos web-services.

Download

O DUNNING-API é uma API na linguagem Java para acesso às entidades (Empresas) e seus respectivos dados (Clientes e Títulos) para integração. Para o desenvolvimento de um cliente integrador na linguagem Java, é necessário o download do projeto dunning-api:

API de Integração

Documentação

Api Soap

Acesso a documentação para acesso à Api Soap

  • Clientes
  • Títulos
  • Baixas
  • Filiais
  • Grupos Econômicos
  • Histórico de Importação

  • Api Rest

    Clientes

    https://www.dunning.com.br/api/v2/cliente?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv

    GET: obter lista de clientes

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/cliente?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import java.util.*;
    import dunning.rest.*;
    import dunning.api.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = " OTA0NV82MDA0j8pmKbNwEb0fdKJCvv ";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor, token);
    
    //obtém todos os clientes em uma lista.
    List listaClientes = dunningApi.consultarClientes();
    
    //imprime todos os clientes da empresa. 
    System.out.println(listaClientes.toString());
    
    

    POST: inserir/atualizar lista de clientes

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/cliente?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import java.util.*;
    import dunning.rest.*;
    import dunning.utils.enums.*;
    import dunning.api.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    
    //cria uma lista de clientes
    List listaCliente = new ArrayList<>();
    
    // Exemplo de inserção de dois clientes na lista.
    //Criação de Cliente 1
    RestCliente c1 = new RestCliente();
    c1.setNome("Cliente 1");
    c1.setCpf("63184755592");
    c1.setCodigoCliente("133234");
    c1.setTipoPessoa(EnumTipoPessoa.FISICA); 
    c1.setSituacao(EnumAtivoInativo.ATIVO);
    
    listaCliente.add(c1); //Adiciona o Cliente 1 na lista de clientes.
    						
    //Criação de Cliente 2		
    RestCliente c2 = new RestCliente();
    c2.setNome("Cliente 2");
    c2.setCpf("21897551231");
    c2.setCodigoCliente("133235"); 
    c2.setTipoPessoa(EnumTipoPessoa.FISICA);
    c2.addEndereco("", "rua aimorés", "34", "", "centro", "Belo Horizonte", "MG"); 
    c2.addEmail("teste@hotmail.com"); 
    c2.setSituacao(EnumAtivoInativo.ATIVO);
    //Adicionando telefones
    List telefones =new ArrayList<>();
    RestContatoTelefone t2=new RestContatoTelefone();
    t2.setDdd("31");
    t2.setNumero("971277538");
    telefones.add(t2);
    c2.setTelefones(telefones);
    listaCliente.add(c2); //Adiciona o Cliente 2 na lista de clientes.
    						
    //envia a lista com os dois clientes a serem inseridos.
    //caso exista um cliente com o mesmo código, este será substituído.
    dunningApi.enviarClientes(listaCliente);
    
    								

    DELETE: remover uma lista de clientes

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/cliente?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import java.util.*;
    import dunning.rest.*;
    import dunning.api.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    
    //cria uma lista de clientes 
    List listaCliente = new ArrayList<>();
    
    // Um objeto Cliente é criado (Apenas código) para ser adicionado à lista de remoção. 
    //Criação de Cliente 1
    RestCliente c1 = new RestCliente();
    c1.setCodigoCliente("133234");
    
    //Adiciona o Cliente 1 na lista de clientes.
    listaCliente.add(c1);
    			
    //Criação de Cliente 2		
    RestCliente c2 = new RestCliente();
    c2.setCodigoCliente("133235");
    				
    //Adiciona o Cliente 2 na lista de clientes.
    listaCliente.add(c2);
    				
    //envia a lista com os dois clientes a serem removidos.
    dunningApi.removerClientes(listaCliente);
    
    								


    Clientes (ID)

    https://www.dunning.com.br/api/v2/cliente/(codigo cliente)?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv

    GET: obter cliente por código

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/cliente?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import dunning.api.*;
    import dunning.rest.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    
    //imprime dados de apenas um cliente específico (Cliente de Código: 001)
    RestCliente cliente = dunningApi.consultarCliente("001");
    System.out.println(cliente.toString());
    

    DELETE: remover um cliente específico

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/cliente?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import dunning.api.*;
    import dunning.rest.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    
    //declara e informa o código do cliente a ser removido
    String codigoCliente = "133234";
    	
    //Remove o cliente de código 133234.
    dunningApi.removerRestCliente(codigoCliente);
    
    								


    Títulos

    https://www.dunning.com.br/api/v2/cliente/(codigo cliente)/titulo?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv

    GET: obter lista de titulos

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/titulo?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import java.util.*;
    import dunning.api.*;
    import dunning.rest.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //declara e informa o código do cliente onde serão coletados os títulos
    String codigoCliente = "001";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    
    //imprime todos os títulos do cliente de código 001.
    List listaTitulos = dunningApi.consultarRestTitulos(codigoCliente);
    System.out.println(listaTitulos.toString());
    

    POST: inserir/atualizar lista de títulos

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/titulo?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import java.util.*;
    import dunning.rest.*;
    import dunning.utils.UtilFormatador;
    import dunning.api.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    				
    //declara e informa o código do cliente no qual serão vinculados os novos títulos
    String codigoCliente = "001";
    
    //cria uma lista de títulos
    List listaTitulos = new ArrayList<>();
    
    // Exemplo de inserção de dois títulos na lista.
    //Criação de Título 1
    RestTitulo t1 = new RestTitulo();
    t1.setCodigoTitulo("43332");
    t1.setDataEmissao(UtilFormatador.converteStringParaDate_DDMMYYYY_BARRAS("01/12/2015"));
    t1.setDataVencimento(UtilFormatador.converteStringParaDate_DDMMYYYY_BARRAS("12/12/2015"));
    t1.setValor(100f);
    t1.setTipo("NF");
    listaTitulos.add(t1); //Adiciona o Título 1 na lista de títulos.
    				
    //Criação de Título 2		
    RestTitulo t2 = new RestTitulo();
    t2.setCodigoTitulo("43333");
    t2.setDataEmissao(UtilFormatador.converteStringParaDate_DDMMYYYY_BARRAS("01/12/2013"));
    t2.setDataVencimento(UtilFormatador.converteStringParaDate_DDMMYYYY_BARRAS("13/12/2013"));;
    t2.setValor(120f);
    t2.setTipo("Boleto");
    listaTitulos.add(t2); //Adiciona o Título 2 na lista de clientes.
    				
    //envia a lista com os dois Títulos do cliente 001 a serem inseridos.
    //caso exista um título com o mesmo código, este será substituído.
    dunningApi.enviarRestTitulos(codigoCliente, listaTitulos);
    
    								

    DELETE: remover lista de títulos

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/titulo?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import java.util.*;
    import dunning.api.*;
    import dunning.rest.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    				
    //declara e informa o código do cliente que possui os títulos
    String codigoCliente = "001";
    
    //cria uma lista de títulos inserindo apenas o seu código
    List listaTitulos = new ArrayList<>();
    
    // Exemplo de inserção de dois títulos na lista. (Apenas código)
    //Criação de Título 1
    RestTitulo t1 = new RestTitulo();
    t1.setCodigoTitulo("43332");
    listaTitulos.add(t1); //Adiciona o Título 1 na lista de títulos.
    				
    //Criação de Título 2		
    RestTitulo t2 = new RestTitulo();
    t2.setCodigoTitulo("43333");
    listaTitulos.add(t2); //Adiciona o Título 2 na lista de clientes.
    				
    //envia a lista com os dois Títulos do cliente 001 a serem removidos.
    dunningApi.removerRestTitulos(codigoCliente, listaTitulos);
    
    								


    Títulos (ID)

    https://www.dunning.com.br/api/v2/cliente/(codigo cliente)/titulo/(codigo titulo)?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv

    GET: obter título por código

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/titulo?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import dunning.api.*;
    import dunning.rest.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //declara e informa o código do cliente onde será coletado o título
    String codigoCliente = "001";
    
    //declara e informa o código do título a ser coletado
    String codigoTitulo = "55";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    
    //imprime o título de código 55 do cliente de código 001.
    RestTitulo titulo = dunningApi.consultarRestTitulo(codigoCliente, codigoTitulo);
    System.out.println(titulo.toString());
    

    DELETE: remover título específico

    curl --include \
         --request GET \
         --header "Content-Type: application/json" \
    'https://www.dunning.com.br/api/v2/titulo?token=OTA0NV82MDA0j8pmKbNwEb0fdKJCvv'
    
    import java.util.ArrayList;
    import dunning.api.*;
    import dunning.rest.*;
    
    //declara o servidor e respectivo token obtido.
    String servidor = "https://dunning.com.br/api/v2";
    String token = "OTA0NV82MDA0j8pmKbNwEb0fdKJCvv";
    
    //inicia o DunningApi
    DunningApi dunningApi = new DunningApi(servidor,token);
    		
    //declara e informa o código do cliente que possui o título
    String codigoCliente = "001";
    
    //declara e informa o código do Título a ser removido
    String codigoTitulo = "43332";
    		
    //remove o título 43332 do cliente 001
    dunningApi.removerRestTitulo(codigoCliente, codigoTitulo);
    
    								

    Integração via FTP

    Os registros a serem importados para o Dunning, podem ser realizados via integração FTP.

    A integração FTP se baseia no envio diário de arquivos no formato .csv, .xls ou .xlsx válidos que contenham os clientes (arquivo: clientes.csv ou cliente.xls ou cliente.xlsx), seus títulos (titulos.csv ou titulos.xls ou titulos.xlsx) e as respectivas baixas (arquivo: baixas.csv ou baixas.xls ou baixas.xlsx)

    Configuração: O usuário deverá acessar o DUNNING, Tela de Configurações, Integrador e habilitar a Integração via FTP. A configuração para envio dos arquivos e acesso ao FTP está realizada.

    IntegraçãoFTP

    Após realizada a configuração, o envio FTP é realizado da seguinte forma:

    1. URL: ftp://dunning.com.br
    2. Usuário: "Código Token" Ex: NzQ2OV82NjUweMepF0WH17ZjihTbC0
    3. Senha: "" (Vazio)

    Os dados enviados ao Dunning estarão disponíveis no dia seguinte à importação.