Antes que você possa começar de fato os testes com a nossa API, é importante conhecer alguns processos básicos:

💡 Dica para melhorar a sua experiência

Atualmente, conseguimos testar as nossas API’s diretamente pelo site do Developer, porém, existem alguns programas que também podem realizar esse processo, como o Postman, Insomnia e o ThunderClient (uma extensão do VS Code).

Para o nosso teste, vamos utilizar diretamente o Developer. Assim como, vamos utilizar o APP KEY e o APP SECRET padrões, mas se preferir, pode alterar para as suas credenciais. 😉

Entendendo o Faturamento em Lote via API

Aqui, vamos explicar como o faturamento em lote opera e os detalhes preliminares necessários antes de executá-lo.

1) Com esse método, você poderá faturar todas as Ordens de Serviço que estiverem na coluna que antecede a coluna "Faturado" do Kanban de Ordens de Serviço, conforme exemplo abaixo:

💡 Dica Importante

No Omie, você pode ter de 3 a 6 etapas para a venda de serviços. E você pode personalizar o nome de cada uma das etapas e a ordem em que aparecem no kanban.

Mesmo que você mude o nome da etapa "Faturar", ela continuará posicionada antes da coluna "Faturado".

2) Para o faturamento em lote via API, serão necessários alguns dados prévios, como listar as etapas de faturamento, listar as ordens de serviço registradas e entender como modificar as OSs para a etapa de faturar.

Por isso, separamos algumas instruções ara te ajudar a encontrar essas informações:

Liste as Etapas de Faturamento

Utilize o método ListarEtapasFaturamento para identificar quais são as etapas de venda de serviço da sua empresa. Separamos um exemplo de requisição:

{
  "pagina": 1,
  "registros_por_pagina": 20 
}

Busque os resultados para "cDescOperacao": "Venda de Serviço".

      "cCodOperacao": "01",
      "cDescOperacao": "Venda de Serviço",
      "etapas":

💡 Dica. Por padrão, a etapa de faturamento, denominada "Faturar" na imagem anterior, possui um código fixo na API: "cCodigo": "50".

Liste as suas Ordens de Serviço

Utilize o método ListarOS para obter uma lista de todas as Ordens de Serviço registradas no sistema. Separamos um exemplo de requisição:

{
  "pagina": 1,
  "registros_por_pagina": 50,
  "apenas_importado_api": "N"
}

Este método fornecerá os dados de referência da OS, como o código de integração (1), o código da OS (2) e o número da OS (3). Estas informações serão necessárias para a etapa seguinte.

E também, na tag "cEtapa" (4), será indicada a etapa de venda em que a OS está localizada:

Mova todas as OSs de interesse para a Coluna de Faturar

Por fim, é preciso mover todas as Ordens de Serviço de interesse para a etapa "Faturar", ou seja, para a "cEtapa": "50".

Para isso, utilize o método TrocarEtapaOS e preencha os dados das OSs de interesse, consultados na instrução anterior. Abaixo está um exemplo de requisição:

{
  "cCodIntOS": "",
  "nCodOS": 2203932,
  "cNumOS": "",
  "cEtapa": "50"
}

Realizando o Faturamento em Lote via API

1) Após ter realizado os passos anteriores, você poderá gerar o faturamento em lote, através do método: FaturarLoteOS

{
  "cEtapa": "50"
}

2) Ao receber a resposta da requisição, você terá acesso ao Código do Status do Processamento (cCodStatus):

📌 cCodStatus

Se o retorno for '0' significa que a solicitação foi executada com sucesso.

Se o retorno for maior que '0' ocorreu algum erro durante o processamento da solicitação.

3) Para obter detalhes adicionais sobre o faturamento e verificar se as notas foram emitidas, utilize o método "ListarLoteOS", com a tag "cExibirDetalhes", conforme ilustrado no exemplo abaixo:

{
  "dDtIncDe": "29/11/2023",
  "dDtIncAte": "29/11/2023",
  "cExibirDetalhes": "S"
}

Ou, se preferir, você pode consultar diretamente o lote faturado, utilizando a tag "nIdLoteFat", conforme o exemplo:

{
  "nIdLoteFat": 3656992077,
  "cExibirDetalhes": "S"
}

4) Desse modo, o status da emissão será apresentado, podendo ser: RUNNING, DONE ou ERROR.

Caso ocorra algum erro no "cStatus", detalhes adicionais serão mostrados na tag "cMensagem", conforme ilustrado abaixo:

Nessa situação, após fazer as correções necessárias, basta faturar o lote novamente.