01
Introdução
02
Base URL
03
Autenticação
04
Registro de monitoramento
Comando Get Info
05
Consulta de terminais
06
Possíveis erros
07
Referências
A API Monitoria TEF House visa receber dados das TEF Houses para realização de monitoria de informações relacionadas a rollouts de novas implementações, além de atualizações de versões de host e terminais utilizados pelo PDV.
Em todas as chamadas descritas, é necessário informar o client_id (Identificador gerado quando o desenvolvedor cria uma aplicação no portal e que pode ser encontrado nas configurações da dashboard da aplicação) no header da requisição.
Esta API segue a arquitetura REST. No final desta documentação você encontra a seção de Referências com o Swagger desta API.
Homologação:
https://hml-api.elo.com.br/tef-house-monitoring/v1
Para ter acesso aos recursos desta API, será necessário possuir um access_token válido e informá-lo no header
das requisições, no padrão P Bearer Authentication
. O processo de autenticação da aplicação e obtenção do access_token se dá através do recurso POST /tef-houses/oauth/access-token, informando no header da requisição o client_id e o atributo Authorization.
O Authorization
pode ser obtido concatenando o texto "Basic " ao resultado da codificação em Base 64 dos campos client_id e client_secret concatenados com :.
Abaixo, um exemplo de pseudo-código para gerar o Authorization:
var authorization = "Basic " + base64(client_id + ":" + client_secret);
Exemplo do cabeçalho da requisição, com o Authorization já definido:
client_id: 000c0000-000b-0000-ba0c-fb0d0000b000
Authorization: Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkL
Exemplo do corpo da requisição:
{
"grant_type": "client_credentials"
}
Exemplo do corpo de resposta:
{
"access_token": "ZTFmOTY2ODktY2E4My0zMzVhLTg1OWQtN2VkYzRhOGZjMmI4OjI5OWZjMjVjLWFjNDEtM2ViMi1iNGM0LTk4ZjA4ZWI3OWNkYg==",
"token_type": "Bearer",
"expires_in": 600
}
O campo expires_in
é o valor em segundos, e deve ser respeitado. Portanto, a Elo define que o parceiro não requisite um novo access-token enquanto houver um válido.
Essa API é liberada para consumo através de uma whitelist de ips de acesso, é necessário que as TEF Houses forneçam seus ips de saída para o consumo desta API.
Para adicionar um registro para o monitoramento da TEF House, utilize o recurso POST para /tef-houses/me/terminals
Exemplo do conteúdo dos cabeçalhos da requisição:
client_id: "string"
authorization: Bearer access_token
Campos do conteúdo desta requisição:
pdvId: (String) Identificador do ponto de venda. Identificador que é enviado ao Adquirente.
merchantCNPJ: (string) CNPJ do estabelecimento comercial (OBS: O campo merchantCNPJ deverá ser enviado neste formato "99999999999999", sem caracteres especiais).
merchantName: (string) Razão social do estabelecimento comercial.
merchantCode: (integer) Código do estabelecimento comercial. Campo de 10 dígitos.
acquirerName: (string) Nome do credenciador. Campo do tipo ENUM, deve ser enviado em letras maiúsculas. Ex.: Cielo SA deve ser enviado como CIELO.
Valores possíveis:
(ACQIO, AGILLI, BANCOOB, BOLTCARD, BS2, CIELO, CLOUD_WALK, CRED_PERNAMBUCANAS_ELO, CREFISA, DINERS_SAQUE_TECBAN, DISCOVER, ELO, ELO_GATEWAY, ELO_SAQUE_HUB_TECBAN, ELO_SAQUE_TECBAN, FIRST_DATA, GETNET, GLOBAL_PAYMENTS, GRANITO, LISTO, PAGSEGURO, REDE, SAFRAPAY, SEAC_GATEWAY, SERGIPE_ADMINISTRADORA_DE_CARTOES, SICREDI, SMARTBANK, SOROCRED, STONE, SUMUP, TRIBANCO, VERO, VOXCRED).
terminalModel: (string) Modelo do terminal associado ao PDV (OBS: O campo terminalModel deverá ser enviado sem caracteres especiais). Este campo é obtido do comando GETINFO da BC.
terminalSerialNumber: (string) Identificador (número de série) do terminal associado ao PDV. Este campo é obtido do comando GETINFO da BC e deve ser transcrito conforme devolutiva do comando, mas sem os espaços à direita.
sharedLibraryVersion: (string) Versão da biblioteca compartilhada utilizada no terminal (OBS: Este campo deverá ser enviado usando ponto (.) como separador). Este campo é obtido do comando GETINFO da BC.
hostKernelByPassVersion: (string) Versão do kernel bypass para o host (OBS: Este campo deverá ser enviado usando ponto (.) como separador).
clientKernelByPassVersion: (string) Versão do kernel bypass para o client (OBS: Este campo deverá ser enviado usando ponto (.) como separador).
qrCodeSystemName: (string) Nome do sistema responsável pelo tratamento do QR Code.
qrCodeSystemVersion: (string) Versão do sistema responsável pelo tratamento do QR Code (OBS: Este campo deverá ser enviado usando ponto (.) como separador).
Exemplo do corpo da requsição:
{
"pdvId": "99999999",
"merchantCNPJ": "99999999999999",
"merchantName": "Loja exemplo",
"merchantCode": 9999999999,
"acquirerName": "CIELO",
"terminalModel": "PPC930",
"terminalSerialNumber": "7200051801000163",
"sharedLibraryVersion": "2.12",
"hostKernelByPassVersion": "8.0.7.28",
"clientKernelByPassVersion": "8.0.123.1.1",
"qrCodeSystemName": "Nomeaplicaçãotef",
"qrCodeSystemVersion": "7.0.7.30"
}
Como método de obtenção das informações do PINpad, (Terminal Model, Terminal Serial Number, Library version) sugerimos a utilização do comando Get Info padrão da Biblioteca Compartilhada para que todos os PINpad consigam responder ao comando independente da sua versão (BC ou ABECS).
Exemplo resultado: Chamada e resposta da execução do Comando Get Info.
SENT | RECEIVE |
---|---|
GIN00200 | GIN000100INGENICO LANE3000;232MB C11.16.08 PatchJ(b54 2.12002.11 210209 19291691301116973086 |
GIN00200 | GIN000100GERTEC PPC-930;192MB;U C1202.11607.VR9415 @2.12002.07.200106 7200051801000163 |
GIN00200 | GIN000100GERTEC PPC920;10MB;U C0066:0077:0060:0109@1.08001.13 160202 7101902011005627 |
Para realizar a consulta de terminais de uma determinada TEF house, utilize o recurso GET para /tef-houses/me/terminals
Exemplo do conteúdo dos cabeçalhos da requisição:
client_id: "string"
authorization: Bearer access_token
Exemplo de resposta:
[
{
"pdvId": "99999999",
"merchantCNPJ": "99999999999999",
"merchantName": "Loja do Zé",
"merchantCode": 9999999999,
"acquirerName": "CIELO",
"terminalModel": "PPC930",
"terminalSerialNumber": "7200051801000163",
"sharedLibraryVersion": "2.12",
"hostKernelByPassVersion": "8.0.7.28",
"clientKernelByPassVersion": "8.0.123.1.1",
"qrCodeSystemName": "Nomeaplicaçãotef",
"qrCodeSystemVersion": "7.0.7.30",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"creationDate": "2022-01-25T17:16:55.618Z"
}
]
Abaixo, você verá uma lista de possíveis erros e o que eles podem significar.
400 Bad Request - A solicitação feita para o servidor é incorreta.
401 Unauthorized - Erro de credenciais de autenticação inválidas para o recurso de destino.
403 Forbidden - O acesso ao recurso é proibido.
404 Not Found. - O servidor não pode encontrar o recurso solicitado.
412 Precondition Failed - O acesso ao recurso de destino foi negado.
422 Unprocessable Entity - A requisição feita ao servidor é correta, porém não foi possível processar as instruções contidas.
500 Internal error - Problemas internos no servidor.
502 Bad Gateway - Conexão com o servidor completamente inativa.