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, exceto o próprio login, devem incluir o header Authorization: Bearer <token>. O token JWT é obtido no login, POST /user/signin/local, com email (e-mail de login, CPF ou CNPJ) e password no corpo, e volta no campo token da resposta. Se o usuário tiver a verificação em duas etapas habilitada, a primeira resposta não traz token (traz MFAEnabled: true) e o login é refeito com o código em mfacode. Por padrão o token vale 14 horas; para outra validade, envie expireinhour de 1h a 24h (ex.: 12h). Veja Segurança do token.

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

Baixar arquivos pelos links da resposta

Várias respostas trazem um link para baixar um arquivo: XML e DANFE de notas, etiquetas, anexos de contas a pagar e a receber, templates de planilha. Esses links não trazem mais o token embutido (mudança de 16/10/2026, veja o changelog). Para baixar, faça um GET no link com o mesmo header Authorization das demais chamadas:

curl -H "Authorization: Bearer SEU_TOKEN" -o nota.xml \
  "https://{AccountName}.api-idworks.com.br/1.0/invoice/danfe?Folder=Inbound&Type=XML&Origin=Feed&File={chave-acesso}"

Operação	Campos com link	Como baixar
GET /purchase/{idpurchase}	UrlFileXml, UrlFileDanfe, Payments[].Files[].FileUrl	Link + header Authorization
GET /purchase/feed · PUT /purchase/feed/{idnfevents} · POST /purchase/feed/{idnfevents}/manifest	XmlFile, XmlDanfe	Link + header Authorization
GET /invoice-service/{idserviceorder}	UrlFileXml, UrlFileDanfe	Link + header Authorization
GET /invoice-service/feed	XmlFile, XmlDanfe	Link + header Authorization
GET /cte	XmlFile, XmlDanfe	Link + header Authorization
GET /accounts/payable/{idaccountpayable} · GET /accounts/receivable/{idaccountreceivable}	Files[].FileUrl	Link + header Authorization
PUT /orders/{idorder}/invoice/{nfenumber}	UrlFileXml, UrlFileDanfe	Link + header Authorization
GET /type/job/type	TemplateUrl (quando o template é servido pela API)	Link + header Authorization
GET /supplier/{idsupplier}	CarrierTableUpload[].UrlFile	URL pré-assinada do S3, válida por 2 horas: abra direto, sem o header
GET /orders/{idorder}	Packages[].UrlLabel, Packages[].UrlLabelDownload, Files[].UrlFileXml, Files[].UrlFileDanfe, Files[].UrlFileDanfeSimplificado	Com token por padrão (abre direto). Com ?UrlToken=0 os links saem sem o token: link + header Authorization

:::warning Prefira o header ao parâmetro token As rotas de download ainda aceitam o token no parâmetro token da URL, mas a query string fica em log, histórico do navegador e cabeçalho Referer. Se a sua integração hoje abre o link recebido sem enviar o header, passe a enviar o Authorization: funciona antes e depois da mudança. :::

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. :::