API de integração passiva Original Gabster

Aspectos gerais

Os parágrafos seguintes descrevem, de maneira rápida, o que é uma API de integração, como funciona nossa API e o que é necessário para integrar um sistema terceiro com a Gabster.

Como funciona?

A API Gabster é um conjunto de métodos que proporcionam a representação estruturada de diversas informações de fábricas, lojas, orçamentos, pedidos, usuários, entre outros, para que estas sejam utilizadas por softwares ou serviços terceiros.

Isto significa que um número significante de dados constantes em nossa plataforma pode ser utilizada, conforme aceitação e liberação dos nossos clientes, em outras plataformas e sistemas de modo a integrar totalmente a criação, negociação e produção do móvel.

Esta é a forma mais segura e rápida de integrar totalmente os dados de uma fábrica ou marcenaria.

Mas o que é uma API?

API é um conjunto de rotinas programadas para proporcionar o acesso a informações de maneira simples e precisa. Nós, aqui na Gabster, utilizamos o que é chamado de API RESTful, que é uma abstração estruturada dos dados. Isto significa que qualquer sistema ou serviço terceiro pode, a partir de um pequeno desenvolvimento, integrar facilmente sua aplicação.

Isto proporciona inúmeras vantagens a nossos clientes. A principal é integrar suas informações de acordo com seus objetivos estratégicos. Imagine todas as informações de sua fábrica ou loja disponíveis em tempo real para auxiliar sua tomada de decisão.

Como faço para integrar um sistema com a Gabster?

Em primeiro lugar, é necessário entender alguns pontos importantes da integração:

A Gabster fornece a sua API e o acesso a todos os dados disponíveis por ela, desde que com a aceitação por parte do nosso cliente. A integração destes dados com outros sistemas fica a cargo da negociação do cliente com a empresa fornecedora do software terceiro.

Ao aceitar o Termos de Concessão de Dados, o cliente definirá quais dados serão disponibilizados ao software terceiro e receberá uma chave de integração única. Esta chave deverá ser fornecida ao desenvolvedor do software terceiro para que ele possa fazer as requisições para nossa API.

A Gabster fornece a documentação completa para que o desenvolvedor do software terceiro possa utilizar nossa API, porém não fornece suporte ao desenvolvimento da integração. Toda a responsabilidade técnica da integração é do desenvolvedor do software terceiro.

Qual o endereço para acessar?

A API segue um padrão para ser acessada, a url base para a listagem dos itens pode ser acessada no seguinte formato https://api.gabster.com.br/integracao/api/v2/{modelo}/

Enquanto para acessar somente as informações de um item, o formato é https://api.gabster.com.br/integracao/api/v2/{modelo}/{id}/

Por exemplo, para acessar a lista com informação de todos acabamentos, a url a ser acessada é https://api.gabster.com.br/integracao/api/v2/acabamento/

Enquanto para acessar somente as informações de acabamento Carvalho, cujo id é 1234, a url é https://api.gabster.com.br/integracao/api/v2/acabamento/1234/

Estrutura de informação

A API de Integração Passiva V2 da Gabster estrutura todos os dados de retorno em formato JSON. Além disso, a estrutura de dados obedece um padrão lógico de lista > detalhe, conforme o demonstrado abaixo:

Formato de retorno de lista

O modelo abaixo representa a lista de pedidos de uma fábrica:

Copyhtml{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 4
    },
    "objects": [
        {
            "cd_projeto": 123456,
            "cd_usuario_cadastro": 1234,
            "cd_usuario_modificacao": 1234,
            "datahora_cadastro": "2018-06-14T00:00:00",
            "datahora_cancelamento": null,
            "datahora_importacao": null,
            "datahora_liberacao": null,
            "datahora_modificacao": "2018-06-14T00:00:00",
            "descricao": "Lorem Ipsum Dolor Sit Amet",
            "id": 1234567,
            "identificador_arquivo_skp": "",
            "nome_arquivo_skp": "",
            "valor": 99.50
        },
        {
            "cd_projeto": 654321,
            "cd_usuario_cadastro": 4321,
            "cd_usuario_modificacao": 4321,
            "datahora_cadastro": "2018-06-14T12:00:00",
            "datahora_cancelamento": null,
            "datahora_importacao": null,
            "datahora_liberacao": null,
            "datahora_modificacao": "2018-06-14T12:00:00",
            "descricao": "Lorem Ipsum Dolor Sit Amet",
            "id": 7564321,
            "identificador_arquivo_skp": "",
            "nome_arquivo_skp": "",
            "valor": 50.99
        }
    ]
}

Formato de retorno de detalhe

O modelo abaixo representa o detalhe de um pedido de uma fábrica:

Copyhtml{
    "cd_projeto": 123456,
    "cd_usuario_cadastro": 1234,
    "cd_usuario_modificacao": 1234,
    "datahora_cadastro": "2018-06-14T12:00:00",
    "datahora_cancelamento": null,
    "datahora_importacao": null,
    "datahora_liberacao": null,
    "datahora_modificacao": "2018-06-14T12:00:00",
    "descricao": "Lorem Ipsum Dolor Sit Amet",
    "id": 7654321,
    "identificador_arquivo_skp": "",
    "nome_arquivo_skp": "",
    "valor": 49.99
}

O exemplo acima demonstra a estrutura detalhada de um registro. O detalhe da estrutura refere-se a cada item listado no exemplo anterior. Ou seja, na listagem de pedidos, recebemos os valores disponíveis para detalhamente e, neste exemplo, detalhamos um dos seus itens através de um requisição para /integracao/api/v2/pedido/99836/?format=json.

Métodos

A a API de Integração Passiva V2 aceita os métodos HTTP GET, POST e PUT. Este métodos estão disponíveis individualmente nos objetos. Verifique a documentação do objeto para saber quais métodos ele suporta.

Autenticação e segurança

A API de Integração Passiva V2 utiliza autenticação baseada em API Key. Desta maneira, o escopo de segurança limita-se às restrições da cada chave de usuário. Por exemplo, um usuário com acesso apenas a pedidos, terá uma chave que acessará apenas aos seus pedidos.

Desta forma é possível criar múltiplas chaves para usuários diferentes dentro do mesmo escopo de fábrica e loja, com permissões diferentes.

Enviando cabeçalhos de autenticação

Toda requisição, necessariamente, deve informar qual seu escopo para determinar suas restrições. Esta informação está representada em um usuário e sua API Key, como no exemplo abaixo:

Copyhtml{
  "Authorization:ApiKey":"usuarioteste@gabster.com.br:b7a0ade77ac34a62fd4c221533741becd69c602338"
}

Esta informação deverá ser informada no cabeçalho da requisição.

Tratando o retorno

Como qualquer API Restful, a API de Integração Passiva V2 da Gabster segue o padrão de Status HTTP para definir o tipo de retorno de suas requisições. A documentação completa e a descrição destes códigos podem ser encontradas na documentação do w3c.

Objetos

Pedidos de fábrica

Representa a estrutura de pedidos enviados para fabricação. Aqui são exibidos tanto os pedidos aptos a produzir quanto os já em produção/produzidos.

Listagem /integracao/api/v2/pedido_fabrica/?offset=0&limit=20&format=json
Apresenta a lista com os pedidos de fábrica

Detalhe: /integracao/api/v2/pedido_fabrica/[codigo]/?format=json
Apresenta os detalhes para apenas um pedido de fábrica, identificado pelo [codigo]

Métodos GET e POST

Itens do Pedido de Fábrica

Listagem /integracao/api/v2/pedido_fabrica_item/?offset=0&limit=20&format=json
Apresenta a lista com os itens do pedidos de fábrica

Detalhe: /integracao/api/v2/pedido_fabrica_item/[codigo]/?format=json
Apresenta os detalhes para apenas um item do pedido de fábrica, identificado pelo [codigo]

Métodos GET e POST

Itens do Pedido de Fábrica com Guid

Listagem /integracao/api/v2/pedido_fabrica_item_guid/?offset=0&limit=20&format=json
Apresenta a lista com os itens do pedidos de fábrica com Guid do componente 3D

Detalhe: /integracao/api/v2/pedido_fabrica_item_guid/[codigo]/?format=json
Apresenta os detalhes para apenas um item do pedido de fábrica, identificado pelo [codigo]

Métodos GET e POST

Pedido de Cliente

Listagem /integracao/api/v2/pedido_cliente/?offset=0&limit=20&format=json
Apresenta a lista com os pedidos de cliente

Detalhe: /integracao/api/v2/pedido_cliente/[codigo]/?format=json
Apresenta os detalhes para apenas um pedido de cliente, identificado pelo [codigo]

Métodos GET e POST

Itens do Pedido de Cliente

Listagem /integracao/api/v2/pedido_cliente_item/?offset=0&limit=20&format=json
Apresenta a lista com os itens do pedidos de cliente

Detalhe: /integracao/api/v2/pedido_cliente_item/[codigo]/?format=json
Apresenta os detalhes para apenas um item do pedido de cliente, identificado pelo [codigo]

Métodos GET e POST

Orcamento de Cliente

Listagem /integracao/api/v2/orcamento_cliente/?offset=0&limit=20&format=json
Apresenta a lista com os orçamento de cliente em ordem decrescente

Detalhe: /integracao/api/v2/orcamento_cliente/[codigo]/?format=json
Apresenta os detalhes para apenas um orçamento de cliente, identificado pelo [codigo]

Métodos GET e POST

Orcamento de Matéria Prima

Detalhe: /integracao/api/v2/materia_prima_orcamento/[codigo]/?format=json
Apresenta os orçamentos de matérias prima , identificado pelo [codigo] do projeto

Métodos GET

Orçamento de Componente

(Plugin versão mínima 3.8.0.5)

Listagem /integracao/api/v2/orcamento_componente/?offset=0&limit=20&format=json
Apresenta a lista com os orçamento dos componentes

Detalhe: /integracao/api/v2/orcamento_componente/[codigo]/?format=json
Apresenta os orçamentos dos componentes , identificado pelo [codigo] do orçamento componente

Filtro: /integracao/api/v2/orcamento_componente/?format=json&cd_orcamento_cliente=[código orçamento cliente]
Apresenta os orçamentos dos componentes , filtrados pelo [codigo] do orçamento cliente

Métodos GET

Itens do Orçamento de Cliente

Listagem /integracao/api/v2/orcamento_cliente_item/?offset=0&limit=20&format=json
Apresenta a lista com os itens do orçamento de cliente

Detalhe: /integracao/api/v2/orcamento_cliente_item/[codigo]/?format=json
Apresenta os detalhes para apenas um item do orçamento de cliente, identificado pelo [codigo]

Métodos GET e POST

Materia Prima

Listagem /integracao/api/v2/materia_prima/?offset=0&limit=20&format=json
Apresenta a lista com as matérias primas

Detalhe: /integracao/api/v2/materia_prima/[codigo]/?format=json
Apresenta os detalhes para apenas uma matérias prima, identificado pelo [codigo]

Métodos GET, POST e PUT

Componente

Listagem /integracao/api/v2/componente/?offset=0&limit=20&format=json
Apresenta a lista com os componentes

Detalhe: /integracao/api/v2/componente/[codigo]/?format=json
Apresenta os detalhes para apenas um componente, identificado pelo [codigo]

Métodos GET, POST e PUT

Acabamento

Listagem /integracao/api/v2/acabamento/?offset=0&limit=20&format=json
Apresenta a lista com os acabamentos

Detalhe: /integracao/api/v2/acabamento/[codigo]/?format=json
Apresenta os detalhes para apenas um acabamento, identificado pelo [codigo]

Métodos GET, POST e PUT

Produto

Listagem /integracao/api/v2/produto/?offset=0&limit=20&format=json
Apresenta a lista com os produtos

Detalhe: /integracao/api/v2/produto/[codigo]/?format=json
Apresenta os detalhes para apenas um item do produto, identificado pelo [codigo]

Métodos GET, POST e PUT

Projeto

Listagem /integracao/api/v2/projeto/?offset=0&limit=20&format=json
Apresenta a lista com os projetos

Detalhe: /integracao/api/v2/projeto/[codigo]/?format=json
Apresenta os detalhes para apenas um projeto, identificado pelo [codigo]

Métodos GET, POST e PUT

Materia Prima Custo

Listagem /integracao/api/v2/materia_prima_custo/?offset=0&limit=20&format=json
Apresenta a lista com os custos de matéria prima

Métodos GET

Detalhe: /integracao/api/v2/materia_prima_custo/[codigo]/?format=json
Apresenta os detalhes para apenas um custos de matéria prima, identificado pelo [codigo]

Métodos GET e POST

Materia Prima Calculo

Listagem /integracao/api/v2/materia_prima_calculo/?offset=0&limit=20&format=json
Apresenta a lista com os cálculos de matéria prima

Detalhe: /integracao/api/v2/materia_prima_calculo/[codigo]/?format=json
Apresenta os detalhes para apenas um cálculo de matéria prima, identificado pelo [codigo]

Métodos GET e POST

Materia Prima Preco

Listagem /integracao/api/v2/materia_prima_preco/?offset=0&limit=20&format=json
Apresenta a lista com os preços de matéria prima

Detalhe: /integracao/api/v2/materia_prima_preco/[codigo]/?format=json
Apresenta os detalhes para apenas um preço de matéria prima, identificado pelo [codigo]

Métodos GET, POST e PUT

Cliente

Listagem /integracao/api/v2/cliente/?offset=0&limit=20&format=json
Apresenta a lista com os clientes

Detalhe: /integracao/api/v2/cliente/[codigo]/?format=json
Apresenta os detalhes para apenas um cliente, identificado pelo [codigo]

Métodos GET, POST e PUT

Unidade

Listagem /integracao/api/v2/unidade/?offset=0&limit=20&format=json
Apresenta a lista com as unidades

Detalhe: /integracao/api/v2/unidade/[codigo]/?format=json
Apresenta os detalhes para apenas uma unidade, identificado pelo [codigo]

Métodos GET

Grupo de cálculo de matéria prima

Listagem /integracao/api/v2/materia_prima_calculo_grupo/?offset=0&limit=20&format=json
Apresenta a lista com os grupos de cálculo de matéria prima

Detalhe: /integracao/api/v2/materia_prima_calculo_grupo/[codigo]/?format=json
Apresenta os detalhes para apenas uma grupo de cálculo de matéria prima, identificado pelo [codigo]

Métodos GET

Subgrupo de acabamento

Listagem /integracao/api/v2/acabamento_subgrupo/?offset=0&limit=20&format=json
Apresenta a lista com os subgrupos de acabamento

Detalhe: /integracao/api/v2/acabamento_subgrupo/[codigo]/?format=json
Apresenta os detalhes para apenas uma subgrupo de acabamento, identificado pelo [codigo]

Métodos GET

Dados de Acesso

Preparamos um ambiente de testes controlado para que seja possível homologar a integração. Para tanto, este ambiente possui um projeto previamente cadastrado, orçado e enviado pra produção. Também estamos anexando aqui o arquivo .skp (Sketchup) com o objetivo de facilitar a verificação dos dados que estão sendo disponibilizados.

Para integrar a API, utilize a seguinte chave de acesso:
homologador@viagabster.com.br:05cbec084f70b95de670f4621f15b8988b33c9d2

Para realizar o download do projeto clique aqui (código 73762)

Exemplos

• PHP
• Java
• Python

Copyphp<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,
    'https://api.gabster.com.br/integracao/api/v2/orcamento_cliente/?format=json');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json; charset=UTF-8',
    'Authorization: ApiKey homologador@viagabster.com.br:05cbec084f70b95de670f4621f15b8988b33c9d2'
));

$output = curl_exec($ch);

curl_close($ch);

?>

Copyjavaimport java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.IOException;

import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.HttpResponse;
import org.apache.http.impl.client.HttpClientBuilder;

public class Call {

    public static void main(String[] args) {

        String response = get_API("https://api.gabster.com.br/integracao/api/v2/orcamento_cliente/?format=json");
        System.out.println(response);
    }

    private static String get_API(String path) {

        String apiKey = "ApiKey homologador@viagabster.com.br:05cbec084f70b95de670f4621f15b8988b33c9d2";
        StringBuffer response_s = new StringBuffer();

        try {

            HttpClient httpclient = HttpClientBuilder.create().build();
            HttpGet request = new HttpGet(path);
            request.addHeader("Authorization", apiKey);
            HttpResponse response = httpclient.execute(request);

            System.out.println("Response Code : " + response.getStatusLine().getStatusCode());

            BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));

            String line;
            while ((line = rd.readLine()) != null) {
                response_s.append(line);
            }
        }

        catch (IOException e) {
            System.out.println(e.getMessage());
        }

        return response_s.toString();
    }
}

Copypythonimport requests

url = 'https://api.gabster.com.br/integracao/api/v2/orcamento_cliente/?format=json'

headers = {'Content-Type': 'application/json', 'charset':'UTF-8',
'Authorization': 'ApiKey homologador@viagabster.com.br:05cbec084f70b95de670f4621f15b8988b33c9d2'}

r = requests.get(url, headers=headers)