Serviço de criação de recarga
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 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:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
POST de autenticidade:
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
esitef-homologacao.softwareexpress.com.br
Resposta:
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
esitef-homologacao.softwareexpress.com.br
Resposta:
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). 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.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 | = 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 |