API para integração

A API é a mesma que as telas do sistema usam, mas um programa seu ou de um parceiro alcança só uma parte dela: as operações de venda e de nota fiscal e os cadastros que elas usam.

Ela atende de dois jeitos, com as mesmas regras de acesso:

• REST: chamadas HTTP com JSON. A referência completa das rotas mostra cada endereço, o que ele espera receber e o que devolve.
• gRPC: para quem prefere um cliente gerado. Há SDKs prontos para Go e Python.

Os exemplos de código trazem o passo a passo pronto para rodar nos dois jeitos.

Para experimentar antes de programar, carregue todas as rotas no Postman ou no Apidog.

O que a integração alcança

Área	O que dá para fazer
NF-e, NFC-e e NFS-e	Emitir, consultar, cancelar e baixar as notas
Pedidos e orçamentos	Lançar, alterar, consultar e acompanhar
Ordens de serviço	Abrir, alterar e consultar
Clientes	Cadastrar, alterar e consultar
Produtos	Cadastrar, alterar e consultar
Formas de pagamento	Consultar e cadastrar

A referência traz só essas rotas. Qualquer outra responde à integração com o erro 403 “esta operação não está disponível para integração”, mesmo que o usuário dela tenha permissão na tela: financeiro, estoque, configurações da empresa, certificado digital, integrações e usuários ficam só para quem usa o sistema. A leitura dos dados da empresa e do usuário conectado continua liberada.

Senhas, chaves secretas, tokens e o arquivo do certificado digital nunca voltam nas respostas da API, nem para o próprio sistema: eles só entram (no cadastro) e ficam guardados para uso interno.

O que é preciso

A empresa precisa ter o módulo API contratado. Ele libera o acesso de programas que não são o próprio sistema; sem ele, a chamada é recusada com a mensagem “o acesso por API exige o módulo API contratado para esta empresa”.

O módulo vale por empresa: se a integração opera em três empresas, as três precisam dele.

Quem pode acessar

Quem decide o alcance da integração é você:

1. O usuário a que a integração está ligada. Ela enxerga exatamente o que aquele usuário enxerga: nem um registro a mais, e só o que as permissões do grupo dele liberam.
2. As áreas autorizadas, quando o acesso é por aplicativo autorizado (veja o passo 2). Dentro do que o usuário alcança, você escolhe por área se o aplicativo pode apenas consultar ou também alterar.

Passo 1: crie o usuário da integração

Em Sistema > Segurança > Usuários, crie um usuário só para a integração. Não reaproveite o seu.

Em Sistema > Segurança > Grupos/Permissões, ligue esse usuário a um grupo com as permissões do que ela precisa fazer. Se a integração só lança pedidos, ela não precisa de permissão no financeiro.

Um usuário por integração

Crie um usuário separado para cada integração.

O sistema mantém uma sessão por usuário no computador, e a integração conta como computador: quando um programa ou um navegador entra com o usuário, a sessão anterior dele cai. Se duas integrações dividirem o mesmo usuário, ou se alguém entrar pelo navegador com o usuário da integração, um derruba o outro, e as chamadas passam a falhar de forma intermitente com erro de autenticação.

Nota

Não ligue a verificação em duas etapas no usuário da integração. Ela pede um código por e-mail a cada acesso novo, o que um programa não tem como responder.

Passo 2: escolha como a integração entra

Com usuário e senha

É o caminho do programa que é seu. Ele entra com o usuário da integração e recebe um token:

curl -X POST https://app.suaempresa.com.br/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "..."}'

A resposta traz o token e a lista de empresas do usuário (orgs), com a empresa padrão em currentOrg. Para entrar direto numa empresa, informe "orgId" no pedido.

O token vale por algumas horas. Enquanto ele é usado, o sistema devolve um token renovado no cabeçalho X-New-Token (no gRPC, no trailer x-new-token); guarde o novo e continue com ele. Os SDKs fazem isso sozinhos.

Com um aplicativo autorizado

É o caminho de um aplicativo de terceiro, que não deve conhecer a senha. O aplicativo abre uma página de autorização do próprio sistema, onde você:

1. Entra com o usuário da integração: é esse login que autoriza o acesso.
2. Escolhe a empresa em que ele vai operar.
3. Marca o que ele pode fazer em cada área.

O aplicativo recebe uma autorização com prazo, ligada ao usuário e limitada às áreas marcadas. As áreas disponíveis são cadastro de pessoas, produtos e estoque, vendas, financeiro, notas fiscais, relatórios, CRM, marketing, redes sociais, importação e BI. Cada uma tem três níveis:

Nível	O que significa
Sem acesso	A área fica invisível para o aplicativo
Consultar	Ele lê, mas não altera nada
Consultar e alterar	Ele também cria e edita registros da área

Na prática: um aplicativo autorizado só em “consultar vendas” não grava nada, mesmo que o usuário dele seja administrador.

Passo 3: chame a API

O endereço é o mesmo que você usa para acessar o sistema. Se a sua empresa acessa por um endereço próprio, use esse endereço.

REST

Cada chamada leva dois cabeçalhos:

• A credencial: Token: <token do login>, ou Authorization: Bearer <token> no aplicativo autorizado
• Org: <identificador da empresa>: a empresa em que a chamada opera

O corpo e a resposta são JSON. As listagens são enviadas por POST numa rota terminada em /list, porque os filtros não cabem no endereço.

O que vai no corpo

Para cadastrar ou alterar, envie o registro com os campos que você informa. O que o próprio sistema preenche (código interno id, datas de criação e de alteração, quem cadastrou, número do documento, totais calculados, situação e protocolo da nota) aparece só na resposta. Se vier no corpo, é ignorado: dá para alterar reenviando o registro que você consultou.

Campo que não existe é recusado com 400 e a mensagem unknown field, com o nome do campo. Confira a grafia na referência: a integração fica sabendo na hora que errou o nome, em vez de o dado sumir sem aviso.

gRPC

O servidor gRPC atende no mesmo endereço, na porta 443. A credencial e a empresa vão na metadata da chamada: token (ou authorization: Bearer <token>) e org.

Cada rota da referência REST corresponde a um método gRPC com as mesmas mensagens: POST /api/produtos/list, por exemplo, é o método List do serviço produto.ProdutoService. Os SDKs trazem esses clientes prontos:

Linguagem	Instalação
Go	go get github.com/linksoft-dev/sdks/go@latest
Python	pip install "git+https://github.com/linksoft-dev/sdks.git#subdirectory=python"

Quando a chamada é recusada

Resposta	O que significa
400 (gRPC INVALID_ARGUMENT)	Dado inválido ou campo que não existe. A mensagem diz qual.
401 (gRPC UNAUTHENTICATED)	Credencial ausente, vencida ou de uma sessão encerrada. Entre de novo.
403 com “exige o módulo API” (gRPC FAILED_PRECONDITION)	A empresa não tem o módulo API contratado.
403 sem permissão (gRPC PERMISSION_DENIED)	O usuário da integração não tem a permissão, ou o aplicativo não foi autorizado naquela área.
429 (gRPC RESOURCE_EXHAUSTED)	O aplicativo autorizado passou do limite de chamadas. Espere um minuto.

O corpo da resposta traz o motivo em message: leia antes de tentar de novo.

Acompanhar e revogar

Em IA > IA externa, a lista de Aplicativos conectados mostra cada aplicativo autorizado, quem autorizou e quando foi usado pela última vez.

• Permissões muda as áreas liberadas. A mudança vale na hora: apertar o acesso já bloqueia a próxima chamada.
• Revogar encerra o acesso imediatamente. Use ao trocar de fornecedor, ao desligar uma integração ou se não reconhecer uma conexão.

Para cortar uma integração que entra com usuário e senha, bloqueie o usuário dela (veja Como inativar ou bloquear um usuário) ou troque a senha.

A antiga tela Acesso Externo, que gerava tokens, foi desativada e não gera token novo. Veja Tokens de Acesso.

Limite de chamadas

Cada aplicativo autorizado pode fazer até 300 chamadas por minuto. Acima disso as chamadas são recusadas por um minuto, com a resposta 429.

O limite existe para conter integração presa em laço. Uso normal fica bem abaixo dele. Se a sua integração está esbarrando no teto, quase sempre é porque está consultando em loop algo que poderia buscar de uma vez só.

Perguntas frequentes

A integração enxerga dados de outras empresas? Só das empresas a que o usuário dela tem acesso, e sempre uma por chamada, a informada em Org. O aplicativo autorizado fica preso à empresa escolhida na autorização.

Preciso mudar alguma coisa quando o sistema é atualizado? Não. As rotas documentadas são as mesmas que as telas usam; elas mudam junto com o sistema e mantêm compatibilidade.

Posso usar direto do navegador, em JavaScript? Pode, mas evite: isso exporia a credencial para quem abrir a página. O lugar certo da integração é no seu servidor.

Existe alguma rota que fica de fora? Sim. A referência mostra apenas o que está aberto a integrações. Rotas de administração interna do sistema não são acessíveis por integração, mesmo que o usuário tenha permissão.