API para integração

A API é a mesma que as telas do sistema usam. Tudo que você faz pela tela — cadastrar um cliente, lançar um pedido, consultar estoque, emitir nota — pode ser feito por um programa seu ou de um parceiro.

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.

Prefere assistir? Veja o vídeo

Em poucos minutos você vê o passo a passo na prática. Se preferir ler, o passo a passo completo está logo abaixo.

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 Segurança > Cadastro de Usuários, crie um usuário só para a integração — não reaproveite o seu.

Em Segurança > Grupos de Usuário, 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 de integração por usuário: quando um programa entra com ele, a sessão anterior de programa daquele usuário cai. Se duas integrações dividirem o mesmo usuário, uma derruba a outra, e as chamadas passam a falhar de forma intermitente com erro de autenticação.

Entrar pelo navegador com o usuário da integração não derruba a integração, e ela não derruba quem está na tela.

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.

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"

Para ferramentas como grpcurl e Postman, o repositório dos SDKs traz também o arquivo api.protoset, com a descrição de todos os serviços abertos.

Quando a chamada é recusada

Resposta	O que significa
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 Inteligência Artificial > 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 ou troque a senha.

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.