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

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

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.

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

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​