Processo de Autorização para uso dos Serviços da API
A autorização para realizar chamadas à API segue o protocolo OAuth2. Ao cadastrar um estabelecimento, o Desenvolvedor da Automação terá acesso às devidas credenciais para utilizar a API. Essas credenciais consistem de um site_id e um site_secret correspondentes ao estabelecimento. Como passo inicial para começar a utilizar os recursos da API Omnichannel, a Automação deve informar esses dois parâmetros ao endpoint /auth-token da API para obter tokens de autorização. Feito esse passo, a Automação deve informar esses tokens em todas as chamadas aos serviços da API.
[Geração do site_secret da loja]#
A Automação pode obter o site_secret de uma loja de duas maneiras distintas: pessoalmente pelo canal de atendimento ou "programaticamente" pela API.
Ao iniciar o processo de integração, o Cliente ou o Desenvolvedor podem solicitar ao nosso time de suporte essas credenciais. Caberá ao Desenvolvedor fornecer uma forma para o Cliente instalar essas credenciais na Automação de maneira segura.
Caso o Cliente possua uma assinatura digital da cadeia ICP-Brasil, a Automação pode, em tempo de execução, utilizar a API Omnichannel para geração e download das credenciais. Esta aseção descreve o endpoint para esse propósito. A cada chamada ao endpoint, um novo site_secret e gerado e o anterior perde a validade.
O site_secret equivale a uma senha associada a cada site_id e serve o propósito de autenticação para obtenção do auth-token. Ou seja, ele permite ao aplicativo realizar transações com o Omni API em nome do site_id. Por isso ele deve ser armazenado de forma segura no aplicativo.
Recomendamos também que a automação renove o site_secret periodicamente. Caso utilize este endpoint, é possível, por exemplo, renovar o site_secret diariamente.
Detalhes da chamada#
Os detalhes desta operação ainda estão em discussão (os parâmetros podem sofrer alterações).
Recurso: /v1/site_secret
Método HTTP: [POST]
Content-Type: application/json;charset=UTF-8
Parâmetros do corpo:
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| certificate_chain | Arquivo da cadeia de certificados para validação da assinatura. Deve obrigatoriamente conter o Certificado ICP (chave pública assinada pela CA) correspondente ao CNPJ da loja associada ao site_id informado. Recomendamos que contenha também os certificados intermediários da CA que assinaram o certificado da loja. O formato deve ser uma string PEM com a sequência “\n” no lugar das quebras de linha. | String | ||
| jwt | O conteúdo deste parâmetro deve ser um JSON Web Token (JWT) codificado, ou seja, uma String no formato: <Header codificado em Base64Url>.<Payload codificado em Base64Url>.<Assinatura de (Header + "." + Payload) codificado em Base64Url> Seguir as especificações do Header e Payload informados na tabela do conteúdo do jwt abaixo. | String |
| Conteúdo jwt | ||||
|---|---|---|---|---|
| Header | ||||
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
| alg | Valor RS256 | String | SIM | |
| typ | Valor JWT | String | SIM | |
| Payload | ||||
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
| iss | Conteúdo integral e inalterado do campo Common Name do certificado ICP (Normalmente está no formato “Nome Empresarial:CNPJ) | String | SIM | |
| sub | Valor do site_id | String | SIM | |
| aud | Valor “omnichannel” | |||
| iat | Horário da criação deste JWT no formato NumericDate da RFC 7519 (número de segundos desde 1970-01-01T00:00:00Z UTC) | Number | SIM | |
| clientId | Valor do clientId | String | SIM | |
parâmetro extra do Gateway | Os parâmetros extras do Gateway são parâmetros adicionais de identificação da loja definidos pelo Gateway de Pagamento (isto é, cabe ao Gateway de Pagamento especificar e informar esses parâmetros para a Automação). O servidor Omni utilizará esses e os demais parâmetros do Payload para autenticar a loja junto ao Gateway de Pagamento. Os parâmetros extras serão repassados ao Gateway sem alteração. Por exemplo, se a Automação estiver integrando com o Gateway da Adquirente Bin, os parâmetros extras devem ser: "institutionNumber": [String], "serviceContractId": [String], "terminalId": [String], "merchantId": [String] | String | SIM |
Resposta#
- Content-Type: application/json;charset=UTF-8
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| site_secret | Token de autorização para acesso aos serviços da API | String |
Exemplo#
Conteúdo não codificado do JWT (apenas para ilustração para reprodução do exemplo, pois não é enviado nesse formato):
Requisição e Resposta
Token#
Antes de chamar qualquer serviço da API, a Automação deve primeiro gerar um token de autorização através do endpoint /auth-token. Cada token possui um tempo de validade, portanto a Automação também precisa gerar o token sempre que essa validade expirar.
Detalhes da chamada#
Recurso: /v1/auth-token
Método HTTP: POST
Content-Type: application/x-www-form-urlencoded
Parâmetros do corpo:
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| grant_type | Tipo de autorização (usar sempre o valor “client_credentials”) | AN | ?? | SIM |
| site_id | Identificação da loja pedindo recurso da API | AN | ?? | SIM |
| site_secret | Senha da loja | AN | ?? | SIM |
| client_id |
Resposta#
Content-Type: application/json;charset=UTF-8
Corpo:
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| access_token | Token de autorização para acesso aos serviços da API | AN | ?? | SIM |
| token_type | Tipo do token (sempre “Bearer”) | AN | ?? | SIM |
| expires_in | Tempo em segundos | N | ?? | SIM |
Exemplo#
Requisição e Resposta
Uso do token#
Nas demais chamada à API, a Automação deve incluir o token no campo "Authorization" do cabeçalho, no seguinte formato:
Authorization: Bearer valor de access_token
Caso a chamada resulte no erro HTTP 401, a Automação deve gerar um novo token.
Política de troca e envio de secret#
Boa prática requer que o site_secret deve ser trocado de tempos em tempos e a automação tem a responsabilidade de trocar o site_secret.
A área de segurança da Fiserv determina que o processo de passagem do site_secret deve ser feito de forma a atender as normas de segurança, não pode envolver envio em claro por e-mail ou por meios já considerados inseguros.