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:

Copiarhttps://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"
}

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.