API REST - Quickstart

A API REST do iDempiere permite integração com sistemas externos para consulta e manipulação de dados do ERP.

Documentação Oficial

A documentação completa, collections do Postman e especificações estão mantidas pelo projeto iDempiere:

Docs: https://bxservice.github.io/idempiere-rest-docs
Repositório: https://github.com/bxservice/idempiere-rest

URL Base

https://{seu-ambiente}.api.devco.cloud

Acesso à API

:::caution Verificação de Contrato A API REST pode não estar disponível em todos os planos ou ambientes. Caso não possua as credenciais de acesso ou esteja recebendo erros de permissão, entre em contato com o time comercial para verificar a disponibilidade e valores para seu contrato. :::

Autenticação

Todas as requisições exigem um token JWT no header Authorization: Bearer {token}.

Docs completa: Authentication

:::info Tipo de Papel (Role Type) Apenas papéis com Role Type configurado como WebService (ou em branco) são permitidos para autenticação via API. :::

Se você já conhece os parâmetros de sessão (client, role, organization), use o login direto em uma única chamada:

curl -X POST "https://{seu-ambiente}.api.devco.cloud/api/v1/auth/tokens" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "seu_usuario",
    "password": "sua_senha",
    "parameters": {
      "clientId": 11,
      "roleId": 1000000,
      "organizationId": 1000001,
      "warehouseId": 1000000,
      "language": "pt_BR"
    }
}'

A resposta já retorna o token final pronto para uso nas requisições.

Útil quando você não conhece os IDs de client/role/organization, ou precisa apresentar opções ao usuário. Espelha o fluxo de login da interface do iDempiere.

Etapa 1 — Autenticação inicial: retorna um token temporário e a lista de clients disponíveis.

curl -X POST "https://{seu-ambiente}.api.devco.cloud/api/v1/auth/tokens" \
  -H "Content-Type: application/json" \
  -d '{"userName": "seu_usuario", "password": "sua_senha"}'

Etapa 2 — Consultar opções de sessão: use o token temporário da etapa 1 para descobrir roles, organizations e warehouses disponíveis.

# Roles disponíveis
curl -X GET "https://{seu-ambiente}.api.devco.cloud/api/v1/auth/roles?client=11" \
  -H "Authorization: Bearer {token_temporario}"

# Organizations disponíveis
curl -X GET "https://{seu-ambiente}.api.devco.cloud/api/v1/auth/organizations?client=11&role=1000000" \
  -H "Authorization: Bearer {token_temporario}"

# Warehouses disponíveis
curl -X GET "https://{seu-ambiente}.api.devco.cloud/api/v1/auth/warehouses?client=11&role=1000000&organization=1000001" \
  -H "Authorization: Bearer {token_temporario}"

Etapa 3 — Obter o token definitivo: com os parâmetros escolhidos, faça um PUT para obter o token final.

curl -X PUT "https://{seu-ambiente}.api.devco.cloud/api/v1/auth/tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token_temporario}" \
  -d '{
    "clientId": 11,
    "roleId": 1000000,
    "organizationId": 1000001,
    "warehouseId": 1000000,
    "language": "pt_BR"
}'

O token retornado nesta etapa é o que deve ser usado em todas as requisições subsequentes.

Token Refresh

Os tokens possuem tempo de expiração (padrão: 1h para access token, 24h para refresh token). Para renovar sem refazer login:

curl -X POST "https://{seu-ambiente}.api.devco.cloud/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "seu_refresh_token", "clientId": 11, "userId": 101}'

aviso

Refresh tokens são de uso único. Reutilizar um refresh token já consumido invalida a sessão por segurança.

Server-to-Server

Para integrações server-to-server (service accounts), consulte a documentação oficial.

CRUD Básico - Models

Listar (GET)

Retorna registros da entidade. No exemplo, lista produtos cadastrados (m_product).

curl -X GET "https://{seu-ambiente}.api.devco.cloud/api/v1/models/m_product" \
  -H "Authorization: Bearer {token}"

Criar (POST)

Insere um novo registro. Campos obrigatórios variam conforme a entidade e configurações do ERP.

curl -X POST "https://{seu-ambiente}.api.devco.cloud/api/v1/models/m_product" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "AD_Org_ID": 1000001,
    "Name": "Produto Exemplo",
    "C_UOM_ID": 100,
    "M_Product_Category_ID": 1000000,
    "C_TaxCategory_ID": 1000000
}'

Atualizar (PUT)

Atualiza campos de um registro existente. Envie apenas os campos a serem alterados.

curl -X PUT "https://{seu-ambiente}.api.devco.cloud/api/v1/models/m_product/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "Name": "Produto Atualizado"
}'

Excluir (DELETE)

Remove um registro pelo ID. Restrições de integridade referencial do ERP se aplicam.

curl -X DELETE "https://{seu-ambiente}.api.devco.cloud/api/v1/models/m_product/{id}" \
  -H "Authorization: Bearer {token}"

Processos e Relatórios

Docs: Processes

Executa processos e relatórios do ERP. No exemplo, gera o relatório de detalhes de parceiros de negócios (rv_bpartner) em PDF.

curl -X POST "https://{seu-ambiente}.api.devco.cloud/api/v1/processes/rv_bpartner" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "report-type": "PDF",
    "print-format-id": 123456
}'

observação

O print-format-id deve corresponder a um formato de impressão válido configurado no ERP. Consulte a janela Formato de Impressão para obter o ID correto.

Responsabilidades

Item	dev&Co	Cliente
Instalação e disponibilização da API REST	✓
Infraestrutura, proxy e monitoramento	✓
Ajustes de rate limit mediante análise	✓
Disponibilidade do serviço	✓
Criação de usuários, perfis e permissões		✓
Geração e renovação de tokens		✓
Desenvolvimento e manutenção da integração		✓
Troubleshooting do código/aplicação externa		✓

Limites de Uso

Os rate limits padrão são permissivos para uso normal em produção. Caso nosso monitoramento identifique consumo excessivo, entraremos em contato para alinhamento.

:::warning Ambientes Multi-tenant (Atacarejo / Ferro&Aço) Alguns parâmetros da API não podem ser alterados a nível de empresa. Configurações globais são definidas pela dev&Co visando estabilidade do ambiente compartilhado. :::

Suporte

Dúvidas sobre a API devem ser direcionadas ao canal de suporte da dev&Co.

Escopo do suporte:

Orientação básica sobre uso da API
Dúvidas sobre estruturas e entidades do ERP

Fora do escopo:

Debug de código em qualquer linguagem
Suporte a frameworks ou bibliotecas externas
Desenvolvimento de integrações

:::tip Pré-requisito Conhecimento das estruturas do ERP (tabelas, janelas, processos) é obrigatório para uso efetivo da API. :::

Documentação Oficial​

URL Base​

Acesso à API​

Autenticação​

One-Step Login (recomendado para integrações)​

Normal Login Flow (3 etapas)​

Token Refresh​

Server-to-Server​

CRUD Básico - Models​

Listar (GET)​

Criar (POST)​

Atualizar (PUT)​

Excluir (DELETE)​

Processos e Relatórios​

Responsabilidades​

Limites de Uso​

Suporte​