As APIs do Omie foram desenvolvidas para oferecer flexibilidade e eficiência na integração de sistemas e automatização de processos, permitindo que você conecte suas soluções diretamente ao Omie.

Aqui, vamos te mostrar o passo a passo para cadastrar as suas Ordens de Serviço através das nossas APIs.

Preparado para simplificar sua gestão e otimizar seu tempo? Então, vamos lá! 🚀

Tópicos do Artigo

Informações Importantes sobre as APIs Omie
Cadastrando uma Ordem de Serviço

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 OS via API

1) Antes de cadastrar uma Ordem de Serviço 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 do Serviço (nCodServico): Caso o serviço já esteja cadastrado, consulte através do método ListarCadastroServico
Código da Etapa do Faturamento (cEtapa) :ListarEtapasFaturamento
Código do Cliente (nCodCli): ListarClientes
Código da Categoria (cCodCateg): ListarCategorias
Código da Conta Corrente (nCodCC): ListarContasCorrentes
Dados da Cidade (cCidPrestServ): PesquisarCidades

2) Com esses dados em mãos, identifique em qual dos três cenários abaixo você se encaixa.

Em seguida, clique no cenário correspondente para visualizar o passo a passo do cadastro da OS.

Incluindo uma OS com um Serviço não cadastrado

💡 Neste exemplo, a requisição é utilizada quando o serviço ainda não está cadastrado no sistema Omie e você deseja incluí-lo diretamente ao criar a OS.

Para isso, é necessário fornecer todas as informações referentes ao serviço, incluindo:

Detalhes do serviço (descrição, unidade de medida, entre outros)
Códigos específicos de cada município, conforme exigido pela legislação local.
Dados tributários (impostos aplicáveis, alíquotas e retenções).

1) No Portal do Desenvolvedor, acesse a lista de APIs:

2) No tópico "Serviços e NFS-e", selecione a opção "Ordens de Serviço":

3) Para cadastrar Clientes ou Fornecedores, é preciso utilizar o método IncluirOS:

4) Após selecionar o método IncluirOS, 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

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, na 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/servicos/os/
(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 IncluirOS.
(4) Conteúdo – Este é o campo onde você configurará sua requisição, inserindo os dados necessários para cadastrar sua Ordem de Serviço.

7) A seguir, demonstramos um exemplo de requisição para cadastro de Ordem de Serviço informando os dados do Serviço prestado:

{
  "Cabecalho": {
    "cCodIntOS": "xxxOsApi",
    "cCodParc": "999",
    "cEtapa": "10",
    "dDtPrevisao": "27/02/2025",
    "nCodCli": 3795260786,
    "nQtdeParc": 3
  },
  "Departamentos": [],
  "Email": {
    "cEnvBoleto": "N",
    "cEnvLink": "N",
    "cEnviarPara": "api@omie.com.br"
  },
  "InformacoesAdicionais": {
    "cCidPrestServ": "SAO PAULO (SP)",
    "cCodCateg": "1.01.02",
    "cDadosAdicNF": "OS incluída via API",
    "nCodCC": 3731356020
  },
  "ServicosPrestados": [
    {
      "cCodServLC116": "7.07",
      "cCodServMun": "01015",
      "cDadosAdicItem": "Serviços prestados (API)",
      "cDescServ": "Serviço prestado 001 (API)",
      "cRetemISS": "N",
      "cTribServ": "01",
      "impostos": {
        "cRetemIRRF": "S",
        "cRetemPIS": "S",
        "nAliqCOFINS": 0,
        "nAliqCSLL": 0,
        "nAliqIRRF": 15,
        "nAliqISS": 3,
        "nAliqPIS": 4.5
      },
      "nQtde": 3,
      "nValUnit": 1000
    }
  ]
}

8) Ao executar a requisição com todos os parâmetros devidamente preenchidos, você receberá uma resposta positiva contendo o código da OS cadastrada.

Esse identificador, retornado nas tag "nCodOS", serve como referência para consultas e operações futuras via API.

{
  "cCodIntOS": "xxxOsApi",
  "nCodOS": 3847270140,
  "cNumOS": "000000000000016",
  "cCodStatus": "0",
  "cDescStatus": "Ordem de Serviço adicionada com sucesso!"
}

9) No Omie ERP, a Ordem de Serviço estará cadastrada:

Incluindo uma OS com um Serviço já cadastrado

💡 Neste exemplo, a requisição é utilizada quando o serviço já cadastrado no sistema Omie .

Para isso, é necessário fornecer apenas o Código do Serviço "nCodServico" e a quantidade "nQtde", e todas as informações referentes ao serviço serão preenchidas automaticamente, incluindo:

Detalhes do serviço (descrição, unidade de medida, entre outros);
Códigos específicos de cada município, conforme exigido pela legislação local;
Dados tributários (impostos aplicáveis, alíquotas e retenções).

1) No Portal do Desenvolvedor, acesse a lista de APIs:

2) No tópico "Serviços e NFS-e", selecione a opção "Ordens de Serviço":

3) Para cadastrar Clientes ou Fornecedores, é preciso utilizar o método IncluirOS:

4) Após selecionar o método IncluirOS, 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

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, na 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/servicos/os/
(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 IncluirOS.
(4) Conteúdo – Este é o campo onde você configurará sua requisição, inserindo os dados necessários para cadastrar sua Ordem de Serviço.

7) A seguir, demonstramos um exemplo de requisição para cadastro de Ordem de Serviço informando os dados do Serviço já cadastrado no Omie:

{
  "Cabecalho": {
    "cCodIntOS": "16736292",
    "cCodParc": "999",
    "cEtapa": "10",
    "dDtPrevisao": "27/02/2025",
    "nCodCli": 3795260786,
    "nQtdeParc": 1
  },
  "Departamentos": [],
  "Email": {
    "cEnvBoleto": "N",
    "cEnvLink": "N",
    "cEnviarPara": "api@omie.com.br"
  },
  "InformacoesAdicionais": {
    "cCidPrestServ": "SAO PAULO (SP)",
    "cCodCateg": "1.01.02",
    "cDadosAdicNF": "OS incluída via API",
    "nCodCC": 3731356020
  },
  "ServicosPrestados": [
    {
      "cCodServLC116": "7.07",
      "cCodServMun": "01015",
      "cDescServ": "Manutenção de Computadores",
      "cRetemISS": "N",
      "cTribServ": "01",
      "nQtde": 3,
      "nValUnit": 1000
    }
  ]
}

📣 Importante

Ao informar o serviço, você pode utilizar o código do serviço nCodServico, o código de integração cCodIntServico ou a sua descrição cDescServ.
O parâmetro "cCodIntServico" é utilizado exclusivamente para integrações via API, por isso, ele não será demonstrado no ERP.

8) Ao executar a requisição com todos os parâmetros devidamente preenchidos, você receberá uma resposta positiva contendo o código da OS cadastrada.

Esse identificador, retornado nas tag "nCodOS", serve como referência para consultas e operações futuras via API.

{
  "cCodIntOS": "16736292",
  "nCodOS": 3847448488,
  "cNumOS": "000000000000018",
  "cCodStatus": "0",
  "cDescStatus": "Ordem de Serviço adicionada com sucesso!"
}

9) No Omie ERP, a Ordem de Serviço estará cadastrada:

Incluindo uma OS com um Serviço já cadastrado e outro não cadastrado

💡 Neste exemplo, a requisição é utilizada quando você terá dois serviços na OS, mas apenas um deles já está cadastrado no Omie.

Para o serviço cadastrado, é necessário fornecer apenas o Código do Serviço "nCodServico" e a quantidade "nQtde", e todas as informações relacionadas serão preenchidas automaticamente.

Para o serviço não cadastrado, todos os dados deverão ser informados manualmente, incluindo:

Detalhes do serviço (descrição, unidade de medida, entre outros);
Códigos específicos de cada município, conforme exigido pela legislação local;
Dados tributários (impostos aplicáveis, alíquotas e retenções).

1) No Portal do Desenvolvedor, acesse a lista de APIs:

2) No tópico "Serviços e NFS-e", selecione a opção "Ordens de Serviço":

3) Para cadastrar Clientes ou Fornecedores, é preciso utilizar o método IncluirOS:

4) Após selecionar o método IncluirOS, 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

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, na 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/servicos/os/
(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 IncluirOS.
(4) Conteúdo – Este é o campo onde você configurará sua requisição, inserindo os dados necessários para cadastrar sua Ordem de Serviço.

7) A seguir, apresentamos um exemplo de requisição para o cadastro de uma Ordem de Serviço contendo dois serviços: um já registrado no Omie e outro ainda não cadastrado.

{
  "Cabecalho": {
    "cCodIntOS": "16735292",
    "cCodParc": "999",
    "cEtapa": "10",
    "dDtPrevisao": "27/02/2025",
    "nCodCli": 3795260786,
    "nQtdeParc": 1
  },
  "Departamentos": [],
  "Email": {
    "cEnvBoleto": "N",
    "cEnvLink": "N",
    "cEnviarPara": "api@omie.com.br"
  },
  "InformacoesAdicionais": {
    "cCidPrestServ": "SAO PAULO (SP)",
    "cCodCateg": "1.01.02",
    "cDadosAdicNF": "OS incluida via API com dois serviços",
    "nCodCC": 3731356020
  },
  "ServicosPrestados": [
    {
      "cCodServLC116": "7.07",
      "cCodServMun": "01015",
      "cDadosAdicItem": "Serviços prestados",
      "cDescServ": "Serviço prestado 001",
      "cRetemISS": "N",
      "cTribServ": "01",
      "impostos": {
        "cRetemIRRF": "S",
        "cRetemPIS": "S",
        "nAliqCOFINS": 0,
        "nAliqCSLL": 0,
        "nAliqIRRF": 15,
        "nAliqISS": 3,
        "nAliqPIS": 4.5
      },
      "nQtde": 2,
      "nValUnit": 1000
    },
    {
      "nCodServico": 3846592864,
      "nQtde": 1,
      "nValUnit": 1000
    }
  ]
}

📣 Importante

Ao informar o serviço, você pode utilizar o código do serviço nCodServico, o código de integração cCodIntServico ou a sua descrição cDescServ.
O parâmetro "cCodIntServico" é utilizado exclusivamente para integrações via API, por isso, ele não será demonstrado no ERP.

8) Ao executar a requisição com todos os parâmetros devidamente preenchidos, você receberá uma resposta positiva contendo o código da OS cadastrada.

Esse identificador, retornado nas tag "nCodOS", serve como referência para consultas e operações futuras via API.

{
  "cCodIntOS": "16735292",
  "nCodOS": 3847459786,
  "cNumOS": "000000000000019",
  "cCodStatus": "0",
  "cDescStatus": "Ordem de Serviço adicionada com sucesso!"
}

9) No Omie ERP, a Ordem de Serviço estará cadastrada:

Tópicos do Artigo

Informações Importantes sobre as APIs Omie

Cadastrando uma OS via API

Incluindo uma OS com um Serviço não cadastrado

💡 Entendendo os parâmetros

Incluindo uma OS com um Serviço já cadastrado

💡 Entendendo os parâmetros

📣 Importante

Incluindo uma OS com um Serviço já cadastrado e outro não cadastrado

💡 Entendendo os parâmetros

📣 Importante

📚 Artigos Relacionados