Aprova Fácil
Integração via WebService
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
1
ÍNDICE
1. Introdução.......................................................................................................................................................................6
2. Integração........................................................................................................................................................................7
2.1. Meios de Pagamento Suportados....................................................................................................................7
2.2. Tecnologias de Conectividade.........................................................................................................................7
2.3. Etapas da Automatização................................................................................................................................7
2.4. Tempo de Captura de uma Transação Aprovada............................................................................................8
2.5. Codificação da Resposta do Aprova Fácil.......................................................................................................9
3. Cartão de Crédito – Pedido de Aprovação – APC....................................................................................................10
3.1. Descrição.......................................................................................................................................................10
3.2. Métodos de Envio..........................................................................................................................................10
3.3. URL Chamada...............................................................................................................................................10
3.4. Parâmetros do Pedido....................................................................................................................................10
3.5. Agendamento – Descrição.............................................................................................................................12
3.6. Recorrência – Descrição................................................................................................................................13
3.7. Consulta AVS (Adress Verification Service)................................................................................................14
3.8. Exemplos do Pedido......................................................................................................................................14
3.9. Resultado do Processamento Formato XML.................................................................................................16
3.10. Resultados de Erros Comuns.......................................................................................................................18
4. Cartão de Crédito – Pedido de Captura – CAP.........................................................................................................20
4.1. CAP – Descrição...........................................................................................................................................20
4.2. CAP – Métodos de Envio..............................................................................................................................20
4.3. CAP – URLs..................................................................................................................................................20
4.4. CAP – Parâmetros de Requisição..................................................................................................................20
4.5. CAP – Exemplos de Requisição GET...........................................................................................................20
4.6. Exemplo de Resultados.................................................................................................................................21
4.7. Resultado de Captura com Sucesso...............................................................................................................21
4.8. Resultados de Erro Comuns..........................................................................................................................21
5. Cartão de Crédito – Cancelamento de Transações – CAN.......................................................................................23
5.1. CAN – Descrição...........................................................................................................................................23
5.2. CAN – Métodos de Envio.............................................................................................................................23
5.3. CAN – URLs.................................................................................................................................................23
5.4. CAN – Parâmetros de Requisição.................................................................................................................23
5.5. CAN – Exemplos de Requisição...................................................................................................................23
5.6. Resultado XML.............................................................................................................................................24
5.7. Resultado das Tags XML..............................................................................................................................24
5.8. Exemplos de Resultados................................................................................................................................24
5.9. Resultado de Cancelamento com Sucesso.....................................................................................................25
5.10. Resultados de Erros Comuns NSUCancelamento.......................................................................................25
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
2
6. Cartão de Crédito – Retorno de Cancelamento Previamente Solicitado................................................................26
6.1. Descrição.......................................................................................................................................................26
6.2. URLs..............................................................................................................................................................26
6.3. Métodos de Envio..........................................................................................................................................26
6.4. Parâmetros de Retorno..................................................................................................................................26
6.5. Exemplo de Retorno......................................................................................................................................26
6.6. Resultado de Cancelamento bem Sucedido...................................................................................................26
7.Cartão de Crédito – Requisição da Lista dos Cartões de Crédito cujas Datas de Validade estão Prestes a Expirar (Agendamento e Recorrência)...........................................................................................................................27
7.1. Descrição.......................................................................................................................................................27
7.2. URLs..............................................................................................................................................................27
7.3. Métodos de Envio..........................................................................................................................................27
7.4. Parâmetros de Requisição.............................................................................................................................27
7.5. Exemplos de Requisição...............................................................................................................................27
7.6. Resultado XML.............................................................................................................................................28
7.7. Tags XML Resultantes..................................................................................................................................28
7.8. Exemplo de Resultado...................................................................................................................................28
7.9. Resultados de Erros Comuns.........................................................................................................................29
8. Boleto Bancário – Pedido de Emissão – BOL............................................................................................................30
8.1. BOL – Descrição...........................................................................................................................................30
8.2. BOL – Métodos de Envio..............................................................................................................................30
8.3. BOL – URLs..................................................................................................................................................30
8.4. BOL – Parâmetros de Requisição..................................................................................................................30
8.5. BOL – Exemplo de Requisição GET............................................................................................................31
8.6. BOL – Resultados..........................................................................................................................................32
9. Transferências Bancárias On­line – Pedido de Aprovação......................................................................................33
9.1. Descrição.......................................................................................................................................................33
9.2. Métodos de Envio..........................................................................................................................................33
9.3. URL's.............................................................................................................................................................33
9.4. Parâmetros de Requisição.............................................................................................................................33
9.5. Exemplo de Requisição.................................................................................................................................33
9.6. Exemplo de Resultados.................................................................................................................................34
9.7. Resultados de Erros Comuns.........................................................................................................................34
10. Transferência Bancária On Line – Retorno de Confirmação de Pedido..............................................................36
10.1. Descrição.....................................................................................................................................................36
10.2. Métodos de Envio........................................................................................................................................36
10.3. URL.............................................................................................................................................................36
10.4. Parâmetros de Retorno................................................................................................................................36
10.5. Exemplo de Retorno....................................................................................................................................36
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
3
10.6. Resultados de Erros Comuns.......................................................................................................................36
11. Débito em Conta Corrente – Pedido de Aprovação – DEB....................................................................................37
11.1. DEB – Descrição.........................................................................................................................................37
11.2. DEB – Métodos de Envio............................................................................................................................37
11.3. DEB – URL.................................................................................................................................................37
11.4. DEB – Parâmetros de Requisição................................................................................................................37
11.5. Exemplo de Requisição...............................................................................................................................38
11.6. Exemplo de Resultados...............................................................................................................................39
12. Diagrama de Funcionamento....................................................................................................................................40
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
4
Prezado Cliente,
Apresentamos a seguir o Manual de integração do Aprova Fácil – Modo WebService.
O modo WebService é uma forma de integração simples, que dispensa a instalação de clientes do Aprova Fácil, no servidor do Lojista.
Esperamos através desta documentação orientá­lo da melhor forma possível e aproveitamos a oportunidade para colocar­nos à sua disposição para maiores esclarecimentos.
Para entrar em contato conosco, utilize os canais de contato disponibilizados na URL abaixo:
http://www.cobrebem.com/contato.html
Nota: De acordo com as exigências do PCI­DSS a Cobre Bem Tecnologia não é autotizada a receber números de cartão de crédito. Caso necessite de suporte em relação a alguma transação efetuada, nos informe o número da transação.
Boas cobranças e Cobre Bem!
Equipe Cobre Bem
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
5
1. Introdução
O WebService é uma das formas disponíveis para efetuar a integração de sua loja virtual/aplicativo à solução de automatização de vendas, o Aprova Fácil; através de diversos meios de pagamento.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
6
2. Integração
Para iniciar o processo de integração, o desenvolvedor da loja deverá informar­nos o(s) endereço(s) IP da loja/aplicação que se comunicará com o Aprova Fácil.
Para utilizar essa forma de integração é necessário que o endereço IP de onde as transações partirão seja fixo. Caso você não possua um IP fixo o ideal é realizar a integração através do CGI do Aprova Fácil ou via componente COM CobreBemX. Ofertamos também a integração através de STAC onde o seu cliente é direcionado para digitar os dados de cartão em nosso servidor seguro.
2.1. Meios de Pagamento Suportados
O Aprova Fácil realiza a automatização de diversos meios de pagamento simultaneamente com Bancos e Administradoras de Cartões de Crédito, utilizando a internet como meio de captura.
http://www.cobrebem.com/aprovafacil.html
2.2. Tecnologias de Conectividade
http://www.cobrebem.com/administradoras.html
2.3. Etapas da Automatização
2.3.1. Cartão de Crédito
a) Requisição de aprovação;
b) Requisição de captura;
c) Requisição de cancelamento;
d) Cancelamento de retorno não­imediato;
e) Lista de ID de Cartões vencidos / a vencer (pagamentos recorrentes).
2.3.2. Boleto Bancário
a) Pedido de emissão;
b) Lista de confirmação de pagamento.
2.3.3. Transferência Bancária On line (Débito On Line)
a) Requisição de aprovação;
b) Confirmação de recebimento de resultado;
c) Retorno de confirmação de pagamento.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
7
2.3.4. Débito em Conta Corrente
a) Pedido de aprovação;
b) Solicitação de Resultado de Transação.
2.4. Tempo de Captura de uma Transação Aprovada
Nas vendas realizadas através do meio de pagamento Cartão de Crédito, é possível realizar confirmação (captura) da transação de 02 (duas) formas:
–
Manual;
–
Automática.
A confirmação/captura de uma transação se refere ao envio para a Administradora da confirmação do pedido por parte da loja. A reserva de crédito estabelecida na aprovação é transformada em um débito efetivo no cartão de crédito do Cliente. A confirmação/captura pode ser realizada de forma Manual ou Automática, dependendo da implementação realizada pelo desenvolvedor.
O Lojista determina o modo da confirmação/captura de acordo com o tipo de venda/negócio adotado. Geralmente, o Lojista adota o modo de confirmação com captura manual, quando deseja realizar uma verificação do pedido antes de confirmar/capturar a transação junto à Administradora de Cartão de Crédito.
Caso o lojista não realize a captura da transação no prazo estipulado pelas Administradoras de Cartão de Crédito, de acordo com a tecnologia de conectividade, a mesma será desfeita automaticamente. Nesse caso, o débito não será realizado no cartão de crédito do cliente.
O lojista poderá visualizar a data/hora desse processo, denominado “Desfazimento” da transação, no campo “Data/Hora Cancelamento” existente no Extrato do Aprova Fácil.
Abaixo segue um quadro ilustrativo, contendo os prazos de confirmação (captura) da transação, de acordo com a tecnologia de conectividade e Administradora de Cartão de Crédito para sua análise.
Adm. de Cartão de Crédito
Tecnologia de Conectividade
TEF Dedicado Visanet
Verified By Visa
MoSet
Komerci
Redecard
American Express
Hipercard
Aura
Prazo de Confirmação ­ Manual
47 horas
até 5 dias
Komerci Webservice
Somente é possível captura Manual com Pré­Autorização, neste caso são 5 dias. (*) veja Nota 1
TEF Dedicado
23 horas
WebPos
5 dias
TEF Dedicado
47 horas
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
8
As tecnologias de conectividade Komerci e Komerci WebService da Redecard não permitem confirmação (captura) do tipo manual, somente a automática com prazo de confirmação (captura) máxima de 2 e 5 minutos, respectivamente.
(*) Nota 1: Se o estabelecimento está habilitado na tecnologia de conectividade Komerci ou Komerci Webservice com “Pré­Autorização” junto à Administradora Redecard, a captura poderá ser realizada de forma manual. Nesse caso, o prazo para realizar a confirmação (captura) será de 5 dias consecutivos a partir da data do processamento, realizado pela Administradora de Cartão de Crédito Redecard.
2.5. Codificação da Resposta do Aprova Fácil
Se desejar que a resposta seja codificada em UTF­8, utilize, na requisição, o parâmetro ResponderEmUTF8 passando para ele o valor “S”. Caso contrário, a resposta será em ISO 8859­1.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
9
3. Cartão de Crédito – Pedido de Aprovação – APC
3.1. Descrição
O pedido de aprovação deverá ser usado sempre que a aplicação do desenvolvedor precisar da aprovação financeira para uma venda com cartão de crédito.
Existem três tipos de pedidos de aprovação: venda única, venda recorrente e venda agendada.
O pedido de venda única ocorre quando os dados são enviados ao Aprova Fácil, que, por sua vez, os envia para a Administradora, esta retorna com a resposta de aprovação ou não aprovação da transação.
O pedido de venda recorrente ocorre quando um ID de pedido previamente processado é enviado ao Aprova Fácil, ao invés da informação do cartão de crédito. Assim, o Aprova Fácil recupera as informações da transação prévia do cartão de crédito e as inclui nos parâmetros recebidos antes de processá­la.
O pedido de venda agendada ocorre quando há a necessidade de efetuar débito mensal no cartão de crédito. O Aprova Fácil realiza as transações de forma automática a partir da primeira transação aprovada no agendamento, criado de acordo com a quantidade de meses estipulada.
3.2. Métodos de Envio
Como os dados passados no envio do pedido são sigilosos, o método de envio a ser adotado é o POST, através de HTTPS.
3.3. URLs Chamada
3.3.1. Servidor principal: www.aprovafacil.com/cgi­bin/APFW/<usuario>/APC
3.3.2. Servidor de backup: backup.aprovafacil.com/cgi­bin/APFW/<usuario>/APC
3.3.3. Servidor de backup2: backup2.aprovafacil.com/cgi­bin/APFW/<usuario>/APC
3.3.4. Servidor de teste: teste.aprovafacil.com/cgi­bin/APFW/<usuario>/APC
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
3.4. Parâmetros do Pedido
Tecnologias: TEF Dedicado / MoSet / Web POS / Komerci Web Service
Nome
Descrição
Formatação
NumeroDocumento
Identificação da venda pela Até 50 caracteres loja.
alfanuméricos.
ValorDocumento
Valor da transação
Exemplo
123ABC
Numérico, sendo as casas 123.56
decimais separadas por ponto (.)
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
Obrigatório
Não
Sim
10
Nome
Descrição
QuantidadeParcelas Quantidade de parcelas
Formatação
02 dígitos numéricos
Exemplo
01
Obrigatório
Sim
NumeroCartao
Número do cartão de crédito Até 19 dígitos numéricos
40730200000000
Sim
02
MesValidade
Mês em que o cartão expira
02 dígitos numéricos
11
Sim
AnoValidade
Ano em que o cartão expira
02 dígitos numéricos
08
Sim
CodigoSeguranca*
CVC2/CVV2 do cartão
Até 04 dígitos numéricos
123
Sim, se tecnologia diferente de Komerci Web Service**
PreAutorizacao
Veja descrição abaixo***
Char. S=Sim e N= Não S
Não
000.000.000.000
200.200.200.0
Sim
EnderecoIPCompra
IP de quem compra
dor
NomePortadorCart
Nome que está gravado no ao
Até 50 caracteres alfanuméricos José da Silva
cartão
Bandeira
VISA
MASTERCARD
DINERS
Bandeira do cartão de AMEX
crédito
HIPERCARD
JCB
SOROCRED
AURA
CPFPortadorCartao CPF do portador do cartão
14 dígitos numéricos
11 dígitos numéricos
VISA
Não
Não
12345678123412
Não
12345678912
DataNascimentoPo Data de nascimento do aaaammdd
rtadorCartao
portador do cartão
20071027
Não
Utilizado para acionar o ParcelamentoAdmi
parcelamento Apenas um caracter: S
nistradora
administradora
S
Não
Moeda
Valores válidos: BRL, MXN, Moeda utilizada na venda CLP (Demais valores ISO para (caso não seja informado, BRL
definições de moeda ­ ISO será assumido o valor BRL)
4217)
Não
* É possível controlar o resultado no ambiente de testes do Aprova Fácil. Para isto, utilize o parâmetro “CodigoSeguranca”. Veja abaixo o resultado esperado. Essa modalidade não está disponível para Aura e Sorocred.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
11
CodigoSeguranca Informado •555 ou 123
•501
•502
•504
•506
Retorno:
•Autorizado •05 ­ 05NAO AUTORIZADA •78 ­ 78CAR BLOQ1.USO •14 ­ 14CARTAOINVALIDO •60 ­ Valor Inválido. Por favor, ent •507
•508
•509
•444
•333
•68 ­ T68TRANSACAO JA EFETUADA •54 ­ 54CARTAO VENCIDO •56 ­ Dado Inválido. Por favor, entr •N7 ­ N7COD.SEG.INVAL •84 ­ T84REFACA TRANS
** Por determinação da Redecard o CVV2 não deve ser solicitado do comprador quando a tecnologia utilizada for Komerci Web Service.
*** A Pré­autorização é o bloqueio temporário de uma quantia no cartão de crédito, com objetivo de garantir a sua reserva; é um recurso que pode ser utilizado nas tecnologias de conectividade Komerci e Komerci WebService (Redecard). O tipo de venda que contém esse recurso somente é utilizado em projetos especiais que tenham essa necessidade.
3.5. Agendamento ­ Descrição
O agendamento de transações é utilizado, quando há a necessidade de efetuar mensalmente o débito no cartão de crédito do cliente mantendo sempre as mesmas condições: –
Mesmo valor;
–
Débito mensal realizado sempre no mesmo dia.
O agendamento é realizado de forma automática pelo Aprova Fácil, obedecendo as regras de débito informadas através dos parâmetros de agendamentos descritos no item 3.5.2 deste manual.
Importante: Para que o agendamento seja aceito é necessário que a primeira transação tenha sido aprovada pela Administradora de Cartão de Crédito. Caso contrário, não será realizado o agendamento.
3.5.1. Agendamento – Tecnologia de Conectividade O agendamento é suportado pelas tecnologias de conectividade listadas abaixo:
­ TEF Dedicado, MoSet (Visanet), Komerci WebService (Redecard) e WebPos (Amex).
3.5.2. Agendamento ­ Parâmetros Utilizados para Agendar uma Transação
Os parâmetros de requisição, exibidos na tabela abaixo, devem ser enviados na primeira solicitação de débito do cartão de crédito juntamente com os demais dados do pedido. Neste caso o parâmetro NumeroDocumento passa a ser obrigatório, não poderá ser nulo e deverá ser único.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
12
Nome
Descrição
Formatação
Exemplo
Agendamento
Utilizado Incluir ou Caracter: I – Incluir / E Excluir
– Excluir/ A – Atualizar
DiaParaAgendar
Dia que será feito o dd
débito
09
Se Agendamento=I
QuantidadeMesesParaAgendar
Quantidade de meses a 2 dígitos numéricos
debitar
08
Se Agendamento=I
2 dígitos numéricos
04
Se Agendamento=I
QuantidadeDiasEntreTentativas
Dias entre cada tentativa 2 dígitos numéricos
03
Se Agendamento=I
ParcelamentoAdministradora
Utilizado para acionar o Apenas um caracter: S S
parcelamento administradora
NumeroTentativasNaoAprovado Tentativas para
aprovação
I
Obrigatório
Sim
Não
3.6. Recorrência – Descrição
A recorrência de transações é utilizada, quando se deseja efetuar novos débitos em um cartão de crédito, seja esta de qualquer periodicidade; é possível alterar o valor do débito a cada cobrança, se necessário.
O processo de "re­cobrança" em uma recorrência, se difere do processo de "re­cobrança" em um agendamento. A re­cobrança em uma recorrência é comandada pela aplicação do lojista, nesse caso, deve ser informado apenas o número que identifica a última transação aprovada e confirmada, sendo este, representado pelo parâmetro "Transacao".
Nota: O Número da Transação é criado automaticamente pelo Aprova Fácil, com objetivo de identificar cada transação. Esse número é único e jamais será repetido.
3.6.1. Recorrência – Tecnologias de Conectividade
A recorrência de transações é suportada pelas tecnologias de conectividade: TEF Dedicado, MoSet (Visanet), Komerci WebService (Redecard) e WebPos (Amex).
Existem 3 formas de capturar o CVV2 para Administradora de Cartão de Crédito Visanet (digitada, chip e trilha). Para trabalhar com recorrência utilizando a tecnologiade conectividade TEF 4.1, é necessário desabilitar a opção digitada de CVV2.
3.6.2. Recorrência – Parâmetros de Requisição
Nome
Descrição
Formatação
TransacaoAnterior
Número da Transação 14 caracteres numéricos
ValorDocumento
Valor da transação
Numérico, sendo as casas decimais separadas por ponto (.)
Exemplo
Obrigatório
78712879871121 Sim
123.56
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
Sim
13
Nome
Descrição
QuantidadeParcelas Quantidade de parcelas
Formatação
Exemplo
02 dígitos numéricos
1
ParcelamentoAdmi Utilizado para acionar o Apenas um caracter: S
nistradora
parcelamento administradora
Obrigatório
Sim
S
Não
3.7. Consulta AVS (Adress Verification Service)
O AVS é um serviço oferecido pelas Administradoras de Cartão de Crédito, para que o lojista possa realizar uma consulta para confirmação dos dados de CPF (Cadastro Pessoa Física) e do endereço de entrega da fatura do titular do cartão no ato da compra .
Para disponibilizar essa consulta, o estabelecimento deverá habilitar esse serviço junto às Administradoras de Cartão de Crédito, e, após, informar à Cobre Bem Tecnologia que a mesma será utilizada.
A consulta AVS é suportada para as bandeiras Amex e Mastercard, nas tecnologias de conectividade WebPos, Komerci e Komerci WebService, respectivamente.
Se o estabelecimento do lojista possuir habilitação para realizar vendas com AVS, no momento da solicitação dos dados, deverão ser informados também os parâmetros de requisição a seguir:
Tecnologia Komerci
Nome
AVS
Descrição
Valores: N – Não realizar
S – Para realizar consulta
Formatação
Exemplo
Obrigatório
S
Sim, caso deseja que a transação contemple consulta AVS
01 caracter
Demais Tecnologias
Nome
Descrição
Formatação
AVS
Valores: N – Não realizar
S – Para realizar consulta 01 caracter maiúsculo
Exemplo
Obrigatório
S
Sim
CPFPortadorCartao
CPF do Portador do cartão 14 dígitos numéricos
de crédito
11 dígitos numéricos
12345678123412
12345678912
Se AVS = S
EnderecoPortadorCartao
Endereço do Portador do Até 50 caracteres
cartão de crédito
Endereço + número
Av. das flores 123
Se AVS = S
CEPPortadorCartao
CEP do Portador do cartão 08 dígitos numéricos
de crédito
20555000
Se AVS = S
3.8. Exemplo de Pedido 3.8.1. Venda Única
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
14
<form action=https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/APC method=post>
<input type=text name=NumeroDocumento value="123ABC">
<input type=text name=ValorDocumento value="123.56">
<input type=text name=QuantidadeParcelas value="1">
<input type=text name=NumeroCartao value="4073020000000002">
<input type=text name=MesValidade value="11">
<input type=text name=AnoValidade value="08">
<input type=text name=CodigoSeguranca value="123">
<input type=text name=CPFPortadorCartao value="12345678123412">
<input type=submit value="Solicitar Aprovacao">
</form>
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
3.8.2. Pagamento Recorrente
<form action=https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/APC method=post>
<input type=text name=NumeroDocumento value="123ABC">
<input type=text name=ValorDocumento value="123.56">
<input type=text name=QuantidadeParcelas value="1">
<input type=text name=TransacaoAnterior value="123ABC">
<input type=submit value="Solicitar Aprovacao">
</form> Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
3.8.3. Pagamento Agendado
<form action=https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/APC method=post>
<input type=text name=NumeroDocumento value="123ABC">
<input type=text name=ValorDocumento value="123.56">
<input type=text name=QuantidadeParcelas value="1">
<input type=text name=NumeroCartao value="4073020000000002">
<input type=text name=MesValidade value="11">
<input type=text name=AnoValidade value="08">
<input type=text name=CodigoSeguranca value="123">
<input type=text name=CPFPortadorCartao value="12345678123412">
<input type=text name=QuantidadeParcelas value="1">
<input type=text name=Agendamento value=I>
<input type=text name=DiaParaAgendar value=03>
<input type=text name=QuantidadeMesesParaAgendar value=10>
<input type=text name=NumeroTentativasNaoAprovado value=3>
<input type=text name=QuantidadeDiasEntreTentativas value=5>
<input type=submit value="Solicitar Aprovacao">
</form>
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
15
3.8.4. Pagamento com Consulta AVS
<form action=https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/APC method=post>
<input type=text name=NumeroDocumento value="123ABC">
<input type=text name=ValorDocumento value="123.56">
<input type=text name=QuantidadeParcelas value="1">
<input type=text name=NumeroCartao value="4073020000000002">
<input type=text name=MesValidade value="11">
<input type=text name=AnoValidade value="08">
<input type=text name=CodigoSeguranca value="123">
<input type=text name=QuantidadeParcelas value="1">
<input type=text name=Agendamento value=I>
<input type=text name=DiaParaAgendar value=03>
<input type=text name=QuantidadeMesesParaAgendar value=10>
<input type=text name=NumeroTentativasNaoAprovado value=3>
<input type=text name=QuantidadeDiasEntreTentativas value=5>
<input type=text name=AVS value=S>
<input type=text name=CEPPortadorCartao value=12312000>
<input type=text name=CPFPortadorCartao value=11111111111>
<input type=text name=EnderecoPortadorCartao value=”Rua do Sacado”>
<input type=submit value="Solicitar Aprovacao">
</form> Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
3.9. Resultado do Processamento Formato XML
Resposta XMLdo processamento de uma transação.
<ResultadoAPC>
<TransacaoAprovada>TRUE</TransacaoAprovada> <ResultadoSolicitacaoAprovacao>00 ­ APROVADA</ResultadoSolicitacaoAprovacao> <CodigoAutorizacao>082030</CodigoAutorizacao> <Transacao>73314072604262</Transacao> <CartaoMascarado>407302******0002</CartaoMascarado> <NumeroDocumento>12345</NumeroDocumento> <ComprovanteAdministradora>RETORNO, DEPENDE DA TECNOLOGIA</ComprovanteAdministradora> <NacionalidadeEmissor> </NacionalidadeEmissor> <ResultadoAVS> </ResultadoAVS> <EnderecoAVS> <Endereco> </Endereco> <Numero> </Numero> <Complemento> </Complemento> <Cep> </Cep> </EnderecoAVS> </ResultadoAPC>
3.9.1. Descrição dos Parâmetros
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
16
Seguem abaixo a descrição e formato dos parâmetros retornados no XML
Nome
Descrição
TransacaoAprovada
Resultado do pedido de aprovação
Formatação
True = Aprovado
False = Negado
Exemplo Obrigatório
True
Sim
ResultadoSolicitacaoAprovacao Descrição da aprovação do Texto varchar
resultado do pedido
veja tabela abaixo
sim
CodigoAutorizacao
Código de autorização retornado Texto de 6 dígitos
pela Administradora do cartão de crédito
N12345
Transacao
ID da transação Aprova Fácil
732638688
27369
Sim
CartaoMascarado
Número mascarado do Cartão de Até 19 dígitos 444433***
Crédito
numéricos
***1111
Sim
NumeroDocumento
ID do pedido da companhia
Até 50 caracteres
123ABC
Sim
NumeroSequencialUnico
Número de aprovação da Administradora
6 dígitos numéricos
123456
não
ComprovanteAdministradora
Texto comprovante da Administradora
Texto varchar
N/A
Não
NacionalidadeEmissor
País emissor
Texto nulo
N/A
Não
ResultadoAVS
Resultado da verificação de endereço (Veja a tabela do item 3.9.2)
Texto nulo
N/A
Não
EnderecoAVS
Tag de grupo para endereço N/A
verificado
N/A
Não
Endereco
Endereço de rua verificado
Texto nulo
Numero
Número de endereço verificado
Texto nulo
N/A
Não
Complemento
Complemento do endereço Texto nulo
verificado
N/A
Não
Cep
CEP do endereço verificado
N/A
Não
Texto de 14 dígitos
Texto nulo
Sim se aprovado
Não
3.9.2. Tabela de Valores retornados para o parâmetro ResultadoAVS
Amex
Código
Descrição
X
Endereço e CEP 9 ­ digitos coincidem.
Y
Endereço e CEP 5 ­ digitos coincidem.
W
Somente o CEP 9 ­ Digitos coincide.
S
Serviço não suportado.
G
Emissor não participa do AVS.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
17
Amex
Código
Descrição
A
Endereço coincide. Cep não coincide ou não verificado.
Z
Cep 5 ­ digitos coincide. Endereço não coincide.
R
Emissor não disponivel.
U
Endereço indisponivel.
N
Nada coincide.
E
Endereço e Cep não informado.
Redecard
Código
Descrição
W
Sim, todos os dígitos coincidem.
X
O CEP e CPF coincidem, endereço não coincide.
Z
Endereço e CPF coincidem, CEP não coincide.
Y
O CEP coincide, CPF e endereço não coincidem.
A
CPF coincide, CEP e endereço não coincidem.
U
O CEP e CPF não coincidem, endereço coincide.
S
O CEP e endereço coincidem, CPF não coincide. N
Nada coincide.
3.10. Resultados de Erros Comuns
Texto do Resultado
Descrição
Erro ­ Valor Inválido
Valor Inválido
Erro ­ Valor deve ser maior que zero
Valor deve ser maior que zero
Erro ­ Número Parcelas Inválido
Número Parcelas Inválido
Erro ­ Número Parcelas deve ser maior que zero
Número Parcelas deve ser maior que zero
Erro ­ Transação Anterior não Localizada
Transação Anterior não Localizada
Erro ­ Conectividade não permite recorrência
Conectividade não permite recorrência
Erro ­ Cartão Inválido
Cartão Inválido
Erro ­ Estabelecimento não cadastrado para a Bandeira XXX Merchant can not accept XXX payments
Adquirinte YYY
Erro ­ Estabelecimento não habilitado para a Bandeira XXX XXX disabled for merchant
Adquirinte YYY
Erro ­ Código do Emissor do cartão Inválido
Código do Emissor do cartão Inválido
Erro ­ Mês/Ano Validade Inválidos
Mês/Ano Validade Inválidos
Erro ­ Cartão fora do prazo de validade
Cartão fora do prazo de validade
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
18
Texto do Resultado
Descrição
Erro ­ Número Parcelas Agendamento Inválido
Número Parcelas Agendamento Inválido
Erro ­ Número Parcelas Agendamento deve ser maior que 1
Número Parcelas Agendamento deve ser maior que 1
Erro ­ Dia Débito Inválido
Dia Débito Inválido
Erro ­ Dia Débito deve estar entre 1 e 31
Dia Débito deve estar entre 1 e 31
Erro ­ Número Tentativas Inválido
Número Tentativas Inválido
Erro ­ Número Tentativas ser maior que 1 ou igual a zero
Número Tentativas ser maior que 1 ou igual a zero
Erro ­ Dias entre Tentativas Inválido
Dias entre Tentativas Inválido
Erro ­ Dias entre Tentativas ser maior ou igual a 1
Dias entre Tentativas ser maior ou igual a 1
Erro ­ Cliente sem Estabelecimento de Aprovação
Cliente sem Estabelecimento de Aprovação
Erro ­ Conexão não Estabelecida
Conexão não Estabelecida
Erro ­ Conexão AVS não Estabelecida
Conexão AVS não Estabelecida
Erro ­ Sem Servidor Aprovação
Sem Servidor Aprovação
Erro ­ IP não permitido
IP não permitido
Erro ­ Última Aprovação para o cartão tem menos do que 5 Última Aprovação para o cartão tem menos do que 5 minutos
minutos
Erro ­ Cartão com 3 tentativas não aprovadas
Cartão com 3 tentativas não aprovadas
Erro ­ Parâmetros Incorretos
Parâmetros Incorretos
Erro ­ Código Cliente Inválido
Código Cliente Inválido
Erro ­ Código de Cliente Forjado
Código de Cliente Forjado
Erro ­ Modo de Operação Inválido
Modo de Operação Inválido
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
19
4. Cartão de Crédito – Pedido de Captura – CAP 4.1.CAP – Descrição
A diretiva de execução CAP efetua a captura de uma transação. Entende­se por captura o processo de confirmação de uma transação, o que caracteriza a venda efetivada, sendo realizado assim, o débito no cartão de crédito do cliente.
De acordo com os padrões ISO 8583, todas as transações aprovadas pelas Administradoras de Cartões de Crédito devem ser capturadas (confirmadas) pela aplicação do Lojista.
Caso a transação não seja capturada (confirmada) pela aplicação do Lojista, no prazo estipulado pelas Administradoras de Cartões Crédito, a mesma será automaticamente desfeita, não havendo assim o débito efetivo no cartão de crédito do cliente, essa informação será exibida no campo “Data Hora Cancelamento”do Extrato do Aprova Fácil.
4.2. CAP – Métodos de Envio
Os métodos de envio dos parâmetros podem ser o POST ou GET, utilizando conexões HTTP ou HTTPS, já que não são trafegados dados sigilosos.
4.3. CAP – URLs
4.3.1. Servidor principal: www.aprovafacil.com/cgi­bin/APFW/<usuario>/CAP
4.3.2. Servidor de backup: backup.aprovafacil.com/cgi­bin/APFW/<usuario>/CAP
4.3.3. Servidor de backup2: backup2.aprovafacil.com/cgi­bin/APFW/<usuario>/CAP
4.3.4. Servidor de teste: teste.aprovafacil.com/cgi­bin/APFW/<usuario>/CAP
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
4.4. CAP ­ Parâmetros de Requisição
Nome
Descrição
Formatação
Exemplo
NumeroDocumento
Identificação da venda Até 50 caracteres
123ABC
pela loja.
Transação
Número da transação
14 caracteres 73263500055432
numéricos
Obrigatório
Não
Se NumeroDocumento for nulo
4.5. CAP ­ Exemplos de Requisição GET
4.5.1. Captura utilizando o número documento gerado pelo estabelecimento
https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/CAP?NumeroDocumento=456DEF
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
20
4.5.2. Captura Utilizando o número da transação gerado pelo Aprova Fácil
https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/CAP?Transacao= 73263783188291
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
4.6. Exemplo de Resultados
4.6.1. Captura com Sucesso
<ResultadoCAP>
<ResultadoSolicitacaoConfirmacao>
Confirmado%2073263500055432
</ResultadoSolicitacaoConfirmacao>
<ComprovanteAdministradora></ComprovanteAdministradora>
</ResultadoCAP>
4.6.2. Captura com Erro
<ResultadoCAP>
<ResultadoSolicitacaoConfirmacao>
Erro%20­%20Transa%E7%E3o%20a%20confirmar%20n%E3o%20encontrada%20ou
%20jE1%20confirmada
</ResultadoSolicitacaoConfirmacao>
<ComprovanteAdministradora></ComprovanteAdministradora>
</ResultadoCAP> 4.7. Resultado de Captura com Sucesso
O resultado de uma transação de captura bem sucedida começará com a palavra “Confirmado”, seguida de um carácter de espaço, e do número de transação Aprova Fácil.
4.8. Resultados de Erro Comuns
Texto do Resultado
Erro ­ Transação Inválida
Descrição
Transação Inválida
Erro ­ Transação a confirmar não encontrada ou já confirmada Transação a confirmar não encontrada ou já confirmada
Erro ­ IP não permitido
IP não permitido
Erro ­ Estabelecimento não cadastrado para a Bandeira XXX Estabelecimento não cadastrado para a Bandeira XXX Adquirinte YYY
Adquirinte YYY
Erro ­ Estabelecimento não habilitado para a Bandeira XXX XXX não habilitada para o estabelecimento
Adquirinte YYY
Erro ­ Captura Já Efetuada
Captura já efetuada
Erro ­ Parâmetros Incorretos
Parâmetros incorretos
Erro ­ Código Cliente Inválido
Código cliente inválido
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
21
Texto do Resultado
Descrição
Erro ­ Código de Cliente Forjado
Código de cliente forjado
Erro ­ Modo de Operação Inválido
Modo de operação inválido
Erro ­ Conexão para confirmação não Estabelecida
Conexão para confirmação não estabelecida
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
22
5. Cartão de Crédito – Cancelamento de Transações – CAN
5.1. CAN – Descrição
A diretiva de execução CAN é utilizada no processo de cancelamento da transação. O cancelamento de uma transação somente poderá ser realizado quando a mesma for aprovada pela Administradora e confirmada pelo lojista. Por isso, para que o Aprova Fácil possa realizar o cancelamento, este deve ser solicitado no mesmo dia em que a transação foi processada, ou seja, foi confirmada pela Administradora.
5.2. CAN – Métodos de Envio
O método de envio utilizado pode ser o POST ou GET e as informações podem ser enviadas através de HTTP ou HTTPS, já que não são trafegados dados sigilosos.
5.3. CAN – URLs
5.3.1. Servidor principal: www.aprovafacil.com/cgi­bin/APFW/<usuario>/CAN
5.3.2. Servidor de backup: backup.aprovafacil.com/cgi­bin/APFW/<usuario>/CAN
5.3.3. Servidor de backup2: backup2.aprovafacil.com/cgi­bin/APFW/<usuario>/CAN
5.3.4. Servidor de teste: teste.aprovafacil.com/cgi­bin/APFW/<usuario>/CAN
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
5.4. CAN – Parâmetros de Requisição
Nome
Descrição
Formatação
Exemplo
NumeroDocumento
Identificação da venda Até 50 caracteres 123ABC
pela loja.
alfanuméricos.
Transacao
Número da transação
14 caracteres 73263500055432
numéricos
Obrigatório
Não
Se NumeroDocumento for nulo
5.5. CAN – Exemplos de Requisição
5.5.1. Cancelamento utilizando o número do documento gerado pelo estabelecimento
https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/CAN?NumeroDocumento=456DEF
5.5.2. Cancelamento Utilizando o ID da Transação Aprova Fácil https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/CAN?Transacao= 73263783188291
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
23
5.6. Resultado XML
<ResultadoCAN>
<ResultadoSolicitacaoCancelamento></ResultadoSolicitacaoCancelamento>
<NSUCancelamento></NSUCancelamento>
</ResultadoCAN>
5.7. Resultado das Tags XML
Nome
ResultadoCAN
Descrição
Tag Raiz XML
Formatação
Amostra
Obrigatório
N/A
N/A
sim
ResultadoSolicitacaoCancelamento Descrição do resultado do pedido de cancelamento
texto varchar
veja tabela abaixo
sim
NSUCancelamento
6 dígitos numéricos 123456
Número de cancelamento da Administradora
não
5.8. Exemplos de Resultados
5.8.1. Cancelamento Online Com Sucesso
<ResultadoCAN>
<ResultadoSolicitacaoCancelamento>
Cancelado%2073263500055432
</ResultadoSolicitacaoCancelamento>
<NSUCancelamento>
123456
</NSUCancelamento>
</ResultadoCAN>
5.8.2. Cancelamento Marcado para Processamento com Sucesso
<ResultadoCAN>
<ResultadoSolicitacaoCancelamento>
Cancelamento%20marcado%20para%20envio%2073263500055432
</ResultadoSolicitacaoCancelamento>
<NSUCancelamento>
123456
</NSUCancelamento>
</ResultadoCAN>
5.8.3. Erro de Cancelamento On­Line
<ResultadoCAN>
<ResultadoSolicitacaoCancelamento>
Erro%20­%20Transa%E7%E3o%20inv%E1lida
</ResultadoSolicitacaoCancelamento>
<NSUCancelamento></NSUCancelamento>
</ResultadoCAN>
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
24
5.8.4. Erro na Marcação do Cancelamento para Processamento
<ResultadoCAN>
<ResultadoSolicitacaoCancelamento>
Erro%20­%20Transa%E7%E3o%20inv%E1lida
</ResultadoSolicitacaoCancelamento>
<NSUCancelamento></NSUCancelamento>
</ResultadoCAN>
5.9. Resultado de Cancelamento com Sucesso
O resultado de uma transação cancelada com sucesso será a mensagem “Cancelamento OK”.
5.10. Resultados de Erros Comuns NSUCancelamento
Texto Resultante
Descrição
Erro ­ Transação Inválida
Transação nválida
Erro ­ Transação a cancelar não encontrada ou já cancelada
Transação a cancelar não encontrada ou já cancelada
Erro ­ IP não permitido
IP não permitido
Erro ­ Estabelecimento não cadastrado para a Bandeira XXX Estabelecimento não cadastrado para a Bandeira XXX Adquirinte YYY
Adquirinte YYY
Erro ­ Estabelecimento não habilitado para a Bandeira XXX XXX não habilitada para o estabelecimento
Adquirinte YYY
Erro – Cancelamento Já Efetuado
Cancelamento já efetuado
Erro ­ Parâmetros Incorretos
Parâmetros incorretos
Erro ­ Código Cliente Inválido
Código cliente inválido
Erro ­ Código de Cliente Forjado
Código de cliente forjado
Erro ­ Modo de Operação Inválido
Modo de operação inválido
Erro ­ Conexão para cancelamento não Estabelecida
Conexão para cancelamento não estabelecida
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
25
6. Cartão de Crédito – Retorno de Cancelamento Previamente Solicitado
6.1. Descrição
O desenvolvedor deverá fornecer uma URL, a fim de receber um POST ou GET dos servidores do Aprova Fácil com a informação de confirmação do cancelamento previamente solicitado.
6.2. URLs
6.2.1. Servidor cliente, ex :
https://www.seusite.com.br/retorno.php
6.3. Métodos de Envio
6.3.1. HTTPS POST
6.3.2. HTTPS GET
6.4. Parâmetros do Retorno
Nome
Descrição
Formatação
Amostra
Obrigatório
NumeroDocumento
ID do pedido da companhia
Até 50 caracteres
123ABC
sim
ResultadoSolicitaca
oCancelamento
Descrição do resultado do pedido de cancelamento
texto varchar
veja tabela abaixo
sim
NSUCancelamento
Número de cancelamento da administradora
6 dígitos numéricos 123456
não
6.5. Exemplo de Retorno
https://www.seusite.com.br/retorno.php?
NumeroDocumento=123ABC&ResultadoSolicitacaoCancelamento=Cancelado
%2073263500055432&NSUCancelamento=123456
6.6. Resultado de Cancelamento bem Sucedido
O resultado de uma transação, cancelada com sucesso, começará com a palavra “Cancelado”, seguida de um carácter de espaço e do número de ID do Aprova Fácil.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
26
7. Cartão de Crédito – Requisição da Lista dos Cartões de Crédito cujas Datas de Validade estão Prestes a Expirar (Agendamento e Recorrência)
7.1. Descrição
A requisição de listagem da ID de pedidos prestes a expirar retornará uma lista XML, contendo todas as IDs dos pedidos cujos cartões de crédito findarão no período indicado. Essa requisição deverá ser usada por lojistas que precisarem da informação da data limite máxima permitida para pagamentos recorrentes, para cada pedido enviado anteriormente.
7.2. URLs
7.2.1. Servidor principal: www.aprovafacil.com/cgi­bin/APFW/<usuario>/EXP
7.2.2. Servidor backup: backup.aprovafacil.com/cgi­bin/APFW/<usuario>/EXP
7.2.3. Servidor backup2: backup2.aprovafacil.com/cgi­bin/APFW/<usuario>/EXP
7.2.4. Servidor teste: teste.aprovafacil.com/cgi­bin/APFW/<usuario>/EXP
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
7.3. Métodos de Envio
7.3.1. HTTPS POST
7.3.2. HTTPS GET
7.4. Parâmetros de Requisição
Nome
Descrição
Formatação
Amostra
Obrigatório
DataInicial
Mês e ano iniciais para procura no banco de dados
aaaamm
200610
sim
DataFinal
Mês e ano finais para procura no banco de dados
aaaamm
200611
sim
7.5. Exemplo de Requisição
https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/EXP?DataInicial=200610&DataFinal=200611
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
27
7.6. Resultado XML
<ResultadoEXP>
<ResultadoSolicitacaoListaExpiracao></ResultadoSolicitacaoListaExpiracao>
<TamanhoListaExpiracao></TamanhoListaExpiracao>
<CC S= N= D= />
<CC S= N= D= />
...
...
<CC S= N= D= />
</ResultadoEXP>
7.7. Tags XML Resultantes
Nome
Descrição
ResultadoEXP
Tag XML raiz
Formatação
Amostra
Obrigatório
N/A
N/A
sim
ResultadoSolicitacaoListaExpiracao Descrição do resultado da requisição
texto varchar
veja tabela sim
abaixo
TamanhoListaExpiracao
Quantidade
até 6 dígitos numéricos
10
sim
CC
Identifica um item na lista
N/A
N/A
sim
S
Número do item sequencial até 6 dígitos na lista
numéricos
123
sim
N
ID do pedido
até 50 caracteres
123ABC
sim
D
Data de validade do cartão de crédito
aaaamm
200611
sim
7.8. Exemplo de Resultado
7.8.1. Bem sucedido
<ResultadoEXP>
<ResultadoSolicitacaoListaExpiracao>OK</ResultadoSolicitacaoListaExpiracao>
<TamanhoListaExpiracao>5</TamanhoListaExpiracao>
<CC S=1 N=123AB D=200610 />
<CC S=2 N=456CD D=200611 />
<CC S=3 N=789FG D=200610 />
<CC S=4 N=123IJK D=200610 />
<CC S=5 N=456LM D=200611 />
</ResultadoEXP> 7.8.2. Errado
<ResultadoEXP>
<ResultadoSolicitacaoListaExpiracao>
Erro%20­%20Data%20Inicial%20inv%E1lida
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
28
</ResultadoSolicitacaoListaExpiracao>
</ResultadoEXP>
7.9. Resultados de Erros Comuns
Texto Resultante
Descrição
Erro ­ Transação Inválida
Transação inválida
Erro ­ IP não permitido
IP não permitido
Erro ­ Parâmetros Incorretos
Parâmetros incorretos
Erro ­ Código Cliente Inválido
Código cliente inválido
Erro ­ Código de Cliente Forjado
Código de cliente forjado
Erro – Data inicial inválida
Data inicial inválida
Erro – Data final inválida
Data final inválida
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
29
8. Boleto Bancário – Pedido de Emissão – BOL
8.1. BOL – Descrição
O pedido de emissão retornará o boleto bancário no formato HTML, diretamente no navegador do cliente. 8.2. BOL ­ Métodos de Envio
O método de envio utilizado pode ser o POST ou GET, e as informações podem ser enviadas através de HTTP ou HTTPS.
8.3. BOL ­ URL's
8.2.1. Servidor principal: www.aprovafacil.com/cgi­bin/APFW/<usuario>/BOL
8.2.2. Servidor backup: backup.aprovafacil.com/cgi­bin/APFW/<usuario>/BOL
8.2.3. Servidor backup2: backup2.aprovafacil.com/cgi­bin/APFW/<usuario>/BOL
8.2.4. Servidor teste: teste.aprovafacil.com/cgi­bin/APFW/<usuario>/BOL
Nota: <usuario> deverá ser substituído pelo nome do usuário do Aprova Fácil.
8.4. BOL ­ Parâmetros de Requisição
Nome
CCID
Descrição
Formatação
Identifica a conta corrente a ser caracteres utilizada para a geração do boleto alfanuméricos.
Exemplo
Obrigatório
ContaCorrente1
Sim
123ABC
Sim
NumeroDocumento Identificação da venda pela loja.
Até 50 caracteres alfanuméricos.
ValorDocumento
Valor da transação
Numérico, sendo as casas decimais 123.56
separadas por ponto (.)
DataVencimento
Data de vencimento desejada para aaaammdd
o boleto
20071027
Não
PrazoVencimento
Número de dias a serem Até 04 dígitos adicionados a data corrente e gerar numéricos
uma data de validade
3
Não
VencimentoDiaUtil
Altera o vencimento para o S ­ Alterar
proximo dia util
S
Não
CNPJCPFSacado
CPF ou CNPJ do cliente
14 dígitos numéricos
11 dígitos numéricos
12345678123412
12345678912
Não
NomeSacado
Nome do cliente
Até 40 caracteres
Primeiro cliente
Não
EnderecoSacado
Endereço do cliente
Até 40 caracteres
123 Rua do cliente Não
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
Sim
30
Nome
Descrição
Formatação
Exemplo
Obrigatório
CEPSacado
CEP do cliente
05 dígitos numéricos + travessão + 3 dígitos 12345­008
numéricos
Não
CidadeSacado
Nome da cidade do cliente
Até 30 caracteres
Rio de Janeiro
Não
EstadoSacado
Estado do cliente
02 caracteres
RJ
Não
até 64 caracteres
[email protected].
Não
br
EnderecoEmailSaca
Endereço de e­mail do sacado
do
PercentualJurosDia
Numérico, sendo as Percentual de juros a ser cobrado casas decimais 0.99
por dia de atraso no pagamento
separadas por ponto (.)
Não
PercentualMulta
Numérico, sendo as Percentual de multa a ser cobrado casas decimais 0.99
por atraso no pagamento
separadas por ponto (.)
Não
InstrucoesCaixa
Código HTML que será exibido código HTML
nas instruções para o caixa
<b>não receber após vencimento Não
</b>
Demonstrativo
Código HTML que será exibido no código HTML
demonstrativo do recibo do sacado
Referente a compra
de Não
produtos X
SacadorAvalista
Nome do avalista quando este Caracteres
existir
Fulano de Tal
ValorDesconto
Numérico, sendo as Valor do desconto a ser concedido casas decimais 0.99
sobre o valor do documento
separadas por ponto (.)
Não
Não
Numérico, sendo as ValorOutrosAcresci Valor dos acréscimos a serem casas decimais 10
mos
somados ao valor do documento
separadas por ponto (.)
Não
Tipo de documento a ser impresso EspecieDocumento no boleto. Se não for informado, Caracteres
assumirá o valor padrão “RC”
Não
RC
8.5. BOL ­ Exemplo de Requisição GET
Segue um exemplo:
https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/BOL?
DataVencimento=20080410&PrazoVencimento=&NumeroDocumento=123456&ValorDocumento=1%2
C253.67&NomeSacado=Meu+Primeiro+Cliente&CNPJCPFSacado=123.456.789­01 Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
31
8.6. BOL ­ Resultados
8.6.1. Resultados ­ Bem Sucedidos
É retornado o HTML do boleto para a loja.
8.6.2. Resultados ­ Erro na Transação
É retornada para o navegador do cliente uma string (HTML) contendo a mensagem de erro.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
32
9. Transferências Bancárias On Line – Pedido de Aprovação
9.1. Descrição
O pedido de aprovação será realizado toda vez que a aplicação do Lojista necessitar obter aprovação financeira de uma venda, por meio de transferência eletrônica on line. O pedido de transferência eletrônica on line retornará um código HTML que redicionará o navegador do cliente para o site do banco selecionado.
9.2. Métodos de Envio
O método utilizado deve ser o POST, e as informações devem ser enviadas através de HTTPS.
9.3. URLs
9.3.1. Servidor principal: www.aprovafacil.com/cgi­bin/APFW/<usuario>/TRX
9.3.2. Servidor backup: backup.aprovafacil.com/cgi­bin/APFW/<usuario>/TRX
9.3.3. Servidor backup2: backup2.aprovafacil.com/cgi­bin/APFW/<usuario>/TRX
9.3.4. Servidor teste: teste.aprovafacil.com/cgi­bin/APFW/<usuario>/TRX
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
9.4. Parâmetros de Requisição
Nome
Descrição
NumeroDocumento
Formatação
Identificação da venda pela Até
50
loja.
alfanuméricos.
caracteres Exemplo
Obrigatório
123ABC
Não
01
Sim
QuantidadeParcelas Quantidade de parcelas
Valor válido: 01
ValorDocumento
Valor da transação
Numérico, sendo as casas 123.56
decimais separadas por ponto (.)
Sim
Bandeira
Nome do banco
Valores válidos são:
ABNREAL /BBRASIL
BANRISUL / BRADESCO
HSBC / ITAU
UNIBANCO
BRADESCO
Sim
CNPJCPFSacado
CNPJ ou CPF do sacado
14 dígitos numéricos
11 dígitos numéricos
12345678123412
Não
12345678912
9.5. Exemplo de Requisição
Segue exemplo: <form action= https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/TRX method=post> Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
33
<input type=text name=NumeroDocumento value="123ABC"> <input type=text name=QuantidadeParcelas value="01"> <input type=text name=ValorDocumento value="123.56"> <input type=text name=Bandeira value="BRADESCO"> <input type=submit value="Enviar"> </form>
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
9.6. Exemplo de Resultados
9.6.1. Bem Sucedidos
O HTML resultante variará de acordo com o banco escolhido. Segue abaixo um exemplo genérico:
<html> <body onLoad="document.forms[0].submit();"> <p>&nbsp;</p><p>&nbsp;</p><p><center>Aguarde um instante...</center></p> <form action=https://www.bancoselecionado.com.br method=post> <input type=hidden name=TRANSACAO value=1> <input type=hidden name=FILIACAO value=123> <input type=hidden name=NUMPEDIDO value=123456>
</form> </body> </html> 9.6.2. Erro de Transação
<ResultadoTRX>
<TransacaoAprovada>False</TransacaoAprovada>
<ResultadoSolicitacaoAprovacao>
Erro%20­%20Valor%20deve%20ser%20maior%20que%20zero
</ResultadoSolicitacaoAprovacao>
</ResultadoTRX>
9.7. Resultados de Erros Comuns
Texto Resultante
Descrição
Erro ­ Valor Inválido
Valor inválido
Erro ­ Valor deve ser maior que zero
Valor deve ser maior que zero
Erro ­ Estabelecimento não cadastrado para a Bandeira XXX Estabelecimento não cadastrado para a Bandeira XXX Adquirinte YYY
Adquirinte YYY
Erro ­ Cliente sem Estabelecimento de Aprovação
Cliente sem estabelecimento de aprovação
Erro ­ Conexão não Estabelecida
Conexão não estabelecida
Erro ­ Sem Servidor Aprovação
Sem servidor aprovação
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
34
Texto Resultante
Descrição
Erro ­ IP não permitido
IP não permitido
Erro ­ Parâmetros Incorretos
Parâmetros incorretos
Erro ­ Código Cliente Inválido
Código cliente inválido
Erro ­ Código de Cliente Forjado
Código de cliente forjado
Erro ­ Modo de Operação Inválido
Modo de operação inválido
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
35
10. Transferências Bancárias On Line – Retorno de Confirmação de Pedido
10.1. Descrição
O retorno de uma Transferência será feita do Aprova Fácil para o site do Lojista. O desenvolvedor deverá fornecer uma URL para receber o POST ou GET dos servidores do Aprova Fácil, esta conterá a informação de confirmação de pagamento do pedido de transferência bancária on line.
10.2. Métodos de Envio
HTTPS.
O método pode ser o POST ou GET, e as informações podem ser enviadas através de HTTP ou 10.3. URL
Segue um exemplo: https://pagamento.lojacliente.com/RetornoTransacao.php
10.4. Parâmetros de Retorno
Nome
Descrição
Formatação
Exemplo
Obrigatório
NumeroDocumento
Identificação da venda do Até 50 caracteres
Lojista
123ABC
Não
TransacaoAprovada
Resultado da transação
True
Sim
CodigoAutorizacao
Código de autorização Textos varchar
devolvido pelo banco
N12345
Sim se aprovada
Transacao
ID da transacao Aprova Fácil
73263868827369
Sim
True ou False
Texto de 14 dígitos
10.5. Exemplo de Retorno
Segue um exemplo: https://pagamento.lojacliente.com/RetornoTransacao.php?
NumeroDocumento=123ABC&TransacaoAprovada=True&CodigoAutorizacao=123456&Transacao=735
61234567898
10.6. Resultados de Erros Comuns
Texto Resultante
Descrição
Erro ­ Transação Inválida
Transação inválida
Erro ­ Transação a cancelar não encontrada ou já cancelada
Transação a cancelar não encontrada ou já cancelada
Erro – Cancelamento Já Efetuado
Cancelamento já efetuado
Erro ­ Conexão para cancelamento não Estabelecida
Conexão para cancelamento não estabelecida
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
36
11. Débito Automático em Conta Corrente – Pedido de Aprovação – DEB
11.1. DEB – Descrição
O pedido de aprovação será realizado toda vez que a aplicação do Lojista necessitar obter aprovação financeira de uma venda, por meio de débito automático em conta corrente.
O Aprova Fácil envia um arquivo de remessa ao Banco, para que este realize o processamento dos débitos.
11.2. DEB – Métodos de Envio
O método utilizado deve ser o POST, e as informações devem ser enviadas através de HTTPS, já que serão trafegados dados sigilosos.
11.3. DEB – URL
11.2.1. Servidor principal: www.aprovafacil.com/cgi­bin/APFW/<usuario>/DEB
11.2.2. Servidor backup: backup.aprovafacil.com/cgi­bin/APFW/<usuario>/DEB
11.2.3. Servidor backup2: backup2.aprovafacil.com/cgi­bin/APFW/<usuario>/DEB
11.2.4. Servidor teste: teste.aprovafacil.com/cgi­bin/APFW/<usuario>/DEB
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
11.4. DEB – Parâmetros de Requisição
Nome
Descrição
Formatação
caracteres Exemplo
Obrigatório
NumeroDocumento
Identificação da venda pela Até 50 loja.
alfanuméricos.
ValorDocumento
Valor da transação
Numérico, sendo as casas decimais separadas por 123.56
ponto (.)
Sim
NumeroBanco
Identifica o Banco
3 digitos
Sim
CodigoAgencia
Código da agência da conta Somente dígitos de 0 a 9, P 12707
corrente a ser debitada
ou X
Sim
ContaCorrente
Número da conta corrente a Somente dígitos de 0 a 9, P 56749
ser debitada
ou X
Sim
TitularContaCorrente
Nome do titular da conta Até 40 caracteres
corrente a ser debitada
CNPJCPFSacado
CPF ou CNPJ do Sacado
11 digitos se CPF
14 digitos se CNPJ
123ABC
001
Sim
Cliente da Loja Sim
11111111111
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
Sim
37
Nome
Descrição
Formatação
DataNascimentoSaca Data de nascimento do aaaammdd
sacado
do
Exemplo
20071027
Obrigatório
Não
Agendamento
Apenas um caracter: I – Utilizado para incluir ou Incluir/ E – Excluir/ A ­ I
excluir um agendamento
Atualizar
Não
DiaParaAgendar
Dia de cada mês em que dd
será feito o débito
09
Se Agendamento=I
QuantidadeMesesPar Quantidade de meses para 2 dígitos inteiros
aAgendar
agendar
08
Se Agendamento=I
NumeroTentativasN Número de tentativas para 2 dígitos inteiros
aoAprovado
a transação ser aprovada
04
Se Agendamento=I
QuantidadeDiasEntr Quantidade de dias entre 2 dígitos inteiros
eTentativas
cada tentativa
03
Se Agendamento=I
20080820
Não
DataVencimento
Data para qual o débito deve ser programado. Esta data deve ser maior ou aaaammdd
igual ao prazo mínimo permitido para o convênio em cada Banco.
Nota: O parâmetro NumeroDocumento não pode ter valores repetidos.
Nota: Cada banco possui um formato diferente para as propriedades CodigoAgencia e ContaCorrente. Entre em contato conosco para saber como serão preenchidas.
11.5. Exemplo de Requisição
Visualize o trecho de código abaixo:
<form action= https://www.aprovafacil.com/cgi­bin/APFW/<usuario>/DEB method=post>
<input type=text name=NumeroDocumento value="123ABC">
<input type=text name=ValorDocumento value="123.56">
<input type=text name= NumeroBanco value=”001”>
<input type=text name=CodigoAgencia value="12707">
<input type=text name=ContaCorrente value="56749">
<input type=text name=TitularContaCorrente value="Cliente da Loja">
<input type=text name=CNPJCPFSacado value="11111111111">
<input type=submit value="Enviar">
</form>
Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
38
11.6. Exemplo de Resultados
11.6.1. Dados Corretos
<Resposta><Transacao>
XXXXXXXXXX
</Transacao></Resposta>
Onde: XXXXXXXXXX é um número único gerado para identificar a transação. 11.6.2. Dados Incorretos
<Resposta><Erro> YYYYYYYYYY</Erro></Resposta>
Onde: YYYYYYYYYY é a descrição do erro.
11.6.3. Exemplos de resposta
<Resposta><Transacao>73127890046539</Transacao></Resposta>
<Resposta><Erro>Conta Corrente Inválida</Erro></Resposta>
<Resposta><Erro>Banco não Suportado</Erro></Resposta>
<Resposta><Erro>Agência Inválida</Erro></Resposta>
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
39
12. Diagrama de Funcionamento
Aprova Fácil – Integração via WebService – Versão 1.2.10.1.21
http://www.cobrebem.com
40