Como realizar a integração do Operand com outros sistemas via API Pública?

A API pública possibilita a integração do Operand com outros sistemas :)

Este recurso está disponível para o módulo financeiro, dessa forma, é possível realizar integrações com sistema de emissão de Nota Fiscal, emissão de Boletos, softwares de dashboard e BI e até mesmo sistemas próprios, desde que possuam integração via API.

O que é uma API?

Primeiro, é importante entender o que é uma API.

API, Application Programming Interface, ou traduzido para o português, Interface de Programação de Aplicativos, é um conjunto de rotinas e padrões de programação que permite conectar ou acessar aplicativos e plataformas.

Na prática, a API é uma porta criada no Operand, que permite que outras aplicações acessem informações de dentro do sistema.

Como funciona a API Operand?

Nós disponibilizaremos um token e a documentação da API, para que o próprio cliente desenvolva a integração entre o Operand e a aplicação desejada.

⚠️ Importante: o módulo API Operand não é um módulo gratuito. Ele precisa ser contratado para que a opção de gerar o token fique disponível na conta. Caso o módulo não tenha sido contratado, a opção de gerar token não aparecerá em Avatar > Configurações > Módulos e funções. Para contratar o módulo, entre em contato com o time financeiro ou com o seu Customer Success.

Importante: O desenvolvimento da integração será de inteira responsabilidade do cliente e é recomendado que o procedimento seja realizado por um profissional técnico devido a sua complexidade.

Como ativar a API Operand e gerar o token?

O token gerado no Operand é a chave que permitirá que o sistema, que está recebendo a integração, tenha acesso às informações do Operand. Apenas o responsável da conta (root) e administradores possuem permissão para ativar a API e gerar essa chave.

Para isso, basta acessar o seu Avatar > Configurações > Módulos e funções > API Operand > Gerar token, dessa forma, o sistema irá gerar um token que estará pronto para ser utilizado.

Cada conta pode ter apenas um token ativo por vez, mas é possível gerar um novo token a qualquer momento clicando em gerar um novo token e depois em Confirmar.

Ao gerar um novo token, o anterior será substituído. Caso existam integrações ativas elas serão automaticamente inativadas e será necessário atualizar o código do token nessas integrações para ativá-las novamente.

Também é possível desativar o token se necessário, para isso clique em Desativar Token e depois em Confirmar.

Fazendo isso, o token será invalidado automaticamente. Se houver integrações ativas elas serão automaticamente inativadas e será necessário gerar um novo token e atualizar o código nessas integrações para ativá-las novamente.

Como acessar a documentação da API Pública Operand?

Na página da API Operand, onde foi gerado o token, está disponível a documentação. Nesta documentação estão descritos os métodos e as variáveis que permitirão desenvolver a integração com o sistema que desejar, realizando consultas dentro do Operand e enviando essas informações para o sistema integrado.

Além da documentação disponível dentro do Operand, a documentação técnica completa do módulo de API também pode ser consultada diretamente neste link: Documentação técnica da API Operand.

Quais os passos para realizar a integração?

O profissional técnico responsável pela integração deverá criar um ponto intermediário (módulo integrador) para realizar as conexões dos métodos descritos na documentação com os campos de entrada do sistema que será realizada a integração. Nesse momento serão utilizados o token gerado no Operand e a documentação da API.

Para realizar a integração será necessário seguir os passos:

1. Possuir conhecimento para realizar o procedimento (é recomendado que esse processo seja realizado por um profissional técnico devido a sua complexidade).

2. Definir em qual sistema será realizada a integração e verificar se essa aplicação oferece integração via API.

3. Ler a documentação da API Pública Operand e da API da aplicação que será realizada a integração.

4. Ativar a função API Operand e gerar o token (é necessário que o módulo de API Operand esteja contratado).

5. Gerar o token na aplicação desejada (esse token é necessário para que o módulo integrador, que será desenvolvido, entregue as informações na aplicação desejada).

6. Desenvolver a integração para conectar o Operand à aplicação desejada.

7. Testar a integração.

Se estiver tudo certo, a integração estará pronta para uso! :)

Dica: caso queira realizar a integração mas não tenha alguém capacitado no time, é possível contratar uma empresa ou profissional qualificado para realizar o procedimento. Nós indicamos a Connect Think, parceira que já está familiarizada com a integração da API financeira do Operand com o Asaas e pode ajudar nesse processo. Para orçamento e contratação: (11) 4637-5282 | [email protected]

Quanto custa o módulo de API Operand?

O valor da liberação do módulo de API no sistema é de R$ 50,00 mensais, adicionado à mensalidade do plano contratado. A forma como esse valor é cobrado varia de acordo com o tipo de plano:

Plano Mensal

O valor da API é somado diretamente ao valor da mensalidade.

Exemplo: mensalidade antes da API: R$ 600,00. Mensalidade depois da API: R$ 650,00.

Planos Trimestral, Semestral e Anual

Nesses planos, a forma de cobrança depende do momento em que o módulo é contratado:

• Plano em andamento: o valor da API é multiplicado pelos meses restantes até a renovação do plano e dividido pelas parcelas ainda em aberto.

  Exemplo: R$ 50,00 x 4 (meses até a renovação) ÷ 2 (parcelas restantes) = R$ 100,00 adicionados em cada parcela.

• Plano quitado: o valor da API é multiplicado pelos meses até a próxima renovação do plano e cobrado à vista.

  Exemplo: R$ 50,00 x 3 (meses até a próxima renovação) = R$ 150,00 à vista.

• Renovação de plano: o valor da API é multiplicado pelos meses contratados de acordo com o tipo de plano, e dividido conforme o parcelamento negociado (à vista, 6x, 8x, etc.).

  Exemplo: R$ 50,00 x 12 meses (plano anual) ÷ 8 parcelas = R$ 75,00 adicionados em cada parcela do plano.

API de Projetos e Jobs (fase Beta)

Além da API financeira, que já está disponível e em pleno funcionamento, a Operand está desenvolvendo a API de Projetos e Jobs, que hoje está em fase Beta.

⚠️ Importante: a API de Projetos e Jobs ainda está em fase de testes e validação, e por isso ainda não está liberada para todos os clientes. Se você tem disponibilidade para participar do programa Beta, testando e validando essa API conosco durante um período pré-estabelecido, entre em contato com o seu Customer Success para saber como participar.

O que a API de Projetos e Jobs permite fazer?

De forma geral, essa API permite consultar, criar e atualizar projetos e jobs diretamente a partir de um sistema externo integrado ao Operand.

Projetos:

Jobs:

A documentação técnica completa dessas rotas, com parâmetros, headers de autenticação e exemplos de requisição e resposta, está disponível no mesmo link da documentação técnica da API Operand: Documentação técnica da API Operand.

Importante: por ainda estar em fase Beta, algumas funcionalidades ainda não estão disponíveis nessa API, como a criação de tarefas com atribuição de responsáveis e a extração de dados de horas trabalhadas (timesheet). Esses pontos já estão mapeados para desenvolvimentos futuros.

Webhook de Projetos e Jobs

Além da API, a Operand também está testando o Webhook de Projetos e Jobs, um recurso complementar à API e que também está em fase Beta.

Qual a diferença entre a API e o Webhook?

São duas funcionalidades complementares, mas independentes:

• API: funciona por consulta. Seu sistema "pergunta" para o Operand sempre que precisa de uma informação, e recebe a resposta na hora. Por exemplo: seu sistema de BI quer montar um relatório de jobs em atraso, faz uma chamada para a API e recebe a lista atualizada naquele momento.

• Webhook: funciona de forma automática. Em vez de você precisar consultar, o Operand avisa o seu sistema em tempo real sempre que um evento relevante acontece em um projeto ou job — por exemplo, quando um job muda para o status "Concluído", o Operand dispara automaticamente um aviso para a URL configurada por você (podendo alimentar uma automação, um Slack, um CRM, etc.).

É possível usar a API sem o Webhook, dependendo do caso de uso. Sem o Webhook, o cliente busca os dados manualmente sempre que quiser. Com o Webhook ativo, a Operand envia os dados automaticamente assim que algo muda.

Quais eventos posso monitorar via Webhook?

• Projetos: criação, edição/atualização e remoção de projeto.

• Jobs: criação, edição/atualização e remoção de job.

É possível monitorar mais de um tipo de evento no mesmo Webhook: um único endpoint pode receber, simultaneamente, notificações de criação, edição e exclusão de projetos e jobs.

O que é necessário para configurar o Webhook?

1. Ter o módulo de API Operand contratado e habilitado na conta.

2. Ter perfil de administrador, com acesso às configurações do sistema.

3. Ter uma URL HTTPS pública para receber as notificações.

4. Ter um servidor receptor ativo na internet, capaz de processar os eventos recebidos.

Onde configurar o Webhook?

A configuração fica disponível em Configurações > Módulos e Funções > API Operand, habilitando a opção de Webhooks e acessando Configurar Webhook — ou diretamente pelo menu lateral de Configurações > Webhook. As duas formas levam à mesma tela de gerenciamento.

⚠️ Importante: assim como a API de Projetos e Jobs, o Webhook ainda está em fase Beta e a liberação do menu de Webhooks depende de participação no programa Beta. Se você tem interesse e disponibilidade para testar, entre em contato com o seu Customer Success.

Dúvidas comuns sobre o Webhook

• O módulo Webhooks não aparece no sistema: verifique se o módulo de API Operand está habilitado em Configurações > Módulos e Funções > API Operand.

• Erro 401 na autenticação: confirme se a chave (hash) usada no servidor do seu sistema corresponde exatamente à chave gerada no momento do cadastro do Webhook.

• Recebimento de eventos duplicados: para evitar o processamento repetido de um mesmo evento, recomendamos implementar idempotência no seu endpoint, usando um identificador único por evento.