Parâmetros globais

Estes parâmetros podem ser usados com qualquer endpoint da API.

Parâmetro	Tipo	Padrão	Descrição
`x_api_key`	`string`	-	Chave de autenticação obrigatória para todos os pedidos. Passe-a no cabeçalho `x-api-key` ou como parâmetro de query string.
`soft_fail`	`boolean`	`false`	Quando `true`, a API devolve HTTP 200 mesmo quando ocorre um erro. Os erros continuam a ser registados e faturados normalmente.
`is_async`	`boolean`	`false`	Quando `true`, o pedido é processado de forma assíncrona. A resposta contém um `job_id` que deve consultar em `/jobs/{job_id}`.
`fields`	`string`	-	Lista de campos separados por vírgulas a incluir na resposta. Suporta campos aninhados com notação por ponto.

Filtragem de campos

Use o parâmetro fields para manter apenas os dados que realmente precisa na resposta. Isso torna as respostas menores, mais rápidas para baixar e mais fáceis de processar do seu lado. É especialmente útil quando sua plataforma impõe um limite de tamanho de payload (Make.com, Zapier, Lambdas com pouca memória, etc.).

Sintaxe

Passe fields como uma lista separada por vírgulas. Use um ponto (.) para descer em um objeto aninhado.

Campos de primeiro nível são listados pelo nome: fields=name,founded.
Campos aninhados usam notação por ponto: fields=address.city,address.country.
Espaços ao redor das vírgulas são ignorados: fields=name, founded funciona da mesma forma.
Nomes de campo desconhecidos são ignorados silenciosamente, nenhum erro é retornado.

Selecionar campos de primeiro nível

Mantenha apenas as chaves de primeiro nível que lhe interessam. A estrutura original é preservada para os campos mantidos.

curl -X GET "https://api.autom.dev/{endpoint}?param=value&fields=name,founded,tagline" \
  -H "x-api-key: YOUR_API_KEY"

Resposta:

{
  "name": "Example",
  "founded": "2020",
  "tagline": "Just an example"
}

Selecionar campos aninhados

Use a notação por ponto para alcançar objetos aninhados. Apenas os subcampos solicitados são retornados, o resto do objeto pai é descartado. A notação por ponto também funciona para objetos dentro de arrays: ?fields=team.name mantém o name de cada item de team.

curl -X GET "https://api.autom.dev/{endpoint}?param=value&fields=name,location.city,location.country" \
  -H "x-api-key: YOUR_API_KEY"

Resposta:

{
  "name": "Example",
  "location": {
    "city": "Paris",
    "country": "France"
  }
}

Bom saber

A filtragem acontece depois que os dados são obtidos: ela não reduz o custo em créditos da chamada. Ela reduz o tamanho da resposta, o tempo de parsing e a largura de banda.
Chaves de primeiro nível não listadas em fields são removidas da resposta. Listar campos aninhados mantém automaticamente o objeto pai.
Você pode combinar fields livremente com outros parâmetros como soft_fail ou is_async.

Modo soft fail

Trate os erros de forma elegante recebendo sempre um código 200.

Adicione soft_fail=true a qualquer pedido para receber HTTP 200 mesmo quando ocorre um erro.

Os erros continuam a ser registados no seu dashboard e faturados conforme as regras padrão.

Casos de uso

Sistemas que tratam códigos diferentes de 200 como fatais (Make.com, Zapier)
Tratamento de erros personalizado na sua aplicação
Tratamento de erros consistente entre integrações

Nota para utilizadores Make.com: por defeito, os cenários Make.com param com erro quando recebem um código HTTP 404 ou 500. Usar soft_fail=true permite que o seu cenário continue mesmo quando a API devolve um erro, para o tratar nos módulos seguintes.

Exemplo

curl -X GET "https://api.autom.dev/{endpoint}?param=invalid&soft_fail=true" \
  -H "x-api-key: YOUR_API_KEY"

{
  "error": "Not Found"
}

Modo assíncrono

Para pedidos demorados, use o modo assíncrono para evitar timeouts.

Adicione is_async=true para receber imediatamente um job_id.

Como funciona

Envie o pedido com is_async=true
Receba um job_id
Consulte /jobs/{job_id} para obter o resultado

# Passo 1: iniciar o job
curl -X GET "https://api.autom.dev/{endpoint}?param=value&is_async=true" \
  -H "x-api-key: YOUR_API_KEY"
# Resposta: { "job_id": "abc123..." }

# Passo 2: obter o resultado
curl -X GET "https://api.autom.dev/jobs/abc123..." \
  -H "x-api-key: YOUR_API_KEY"

Veja códigos de estado para códigos de resposta, melhores práticas para orientação de integração e tratamento de erros para estratégias de retry.

Nesta página