API: exemplos de código

Todos os exemplos simulam a mesma integração: o sistema de uma loja consulta os produtos, os clientes e os últimos pedidos da empresa. Rodando com GRAVAR=1, ele também cadastra um cliente de exemplo e lança um pedido para ele com o primeiro produto do catálogo.

Antes de rodar, siga o guia de integração para contratar o módulo API e criar o usuário da integração.

Pela API REST

Os três arquivos fazem a mesma coisa e não instalam nada: usam só o que já vem na linguagem.

Linguagem	Arquivo	Como rodar
Python 3	exemplo.py	`python3 exemplo.py`
Node 18 ou mais novo	exemplo.mjs	`node exemplo.mjs`
Go	exemplo.go	`go run exemplo.go`

Informe o endereço e o usuário da integração antes de rodar:

export API_BASE="https://o endereço que você usa para acessar o sistema"
export API_USUARIO="[email protected]"
export API_SENHA="a senha do usuário da integração"
python3 exemplo.py

Com um aplicativo autorizado, troque usuário e senha por API_TOKEN (o token da autorização) e API_ORG (a empresa). API_ORG também serve para escolher a empresa quando o usuário tem acesso a mais de uma.

O miolo do exemplo em Python mostra as chamadas que importam:

# Entra com o usuário da integração e guarda o token e a empresa
login = chama("POST", "/api/users/login", {"username": usuario, "password": senha})
cabecalhos["Token"] = login["token"]
cabecalhos["Org"] = login["currentOrg"]["id"]

# Listagens vão por POST: o filtro não cabe no endereço
produtos = chama("POST", "/api/produtos/list", {"pageSize": 5})["produtoList"]

# O pedido abre sem itens; cada item entra pela rota de produtos do pedido,
# que traz nome, unidade e preço do cadastro e calcula os totais
pedido = chama("POST", "/api/pedidos", {"pedido": {
    "tipo": "ped", "pessoa": {"id": cliente["id"], "nome": cliente["name"]}}})["pedido"]
chama("POST", f"/api/pedidos/{pedido['id']}/produtos",
      {"productId": produto["id"], "product": {"produtoId": produto["id"], "quantidade": 2}})

Pelos SDKs (gRPC)

Os SDKs trazem o cliente de cada serviço pronto e cuidam do login, da empresa e da renovação do token. O exemplo de cada um está no repositório dos SDKs.

O endereço do gRPC é o mesmo do sistema, na porta 443:

export API_ENDERECO="app.suaempresa.com.br:443"
export API_USUARIO="[email protected]"
export API_SENHA="a senha do usuário da integração"

Go

git clone https://github.com/linksoft-dev/sdks.git
cd sdks/go
go run ./exemplos/cliente

No seu programa:

cliente, err := sdk.Dial(os.Getenv("API_ENDERECO"))
if err != nil {
  log.Fatal(err)
}
defer cliente.Close()

if _, err := cliente.Login(ctx, usuario, senha, ""); err != nil {
  log.Fatal(err)
}

produtos := produto.NewProdutoServiceClient(cliente.Conn())
resposta, err := produtos.List(ctx, &produto.ListProdutoRequest{PageSize: 5})

Python

pip install "git+https://github.com/linksoft-dev/sdks.git#subdirectory=python"
git clone https://github.com/linksoft-dev/sdks.git
python sdks/python/exemplos/cliente.py

No seu programa:

from linksoft_sdk import Client
from linksoft_sdk.pb.apps.estoque.produto import produto_pb2, produto_pb2_grpc

with Client(os.environ["API_ENDERECO"]) as cliente:
    cliente.login(usuario, senha)
    produtos = produto_pb2_grpc.ProdutoServiceStub(cliente.channel)
    resposta = produtos.List(produto_pb2.ListProdutoRequest(page_size=5))

O que observar em todos

Listagem é POST. As rotas terminadas em /list recebem os filtros no corpo, porque eles não cabem no endereço. Continuam sendo consulta: um aplicativo autorizado apenas a consultar consegue chamá-las.

Itens do pedido entram um a um. Incluir o item pela rota de produtos do pedido (no gRPC, o método AddProduct) é o que faz o sistema buscar o preço do cadastro e somar os totais — como acontece na tela.

Leia o corpo do erro. Quando uma chamada falha, a mensagem diz o que faltou, por exemplo “o acesso por API exige o módulo API contratado para esta empresa”. O código HTTP sozinho quase nunca basta.

Os nomes dos campos seguem o cadastro. Alguns são em português (nome, quantidade, valorUnitario) e outros em inglês (name, cpfCnpj), acompanhando o cadastro de origem. A referência da API mostra o nome exato de cada um.