As Categorias no Omie desempenham um papel fundamental na organização das receitas e despesas da sua empresa, facilitando a gestão e visualização de relatórios financeiros, como o DRE e o Fluxo de Caixa.
Aqui, vamos te mostrar o passo a passo para cadastrar e alterar as suas Categorias através das nossas APIs.
Preparado para simplificar sua gestão e otimizar seu tempo? Então, vamos lá! 🚀
Informações Importantes sobre as APIs Omie
Antes de iniciar seus testes com a nossa API, é fundamental conhecer alguns processos básicos:
✅ Acessando a documentação: Consulte nossa documentação oficial para entender os endpoints disponíveis e seus respectivos parâmetros.
🔑 Chaves de Integração da API: Saiba como obter e utilizar suas credenciais de acesso para autenticar as requisições.
⚙️ Características e Recomendações: Fique por dentro das melhores práticas para otimizar sua experiência com a API da Omie
🔐 Login no Portal: Para testar suas requisições no Portal do Desenvolvedor é necessário fazer login na plataforma com o mesmo e-mail e senha que você já usa no ERP. Fácil, né? 😉
🧪 Aplicativo Teste: Aprenda a criar um Aplicativo Teste gratuito e descubra, na prática, como utilizar nossas APIs e aproveitar ao máximo os nosso recursos.
💡 Dica Omie: Você pode testar nossas APIs diretamente no nosso Portal do Desenvolvedor. Além disso, ferramentas como Postman, Insomnia e ThunderClient (extensão do VS Code) também são ótimas opções para realizar testes.
Cadastrando uma Categoria
1) No Portal do Desenvolvedor, acesse a lista de APIs:
2) No tópico "Geral", selecione a opção "Categorias":
3) Para cadastrar uma Categoria, é preciso utilizar o método IncluirCategoria:
4) Após selecionar o método IncluirCategoria, você poderá consultar todos os parâmetros disponíveis (1).
Para realizar um teste rápido com os parâmetros básicos, basta clicar em "Teste agora mesmo" (2).
💡 Entendendo os parâmetros
💡 Entendendo os parâmetros
Por aqui, você encontrará uma lista dos parâmetros disponíveis para sua requisição, incluindo:
Nome – Identifica a variável dentro da API.
Tipo de dado – Indica o formato esperado (integer, string, decimal, etc.)
Descrição – Explica a finalidade do parâmetro e como utilizá-lo.
Para obter mais detalhes sobre um parâmetro específico, basta passar o mouse sobre o ícone ➕, e uma explicação detalhada será exibida.
5) Para realizar um teste pelo Developer - Portal do Desenvolvedor, é preciso realizar o login no Omie:
6) Após realizar o login, você será direcionado para a tela de testes do Developer, onde poderá configurar e enviar requisições para a API. Veja como cada campo funciona:
(1) Endpoint:O Omie preencherá automaticamente este campo com:
🔗
https://app.omie.com.br/api/v1/geral/categorias/
(2) Aplicativo ou Chave de Acesso: Aqui, você verá uma lista dos aplicativos aos quais seu e-mail tem acesso. Basta selecionar o desejado, e os campos App Key e App Secret serão preenchidos automaticamente.
Caso precise testar um aplicativo que não aparece na lista, selecione "O aplicativo que eu quero não está na lista" e insira manualmente suas credenciais.
(3) Call: O Omie definirá automaticamente o tipo de chamada como IncluirCategoria.
(4) Conteúdo – Este é o campo onde você configurará sua requisição, inserindo os dados necessários para cadastrar a Categoria
7) A seguir, demonstramos um exemplo de requisição para cadastro de uma Categoria com dados mínimos:
{
"categoria_superior": "1.01",
"descricao": "Categoria exemplo cadastrada via API",
"natureza": "Utiliza esta Categoria para Vendas"
}
📣 Importante
Para realizar a requisição, é necessário informar alguns parâmetros obrigatórios, assim como no cadastro manual de categorias. Confira:
"categoria_superior": este parâmetro define se a Categoria será classificada como Receita ou Despesa e em qual grupo será inserida.
"descrição": você informará neste parâmetro o nome da Categoria que deseja cadastrar.
Caso precise do código da Categoria Superior, utilize o método "ListarCategorias".
No retorno da requisição, as Categorias Superiores (agrupadoras) possuem um código de até 4 dígitos, no formato: “X.XX”.
A tag "natureza" corresponde à descrição da Natureza da Conta, equivalente ao campo "Observação" da categoria no ERP.
8) Ao executar a requisição com todos os parâmetros corretamente informados, você receberá uma resposta positiva contendo o código da Categoria cadastrada.
Esse identificador, retornado na tag “codigo”, é fundamental, pois serve como referência para consultas e para a realização de operações via API.
{
"codigo_status": "0",
"descricao_status": "Categoria cadastrada com sucesso!",
"codigo": "1.01.87"
}
9) No Omie ERP, a Categoria estará cadastrada:
Alterando uma Categoria
💡 É possível alterar diversas informações na Categoria. Neste exemplo que preparamos, vamos vincular a Categoria a um grupo do DRE.
1) No Portal do Desenvolvedor, acesse a lista de APIs:
2) Antes de alterar uma Categoria via API, é importante já ter em mãos alguns dados necessário para enviar como parâmetros na requisição.
Você precisará do:
Código da Categoria: ListarCategorias
Código da Conta do DRE: ListarCadastroDRE
3) No tópico "Geral", selecione a opção "Categorias":
4) Para cadastrar uma Categoria, é preciso utilizar o método AlterarCategoria:
5) Após selecionar o método AlterarCategoria, você poderá consultar todos os parâmetros disponíveis (1).
Para realizar um teste rápido com os parâmetros básicos, basta clicar em "Teste agora mesmo" (2).
💡 Entendendo os parâmetros
💡 Entendendo os parâmetros
Por aqui, você encontrará uma lista dos parâmetros disponíveis para sua requisição, incluindo:
Nome – Identifica a variável dentro da API.
Tipo de dado – Indica o formato esperado (integer, string, decimal, etc.)
Descrição – Explica a finalidade do parâmetro e como utilizá-lo.
Para obter mais detalhes sobre um parâmetro específico, basta passar o mouse sobre o ícone ➕, e uma explicação detalhada será exibida.
6) Para realizar um teste pelo Developer - Portal do Desenvolvedor, é preciso realizar o login no Omie:
7) Após realizar o login, você será direcionado para a tela de testes do Developer, onde poderá configurar e enviar requisições para a API. Veja como cada campo funciona:
(1) Endpoint:O Omie preencherá automaticamente este campo com:
🔗
https://app.omie.com.br/api/v1/geral/categorias/
(2) Aplicativo ou Chave de Acesso: Aqui, você verá uma lista dos aplicativos aos quais seu e-mail tem acesso. Basta selecionar o desejado, e os campos App Key e App Secret serão preenchidos automaticamente.
Caso precise testar um aplicativo que não aparece na lista, selecione "O aplicativo que eu quero não está na lista" e insira manualmente suas credenciais.
(3) Call: O Omie definirá automaticamente o tipo de chamada como AlterarCategoria.
(4) Conteúdo – Este é o campo onde você configurará sua requisição, inserindo os dados necessários para alterar a Categoria.
8) É possível alterar diversas informações na Categoria. Neste exemplo que preparamos, vamos vincular a Categoria a um grupo do DRE.
{
"codigo": "1.01.95",
"codigo_dre": "1.01.01"
}
9) Ao executar a requisição com todos os parâmetros corretamente informados, você receberá uma resposta positiva contendo o código da Categoria cadastrada.
Esse identificador, retornado na tag “codigo”, é fundamental, pois serve como referência para consultas e para a realização de operações via API.
{
"codigo_status": "0",
"descricao_status": "Categoria alterada com sucesso!",
"codigo": "1.01.01"
}
10) No Omie ERP, a Categoria estará alterada:
📚 Artigos Relacionados:
