Como usar a API Calcme para integrar outros sistemas

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.

O que é a API 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

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.

Como encontrar a API no Calcme

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.

1. Clique no nome do usuário, no topo à direita.

2. Acesse Usuários.

3. Localize o usuário dedicado à integração e clique em Editar.

4. 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.

Como gerar o token

1. Na aba API Calcme, clique em Gerar token de API.

2. Copie o token assim que ele for exibido.

3. Guarde-o em um gerenciador de segredos ou variável de ambiente da aplicação.

4. 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.

Como autenticar uma chamada

Use esta URL base:

https://serv.calcme.com.br

As rotas da versão atual começam por:

/api/open/v1

Envie o token em todas as chamadas no header:

X-CalcMe-Api-Token: SEU_TOKEN

Exemplo 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.

Como consultar rotas, filtros e exemplos

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.

Áreas disponíveis

• 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.

Paginação e respostas

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": []
}

Erros mais comuns

• 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.

Empresa e permissões

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.

O que não está incluído nesta versã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.

Como acompanhar o uso

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.

Checklist antes de colocar em produção

• 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.

Precisa de ajuda?

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.

Falar com a equipe Calcme