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