Serviço de criação de recarga

POST de autenticidade x assinatura

O e-SiTef 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 e-SiTef 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 e-SiTef 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 JHVGytfdgauygdauiw78264284527852897hagdg`.	< 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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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"
      }
   }
}

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

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc"
--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 e-SiTef	< 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). Caso a loja não tenha feito uma recarga anteriormente ou não tenha guardado um valor de `general_hash` previamente recebido do e-SiTef, o valor: `0000000000000000` pode ser passado ao e-SiTef. 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. 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 e-SiTef	= 64 AN
`merchant_id`	Código de identificação da loja no e-SiTef	< 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 e-SiTef.
`code`	Código de resposta do e-SiTef. Qualquer código diferente de `0`(zero) significa falha. Saiba mais.	< 4 N
`message`	Mensagem de resposta do e-SiTef.	< 500 AN

Parâmetros enviados pelo e-SiTef no POST HTTPS

Importante:

O e-SiTef 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 e-SiTef	= 64 AN
`merchantId`	Código de identificação da loja no e-SiTef	< 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