API do Prospector

Começando em três passos

1. Dentro do sistema, abra Configurações → API e crie um token. O valor completo aparece uma única vez — copie na hora.
2. Marque na criação apenas os escopos de que o seu programa precisa.
3. Chame a API com o token no cabeçalho, como no exemplo abaixo.

curl -s "https://prospector.machinenodes.com.br/api/v1/leads?limit=5" \
  -H "Authorization: Bearer psk_seu_token_aqui"

Autenticação

Todo pedido leva o token no cabeçalho Authorization: Bearer psk_… (o cabeçalho x-api-key também é aceito). Sem token válido a resposta é 401; com token válido mas sem o escopo necessário, 403.

O token responde por uma empresa só — o dado que ele alcança é o daquela conta, e nada além dela.

Endpoints

Endereço-base https://prospector.machinenodes.com.br/api/v1. Esta tabela é gerada a partir da especificação — não existe versão escrita à mão para divergir dela.

Limite de uso

Cada token tem um teto por minuto (padrão 60). Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Ao estourar, a API devolve 429 com Retry-After em segundos — espere esse tempo e repita. Repetir na hora só gasta o teto de novo.

Erros

Erro sempre volta em JSON, com o mesmo formato, e o status HTTP diz o tipo: 400 pedido malformado, 401 sem token, 403 sem escopo, 404 não existe, 429 limite estourado.

{
  "error": {
    "code": "forbidden",
    "message": "Token sem o escopo necessário."
  }
}

Webhooks

Cadastre URLs em Configurações → API para receber eventos assim que acontecem, em vez de ficar perguntando à API. Cada entrega leva o cabeçalho X-Prospector-Signature: sha256=<hmac>, calculado sobre o corpo exato com o segredo daquele endpoint.

Confira a assinatura antes de confiar no conteúdo. Um endereço de webhook é público por natureza: qualquer um pode chamá-lo. A assinatura é o que separa a entrega legítima de uma inventada.