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="integracao@suaempresa.com.br"
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}})

Emitir NF-e ou NFC-e

A emissão aceita a nota inteira na chamada, sem cadastrá-la antes. Cada item aponta um produto do cadastro — pelo produtoId, pelo codigo, pelo codigoEan ou pelo nome exato em produtoNome —, e a tributação, os impostos e os totais saem do cadastro, como na tela:

curl -X POST "$API_BASE/api/nfe/emitir" \
  -H "Token: $TOKEN" -H "Org: $ORG" -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "venda-1234",
    "nota": {
      "naturezaOperacao": "VENDA",
      "pessoa": {"nome": "MARIA DA SILVA", "cpfCnpj": "11144477735", "endUf": "RN",
                 "endCidade": "MOSSORO", "endCidadeCod": "2408003", "endCep": "59600000",
                 "endEndereco": "RUA DAS FLORES", "endNumero": "10", "endBairro": "CENTRO"},
      "produtos": [{"codigo": "1001", "quantidade": 2}],
      "pagamentos": [{"formaPagamentoNome": "DINHEIRO", "valor": 20}]
    }
  }'

Para NFC-e, a rota é /api/nfce/emitir. Para emitir uma nota que já está cadastrada, envie só {"id": "..."} em vez de nota.

A resposta traz o desfecho: situacao, chave, numero, serie, protocolo e os links urlDanfe e urlXml. Se a SEFAZ estiver fora do ar, a nota volta com situacao PENDENTE e o motivo em motivo, e o sistema a autoriza sozinho quando a SEFAZ voltar.

Use a idempotencyKey. Se a conexão cair antes da resposta, repita a chamada com a mesma chave: o sistema devolve a nota da primeira chamada em vez de emitir outra. Uma chave nova é uma nota nova.

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="integracao@suaempresa.com.br"
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.