Use a API Calcme para consultar e manter dados do sistema com segurança, usando um token vinculado a um usuário e respeitando as permissões já configuradas no Calcme.
A API Calcme permite conectar aplicações externas ao Calcme sem usar os endpoints internos da interface. Ela foi criada para integrações administrativas e comerciais, com rotas versionadas, autenticação própria e isolamento dos dados por empresa.
Cada chamada passa por duas validações:
o usuário precisa ter permissão para usar a API;
o usuário também precisa ter a permissão específica da operação, como consultar clientes ou cadastrar produtos.
Se uma permissão for removida, ela deixa de valer nas próximas chamadas. O token não amplia o acesso do usuário.
Consulte seu plano para confirmar se a API Calcme está disponível. Se a API não estiver disponível no seu plano, entre em contato com o Comercial da Calcme para conhecer as opções de habilitação.
Para configurar a API, você precisa de:
um usuário dedicado à integração;
a permissão de uso da API habilitada para esse usuário;
as permissões dos cadastros e operações que a integração utilizará;
um local seguro para guardar o token.
Recomendamos criar um usuário exclusivo para cada integração. Assim, fica mais simples limitar permissões, identificar o uso e revogar o acesso sem afetar uma pessoa da equipe.
Habilite a permissão de uso da API para o usuário dedicado à integração.
Para acessar essa configuração, você precisa ser administrador ou ter no grupo de usuários as permissões para visualizar e editar usuários.
Clique no nome do usuário, no topo à direita.
Acesse Usuários.
Localize o usuário dedicado à integração e clique em Editar.
Dentro do cadastro, abra a aba API Calcme.
Se a aba não aparecer, verifique se o usuário recebeu a permissão de uso da API. Caso você não administre permissões, solicite o ajuste ao administrador ou ao responsável pelas permissões no Calcme.
Na aba API Calcme, clique em Gerar token de API.
Copie o token assim que ele for exibido.
Guarde-o em um gerenciador de segredos ou variável de ambiente da aplicação.
Não envie o token por e-mail, chat, planilha, ticket ou código-fonte.
O token completo aparece somente uma vez. Depois disso, o Calcme mostra apenas o identificador mascarado, a data de criação e o último uso.
Resetar token: invalida o token atual imediatamente e cria outro. Revogar: faz o token deixar de funcionar.
Use esta URL base:
https://serv.calcme.com.brAs rotas da versão atual começam por:
/api/open/v1Envie o token em todas as chamadas no header:
X-CalcMe-Api-Token: SEU_TOKENExemplo de consulta de clientes:
curl --request GET \
--url 'https://serv.calcme.com.br/api/open/v1/people/clients?page=0&size=20' \
--header 'Accept: application/json' \
--header 'X-CalcMe-Api-Token: SEU_TOKEN'Use apenas um token de teste e nunca copie o token real para documentação ou ferramentas compartilhadas.
A aba API Calcme contém o catálogo atualizado da sua versão do sistema. As rotas são organizadas por área e mostram:
método HTTP: GET, POST, PUT ou DELETE;
caminho da rota e descrição da operação;
URL completa;
filtros aceitos e valores de exemplo;
corpo de exemplo nas operações de escrita;
permissão exigida, quando exibida ao perfil autorizado.
Clique em Detalhes em uma rota para ver e copiar a URL, os filtros e o corpo de exemplo. Prefira sempre esse catálogo dinâmico: ele acompanha os campos e as rotas disponíveis no sistema.
Pessoas: clientes, fornecedores, transportadoras, vendedores, funcionários, motoristas e grupos.
Cadastros: produtos simples, grupos, marcas, materiais, veículos, origens de negócio, motivos de perda, condições de pagamento, grupos de preço, tipos de tarefa, tipos de assistência, despesas e status.
Vendas: orçamentos, pedidos e assistências, incluindo itens de produto simples.
Compras: cadastro e manutenção de compras.
Financeiro: contas a pagar e contas a receber.
Tarefas e agenda: tarefas e compromissos.
Painéis: consultas de vendas, financeiro e visão estratégica.
O catálogo exibido no Calcme é a referência para saber quais operações estão disponíveis e quais permissões cada uma exige.
Nas listagens paginadas:
page começa em 0;
size define a quantidade de registros;
use somente os filtros e ordenações mostrados nos detalhes da rota.
As respostas seguem o padrão do Calcme, com o resultado em data e eventuais mensagens em errors:
{
"data": {},
"errors": []
}401 — Não autorizado: token ausente, inválido, revogado ou substituído por um reset.
403 — Sem permissão: usuário, empresa ou operação sem autorização.
404 — Não encontrado: registro inexistente ou indisponível para a empresa do token.
400 — Requisição inválida: filtro, campo ou regra de negócio inválida.
409 — Conflito: duplicidade ou conflito de estado.
500 — Erro interno: falha inesperada; registre horário, rota e identificador da requisição, sem enviar o token.
O token fica vinculado à empresa original do usuário. Trocar a empresa ativa na interface não altera a empresa acessada pela API.
Use o princípio do menor acesso: habilite apenas os módulos e ações necessários. Para uma integração somente de consulta, não libere permissões de cadastro, edição ou remoção.
A API atual não deve ser usada como promessa de acesso a:
emissão fiscal;
cobranças, boletos, Pix ou CalcPay;
PDV;
webhooks externos;
execução de PCP;
exportações de arquivos;
contratos e assinaturas;
itens customizados específicos de determinados módulos ou segmentos;
integrações de terceiros acionadas pela própria API.
Consulte o catálogo da aba API Calcme antes de desenhar a integração.
Perfis autorizados podem abrir Ver uso / logs na aba API Calcme para acompanhar total de chamadas, sucessos, falhas, taxa de sucesso e registros por rota e resultado.
Nunca registre o token completo em logs. Para pedir ajuda, informe:
data e horário da chamada;
método e rota;
código HTTP;
mensagem retornada;
identificador mascarado do token, se necessário.
use um usuário exclusivo para a integração;
limite as permissões ao necessário;
armazene o token em segredo;
teste primeiro com poucos registros;
trate erros sem repetir chamadas em loop;
registre as operações críticas no sistema integrado;
defina como o token será rotacionado e revogado;
valide criação, edição e remoção em ambiente controlado.
Para dúvidas sobre a aba API Calcme, o catálogo ou erros nas chamadas, fale com a equipe Calcme. Não envie o token na conversa.