Usando a API com um agente de IA

Um agente de IA usa a API do Fácil123 de um jeito diferente de uma integração tradicional. A integração é escrita uma vez, contra um schema que o desenvolvedor leu antes: ela já sabe quais campos existem e quais permissões tem. O agente descobre tudo isso na hora, tentando, e é aí que ele erra: inventa nome de campo, tenta adivinhar se pode fazer algo, insiste numa chamada que nunca vai funcionar.

Este artigo reúne as regras que evitam esses erros. Todas elas estão detalhadas nos outros artigos da seção API, e no fim tem um bloco pronto para você colar nas instruções do seu agente.

Escolhendo o token

O tipo de token muda quem o agente é dentro do sistema:

Token pessoal
Autentica como você mesmo, com as suas permissões. É a escolha quando o agente resolve tarefas em seu nome, porque tudo que ele fizer aparece na auditoria como sendo seu. Veja Tokens pessoais.

Token de API
Funciona como um usuário próprio, com permissões configuradas à parte. É a escolha quando o agente é parte de um sistema que integra com o Fácil123, e não o assistente de uma pessoa. Veja Gerando e usando seu token de API.

Prefira o token pessoal para um agente que trabalha ao seu lado, e limite as permissões dele ao que a tarefa exige. O agente nunca tem mais acesso do que o usuário do token.

Descobrindo o schema em vez de adivinhar

Nenhum agente precisa (nem deve) adivinhar nomes de campos: o schema é consultável em tempo de execução, e é isso que separa uma chamada correta de uma tentativa e erro. Duas ferramentas resolvem quase tudo:

Introspecção, para descobrir queries, mutations, campos, tipos e os valores aceitos por cada enum. Veja Explorando a API por introspecção.
Templates getNewXXX, que devolvem um registro novo já preenchido com os valores padrão do sistema. Em vez de descobrir campo por campo o que uma mutation exige, o agente parte do template e altera só o que precisa. Veja Usando templates de novos registros na API.

Instrua o agente a consultar o schema antes de escrever a primeira chamada de um recurso novo, e não depois de errar.

Descobrindo os nomes das permissões

As permissões de acesso que você vê na tela em português têm um nome técnico na API. O schema publica a lista completa no enum AccessScopeEnum, cada valor com a sua descrição:

{
  __type(name: "AccessScopeEnum") {
    enumValues {
      name
      description
    }
  }
}

A resposta traz pares como invoice_update para Venda → Alterar, e mdfe_list para MDF-e → Listar. É a tradução entre o que aparece na tela de Permissão de Acesso e o que a API usa, e serve tanto para o agente entender uma mensagem de erro quanto para você conferir uma permissão específica.

Reagindo aos erros em vez de prevê-los

Este é o ponto onde os agentes mais tropeçam. Um agente tende a querer saber de antemão se pode fazer algo, e a API do Fácil123 não é feita para isso: ela é feita para responder claramente quando não pode.

Não calcule permissões. O campo denied_access_scopes do usuário lista o que está bloqueado, e é tentador compará-lo com a lista completa de permissões para deduzir o que está liberado. Essa conta erra em silêncio, porque uma permissão liberada ainda pode estar barrada por um app não instalado.

Faça a chamada e leia o erro. Se o acesso não existe, a resposta é um FORBIDDEN que nomeia a causa: required_scope quando é a permissão do usuário, required_apps quando é app não instalado. Isso já é suficiente para o agente saber que não deve seguir por ali, e para reportar exatamente o que precisa ser liberado.

Não insista. FORBIDDEN, PLAN_EXCEEDED, NOT_FOUND e UNPROCESSABLE devolvem o mesmo resultado em toda tentativa. Repetir só consome a cota de requisições. O único erro que pede nova tentativa é o 429, e depois de esperar o tempo indicado no Retry-After.

Não improvise caminho alternativo. Um agente que recebe um FORBIDDEN costuma tentar outra query para chegar ao mesmo dado. Isso multiplica requisições e não muda o resultado, porque a permissão vale para o dado, não para a rota.

Veja Entendendo os erros da API para o catálogo completo.

Respeitando o limite de requisições

Um agente em repetição é a forma mais rápida de estourar a cota, porque ele dispara chamadas em bloco. São 300 requisições por minuto e 30 a cada 5 segundos, os dois valendo ao mesmo tempo. Prefira uma query maior a várias pequenas, que é justamente o que o GraphQL faz bem. Veja Limite de requisições da API.

Nomeando as operações

Toda query ou mutation deve ter um nome de operação formado pelo nome da sua empresa e pela chamada usada, como query padariaDoJoao_getProducts. É assim que identificamos as chamadas da sua integração nos nossos registros quando você precisa de suporte. Operações anônimas funcionam, mas dificultam o atendimento.

Copiando as instruções para o seu agente

O bloco abaixo resume as regras deste artigo. Cole nas instruções do seu agente (o AGENTS.md, CLAUDE.md ou o campo de instruções da ferramenta que você usa):

## API do Fácil123

- Endpoint: POST https://app.facil123.com.br/graphql. Só POST, com a query no corpo.
- Autentique com `Authorization: Bearer <TOKEN>` e envie `Accept: application/json`.
- Nomeie toda operação com o nome da empresa seguido da chamada: `query minhaEmpresa_getProducts { ... }`.
- Antes de usar um recurso novo, descubra o schema por introspecção (`__type`, `__schema`).
  Nunca invente nome de campo.
- Para criar registros, comece pela query `getNewXXX` correspondente, que devolve os valores
  padrão, e altere só o que a tarefa exige.
- Nunca tente deduzir permissões a partir de `denied_access_scopes`. Faça a chamada e leia o erro.
- Erros vêm no array `errors`, com o código em `extensions.code`. O status HTTP `200` não
  significa sucesso: verifique sempre se veio `errors`.
- `FORBIDDEN` significa parar. O `extensions.required_scope` diz qual permissão falta e o
  `extensions.required_apps` diz qual app precisa ser instalado. Reporte isso ao usuário
  e não tente rota alternativa para o mesmo dado.
- `UNPROCESSABLE` significa corrigir os dados: `extensions.errors` traz o problema por atributo,
  e em coleções a lista segue a ordem dos itens enviados.
- `NOT_FOUND` é registro inexistente, `PLAN_EXCEEDED` é limitação do plano. Nenhum dos dois se
  resolve com nova tentativa.
- `429` é o único erro que pede nova tentativa: espere o tempo do cabeçalho `Retry-After`.
  Limites: 300 requisições por minuto e 30 a cada 5 segundos.
- Prefira uma query maior a várias pequenas, e pagine cargas grandes com intervalo entre páginas.

Perguntas e respostas

1 - O agente pode fazer mais do que eu no sistema?
R: Não. Ele age com as permissões do usuário do token, então nunca alcança nada além do que esse usuário alcança. Se você usa um token pessoal, o limite é o seu próprio acesso.

2 - Como sei o que o agente fez?
R: As ações feitas por token aparecem na auditoria como as de qualquer usuário. Veja Auditoria.

3 - O agente reclamou que não consegue ver um dado, mas eu vejo na tela. Por quê?
R: Provavelmente ele está usando um token de API, que é um usuário próprio, com permissões configuradas à parte das suas. Confira as permissões desse usuário na tela de Permissão de Acesso, ou troque para um token pessoal, que usa o seu acesso.