idworks API

Bem-vindo à referência da API pública idworks. Esta documentação descreve todos os endpoints, parâmetros, respostas e códigos de erro disponíveis para integradores.

Baixar a API (Postman & OpenAPI)

Para testar e integrar mais rápido, baixe os artefatos da API — todos gerados a partir desta mesma documentação (sempre em sincronia com os endpoints publicados):

• 📥 Collection do Postman — no Postman: Import → Upload. Vem com as 764 requisições já organizadas por categoria.
• 📄 Spec OpenAPI — YAML · JSON. Útil para gerar SDKs, importar no Insomnia ou no próprio Postman.

:::tip Configure a sua conta Depois de importar, ajuste a variável AccountName da collection (padrão teste) para o nome da sua conta — ex.: acme faz a URL base virar https://acme.api-idworks.com.br/1.0/. :::

Autenticação

Todas as requisições devem incluir o header Authorization: Bearer <token>. O token JWT é obtido via POST /auth/token.

curl -H "Authorization: Bearer SEU_TOKEN" \
  https://{AccountName}.api-idworks.com.br/1.0/account

URL base

Cada cliente acessa a API por um subdomínio próprio derivado do nome da sua conta:

https://{AccountName}.api-idworks.com.br/1.0/

Substitua {AccountName} pelo nome da sua conta idworks (ex: se sua conta é acme, a URL fica https://acme.api-idworks.com.br/1.0/).

Erros de autenticação e autorização

Estes códigos podem aparecer em qualquer endpoint autenticado e são emitidos pelo gateway/autorizador antes do handler ser executado — por isso não são repetidos na documentação de cada operação:

• 401 Unauthorized — falha de autenticação no autorizador da API. O header Authorization está ausente, malformado, ou o JWT é inválido, expirado ou não corresponde ao subdomínio (AccountName) da URL. Corrija o token e refaça a requisição.
• 403 Forbidden — o token é válido mas o usuário não tem privilégio para a operação solicitada. Verifique os perfis de acesso do usuário no produto (Configurações → Perfis de Acesso).

O corpo segue o formato { "errorMessage": "<prefixo> ...mensagem..." } descrito em Formato de erro (ver convenções abaixo).

Rate limits

O limite padrão é de 5 requisições/segundo por endpoint por conta. Respostas excedendo o limite retornam 429 Too Many Requests com o header Retry-After.

Como navegar

Use a barra lateral à esquerda para explorar os recursos. Cada endpoint mostra parâmetros, exemplos de request/response e um botão Send API Request para testar diretamente do navegador.

:::tip Testando a API direto do navegador No painel direito de cada endpoint, clique em Edit ao lado da Base URL para trocar AccountName pelo nome da sua conta (ou mantenha teste para usar a conta de demonstração). Cole o JWT no campo Auth e clique Send API Request. :::