Todas as coleções
APIs
Exemplos de API
Faturamento em Lote de Ordens de Serviço via API
Faturamento em Lote de Ordens de Serviço via API
Thais Oldani avatar
Escrito por Thais Oldani
Atualizado há mais de uma semana

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.

Respondeu à sua pergunta?