Adjulo — SDK Java

SDK Java officiel de l'API Adjulo, la solution souveraine de veille des marchés publics québécois (SEAO) et fédéraux (CanadaBuys).

L'intelligence des marchés publics.

• Java 11+ — s'appuie sur java.net.http.HttpClient (JDK) et Jackson (JsonNode).
• Auth : clé API via en-tête X-API-Key (obtenue depuis le portail Adjulo).
• Retry automatique sur 429/5xx, hiérarchie d'exceptions typées.

---

Installation (Maven)

<dependency>
  <groupId>ca.adjulo</groupId>
  <artifactId>adjulo-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle :

implementation 'ca.adjulo:adjulo-sdk:0.1.0'

---

Démarrage rapide

import ca.adjulo.sdk.AdjuloClient;
import ca.adjulo.sdk.QueryParams;
import com.fasterxml.jackson.databind.JsonNode;

AdjuloClient client = new AdjuloClient("adj_votre_cle"); // ou via ADJULO_API_KEY

// Lister des appels d'offres — réponse { "data": [...], "meta": {...} }
JsonNode page = client.appelsOffres().list(
        QueryParams.of().add("q", "informatique").add("per_page", 20).add("source", "seao"));
for (JsonNode ao : page.get("data")) {
    System.out.println(ao.get("titre").asText());
}

// Détail d'un appel d'offres
JsonNode ao = client.appelsOffres().get("SEAO-123456");

// Recherche sémantique (embeddings e5) — plan Pro/Entreprise
JsonNode res = client.appelsOffres().searchSemantique("déneigement de rues", 10);

// Taux de succès réel d'un fournisseur (gagnés/soumis) — plan Pro
JsonNode taux = client.fournisseurs().tauxSucces("FO-000123");

// Consommation de votre compte
System.out.println(client.compte().usage());

Configuration avancée via le builder :

AdjuloClient client = AdjuloClient.builder()
        .apiKey("adj_votre_cle")
        .baseUrl("https://api.adjulo.io")   // défaut ; ou ADJULO_BASE_URL
        .maxRetries(3)
        .timeout(java.time.Duration.ofSeconds(30))
        .build();

La clé API et l'URL de base peuvent provenir de l'environnement (ADJULO_API_KEY, ADJULO_BASE_URL).

---

Ressources disponibles

Accès	Méthodes
client.appelsOffres()	list · listAll · get · categories · search · searchSemantique · soumissionnaires · contexte
client.fournisseurs()	top · recherche · tauxSucces · concurrents · contrats · goldProfile
client.organismes()	search · searchSemantique · stats
client.stats()	avenants · greAGre · secteurTendances
client.recherche()	contrats · unspsc · scian (recherche sémantique des référentiels)
client.vibe()	opportunites · soumissions · feedback (InsightsVibe)
client.compte()	usage · plans
client.publicApi()	dashboard · contratsRecents · annonces · tendances · version · servicesCatalogue (sans clé)

Échappatoire générique

Tout endpoint non exposé par une méthode dédiée reste accessible :

client.get("/v1/f2f/concurrents", QueryParams.of().add("limit", 5));
client.post("/v1/vibe/feedback", java.util.Map.of("ao_id", "…", "outcome", "gagne"));
JsonNode node = client.request("GET", "/v1/usage", null, null);

Désérialisation typée :

MonDto dto = client.get("/v1/public/version", null, MonDto.class);

---

Gestion des erreurs

Toutes les erreurs héritent de AdjuloException (non vérifiée).

import ca.adjulo.sdk.exception.*;

try {
    client.fournisseurs().tauxSucces("FO-000123");
} catch (AuthenticationException e) {   // 401
    // clé absente/invalide/expirée
} catch (PermissionException e) {        // 403
    // plan insuffisant / abonnement requis
} catch (RateLimitException e) {         // 429
    // e.getRetryAfter() si fourni
}

Exception	HTTP
AuthenticationException	401
PermissionException	403
NotFoundException	404
RateLimitException	429
ServerException	5xx
AdjuloApiException	autres 4xx

---

Développement & tests

mvn test        # tests unitaires (serveur HTTP local du JDK, sans réseau)

Les tests d'intégration live (LiveTest) frappent une API réelle et sont ignorés tant que les variables ne sont pas définies :

export ADJULO_API_KEY="adj_…"
export ADJULO_BASE_URL="https://dev-api.adjulo.io"
mvn test

---

Licence

Propriétaire — © Adjulo. info@adjulo.ca