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.



    © Copyright 2015-2019 Direitos Reservados.