Admin Docs Documentation

Transcrição

1 Admin Docs Documentation Versão FrontEnd Team 08/11/2016

2

3 Sumário 1 Visão Geral 3 2 Braspag Auth Introdução Obtenção de Autorização Tipos de Permissão (Grant Types) Tipos de Escopo Validação de Token Admin API Gerenciamento de Estabelecimento Comercial (EC) Tutoriais Autenticação Direta a partir de sites parceiros i

4 ii

5 Tópicos: Sumário 1

6 2 Sumário

7 CAPÍTULO 1 Visão Geral As APIs REST fornecidas pelo Admin 3.x permitem executar, de forma programática, tarefas administrativas que, até então, eram executadas somente pela interface de usuário. Algumas destas tarefas são listadas abaixo: Cadastro de Estabelecimentos Comerciais WebService/Checkout Acesso aos dados de lojas do Pagador (em breve) Cadastro de Usuários (em breve) Admin API é o conjunto de serviços que implementam as funcionalidades de negócio descritas acima. Braspag Auth é o serviço de autorização necessário para garantir a segurança no consumo da Admin API, através da criação e validação de tokens de acesso com escopo e duração limitados. Tokens de acesso precisam ser obtidos para garantir acesso as APIs de negócio e também para utilização de recursos de Single Sign-On entre aplicativos e sites dentro do domínio Braspag / Cielo. 3

8 4 Capítulo 1. Visão Geral

9 CAPÍTULO 2 Braspag Auth Por Daniel Braga e Ricardo Abdalla 2.1 Introdução Braspag Auth é o Serviço de Autorização da Braspag, implementado de acordo com as especificações do protocolo OAuth2. O objetivo deste serviço é prover fluxos de autorização específicos para aplicações web, aplicações desktop, dispositivos móveis, entre outros. A especificação do OAuth2 é definida pelo RFC Nota: A versão 1.0 do Braspag Auth ainda não implementa os fluxos Authorization Code e Implicit especificados no OAuth Obtenção de Autorização Para obter autorização de acesso aos recursos protegidos pelo Braspag Auth, é preciso informar na requisição HTTP o tipo de permissão desejada, além das credenciais de cliente. O servidor de autorização disponibiliza credenciais para seus clientes registrados. As credenciais de cliente são compostas por duas informações, ClientId e ClientSecret, únicas para cada cliente. Uma vez obtidos, ClientId e ClientSecret devem ser enviados como uma string única, codificada no formato Base64, no cabeçalho Authorization da requisição HTTP, conforme descrito abaixo: Authorization: Basic czzcagrsa3f0mzo3rmpmcdbaqnixs3reumjuzlzkbul O processo de codificação em Base64 deve ser realizado sobre o texto formatado de acordo com o seguinte padrão: [ClientId]:[ClientSecret] Aviso: ClientId e ClientSecret são informações sensíveis que compõem uma credencial única por cliente, não devendo, portanto, serem fornecidas a terceiros. 5

10 2.3 Tipos de Permissão (Grant Types) Client Credentials No fluxo de permissão Client Credentials, o cliente requisita um token de acesso para um recurso protegido usando apenas as suas credenciais. Um escopo de validade para o token de acesso deve ser informado. Se as credenciais forem válidas, o token de acesso é emitido e o cliente pode então utilizá-lo para acessar o recurso protegido (por exemplo, alguma das APIs Braspag). Fluxo Client Credentials: Formato da requisição POST: POST HTTP/1.1 Connection: keep-alive Authorization: Basic NTY3N0M5RUItNERDUpkaXF4VWZLUmhEN1BBUTVuYUZubFBJclg4SWVDc0hlamM= Content-Type: application/x-www-form-urlencoded Accept: */* Accept-Encoding: gzip, deflate Accept-Language: pt,en-us;q=0.8,en;q=0.6 grant_type=client_credentials&scope=[escopo] Formato da resposta: HTTP/ OK Content-Type: application/json; charset=utf-8 Connection: close { "access_token":"99997e6d97fe4a99933dd7b1b88dee3f", 6 Capítulo 2. Braspag Auth

11 "token_type":"bearer", "expires_in":3600, "scope":"[escopo]" } Resource Owner Password Credentials No fluxo de permissão Resource Owner Password Credentials, além das credenciais do cliente (ClientId e ClientSecret), também são informados as credenciais de um usuário (nome de usuário e senha), que são trocadas por um token de acesso e um token de atualização (refresh_token). O acesso realizado com o uso do token será feito em nome do usuário cujas credenciais foram previamente informadas. Por que a senha do proprietário do recurso é exposta à aplicação, este fluxo deve ser utilizado apenas em situações onde há um grande grau de confiança entre a aplicação e o provedor da API de autorização. Em outras palavras, seu uso deve ser restrito apenas à aplicações no domínio Braspag. Fluxo Resource Owner Password Credentials: Formato da requisição POST: POST HTTP/1.1 Connection: keep-alive Authorization: Basic NTY3N0M5RUItNERDUpkaXF4VWZLUmhEN1BBUTVuYUZubFBJclg4SWVDc0hlamM= Content-Type: application/x-www-form-urlencoded Accept: */* Accept-Encoding: gzip, deflate Accept-Language: pt,en-us;q=0.8,en;q=0.6 grant_type=password&username=[usuario]&password=[senha]&scope=[escopo] Formato da resposta: 2.3. Tipos de Permissão (Grant Types) 7

12 HTTP/ OK Content-Type: application/json; charset=utf-8 Connection: close { "access_token":"99997e6d97fe4a99933dd7b1b88dee3f", "token_type":"bearer", "expires_in":3600, "refresh_token":" d dd7b1b88d8888", "scope":"[escopo]" } 2.4 Tipos de Escopo Os escopos definem o contexto de validade de um token de acesso. Escopos são case-sensitive e devem ser informados exatamente como escritos abaixo. Escopo Descrição AdminCielo Single Sign-On de clientes do site Cielo para Admin AdminV2 Single Sign-On para Admin versão 2.x AdminV3 Single Sign-On para Admin versão 3.x AdminApiEc API para gerenciamento de ECs Cielo AdminReportApi API de relatórios do Admin 2.5 Validação de Token Para aplicativos que precisam validar se um determinado token de acesso existe, não está expirado e possui o escopo adequado, Braspag Auth oferece a operação Validate. A operação deve ser chamada através de uma requisição GET, informando {token_a_ser_validado} como parâmetro na URL. A requisição deve possuir ainda {token_de_acesso_valido} no cabeçalho Authorization, conforme exemplificado abaixo: Formato da requisição GET: GET HTTP/1.1 Connection: keep-alive Authorization: Bearer {token_de_acesso_valido} Content-Type: application/x-www-form-urlencoded Accept: */* Accept-Encoding: gzip, deflate Accept-Language: pt,en-us;q=0.8,en;q=0.6 Formato da resposta: HTTP/ OK Content-Type: application/json; charset=utf-8 Connection: close { "isvalid":true, "expires_in":" t21:27:29", "grant_type":"client_credentials", "scope":"[escopo]" } 8 Capítulo 2. Braspag Auth

13 Nota: Tokens gerados a partir do fluxo Resource Owner Password Credentials também retornam o atributo username, contendo o nome do usuário associado, se forem válidos Validação de Token 9

14 10 Capítulo 2. Braspag Auth

15 CAPÍTULO 3 Admin API Por Diogo Marins e Ricardo Abdalla 3.1 Gerenciamento de Estabelecimento Comercial (EC) A API REST para gerenciamento de Estabelecimento Comercial (EC) oferece operações para criação (POST) e atualização (PUT) de ECs Cielo. As chamadas para a API devem ser precedidas de uma chamada inicial para Braspag Auth com o intuíto de obter um token de acesso. Chamadas para a API realizadas sem um token de acesso ou com um token de acesso expirado retornarão o código HTTP 401 Unauthorized. Um token de acesso pode e deve ser reutilizado para múltiplas chamadas à API, desde que estejam dentro do seu período de validade. Os passos a serem efetuados são descritos a seguir: 1. Obtenha junto à Braspag uma credencial de acesso (ClientId e ClientSecret); 2. Com a credencial obtida, obtenha um token de acesso realizando uma chamada para Braspag Auth informando o tipo de permissão client_credentials e o escopo AdminApiEc; 3. Utilize o token de acesso obtido para efetuar chamadas para as operações de criação ou atualização de EC; Criação de EC Cria um EC Cielo (WebService 3, Checkout Completo ou Loja Virtual) no ambiente Braspag. Formato da requisição POST POST HTTP/1.1 Connection: keep-alive Authorization: Bearer 974bd09d b970cc8343cc9a Content-Type: application/json Accept: */* Accept-Encoding: gzip, deflate Accept-Language: pt,en-us;q=0.8,en;q=0.6 { } 11

16 Contrato JSON para criação de EC Nota: Os comentários no código abaixo são meramente explicativos e não devem ser enviados com o contrato. { } /* Dados gerais do EC, obrigatório */ "GeneralData": { " ": "string", /* Endereço de , máximo 60 caracteres */ "DocumentType": 0, /* 0 = Pessoa Jurídica, 1 = Pessoa Física */ "ContactName": "string", /* Nome do contato, máximo 60 caracteres */ "Phone": "string" /* Telefone do EC, formato '(99) ', máximo 16 caracteres */ }, /* Dados da Empresa, obrigatório apenas se Pessoa Jurídica */ "CompanyData": { "FancyName": "string", /* Nome Fantasia, máximo 128 caracteres */ "CorporateName": "string", /* Razão Social, máximo 128 caracteres */ "Cnpj": "string" /* Número do CNPJ, formato ' / ', máximo 16 caracteres */ }, /* Dados do Cliente, obrigatório apenas se Pessoa Física */ "PersonalData": { "FullName": "string", /* Nome completo, máximo 128 caracteres */ "Cpf": "string" /* Número do CPF, formato ' ', máximo 14 caracteres */ }, /* Endereço Comercial, obrigatório */ "BusinessAddress": { "ZipCode": "string", /* CEP, formato ' ', máximo 9 caracteres */ "Address": "string", /* Logradouro, máximo 100 caracteres */ "Number": "string", /* Número, máximo 5 caracteres */ "Complement": "string", /* Complemento, campo opcional, máximo 50 caracteres */ "District": "string", /* Bairro, máximo 32 caracteres */ "City": "string", /* Cidade, máximo 32 caracteres */ "State": "string" /* Estado/UF, máximo 4 caracteres */ }, /* Informações transacionais, obrigatório */ "TransactionalConfiguration": { "Ec": "string", /* Número do EC na Cielo, máximo 16 caracteres */ "ProductionKey": "string", /* Chave de Produção, máximo 64 caracteres */ "Mcc": "string", /* Código do MCC Cielo, máximo 4 caracteres */ "PaymentMethods": /* Array de meios de pagamento habilitados */ [ { "Name": "string", /* Valor válido para meio de pagamento, máximo 32 caracteres */ "MaxInstallments": "string" /* Número de parcelas (1 a 12) */ } ], "CvvRequired": true, /* Obrigatoriedade do código de segurança, formato: true/false */ "IntegrationType": 0 /* Tipo de integração do EC */ } Veja também: Valores válidos para meios de pagamento Veja também: Valores válidos para os tipos de integração 12 Capítulo 3. Admin API

17 Veja também: Códigos de Retorno HTTP Código HTTP Resultado 201 Created EC criado com sucesso 400 Bad Request Contrato inválido / Erro de validação 401 Unauthorized Cliente não autenticado 500 Internal Server Error Erro interno no servidor Atualização de EC Atualiza as informações de um EC Cielo (WebService 3, Checkout Completo ou Loja Virtual) no ambiente Braspag. Formato da requisição PUT PUT HTTP/1.1 Connection: keep-alive Authorization: Bearer 974bd09d b970cc8343cc9a Content-Type: application/json Accept: */* Accept-Encoding: gzip, deflate Accept-Language: pt,en-us;q=0.8,en;q=0.6 { } Contrato JSON para atualização de EC Nota: Os comentários no código abaixo são meramente explicativos e não devem ser enviados com o contrato. { /* Dados gerais do EC, obrigatório */ "GeneralData": { " ": "string", /* Endereço de , máximo 60 caracteres */ "DocumentType": 0, /* 0 = Pessoa Jurídica, 1 = Pessoa Física */ "ContactName": "string", /* Nome do contato, máximo 60 caracteres */ "Phone": "string", /* Telefone do EC, formato '(99) ', máximo 16 caracteres */ "IsBlocked": true /* Indica se EC está bloqueado para transações, formato: true/false */ }, /* Dados da Empresa, obrigatório apenas se Pessoa Jurídica */ "CompanyData": { "FancyName": "string", /* Nome Fantasia, máximo 128 caracteres */ "CorporateName": "string", /* Razão Social, máximo 128 caracteres */ "Cnpj": "string" /* Número do CNPJ, formato ' / ', máximo 16 caracteres */ }, /* Dados do Cliente, obrigatório apenas se Pessoa Física */ "PersonalData": { "FullName": "string", /* Nome completo, máximo 128 caracteres */ "Cpf": "string" /* Número do CPF, formato ' ', máximo 14 caracteres */ }, /* Endereço Comercial, obrigatório */ 3.1. Gerenciamento de Estabelecimento Comercial (EC) 13

18 } "BusinessAddress": { "ZipCode": "string", /* CEP, formato ' ', máximo 9 caracteres */ "Address": "string", /* Logradouro, máximo 100 caracteres */ "Number": "string", /* Número, máximo 5 caracteres */ "Complement": "string", /* Complemento, campo opcional, máximo 50 caracteres */ "District": "string", /* Bairro, máximo 32 caracteres */ "City": "string", /* Cidade, máximo 32 caracteres */ "State": "string" /* Estado/UF, máximo 4 caracteres */ }, /* Informações transacionais, obrigatório */ "TransactionalConfiguration": { "ProductionKey": "string", /* Chave de Produção, máximo 64 caracteres */ "Mcc": "string", /* Código do MCC Cielo, máximo 4 caracteres */ "PaymentMethods": /* Array de meios de pagamento habilitados */ [ { "Name": "string", /* Valor válido para meio de pagamento, máximo 32 caracteres */ "MaxInstallments": "string" /* Número de parcelas (1 a 12) */ } ], "CvvRequired": true, /* Obrigatoriedade do código de segurança, formato: true/false */ "IntegrationType": 0 /* Tipo de integração do EC */ } Veja também: Valores válidos para meios de pagamento Veja também: Valores válidos para os tipos de integração Veja também: Códigos de Retorno HTTP Código HTTP Resultado 200 OK EC atualizado com sucesso 400 Bad Request Contrato inválido / Erro de validação 401 Unauthorized Cliente não autenticado 500 Internal Server Error Erro interno no servidor Valores válidos para os tipos de integração Código IntegrationType 2 Checkout Simplificado 3 Checkout Completo 5 Loja Virtual Completa 6 Webservice Checkout Simplificado e WebService Checkout Completo e WebService Loja Virtual Completa e WebService Capítulo 3. Admin API

19 3.1.4 Valores válidos para meios de pagamento Valor Literal BoletoBradesco BoletoBancoDoBrasil OnlineDebitBancoDoBrasil OnlineDebitBradesco DebitCardVisa DebitCardMaster CreditCardVisa CreditCardMaster CreditCardJcb CreditCardDiscover CreditCardAmex CreditCardElo CreditCardDiners CreditCardAura Meio de Pagamento Boleto Bradesco Boleto Banco do Brasil Transferência Eletrônica Banco do Brasil Transferência Eletrônica Bradesco Visa Electron Mastercard Maestro Cartão de Crédito Visa Cartão de Crédito Mastercard Cartão de Crédito JCB Cartão de Crédito Discover Cartão de Crédito American Express Cartão de Crédito ELO Cartão de Crédito Diners Cartão de Crédito Aura 3.1. Gerenciamento de Estabelecimento Comercial (EC) 15

20 16 Capítulo 3. Admin API

21 CAPÍTULO 4 Tutoriais 4.1 Autenticação Direta a partir de sites parceiros O recurso de Autenticação Direta permite com que usuários autenticados em sites parceiros acessem links no Admin Braspag sem experimentar um novo processo de autenticação. Nota: Para que a Autenticação Direta funcione corretamente, os usuários do site parceiro precisam estar previamente habilitados no Admin Braspag. Fluxo de Autenticação Direta: Passo a passo para implementação: 1. Após a autenticação do usuário no site parceiro, efetue uma chamada para requisição de token de acesso ao serviço Braspag Auth. Informe as credenciais de acesso do cliente (ClientId e ClientSecret) no cabeçalho Authorization, as credenciais de acesso do usuário autenticado e o escopo para o qual o usuário será redirecionado; 17

22 POST HTTP/1.1 Connection: keep-alive Authorization: Basic NTY3N0M5RUItNERDUpkaXF4VWZLUmhEN1BBUTVuYUZubFBJclg4SWVDc0hlamM= Content-Type: application/x-www-form-urlencoded Accept: */* Accept-Encoding: gzip, deflate Accept-Language: pt,en-us;q=0.8,en;q=0.6 grant_type=password&username=[usuario]&password=[senha]&scope=[escopo] 2. Efetue uma requisição POST para o endereço de autenticação direta do Admin Braspag informando o token de acesso (access_token) retornado no passo 1; POST HTTP/1.1 Connection: keep-alive Cache-Control: max-age=0 Content-Type: application/x-www-form-urlencoded Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8 Accept-Encoding: gzip, deflate Accept-Language: pt,en-us;q=0.8,en;q=0.6 AccessToken=[access_token] 3. Se as credenciais do usuário informadas na geração do token forem válidas para o escopo, uma resposta de redirecionamento será retornada com um cookie de autenticação válido para a sessão recém iniciada; HTTP/ Found Cache-Control: no-cache, no-store, must-revalidate Pragma: no-cache Content-Type: text/html; charset=utf-8 Expires: -1 Location: / Set-Cookie:.ASPXAUTH=50309C5D71CACFB18A8A0FD6EE409BBC; path=/; secure; HttpOnly Strict-Transport-Security: max-age= <html><head><title>object moved</title></head><body> <h2>object moved to <a href="/">here</a>.</h2> </body></html> Veja também: Tabela de Escopos disponíveis 18 Capítulo 4. Tutoriais