Documentação da Provider API

Primeiros passos

JSON sobre HTTPS. Envie uma chamada por cliente sempre que o interruptor mudar. Cada chamada pode ser repetida sem risco.

URL basehttps://api.anuto.app/v1

Endpoints

Repetir é seguro

As chamadas com o mesmo externalId atualizam esse cliente. Nunca criam duplicados, por isso pode repetir após um timeout.

Autenticação

Envie a sua chave no cabeçalho Authorization de cada pedido. As chaves começam por anp_, são mostradas uma única vez e podem ser renovadas na página de chaves de API.

Authorization: Bearer anp_…

Ativar ou atualizar um cliente

POST/provider/clients

Envie os dados do cliente quando o interruptor for ligado. Repetir a chamada com o mesmo externalId atualiza esse cliente.

curl -X POST https://api.anuto.app/v1/provider/clients \
  -H "Authorization: Bearer $ANUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "12345",
    "name": "Casa Sol Real Estate",
    "email": "[email protected]",
    "phone": "+34 600 000 000",
    "website": "https://casasol.es",
    "country": "ES",
    "listingsCount": 85
  }'

Resposta

Cada chamada devolve o estado do cliente, o número de anúncios e o plano.

{
  "externalId": "12345",
  "clientId": "Xw3kQ9mZr2LpT7vNa4Bc",
  "status": "active",
  "shopUrl": "https://es.anuto.app/@casa-sol",
  "listings": { "active": 10, "waiting": 0, "planWaiting": 75 },
  "plan": { "tier": "free", "maxActive": 10, "freeMaxActive": 10 },
  "upgradeUrl": "https://es.anuto.app/user/manage/plan",
  "lastSyncAt": "2026-10-08T09:30:00.000Z"
}

Consultar o estado de um cliente

GET/provider/clients/{externalId}

Devolve o estado atual do cliente, o número de anúncios e o plano, na mesma forma da resposta à ativação.

curl https://api.anuto.app/v1/provider/clients/12345 \
  -H "Authorization: Bearer $ANUTO_KEY"

Desativar um cliente

DELETE/provider/clients/{externalId}

Eliminar um cliente desativa-o e retira os seus anúncios da Anuto.

curl -X DELETE https://api.anuto.app/v1/provider/clients/12345 \
  -H "Authorization: Bearer $ANUTO_KEY"

Avisar alterações

POST/provider/clients/{externalId}/changes

Chame-o sempre que o stock de um cliente mudar: um anúncio é criado, alterado, vendido ou eliminado. Voltamos a sincronizar esse cliente em minutos, em vez de esperar pela sincronização regular a cada poucas horas. As chamadas feitas em 5 minutos são agrupadas, por isso pode chamá-lo em cada alteração.

• O corpo é opcional. Acrescente itemIds para indicar até 100 IDs dos seus imóveis ou produtos que mudaram.
• Uma chamada bem-sucedida devolve 202. nextSyncAt é a hora (UTC) em que a nova sincronização fica agendada.
• Para um cliente inativo, a resposta traz queued: false e uma mensagem. Nada fica em fila.

curl -X POST https://api.anuto.app/v1/provider/clients/12345/changes \
  -H "Authorization: Bearer $ANUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "itemIds": ["123", "456"] }'

{
  "queued": true,
  "nextSyncAt": "2026-10-08T12:00:00Z"
}

Verificar a sua chave

GET/provider/me

Devolve o nome do seu fornecedor, os formatos abrangidos pelo seu acesso e o estado da chave. Chame-o primeiro para confirmar que uma nova chave funciona.

curl https://api.anuto.app/v1/provider/me \
  -H "Authorization: Bearer $ANUTO_KEY"

{
  "providerId": "Xw3kQ9mZr2LpT7vNa4Bc",
  "name": "Your software company",
  "formats": ["…"],
  "status": "approved"
}

Modo de teste

Defina test como true para validar os dados e verificar a ligação. Nada é criado: recebe o estado que teria e o resultado das verificações.

{
  "externalId": "12345",
  "name": "Casa Sol Real Estate",
  "email": "[email protected]",
  "country": "ES",
  "test": true
}

{
  "ok": true,
  "wouldBe": "active",
  "checks": { "connection": "ok", "owner": "new_account" }
}

Estados do cliente

• activeAtivo e sincronizado.
• pendingA ligação ainda não funciona, por isso nada é publicado.
• reviewA Anuto está a analisar, porque o email deste novo cliente já pertence a outra conta Anuto.
• inactiveDesativado por si ou removido pela Anuto.

Erros

As chamadas com falha devolvem JSON com statusCode, code e message. Decida com base em code; message é para pessoas.

{
  "statusCode": 404,
  "code": "PROVIDER_CLIENT_NOT_FOUND",
  "message": "No client with externalId 12345"
}

Limites de pedidos

Ao ultrapassar o limite recebe 429 com o cabeçalho Retry-After. Espere esse número de segundos e tente de novo.