Documentazione della Provider API

Per iniziare

JSON su HTTPS. Invia una chiamata per cliente ogni volta che cambia il suo interruttore. Ogni chiamata si può ripetere senza rischi.

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

Endpoint

Riprovare è sicuro

Le chiamate con lo stesso externalId aggiornano quel cliente. Non creano mai duplicati, quindi puoi riprovare dopo un timeout.

Autenticazione

Invia la tua chiave nell'header Authorization di ogni richiesta. Le chiavi iniziano con anp_, sono mostrate una sola volta e si possono ruotare nella pagina delle chiavi API.

Authorization: Bearer anp_…

Attiva o aggiorna un cliente

POST/provider/clients

Invia i dati del cliente quando il suo interruttore si attiva. Ripetere la chiamata con lo stesso externalId aggiorna quel 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
  }'

Risposta

Ogni chiamata restituisce lo stato del cliente, il numero di annunci e il piano.

{
  "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"
}

Consultare lo stato di un cliente

GET/provider/clients/{externalId}

Restituisce lo stato attuale del cliente, il numero di annunci e il piano, nello stesso formato della risposta di attivazione.

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

Disattiva un cliente

DELETE/provider/clients/{externalId}

Eliminare un cliente lo disattiva e ritira i suoi annunci da Anuto.

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

Segnalare le modifiche

POST/provider/clients/{externalId}/changes

Chiamalo ogni volta che lo stock di un cliente cambia: un annuncio viene creato, modificato, venduto o eliminato. Risincronizziamo quel cliente entro pochi minuti, invece di aspettare la sincronizzazione periodica ogni poche ore. Le chiamate entro 5 minuti vengono unite, quindi puoi chiamarlo a ogni modifica.

• Il corpo è facoltativo. Aggiungi itemIds per indicare fino a 100 ID dei tuoi immobili o prodotti modificati.
• Una chiamata riuscita restituisce 202. nextSyncAt è l'ora (UTC) in cui è programmata la risincronizzazione.
• Per un cliente inattivo la risposta contiene queued: false e un messaggio. Non viene messo nulla in coda.

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"
}

Verificare la chiave

GET/provider/me

Restituisce il nome del tuo fornitore, i formati coperti dal tuo accesso e lo stato della chiave. Chiamalo per primo per verificare che una nuova chiave funzioni.

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

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

Modalità test

Imposta test su true per validare i dati e controllare la connessione. Non viene creato nulla: ottieni lo stato che avrebbe e l'esito dei controlli.

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

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

Stati del cliente

• activeAttivo e sincronizzato.
• pendingLa connessione non funziona ancora, quindi non si pubblica nulla.
• reviewAnuto lo sta verificando, perché l'email di questo nuovo cliente appartiene già a un altro account Anuto.
• inactiveDisattivato da te o rimosso da Anuto.

Errori

Le chiamate non riuscite restituiscono JSON con statusCode, code e message. Gestisci gli errori in base a code; message è per le persone.

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

Limiti di frequenza

Se superi il limite ricevi 429 con l'header Retry-After. Aspetta quel numero di secondi, poi riprova.