Tutoriais

DOCUMENTAÇÃO TÉCNICA API RESTful Para Integração com ESCOB – Versão Expandida – Renner

INTRODUÇÃO

O presente documento descreve tecnicamente o serviço web para integração do Revict do Credor (Renner) com o Revict ou outro sistema do escritório de cobrança (ESCOB)/Escritório Jurídico.

Toda troca de informações entre o banco A. J. Renner e os escritórios de cobrança (ESCOBs) ocorrerá através do Revict seguindo o fluxo demonstrado abaixo:

Os ESCOBs ainda poderão fazer requisições complementares para os endpoints abaixo:

END POINT – DESPESAS
END POINT – REDE LOJAS
END POINT – CORRESPONDENTES
END POINT – CLIENTE CONSOLIDADO

 

ALTERAÇÕES REALIZADAS

19/07/2019 – Adicionados campos no endpoint ficha cliente (títulos): “data”, “nosso_numero”,  “taxa_contrato”, “saldo_curva”, “saldo”, “prazo”, “parcela”, “pmt”, “tem_saldo”, “garantia”, “risco”, “descricao_garantia”, “data_retirada”

21/03/2019 – Adicionado end point “despesas”

20/03/2019 – Campos “taxa_multa” e “taxa_juros ” adicionados aos detalhes do(s) título(s) regularizado(s) no acordo

21/12/2016 – O nome do campo cpf no end point “ficha do cliente” foi alterado para cpf_cnpj

20/12/2016 – O indicador de ficha no end point “ficha do cliente” foi alterado para ficha_1, ficha_2, ficha_3, etc

19/12/2016 – Foi adicionado o campo “credor” no JSON de retorno do end point “ficha do cliente”

OBJETIVO

O objetivo do serviço web descrito no presente documento é permitir que o sistema do escritório de cobrança/jurídico, seja integrado com o Revict do credor.

TECNOLOGIA

A tecnologia utilizada para oferta do serviço descrito no presente documento é denominada RESTful API com o método JWT de autenticação que e é descrita nos seguintes documentos:
• RFC6690 (https://tools.ietf.org/html/rfc6690)
• RFC7519 (https://tools.ietf.org/html/rfc7519)

O charset utilizado é o UTF-8

ACESSO AO SERVIÇO

O Revict (ou outro sistema) do escritório de cobrança deverá fazer requisições utilizando o método POST do protocolo HTTPS na seguinte URL:

https://[nome do credor].revict.com.br/api/

A autenticação JWT deve ser realizada chamando a seguinte URL:

https://[nome do credor].revict.com.br/api/auth

Campos para credenciais: user para usuário e pass para senha

Observação: para criar a senha de acesso, após o credor criar o login do prestador de serviço, ele precisa criar uma senha que será alterada pelo prestador de serviço via navegador de internet.

AMBIENTES (homologação e produção)

Para o desenvolvimento e adequação de suas aplicações, os ESCOBs deverão utilizar o ambiente de homologação do Revict/Renner, para isso as requisições à API deverão ocorrer para o endereço:

https://renner-homolog.revict.com.br/api/[nome do endpoint]

Para trocas de dados entre os ESCOBs e o banco A. J. Renner em ambiente de produção, as requisições à API deverão ocorrer para o endereço:

https://renner.revict.com.br/api/[nome do endpoint]

END POINT – FICHA DO CLIENTE

Através do end point ficha do cliente, o ESCOB recebe a carteira a ser cobrada, atualiza as informações cadastrais e de dívidas e identifica se uma “ficha” (cliente) ainda pertence a sua carteira.
Para obter toda carteira/lote atribuída a seu login/ESCOB no Revict do credor (ex.: batimento de carteira), o ESCOB deve fazer as seguintes solicitações GET:

https://[nome do credor].revict.com.br/api/ficha/carteira

https://[nome do credor].revict.com.br/api/ficha/lotes

Para obter apenas as fichas novas, ou seja, nunca recebidas pelo ESCOB, deve ser realizada a seguinte solicitação GET:

https://[nome do credor].revict.com.br/api/ficha/novas

Para obter apenas uma ficha específica, deve ser realizada a seguinte solicitação GET:

https://[nome do credor].revict.com.br/api/ficha/{cod_cliente}

(Ex.: https://[nome do credor].revict.com.br/api/ficha/206400058533788568)

Diariamente o ESCOB deve fazer a carga total para identificar quais títulos foram baixados.

RETORNO

{
    "ficha_1": {
        "cod_cliente": 206400058533788568,
        "nome": "DOUGLAS ROCHA",
        "cpf_cnpj": "58533788568",
        "rg": null,
        "uf_rg": null,
        "orgao_emissor_rg": null,
        "agencia": 0,
        "conta": 0,
        "filial": null,
        "e_mail": null,
        "conjuge": null,
        "pai": null,
        "mae": null,
        "empresa": null,
        "pessoa_juridica": false,
        "vencimento_salarial": null,
        "renda": null,
        "estado_civil": null,
        "qtd_dependentes": null,
        "data_nascimento": null,
        "sexo": null,
        "profissao": null,
        "nome_fantasia": null,
        "credor": "Teste AA L",
        "extra": null,
        "enderecos": {
            "endereco_1": {
                "cod_endereco": 760699,
                "endereco": "Av de exemplo",
                "numero": "584",
                "complemento": "",
                "bairro": "Vila dos Sonhos",
                "cidade": "São Paulo",
                "uf": "SP",
                "cep": "05424425"
            },
            [... endereços subsequentes veem aqui ...]
        },
        "telefones": {
            "telefone_1": {
                "cod_telefone": 9122661,
                "numero": "11994586373",
                "ramal": "",
                "descricao": "Celular",
                "proprietario": "devedor",
                "vizinho": null
            },
            "telefone_2": {
                "cod_telefone": 9124398,
                "numero": "11994585342",
                "ramal": null,
                "descricao": "Homonimo",
                "proprietario": null,
                "vizinho": null
            },
            [... telefones subsequentes veem aqui ...]
        },
        "emails": {
            "email_1": {
                "e_mail": "[email protected]",
                "data_cadastrado": "2016-12-08 09:42:34"
            },
            [... emails subsequentes veem aqui ...]
        },
        "titulos": {
            "titulo_1": {
                "cod_titulo": 11519259,
                "contrato": "aulas avulsas",
                "vencimento": "2016-12-25",
                "carteira": "Cheque Especial",
                "identificacao": null,
                "valor_inicial": 110.23,
                "valor_corrigido": 110.23,
                "cod_fase": null,
                "cod_politica": null,
                "dia_de_corte": null,
                "cedida_vendida": false,
                "data": "2018-06-04",
		"nosso_numero": "000600000709581",
		"taxa_contrato": "2.24",
		"saldo_curva": "17346.43",
		"saldo": "0.00",
		"prazo": "48",
		"parcela": "13",
		"pmt": "686.48",
		"tem_saldo": "N",
		"garantia": "",
		"risco": "A",
		"descricao_garantia": "AUTOMOVEL VW - VOLKS...",
		"data_retirada": null
            },
            "titulo_2": {
                "cod_titulo": 11519258,
                "contrato": "Matrícula",
                "vencimento": "2016-12-24",
                "carteira": "Cartão de Crédito",
                "identificacao": null,
                "valor_inicial": 95.17,
                "valor_corrigido": 95.17,
                "cod_fase": null,
                "cod_politica": null,
                "dia_de_corte": null,
                "cedida_vendida": false,
                "data_do_titulo": null,
		"data": "2018-04-12",
		"nosso_numero": "001500000706319",
		"taxa_contrato": "2.85",
		"saldo_curva": "10142.76",
		"saldo": "0.00",
		"prazo": "24",
		"parcela": "6",
		"pmt": "672.97",
		"tem_saldo": "N",
		"garantia": "",
		"risco": "A",
		"descricao_garantia": "AUTOMOVEL FIAT                               , FIORIN...",
		"data_retirada": null
            },
            "titulo_3": {
                "cod_titulo": 11519257,
                "contrato": "Mensalidade",
                "vencimento": "2016-12-23",
                "carteira": "CDC",
                "identificacao": null,
                "valor_inicial": 80.06,
                "valor_corrigido": 80.06,
                "cod_fase": null,
                "cod_politica": null,
                "dia_de_corte": null,
                "cedida_vendida": false,
		"data_do_titulo": null,
		"data": "2017-10-16",
		"nosso_numero": "000900000691031",
		"taxa_contrato": "2.31",
		"saldo_curva": "22116.56",
		"saldo": "0.00",
		"prazo": "48",
		"parcela": "12",
		"pmt": "868.13",
		"tem_saldo": "N",
		"garantia": "",
		"risco": "A",
		"descricao_garantia": "AUTOMOVEL GM - CHEVROLET , CAPT...",
		"data_retirada": null
            },
            [... títulos subsequentes veem aqui ...]
        }
    },
    [... fichas subsequentes veem aqui  ...]
}

 

END POINT – CARGA DE OCORRÊNCIA

Através do end point de carga de ocorrência, o ESCOB/Jurídico deve enviar para o Revict do credor as ocorrências/históricos ocorridos para cada cliente.

Para obter apenas uma ficha específica, deve ser realizada a seguinte requisição POST:

https://[nome do credor].revict.com.br/api/carga_de_ocorrencia/

JSON para envio da ocorrência:

{
    "ocorrencia_1": {
        "cod_cliente": 206400058533788568,
        "cod_ocorrencia": 5,
        "identificador_do_cobrador": "patricia.souza", /*código ou login do cobrador/analista no ESCOB*/
        "descricao_ocorrencia": "Cliente prometeu pagar em:", /*opcional*/
        "observacoes_adicionais": "04/03 quando receber o salário" /*opcional*/
    },
    "ocorrencia_2": { 
        "cod_cliente": 202300066577555521, 
        "cod_ocorrencia": 2, 
        "identificador_do_cobrador": "marco.oliveira", /*código ou login do cobrador/analista no ESCOB*/
        "descricao_ocorrencia": "Acordo fechado:", /*opcional*/ 
        "observacoes_adicionais": "Cliente pediu apra enviar email para [email protected]" /*opcional*/
    }, 
    [... ocorrências subsequentes veem aqui ...]
}

RETORNO

{
	"ocorrencia_1": {
		"status_processamento": "OK"
	},
	"ocorrencia_2": {
		"status_processamento": "OK"
	}
}

Tabela de ocorrências padrão do Revict (O credor deve fornecer ao prestador de serviços a tabela de ocorrências customizadas)

Código de OcorrênciaOcorrência
1Cliente alega ter pago
2Acordo fechado:
4Proposta de acordo:
5Cliente prometeu pagar em:
6Cliente prometeu pagar no credor em:
7Exclusão de anexo
8Sem condições de regularizar no momento.
9Cliente não reconhece a divida porem comparecerá à Ag/Loja
10Cliente se recusa a pagar
11Confirmação de deposito
12Upload de anexo
13Transferência API
14Recado
20Falecido/Falência
23Pesquisa cadastral solicitada
28Acompanhamento de acordo
29Exclusão SERASA/SCPC
30Retorno da pesquisa cadastral
31Protesto cancelado
32Dívida de difícil solução
42Quebra de acordo
46Retorno de notificação
47Retorno de boleto
49ACEL/URA – Sem detecção (humano ou Cx. postal)
52ACEL/URA – Recado humano
53ACEL/URA – Recado cx. postal
57Reenviar parcela de acordo
64Ação judicial
65Operação cedida
71Notificação enviada por correio
72Notificação enviada por e-mail
76Cliente retornará para negociação
77Alteração de acordo
78Atualização de proposta
79Acordo excluído
109Desconhecido endereço/fone
306Se recusa a negociar
310Retirado de cobrança
312Carta campanha
313Carta campanha e-mail
328Inclusão SCPC/SERASA
329Título protestado
336Pagamento direto
337Confirmação de pagamento ou linha digitável
974Boleto emitido
975Boleto enviado por SMS
976Boleto enviado por FAX
977Boleto enviado por e-mail
978Boleto enviado pelo correio
979Acionamento paralisado
984Sem contato
988Erro ao enviar SMS
989SMS
992Atualização cadastral
993Acionada por requisição do devedor
994Agendamento de ficha por horário
999Sem contato telefônico
1003Contato Realizado

END POINT – GRAVAR ACORDO

Através do end point gravar_acordo, o ESCOB deve informar todos acordos celebrados com os clientes devedores.

Para gravar os acordos realizados, o ESCOB deve fazer a seguinte requisição POST:

https://[nome do credor].revict.com.br/api/acordo/gravar

JSON de envio

{
	"acordo": {
		"condicoes": {
			"codigo_do_credor": "2157",
			"codigo_do_cliente": "215700000126070024",
			"data_acordo": "10-04-2019",
			"hora_acordo": "15:54:57",
			"tipo": "a_vista",
			"quantidade_titulos": 1,
			"quantidade_parcelas": "1",
			"valor_total": "717.01",
			"valor_iof": 0,
			"com_juros": 1,
			"com_abatimento": false,
			"com_correcao_monetaria": 1,
			"com_multa": 1,
			"com_taxa_adm": "0",
			"valor_do_desconto": "0.00",
			"percentual_de_desconto": 0,
			"informacao_complementar": "",
			"percentual_de_honorario": "0",
			"valor_do_honorario": "0.00"
		},
		"parcelas": [{
			"vencimento": "20-12-2018", 
                        "valor": 184.03 
                },{
                        "vencimento": "20-01-2019",
                        "valor": 184.03
		}],
		"titulos": [{
			"codigo_do_titulo": "13937171",
			"vencimento": "10-10-2018",
			"contrato": "0671574",
			"valor_original": "717.01",
			"valor_juros": "0",
			"valor_multa": "0",
                        "valor_taxa": 0, /* Taxa de administração */
			"valor_total": "717.01",
			"valor_do_desconto": "0",
			"percentual_de_desconto": 0
		},{
                       "codigo_do_titulo": "139322487",
                       "vencimento": "15-10-2018",
                       "contrato": "0671578",
                       "valor_original": "216.22",
                       "valor_juros": "0",
                       "valor_multa": "0",
                       "valor_taxa": 0, /* Taxa de administração */
                       "valor_total": "216.22",
                       "valor_do_desconto": "0",
                       "percentual_de_desconto": 0
              }]
	}
}

RETORNO

{
	"cod_acordo": "1338063", /* Nº de controle da simulação no Revict */
	"CodigoSimulacao": "12" /* Nº de controle da simulação no banco Renner */
}

EXEMPLOS DE ERROS

{
	"erro": "Os campos codigo_do_credor, quantidade_titulos, quantidade_parcelas, valor_total, valor_iof, valor_do_desconto, percentual_de_desconto, percentual_de_honorario e valor_do_honorario devem ser numéricos"
}

{
	"erro": "O campo data_acordo não parece uma data válida"
}

{
	"erro": "Há dados inválidos para as parcelas"
}

{
	"erro": "Há dados inválidos para os títulos"
}

{
	"erro": "Acordo fora das condições permitidas: Desconto fora do permitido. Desconto Máximo: 0%"
}

{
	"CodigoSimulacao": null,
	"Erros": [{
		"Codigo": "99",
		"Descricao": ""
	}, {
		"Codigo": "14",
		"Descricao": "O Campo DataVctoSimulacao está fora dos parâmetros."
	}]
}

END POINT – DESPESAS

Através do end point despesas, o ESCOB/Jurídico recebe informações referentes aos custos com o contrato.

Deve ser realizada a seguinte requisição GET:

https://[nome do credor].revict.com.br/api/despesa/{$agencia}/{$contrato}/

{$agencia} -> inserir numero da agência
{$contrato} -> inserir número do contrato

RETORNO

{
	{"ValorSaldoDespesas":0}
}

RETORNO COM ERROS

{
	"Erros": [{
		"Codigo": "3",
		"Descricao": "O campo Agencia está fora dos parâmetros."
	}, {
		"Codigo": "4",
		"Descricao": "O campo Contrato está fora dos parâmetros."
	}]
}

END POINT – REDE LOJAS

Através do end point despesas, o ESCOB/Jurídico recebe informações referentes a rede de lojas autorizadas do Banco Renner.

Deve ser realizada a seguinte requisição GET:

https://[nome do credor].revict.com.br/api/rede_lojas/

RETORNO

[{
	"Codigo": "005026",
	"CNPJ": "95819900000171",
	"Nome": "0M VEICULOS LTDA ME",
	"Abreviatura": "0M VEÍCULOS",
	"Cep": "89251520",
	"Endereco": "RUA ANGELO SCHIOCHET 144",
	"Bairro": "CENTRO",
	"UF": "SC",
	"Cidade": "JARAGUA DO SUL",
	"Agencia": "0011",
	"Agente": "1862",
	"TipoDeServico": "3",
	"Erros": null
}, {
	"Codigo": "006526",
	"CNPJ": "23512810000122",
	"Nome": "1400 VEICULOS LTDA ME",
	"Abreviatura": "1400 VEICULOS",
	"Cep": "93320492",
	"Endereco": "PEDRO ADAMS FILHO 1400",
	"Bairro": "INDUSTRIAL",
	"UF": "RS",
	"Cidade": "NOVO HAMBURGO",
	"Agencia": "0006",
	"Agente": "1550",
	"TipoDeServico": "3",
	"Erros": null
}]

END POINT – CORRESPONDENTES

Através do end point correspondentes, o ESCOB/Jurídico recebe informações referentes a rede de correspondentes autorizados do Banco Renner.

Deve ser realizada a seguinte requisição GET:

https://[nome do credor].revict.com.br/api/correspondentes/

RETORNO

{
	"Correspondentes": [{
		"Codigo": "000001",
		"CNPJ": "03448922000154",
		"Nome": "A MENDES DA SILVA ME",
		"Abreviatura": "A MENDES DA SILVA ME",
		"CEP": "91910251",
		"Endereco": "DOUTOR BARCELOS 1195",
		"Bairro": "TRISTEZA",
		"UF": "RS",
		"Cidade": "PORTO ALEGRE",
		"TipoServico": "PROP ABER CONTA RES 3954 INC I",
		"TipoCorrespondente": "CORRESP. DE INVESTIMENTO"
	}, {
		"Codigo": "000018",
		"CNPJ": "12756786000150",
		"Nome": "ATHOS PRESTACAO DE SERVICOS E CURSOS LTD",
		"Abreviatura": "ATHOS EDUCACAO",
		"CEP": "96020260",
		"Endereco": "DOM JOAQUIM 1515",
		"Bairro": "CENTRO",
		"UF": "RS",
		"Cidade": "PELOTAS",
		"TipoServico": "PROP ABER CONTA RES 3954 INC I",
		"TipoCorrespondente": "CORRESP. DE INVESTIMENTO"
	}]
}

END POINT – CLIENTE CONSOLIDADO

Através do end point cliente consolidado, o ESCOB/Jurídico recebe informações referentes ao cliente do Banco Renner.

Deve ser realizada a seguinte requisição GET:

https://[nome do credor].revict.com.br/api/cliente_consolidado/{$cpf_cnpj}

{$cpf_cnpj} -> inserir numero do documento do cliente

RETORNO

{
	"Pmt": 531.93,
	"Empresa": "01",
	"CPFCNPJ": "91256470082",
	"Agencia": "0002",
	"Contrato": "0000693085",
	"Assessoria": "0032",
	"TelefoneAssessoria": "               ",
	"FilialAssessoria": "0003",
	"EmailAssessoria": null,
	"Localizacao": "0032 - AG. DISTRIBUIÇÃO FASE I / 0003 - MAXISERV - FASE I - CTOS P/ ENVIAR ",
	"Telefone": "32873300",
	"TelefoneCelular": null,
	"EmailCliente": null,
	"SaldoAtraso": 531.93,
	"SaldoLiquidacao": 13377.82,
	"QtdParcela": 48,
	"QtdParcelasaVencer": 33,
	"QtdVencidas": 1,
	"ProximaParcela": "017",
	"PmtVencAtualizada": 555.38,
	"Erros": []
}

RETORNO COM ERROS

{
	"Erros": [{
		"Codigo": "36",
		"Descricao": "Cliente consolidado não encontrado"
	}]
}
{
	"Erros": [{
		"Codigo": "28",
		"Descricao": "O Campo CnpjCpf está fora dos parâmetros."
	}]
}