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:
curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&ddd=00&dealercode=1&generalhash=0000000000000000"
--verbose
Resposta:
{
"list_branch_data_response":{
"status":"NOV",
"esitef":{
"message":"OK. Transaction successful.",
"code":"0"
},
"sitef":{
"code":"000"
},
"hashes":{
"general":"09A9681D09A9681D"
},
"questions":[
{
"id":"5",
"display":"Qual o nome do seu pai?",
"rule":"3",
"min":"5",
"max":"30",
"type":"i"
}
],
"general":[
{
"message":"MENSAGEM DE TESTE"
}
],
"categories":[
{
"code":"01",
"description":"RECARGA",
"amount_ranges":[
{
"message":"MSG_FAIXA_1",
"amount_key":"7",
"bonus_in_percentage":"100",
"bonus":"50",
"payment_amount":"700",
"bonus_category":"1",
"expiry_date":"30",
"bonus_expiry_date":"15",
"min_amount":"500",
"max_amount":"10000"
},
{
"message":"MSG_FAIXA_2",
"amount_key":"8",
"bonus_in_percentage":"500",
"bonus_category":"2",
"min_amount":"1000",
"max_amount":"50000"
}
],
"fixed_amounts":[
{
"bonus":"50",
"message":"MSG_FIXO_1",
"amount":"300",
"amount_key":"1",
"bonus_category":"2",
"bonus_in_percentage":"200",
"payment_amount":"10",
"expiry_date":"60",
"bonus_expiry_date":"15"
},
{
"message":"MSG_FIXO_2",
"amount":"1500",
"amount_key":"2",
"payment_amount":"30"
},
{
"message":"MSG_FIXO_3",
"amount":"2000",
"amount_key":"3"
},
{
"amount":"2200",
"amount_key":"4",
"expiry_date":"90"
},
{
"message":"MSG_FIXO_4",
"amount":"5000",
"amount_key":"6",
"expiry_date":"120"
}
]
},
{
"code":"02",
"description":"SMS",
"amount_ranges":[
],
"fixed_amounts":[
]
},
{
"code":"03",
"description":"PRIMEIRA_RECARGA",
"amount_ranges":[
],
"fixed_amounts":[
]
}
],
"payment_methods":{
"max":"4",
"available":[
"00",
"01",
"02:10",
"03:10",
"04:10",
"05:10",
"06:10"
]
}
}
}
Listagem de dados da filial de recarga tipo others
Requisição:
curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
"list_branch_data_request":{
"general_hash":"0000000000000000",
"dealer":{
"code":"901",
"type_code":"03",
"branch":{
"code":"98006000000"
}
}
}
}
--verbose
Resposta:
{
"list_branch_data_response":{
"status":"NOV",
"esitef":{
"message":"OK. Transaction successful.",
"code":"0"
},
"sitef":{
"code":"000"
},
"hashes":{
"general":"09A9681D09A9681D"
},
"questions":[
],
"general":[
],
"categories":[
{
"amount_ranges":[
],
"fixed_amounts":[
{
"amount":"50"
},
{
"amount":"300"
},
{
"amount":"400"
},
{
"amount":"500"
},
{
"amount":"600"
},
{
"amount":"700"
},
{
"amount":"800"
},
{
"amount":"900"
},
{
"amount":"1000"
}
]
}
],
"payment_methods":{
"max":"4",
"available":[
"00",
"01",
"02:10",
"03:10",
"04:10",
"05:10",
"06:10"
]
}
}
}
Listagem de dados da filial de recarga tipo invoice
Requisição:
curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
"list_branch_data_request":{
"dealer":{
"code":"800",
"branch":{
"code":"80019000000"
}
},
"answers": [
{
"code":"126",
"description": "12340000000"
}
]
}
}
Resposta:
{
"list_branch_data_response": {
"status": "NOV",
"esitef": {
"message": "OK. Transaction successful.",
"code": "0"
},
"sitef": {
"message": "Transacao Aprovada",
"code": "000"
},
"host": {
"message": "Vivo SP Pos",
"code": "00"
},
"acquirer": {
"merchant_code": "302800000000000"
},
"authorization": {
"authorizer_date": "0831",
"authorizer_time": "153738",
"host_usn": "000310003",
"sitef_usn": "310003",
"number": "000000"
},
"hashes": {
"general": ""
},
"questions": [],
"payment_methods": {
"max": "4",
"available": [
"00",
"01",
"02:03-07-08-09-10-14",
"03:03-07-08-09-10-14",
"04:10",
"05:10",
"06:10"
]
},
"general": [],
"categories": [
{
"amount_ranges": [],
"fixed_amounts": []
}
],
"invoices": [
{
"expiry_date": "21082007 ",
"consumption_reference": "082007 ",
"bar_code": "84600000000633900800011200241676508075070821 ",
"amount": "6339 ",
"message": "Boleto Parcial Credito Manual "
},
{
"expiry_date": "25072007 ",
"consumption_reference": "072007 ",
"bar_code": "84660000001866000800011200243533509074070925 ",
"amount": "18660 ",
"message": "Boleto Parcial Credito Manual "
},
{
"expiry_date": "25092007 ",
"consumption_reference": "092007 ",
"bar_code": "84650000000442500800011000217664609076070925 ",
"amount": "4425 ",
"message": "Boleto Parcial Credito Manual "
},
{
"expiry_date": "10092007 ",
"consumption_reference": "082007 ",
"bar_code": "84610000001385700800011200474416708073070910 ",
"amount": "13857 ",
"message": "Boleto Parcial Credito Manual "
},
{
"expiry_date": "25082007 ",
"consumption_reference": "082007 ",
"bar_code": "84650000001165200800011200243533508078070825 ",
"amount": "11652 ",
"message": "Boleto Parcial Credito Manual "
},
{
"expiry_date": "21092007 ",
"consumption_reference": "092007 ",
"bar_code": "84690000019276900800011200245374209078070921 ",
"amount": "192769 ",
"message": "Boleto Parcial Credito Manual "
}
],
"tv_package_subscription_codes": [],
"invoice_holder_name": "",
"echo": "12340000000"
}
}
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 e-SiTef | = 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 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 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 e-SiTef. 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 e-SiTef. 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 e-SiTef. 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 e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do e-SiTef. | < 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 e-SiTef 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.