Serviço de listagem de dados da filial
Detalhes da chamada para recarga tipo normal#
- Recurso:
/v3/rechargebranches - Método HTTP:
GET - Formato da requisição:
query string - Formato da resposta:
JSON
Detalhes da chamada para recarga tipo others#
- Recurso:
/v3/rechargebranches/{nit} - Método HTTP:
PUT - Formato da requisição:
JSON - Formato da resposta:
JSON
Detalhes da chamada para recarga tipo invoice#
- Recurso:
/v3/rechargebranches/{nit} - Método HTTP:
PUT - 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 | Assinatura de autenticidade no formato Bearer {assinatura}. Saiba mais.Exemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34.Este campo é obrigatório caso a transação tenha sido criada pelo processo de assinatura. | < 2000 AN | COND. |
Exemplos#
Abaixo estão exemplos de chamada do serviço de listagem de dados da filial utilizando a ferramenta cURL.
Listagem de dados da filial de recarga tipo normal#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Listagem de dados da filial de recarga tipo others#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Listagem de dados da filial de recarga tipo invoice#
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 para recarga tipo normal#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de listagem de dados da filial para recarga tipo normal:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
nit | Identificação da transação de recarga no Carat | = 64 AN | SIM |
ddd | Código DDD do telefone | = 2 N | SIM |
dealercode | Código da concessionária/operadora | < 3 N | SIM |
generalhash | 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 generalhash 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 generalhash retornado será diferente do generalhash 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 AN | NÃO |
Parâmetros de requisição para recarga tipo others#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de listagem de dados da filial para recarga tipo others:
| Parâmetro | Descrição | Formato | Obrigatório | |||
|---|---|---|---|---|---|---|
nit | Identificação da transação de recarga no Carat. Atenção: Este campo vai na URL da requisição e não no corpo. | = 64 AN | SIM | |||
ddd | Código DDD do telefone | = 2 N | NÃO | |||
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 | NÃO | |||
| dealer | Informações da concessionária/operadora. Estas informações são retornadas na chamada de listagem de concessionárias. | |||||
code | Código da concessionária/operadora | < 3 N | SIM | |||
type_code | Código do tipo da concessionária/operadora | < 3 N | SIM | |||
| dealer.branch | Informações sobre a filial da concessionária | |||||
code | Código da filial da concessionária/operadora | < 11 N | SIM | |||
| answers[] | Este campo agrega uma lista de respostas. Envio obrigatório caso perguntas tenham sido recebidas na listagem de concessionárias. | |||||
code | Código da pergunta a ser respondida (questions.id da resposta da listagem de concessionárias) | < 20 AN | COND. | |||
description | Resposta da pergunta | < 200 AN | COND. | |||
Parâmetros de requisição para recarga tipo invoice#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de listagem de dados da filial para recarga tipo invoice:
| Parâmetro | Descrição | Formato | Obrigatório | |||
|---|---|---|---|---|---|---|
nit | Identificação da transação de recarga no Carat. Atenção: Este campo vai na URL da requisição e não no corpo. | = 64 AN | SIM | |||
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 | NÃO | |||
| dealer | Informações da concessionária/operadora. Estas informações são retornadas na chamada de listagem de concessionárias. | |||||
code | Código da concessionária/operadora | < 3 N | SIM | |||
| dealer.branch | Informações sobre a filial da concessionária | |||||
code | Código da filial da concessionária/operadora | < 11 N | SIM | |||
| answers[] | Este campo agrega uma lista de respostas. Envio obrigatório caso perguntas tenham sido recebidas na listagem de concessionárias. | |||||
code | Código da pergunta a ser respondida (questions.id da resposta da listagem de concessionárias) | < 20 AN | COND. | |||
description | Resposta da pergunta | < 200 AN | COND. | |||
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 listagem de dados da filial:
| Parâmetro | Descrição | Formato |
|---|---|---|
status | Status da transação de recarga no Carat. Saiba mais. | = 3 AN |
invoice_holder_name | Nome do titular da fatura | < 70 AN |
echo | Campo a ser reenviado para recargas do tipo invoice | < 128 AN |
resubmit_transaction | Indica que esta transação deve ser reenviada com o código de assinatura de TV selecionada. | < 5 AN |
| esitef | ||
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 |
| sitef | ||
code | Código de resposta retornado pela autorizadora | < 4 AN |
| hashes | ||
general | 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 |
| questions[] | Este campo agrega uma lista de perguntas para confirmação positiva. As perguntas retornadas devem, obrigatoriamente, ser respondidas pelo usuário e ter suas respostas enviadas ao Carat no passo seguinte (listar dados da filial). | |
id | Código de identificação da pergunta | < 20 AN |
display | Texto da pergunta a ser apresentada | < 180 AN |
rule | Indica onde os dados devem ser coletados. Saiba mais. | < 2 AN |
min | Indica o tamanho mínimo da resposta | < 4 N |
max | Indica o tamanho máximo da resposta | < 5 N |
type | Indica o tipo de dados da resposta a ser coletada. Saiba mais. | < 3 AN |
min_value | Indica o valor mínimo da resposta | < 3 N |
max_value | Indica o valor máximo da resposta | < 3 N |
| general | Este campo agrega uma lista de características gerais dentre as filiais. | |
message | Mensagem geral. | < 101 AN |
| categories | Este campo agrega uma lista de categorias. | |
code | Código da categoria | < 5 AN |
description | Texto descritivo da categoria | < 100 AN |
| categories.amount_ranges | Este campo agrega uma lista de faixas de valores. | |
message | Mensagem informativa da recarga | < 100 AN |
amount_key | Chave do valor da recarga (a ser enviada ao efetuar recarga). | < 5 AN |
bonus_in_percentage | Bônus de recarga em percentual do valor de face (com 2 casas decimais: ex.: 1% = 100). | < 5 N |
bonus | Bônus de recarga. | < 12 N |
payment_amount | Custo da recarga. | < 12 N |
bonus_category | Categoria do bônus (deve ser um dos valores de categories.code). | < 5 AN |
expiry_date | Período de validade (em dias). | < 4 N |
bonus_expiry_date | Período de validade do bônus (em dias). | < 4 N |
min_amount | Valor mínimo da faixa, em centavos de real. | < 12 N |
max_amount | Valor máximo da faixa, em centavos de real. | < 12 N |
| categories.fixed_amounts | Este campo agrega uma lista de valores fixos. | |
message | Mensagem informativa da recarga | < 100 AN |
amount_key | Chave do valor da recarga (a ser enviada ao efetuar recarga). | < 5 AN |
bonus_in_percentage | Bônus de recarga em percentual do valor de face (com 2 casas decimais: ex.: 1% = 100). | < 5 N |
bonus | Bônus de recarga. | < 12 N |
payment_amount | Custo da recarga. | < 12 N |
bonus_category | Categoria do bônus (deve ser um dos valores de categories.code). | < 5 AN |
expiry_date | Período de validade (em dias). | < 4 N |
bonus_expiry_date | Período de validade do bônus (em dias). | < 4 N |
amount | Valor de face da recarga, em centavos de real. | < 12 N |
| payment_methods | ||
max | Número máximo de formas de pagamento | < 2 N |
available | Este campo agrega uma lista de formas de pagamento disponíveis e seus detalhes. Saiba mais. | < 200 AN |
| host | ||
message | Nome da instituição | < 16 AN |
code | Código de resposta da instituição | < 12 AN |
| acquirer | ||
merchant_code | Código do estabelecimento | < 15 N |
| authorization | ||
number | Número autorização | < 6 AN |
sitef_usn | Nsu do Sitef | < 6 N |
host_usn | Nsu do host | < 12 N |
authorizer_time | Hora da resposta do autorizador HHMMSS | = 6 N |
authorizer_date | Data da resposta do autorizador MMDD | = 4 N |
| invoices | Este objeto contém campos retornados para pagamento sem fatura (recarga tipo invoice). | |
expiry_date | Data de vencimento da fatura escolhida em formato AAAAMMDD | = 8 N |
consumption_reference | Data de referência na fatura escolhida em formato MMAAAA | = 6 N |
bar_code | Código de barras da fatura escolhida | = 48 N |
amount | Valor da fatura escolhida | < 12 N |
message | Mensagem geral | < 64 AN |
Retorno do campo payment_methods.available#
O campo payment_methods.available pode conter um ou mais dados para leitura. Cada dado lido possui o seguinte formato:
TipoN:IDColetaN1-IDColetaN2-IDColetaN3-...-IDColetaNn
Onde:
TipoN: indica a forma de pagamento permitida.
| Tipo | Descrição |
|---|---|
00 | Dinheiro |
01 | Cheque |
02 | TEF Débito |
03 | TEF Crédito |
10 | Ticket Eletrônico |
11 | Ticket Papel |
12 | Carteira Digital |
13 | PIX |
50 | TEF Cartão |
99 | Outras Formas |
Observações:
- Caso não existam campos a serem coletados, será retornado apenas o campo
TipoN. - Futuramente, novas formas de pagamento podem ser acrescentadas a esta tabela. Caso o PDV desconheça uma destas novas formas, deve estar preparado para "pular" apenas esta forma, sem afetar seu processamento.
- A forma de pagamento "TEF Cartão" (tipo
50) é utilizada para agrupar, em um único tipo, todas as formas de pagamento que envolva cartões (tipos02e03).
IDColetaNn: indica o ID do campo que o PDV deve coletar e enviar ao SiTef.
| ID | Descrição | Significado e Formato |
|---|---|---|
01 | Tipo de Entrada do Cheque | 0: leitura de CMC-71: digitação da primeira linha do cheque2: digitação do CMC-7 |
02 | Dados do Cheque | - CMC-7 lido ou digitado, ou - digitação da primeira linha do cheque, com o seguinte formato: Compensação (3), Banco (3), Agência (4), C1 (1), Conta Corrente (10), C2 (1), Número do Cheque (6) e C3 (1), nesta ordem. |
03 | Rede Destino | Identificação do autorizador da transação de TEF (conforme tabela de Rede Destino da especificação do SiTef). |
04 | NSU do SiTef da transação de TEF | Identificação da transação de TEF no SiTef. |
05 | Data do SiTef da transação de TEF (No momento, ainda não utilizado) | Data da transação de TEF no SiTef, no formato DDMMAAAA. |
06 | Código da Empresa da transação de TEF | Código do SiTef para a Empresa utilizada na transação de TEF. |
07 | NSU do Host da transação de TEF | Identificação da transação de TEF no Host. |
08 | Data do Host da transação de TEF | Data da transação de TEF no Host, no formato DDMMAAAA. |
09 | Código de Origem da transação de TEF | Código de Estabelecimento da transação de TEF. |
10 | Dados de confirmação da transação de TEF. | Campo 9 retornado na realização da transação de TEF. |
11 | Código de Autorização da transação de TEF | Código de Autorização do Host para a transação de TEF. |
12 | Valor do Cheque | Valor Total do Cheque. Um mesmo cheque pode ser usado para pagar mais de uma conta. |
13 | Rede Destino – Complemento | Complemento do ID 03 |
14 | Bandeira do Cartão | Bandeira do cartão utilizado na transação de TEF. |
15 | Tipo Pagamento | 00 – a vista01 – Pré-datado02 – Parcelado pelo estabelecimento03 - Parcelado pela administradora |
Observações:
O campo de ID 13, diferente dos demais, não indica um campo que deve ser coletado. Este campo funciona apenas como um complemento ao campo de ID 03, enviando a lista de redes destino permitido, no seguinte formato:
13(Rede1,Rede2,...,RedeN)
Ou seja, caso apenas o campo de ID 03 esteja presente, deve ser coletada a rede destino, sem nenhuma restrição quanto às redes que podem pagar uma determinada transação (Exemplo: recarga). No entanto, caso estejam presentes os campos de ID 03 e 13, o primeiro indica que deve ser coletada a rede destino, enquanto o segundo indica quais as redes destino são permitidas para efetuar o pagamento da recarga.
Além disso, como a coleta foi indicada pelo ID 03, o PDV deve enviar a rede destino ao SiTef também por meio deste ID (e não pelo ID 13).
Futuramente, novos campos podem ser acrescentados a esta tabela. Caso o PDV desconheça um destes novos campos, deve estar preparado para "pular" apenas este campo, sem afetar seu processamento.