Serviço de criação de recarga

import ApiDoc from '../../src/components/api-doc/ApiDoc';

POST de autenticidade x assinatura

O Carat possui duas formas de autenticação da loja na interface de recarga REST: POST de autenticidade ou assinatura.

No método de POST de autenticidade, o Carat enviará os dados da transação de recarga recém-criada para a URL de autenticidade cadastrada da loja.

No método de assinatura, a loja deve ter uma chave pública de criptografia RSA cadastrada no Carat e deverá montar uma assinatura JWT (JSON Web Tokens) a ser enviada no cabeçalho Authorization. Neste caso, as informações da transação de recarga serão retornadas diretamente na resposta do serviço. Saiba mais.

Detalhes da chamada

Recurso: /v3/recharge
Método HTTP: POST
Formato da requisição: JSON
Formato da resposta: JSON
Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
`Content-Type`	Deve ser enviado com o valor `application/json`.	= 15 AN	SIM
`Authorization`	Deve ser enviada a assinatura de autenticação da loja no formato `Bearer {assinatura}`. Exemplo: `Bearer {SEU_TOKEN_AQUI}`.	< 2000 AN	NÃO

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de recarga utilizando a ferramenta cURL.

Criação de recarga com envio de todos os parâmetros

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request POST "https://{{url}}/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX",
      "merchant_usn":"2398",
      "order_id":"023748",
      "general_hash":"0000000000000000",
      "recharge_type":"normal"
   }
}
--verbose

Resposta:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      }
   }
}

POST de autenticidade:

curl -X POST \
  https://dominiodaloja.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d 'merchantUSN=987654321&merchantId=LOJAFATURAT&orderId=123456789&nit=e009886843920c5173104557c9f6cd66b1481557fb3f4d88daca072eb8a50c97&generalHash=85E791AD85E791AD'

Criação de recarga com envio mínimo de parâmetros

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request POST "https://{{url}}/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX"
   }
}
--verbose

Resposta:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      }
   }
}

Criação de recarga com envio de assinatura

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request POST "https://{{url}}/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--header "Authorization: Bearer {TOKEN_JWT_EXAMPLE}"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX",
      "merchant_usn":"1446681016",
      "order_id":"13014858663",
      "general_hash":"0000000000000000"
   }
}
--verbose

Resposta:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "nit": "jhadafsafhjhasdfghiyuw43u8785345jksjknsmnnsjkfkiu34u98ynksnn3535",
      "merchant_id": "XXXXXXXX",
      "order_id": "13014858663",
      "merchant_usn": "1446681016",
      "general_hash": "AF32810AAF32810A"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de recarga:

Parâmetro	Descrição	Formato	Obrigatório
`merchant_key`	Chave da loja cadastrada no Carat	< 80 A	SIM
`merchant_usn`	Número sequencial único gerado pela loja	< 12 N	NÃO
`order_id`	Código de identificação do pedido gerado pela loja	< 20 AN	NÃO
`general_hash`	Código de identificação da versão da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).<br/><br/>Caso a loja não tenha feito uma recarga anteriormente ou não tenha guardado um valor de `general_hash` previamente recebido do Carat, o valor: `0000000000000000` pode ser passado ao Carat.<br/><br/>Este campo permite ao lojista saber se ocorreu alteração nos dados da recarga. Isso porque se ocorreu alguma alteração na tabela, o `general_hash` retornado será diferente do `general_hash` que o lojista possui. Neste caso, é aconselhável que o lojista efetue as consultas e atualize os valores das operadoras de recarga em sua aplicação.	= 16 A	NÃO
`recharge_type`	Tipo da recarga a ser realizada.<br/><br/>Valores: `normal` – Recarga de celulares `others` – Recarga para outros tipos de produtos, como PIN de jogos, doações, seguros ou até mesmo recarga de celular por outras modalidades. `invoice` – Pagamento de fatura por assinatura Valor padrão: `normal`	= 6 A	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de recarga:

Parâmetro	Descrição	Formato
`nit`	Identificação da transação de recarga no Carat	= 64 AN
`merchant_id`	Código de identificação da loja no Carat	< 15 AN
`order_id`	Código de identificação do pedido gerado pela loja	< 20 AN
`merchant_usn`	Número sequencial único gerado pela loja	< 12 N
`general_hash`	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN
esitef	Elemento que descreve a resposta do Carat.
`code`	Código de resposta do Carat. Qualquer código diferente de `0`(zero) significa falha. Saiba mais.	< 4 N
`message`	Mensagem de resposta do Carat.	< 500 AN

Parâmetros enviados pelo post de autenticidade

Na tabela abaixo está a descrição dos parâmetros enviados pelo Carat no POST de autenticidade:

Parâmetro	Descrição	Formato
`nit`	Identificação da transação de recarga no Carat.Este é o campo relevante para prosseguimento do processo de efetuar recarga.	= 64 AN
`merchantId`	Código de identificação da loja no Carat	< 15 AN
`orderId`	Código de identificação do pedido gerado pela loja	< 20 AN
`merchantUSN`	Número sequencial único gerado pela loja	< 12 N
`generalHash`	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN

O Carat também pode enviar novos parâmetros sem aviso prévio, o que significa que a aplicação do lojista deve estar preparada para receber campos extras e simplesmente ignorá-los.

Parâmetros enviados pelo Carat no POST HTTPS

Importante:

O Carat utiliza o tipo de mídia x-www-form-urlencoded, para envio do POST HTTPS. Sendo assim, o servidor tem que aceitar este tipo de mídia na URL que for cadastrada para recebimento do POST HTTPS.

Parâmetro	Descrição	Formato
`nit`	Identificação da transação de recarga no Carat	= 64 AN
`merchantId`	Código de identificação da loja no Carat	< 15 AN
`orderId`	Código de identificação do pedido gerado pela loja	< 20 AN
`merchantUSN`	Número sequencial único gerado pela loja	< 12 N
`generalHash`	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN