Home

Aramis S. H. Fernandes edited this page Apr 29, 2016 · 10 revisions

ATENÇÃO!

Esta documentação contempla apenas o uso da API do Sage One. Se você deseja obter informações sobre como utilizar o Sage One através do seu navegador, por favor assista este vídeo.

Como criar uma aplicação para conversar com a API do Sage One Brasil

É necessário ter uma conta no github e registrar ao menos uma aplicação junto à API do Sage One.

Uma vez atendidos estes requisitos, siga o procedimento abaixo:

  1. Acesse sua conta do github;

  2. Acesse a URL da API do Sage One;

    • É necessario que você aceite que developers.sageone.com acesse algumas informações da sua conta do github.
  3. Depois de permitir o acesso, o navegador redireciona para uma tela como esta: Passo 1

  4. Na área intitulada Registered Applications, clique no botão Register an app: Passo 2

  5. Aceite os termos de uso: Passo 3

  6. Repita o passo 4 (clicando em Register an app):

    Passo 2

  7. Preencha o formulário com informações referentes à aplicação a ser cadastrada: Passo 4

    • Favor notar o que campo Callback URL é de preenchimento obrigatório;
    • Este campo pode conter uma URL qualquer, desde que a mesma comece com https, pois também é obrigatório que a conexão HTTP seja criptografada. Se a aplicação sendo cadastrada possuir uma URL capaz de tratar o retorno, então esta URL poderá ser informada.
  8. Clique no botão Register Application;

  9. O navegador vai redirecionar para uma página que lista as aplicações disponíveis: Passo 5

  10. Todas as aplicações que estiverem sendo mostradas nesta página serão reconhecidas pela API do Sage One, e consequentemente conseguirão conversar com ela.

  11. Ao clicar sobre o nome de uma aplicação, uma página com informações detalhadas será carregada. Dentre essas informações destacam-se: client_id, client_secret e signing_secret, que são os dados que a aplicação deve informar à API afim de autenticar-se: Passo 6

ATENÇÃO: Esses dados são altamente sigilosos! Proteja-os da melhor maneira possível!


Permitindo que uma conta Sage One seja acessível pela aplicação recém cadastrada

Depois de ter registrado sua aplicação, agora é hora de configurar a conta Sage One para que a aplicação tenha as permissões necessárias para manipular seus dados.

O primeiro passo é gerar uma URL de autenticação para conectar a conta Sage One à aplicação. Para tanto, é necessário utilizar uma biblioteca de autenticação. Através desta biblioteca é possível gerar uma URL para a página de autorização, onde você poderá ver informações sobre a aplicação que está prestes a autorizar.

Primeiramente, é necessário configurar sua aplicação para que ela consiga se autenticar junto à API do Sage One. A documentação oficial da API pode ser encontrada em:

As seções mais relevantes são Authentication, Signing your requests, Making an API call e Code Samples, conforme pode ser observado na seguinte imagem:

Seções Relevantes

A Sage disponibiliza uma biblioteca de acesso escrita em ruby como exemplo de uso. Você pode usa-la se quiser. Basta acessar este link: https://github.com/Sage/sageone_api_ruby_sdk


A seguir, alguns exemplos de aplicações que conversam com a API do Sage One:

Ruby:

PHP:

Java:

C#:


Depois que sua aplicação estiver pronta, é necessário que ela forneça uma URL para habilitar uma conexão com o Sage One.

Por exemplo: https://app.br.sageone.com/oauth2/auth?client_id=aaxxxaagggaaa432eeee&redirect_uri=https%3A%2F%2Fdevs.s1.br%2Fcallback&response_type=code

Depois que sua aplicação gerar uma URL como esta, é necessário acessar a conta Sage One que será manipulada pela aplicação. Uma vez logado nesta conta Sage One, insira a URL na barra de endereços, e uma página semelhante a esta deverá aparecer na tela:

Passo 7

Conforme pode ser observado na imagem, é necessário que o usuário permita que a aplicação acesse sua conta Sage One.

Este passo é muito importante, pois garante que o cliente está ciente de que sua conta Sage One será acessada por uma aplicação devidamente registrada junto à API. É através deste procedimento que o cliente expressa seu consentimento com o acesso à sua conta por uma aplicação. Isso é um requisito fundamental para os padrões de segurança da Sage.

Ao permitir este acesso, a aplicação registrada em https://developers.sageone.com/ e autorizada através da URL citada acima, será capaz de manipular a conta Sage One associada, emitindo notas, cadastrando produtos, clientes, etc.

Assim que você clicar em Permitir, você será novamente redirecionado para uma URL, desta vez, uma URL que contém um código. Este código deverá ser informado à sua aplicação, ou ela mesma deverá ser capaz de tratá-lo, extraindo-o da URL. Note que esta URL inicia com a URL informada no momento do registro da aplicação. O código em questão é um dos parâmetros da URL:

https://devs.s1.br/callback?code=bfx0w00ebi3d2xa73ff0deb7c153buc3747b8143&country=BR

Em particular, a informação relevante é: code=bfx0w00ebi3d2xa73ff0deb7c153buc3747b8143

Basta extrair o valor da chave code, ou seja, bfx0w00ebi3d2xa73ff0deb7c153buc3747b8143, que é o código a ser informado à aplicação, para que ela possa finalmente comunicar-se com a API. Note que se a aplicação estiver em execução e aceitar conexões vindas de fora, basta que ela saiba tratar esta requisição:

https://devs.s1.br/callback?code=bfx0w00ebi3d2xa73ff0deb7c153buc3747b8143&country=BR

Para mais detalhes das operações suportadas atualmente pela API do Sage One Brasil, utilize as páginas ao lado.