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,/checkTokene/cepsem 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:
| Status | Quando |
|---|---|
| 200 | Leitura, atualização ou exclusão com sucesso |
| 201 | Criação com sucesso (projetos, jobs, tarefas, apontamentos e lançamentos; nas demais rotas, a criação responde 200) |
| 400 | Campo obrigatório ausente ou valor inválido |
| 401 | Token ausente, inválido ou expirado |
| 403 | Sem permissão para a ação |
| 404 | Registro não encontrado |
| 422 | Regra de negócio (ex.: registro inativo, projeto de outro cliente) |
| 500 | Erro 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
Detalhes completos do fluxo de login e tokens
Consulte lançamentos, despesas e receitas
Consulte, crie e atualize clientes
Gerencie projetos, jobs e tarefas
Consulte, lance e ajuste as horas apontadas em jobs e tarefas
Updated 25 days ago

