Visão geral da API

O Fácil123 é uma API baseada em GraphQL que você pode utilizar para:

• Consultar e gerenciar dados de maneira flexível e eficiente.
• Automatizar processos dentro da sua plataforma com chamadas seguras e estruturadas.
• Integrar funcionalidades do Fácil123 diretamente em seus sistemas internos ou produtos digitais.

A API também é o caminho para integrar o Fácil123 com uma ferramenta que não esteja na Loja de Apps, como um CRM, outro ERP ou um agente de IA que atende seus clientes no WhatsApp.

Diferente das APIs REST tradicionais, o GraphQL permite que você defina exatamente os dados que deseja retornar, reduzindo o tráfego e melhorando a performance. Todas as requisições devem ser feitas usando o método POST, com o corpo contendo a query ou mutation no formato JSON.

As respostas da API são retornadas no formato JSON. Você controla o conteúdo da resposta diretamente através da query enviada, sem a necessidade de múltiplas requisições ou endpoints diferentes.

Nomeie suas operações

Toda query ou mutation deve ter um nome de operação, composto pelo nome (ou parte do nome) da sua empresa e pela chamada utilizada:

query padariaDoJoao_getProducts {
  getProducts(page: 1, limit: 100) {
    id
    name
  }
}

Evite a forma anônima ({ getProducts { ... } }): ela funciona, mas dificulta o suporte quando você precisar de ajuda — o nome da operação é como identificamos as chamadas da sua integração nos nossos registros — e operações anônimas poderão receber limites de requisição mais baixos no futuro.

Se você usa uma ferramenta ou agente de IA para gerar as chamadas, inclua essa regra nas instruções: "nomeie toda operação GraphQL com o nome da empresa seguido da chamada usada — por exemplo, query padariaDoJoao_getProducts { ... }". Ela é uma entre várias regras que evitam os erros mais comuns de um agente: veja Usando a API com um agente de IA para o conjunto completo, pronto para colar nas instruções dele.

Para acessar o Fácil123, crie um token de autenticação diretamente na sua conta na plataforma Fácil123. Esse token será utilizado em todas as chamadas à API.

Há dois tipos de token, para casos de uso diferentes:

• Token de API — funciona como um usuário próprio, com permissões configuradas à parte. É a escolha para integrar um aplicativo ou sistema ao Fácil123. Veja Gerando e usando seu token de API.
• Token pessoal — autentica como você mesmo, com as suas permissões. É a escolha para emprestar sua identidade a uma ferramenta ou agente de IA que vai agir em seu nome. Veja Tokens pessoais.

A URL base da API é:

https://app.facil123.com.br/graphql

As requisições autenticadas por token passam por um limite de volume: 300 por minuto e 30 a cada 5 segundos. Se você estourar qualquer um deles, a API responde com 429 Too Many Requests e você deve aguardar antes de continuar. Veja Limite de requisições da API.

Quando algo dá errado, a resposta traz um array errors com um código que diz o que fazer em cada caso. Veja Entendendo os erros da API.