Recarga REST

Visão Geral

A coleta dos dados será realizada pela Loja Virtual, que capturará as informações de recarga e os dados do cartão (em caso de recarga com pagamento) ou apenas as informações de recarga (para realizar apenas uma recarga).

E para saber mais sobre essas nomenclaturas (Bin, Software Express, Carat, e-Sitef) Saiba mais

Comunicação

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do Carat:

URL base de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef

URL base de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio esitef-ec.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao Carat.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o Carat poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxo de recarga sem pagamento

O fluxo de recarga sem pagamento pode ser realizado conforme o exemplo da figura acima.

O desenvolvedor deve seguir o que foi especificado no documento de integração do Carat e enviar os parâmetros:

• De acordo com o tamanho e tipo (numérico ou alfanumérico);
• Se o campo é obrigatório, condicional ou opcional.

De forma resumida, segue abaixo o fluxo transacional para Recarga. Com isso, algumas dúvidas devem ser esclarecidas, agilizando o processo de integração com o Carat.

• 1. O fluxo se inicia com a aplicação da loja realizando uma chamada para iniciar recarga;
  • 1.1. De modo síncrono, o Carat fará um POST HTTPS na URL de autenticidade informada pelo lojista e cadastrada no backoffice do Carat. O POST enviado conterá o NIT necessário para prosseguir com a recarga;
  • 1.2. A resposta da loja ao POST HTTPS obrigatoriamente deve ser "200 OK";
  • 1.3. A resposta do Carat à chamada para iniciar recarga será um código indicando sucesso (valor 0) ou fracasso (valor diferente de 0);
• 2. A loja então deve fazer uma chamada para listar concessionárias passando o NIT recebido anteriormente;
  • 2.1. O Carat retorna uma lista contendo os dados das concessionárias1;
• 3. A loja então deve fazer uma chamada para listar dados da filial passando o código da concessionária escolhida, o DDD desejado e o NIT;
  • 3.1. O Carat retorna os dados da filial, incluindo valores possíveis de recarga, períodos de validade, valores de bônus, dentre outros;
• 4. A loja deve então fazer uma chamada para efetuar recarga passando o NIT, o código da concessionária escolhida, o telefone, o DDD e o valor selecionado;
  • 4.1. O Carat inicia a recarga com a operadora escolhida e retorna os dados da recarga pendente de confirmação;
• 5. A loja deve impreterivelmente fazer uma chamada para confirmar recarga passando o NIT e um campo indicando se a recarga pendente deve ser confirmada ou desfeita na operadora;
  • 5.1. O Carat retorna uma resposta indicando o resultado da confirmação ou desfazimento da recarga;

Fluxo de recarga com pagamento

O fluxo de recarga com ou sem pagamento são iguais, com adendo de que o fluxo com pagamento exige que sejam enviados os dados do pagamento na chamada de efetuar recarga.