Comece com a API da Operand

🚀

Este guia mostra como autenticar e fazer sua primeira chamada à API Operand. Para o catálogo completo de endpoints, veja a API Reference.

Visão geral

A API Operand permite integrar sistemas externos aos módulos Financeiro (Lançamentos, Faturas, Boletos, Notas Fiscais), Cadastros (Clientes, Veículos, Prestadores, Fornecedores, Colaboradores) e à gestão de Projetos, Jobs, Tarefas e Apontamentos de horas da Plataforma Operand.

Todas as chamadas usam a URL base:

https://api.operand.app/v1

Todas as rotas usam o prefixo /v1, inclusive /login, /checkToken e /cep (por exemplo, https://api.operand.app/v1/financial/bills).

⚠️

A v1 é a versão oficial da API Operand. As rotas /beta (e /login, /checkToken e /cep sem o prefixo /v1) estão deprecated e serão desligadas futuramente. Elas continuam funcionando por enquanto, mas novas integrações devem usar a v1, e as existentes devem migrar.

1. Gere um token de acesso

Gere o tokenAccess na Plataforma Operand, em Módulos e Funções → API Operand.

2. Troque o tokenAccess pelo Op-Auth-Token

Chame o endpoint Abrir uma sessão passando o tokenAccess como query parameter:

curl "https://api.operand.app/v1/login?tokenAccess=SEU_TOKEN_ACCESS"

Guarde o Op-Auth-Token retornado na resposta. Ele autentica todas as próximas chamadas.

⚠️

Se uma chamada responder HTTP 401, o token está ausente, inválido ou a sessão expirou. Refaça o login em /login para obter um novo Op-Auth-Token.

3. Envie o token nas próximas chamadas

Use o header Op-Auth-Token em toda chamada autenticada. Por exemplo, para listar os lançamentos financeiros:

curl "https://api.operand.app/v1/financial/bills" \
  -H "Op-Auth-Token: SEU_OP_AUTH_TOKEN"

Para checar se um token de acesso ainda é válido sem abrir sessão, use Verificar um token de acesso.

Formato das respostas

A v1 responde com o status HTTP real. Confie no status, não no corpo, para saber se a chamada deu certo:

StatusQuando
200Leitura, atualização ou exclusão com sucesso
201Criação com sucesso (projetos, jobs, tarefas, apontamentos e lançamentos; nas demais rotas, a criação responde 200)
400Campo obrigatório ausente ou valor inválido
401Token ausente, inválido ou expirado
403Sem permissão para a ação
404Registro não encontrado
422Regra de negócio (ex.: registro inativo, projeto de outro cliente)
500Erro interno ou serviço indisponível

As respostas de sucesso usam o envelope {meta, records}:

{"meta": {"status": "SUCCESS", "count": 2}, "records": [{"id": 1}, {"id": 2}]}

O formato do corpo de erro varia conforme a rota. Cada operação da API Reference mostra o formato que usa.

Próximos passos


Did this page help you?