Démarrer

Démarrage rapide

De la clé d'API au premier colis enlevé, en cinq étapes.

1. Obtenez une clé d'API

Depuis la console Rapidy, ouvrez Intégrations → Clés d'API et créez une clé. Elle commence par pk_.

Le tenant est dérivé de la clé. Aucun en-tête d'organisation à fournir : la clé dit à elle seule pour quelle organisation vous parlez. Une clé de test et une clé de production ne sont pas interchangeables et ne voient pas les mêmes données.

Ne la mettez jamais dans un dépôt, ni dans un bundle JavaScript servi au navigateur : une clé d'API vaut un accès complet à votre organisation.

2. Installez le SDK

Installation

# Rien à installer : l'API est du HTTP + JSON.
curl --version

npm install @rapidy/sdk
# ou : pnpm add @rapidy/sdk

pip install rapidy-sdk

composer require rapidy/sdk

gem install rapidy
# ou, dans un Gemfile : gem 'rapidy'

go get github.com/Smartdev-Africa/rapidy/sdks/go

<dependency>
  <groupId>net.rapidy</groupId>
  <artifactId>rapidy-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

dotnet add package Rapidy.Sdk

dart pub add rapidy_sdk
# Flutter : flutter pub add rapidy_sdk

Aucun SDK n'est obligatoire : l'API est du HTTP et du JSON. Choisissez cURL dans le sélecteur pour voir les requêtes brutes.

3. Construisez le client

Configuration du client

# La clé voyage dans l'en-tête X-Api-Key. Le tenant en est DÉRIVÉ :
# aucun en-tête d'organisation à fournir.
export RAPIDY_API_KEY="pk_live_…"
export RAPIDY_API_URL="https://api.rapidy.net"

import { RapidyClient } from '@rapidy/sdk';

const rapidy = new RapidyClient({
  apiKey: process.env.RAPIDY_API_KEY!,
  baseUrl: 'https://api.rapidy.net',
  // Si votre suivi public est servi sur son propre domaine :
  // trackingBaseUrl: 'https://track.rapidy.net',
});

import os
from rapidy_sdk import RapidyClient

rapidy = RapidyClient(
    api_key=os.environ["RAPIDY_API_KEY"],
    base_url="https://api.rapidy.net",
    # tracking_base_url="https://track.rapidy.net",
)

use Rapidy\Sdk\RapidyClient;

$rapidy = new RapidyClient(
    apiKey: getenv('RAPIDY_API_KEY'),
    baseUrl: 'https://api.rapidy.net',
);

require 'rapidy'

rapidy = Rapidy::Client.new(
  api_key: ENV.fetch('RAPIDY_API_KEY'),
  base_url: 'https://api.rapidy.net'
)

import "github.com/Smartdev-Africa/rapidy/sdks/go/rapidy"

client, err := rapidy.New(rapidy.Options{
    APIKey:  os.Getenv("RAPIDY_API_KEY"),
    BaseURL: "https://api.rapidy.net",
})
if err != nil {
    log.Fatal(err)
}

import net.rapidy.sdk.RapidyClient;

RapidyClient rapidy = RapidyClient.builder()
    .apiKey(System.getenv("RAPIDY_API_KEY"))
    .baseUrl("https://api.rapidy.net")
    .build();

using Rapidy.Sdk;

var rapidy = new RapidyClient(
    apiKey: Environment.GetEnvironmentVariable("RAPIDY_API_KEY")!,
    baseUrl: "https://api.rapidy.net");

import 'package:rapidy_sdk/rapidy_sdk.dart';

final rapidy = RapidyClient(
  apiKey: const String.fromEnvironment('RAPIDY_API_KEY'),
  baseUrl: 'https://api.rapidy.net',
);

trackingBaseUrl n'est utile que si votre suivi public est servi sur son propre domaine. Sinon, il retombe sur baseUrl.

4. Faites partir un colis

Devis → envoi → prêt à enlever

# 1. Devis — `city` est le QUARTIER, pas la ville.
QUOTE=$(curl -s -X POST "$RAPIDY_API_URL/v1/quotes" \
  -H "X-Api-Key: $RAPIDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup":  { "city": "Médina", "address": "Rue 11 x Blaise Diagne" },
    "dropoff": { "city": "Ouakam", "address": "Cité Avion, villa 12" },
    "parcel":  { "weight_kg": 2 }
  }')
QUOTE_ID=$(echo "$QUOTE" | jq -r .quote_id)

# 2. Envoi — `external_order_id` est VOTRE référence.
SHIPMENT=$(curl -s -X POST "$RAPIDY_API_URL/v1/shipments" \
  -H "X-Api-Key: $RAPIDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"quote_id\": \"$QUOTE_ID\", \"external_order_id\": \"CMD-2026-42\" }")
SHIPMENT_ID=$(echo "$SHIPMENT" | jq -r .shipment_id)

# 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
curl -s -X POST "$RAPIDY_API_URL/v1/shipments/$SHIPMENT_ID/mark-ready" \
  -H "X-Api-Key: $RAPIDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "by": "mon-back-office" }'

// 1. Devis — `city` est le QUARTIER, pas la ville.
const quote = await rapidy.createQuote({
  pickup: { city: 'Médina', address: 'Rue 11 x Blaise Diagne' },
  dropoff: { city: 'Ouakam', address: 'Cité Avion, villa 12' },
  parcel: { weightKg: 2 },
});

// 2. Envoi — `externalOrderId` est VOTRE référence de commande.
const shipment = await rapidy.createShipment({
  quoteId: quote.id,
  externalOrderId: 'CMD-2026-42',
});

// 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
await rapidy.markReady(shipment.id, 'mon-back-office');

console.log(shipment.publicTrackingUrl); // à partager au client final

# 1. Devis — `city` est le QUARTIER, pas la ville.
quote = rapidy.create_quote(
    pickup={"city": "Médina", "address": "Rue 11 x Blaise Diagne"},
    dropoff={"city": "Ouakam", "address": "Cité Avion, villa 12"},
    parcel={"weight_kg": 2},
)

# 2. Envoi — `external_order_id` est VOTRE référence de commande.
shipment = rapidy.create_shipment(
    quote_id=quote["quote_id"],
    external_order_id="CMD-2026-42",
)

# 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
rapidy.mark_ready(shipment_id=shipment["shipment_id"], by="mon-back-office")

// 1. Devis — `city` est le QUARTIER, pas la ville.
$quote = $rapidy->createQuote([
    'pickup'  => ['city' => 'Médina', 'address' => 'Rue 11 x Blaise Diagne'],
    'dropoff' => ['city' => 'Ouakam', 'address' => 'Cité Avion, villa 12'],
    'parcel'  => ['weight_kg' => 2],
]);

// 2. Envoi — `external_order_id` est VOTRE référence de commande.
$shipment = $rapidy->createShipment([
    'quote_id'          => $quote['quote_id'],
    'external_order_id' => 'CMD-2026-42',
]);

// 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
$rapidy->markReady($shipment['shipment_id'], by: 'mon-back-office');

# 1. Devis — `city` est le QUARTIER, pas la ville.
quote = rapidy.create_quote(
  pickup: { city: 'Médina', address: 'Rue 11 x Blaise Diagne' },
  dropoff: { city: 'Ouakam', address: 'Cité Avion, villa 12' },
  parcel: { weight_kg: 2 }
)

# 2. Envoi — `external_order_id` est VOTRE référence de commande.
shipment = rapidy.create_shipment(
  quote_id: quote['quote_id'],
  external_order_id: 'CMD-2026-42'
)

# 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
rapidy.mark_ready(shipment_id: shipment['shipment_id'], by: 'mon-back-office')

ctx := context.Background()

// 1. Devis — `city` est le QUARTIER, pas la ville.
quote, err := client.CreateQuote(ctx, map[string]any{
    "pickup":  map[string]any{"city": "Médina", "address": "Rue 11 x Blaise Diagne"},
    "dropoff": map[string]any{"city": "Ouakam", "address": "Cité Avion, villa 12"},
    "parcel":  map[string]any{"weight_kg": 2},
})

// 2. Envoi — `external_order_id` est VOTRE référence de commande.
shipment, err := client.CreateShipment(ctx, map[string]any{
    "quote_id":          quote["quote_id"],
    "external_order_id": "CMD-2026-42",
})

// 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
_, err = client.MarkReady(ctx, shipment["shipment_id"].(string), "mon-back-office")

// 1. Devis — `city` est le QUARTIER, pas la ville.
Map<String, Object> quote = rapidy.createQuote(Map.of(
    "pickup", Map.of("city", "Médina", "address", "Rue 11 x Blaise Diagne"),
    "dropoff", Map.of("city", "Ouakam", "address", "Cité Avion, villa 12"),
    "parcel", Map.of("weight_kg", 2)));

// 2. Envoi — `external_order_id` est VOTRE référence de commande.
Map<String, Object> shipment = rapidy.createShipment(Map.of(
    "quote_id", quote.get("quote_id"),
    "external_order_id", "CMD-2026-42"));

// 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
rapidy.markReady((String) shipment.get("shipment_id"), "mon-back-office");

// 1. Devis — `city` est le QUARTIER, pas la ville.
var quote = await rapidy.CreateQuoteAsync(new Dictionary<string, object>
{
    ["pickup"]  = new Dictionary<string, object> { ["city"] = "Médina", ["address"] = "Rue 11 x Blaise Diagne" },
    ["dropoff"] = new Dictionary<string, object> { ["city"] = "Ouakam", ["address"] = "Cité Avion, villa 12" },
    ["parcel"]  = new Dictionary<string, object> { ["weight_kg"] = 2 },
});

// 2. Envoi — `external_order_id` est VOTRE référence de commande.
var shipment = await rapidy.CreateShipmentAsync(new Dictionary<string, object>
{
    ["quote_id"] = quote["quote_id"]!,
    ["external_order_id"] = "CMD-2026-42",
});

// 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
await rapidy.MarkReadyAsync((string)shipment["shipment_id"]!, "mon-back-office");

// 1. Devis — `city` est le QUARTIER, pas la ville.
final quote = await rapidy.createQuote(CreateQuoteRequest(
  pickup: Address(city: 'Médina', address: 'Rue 11 x Blaise Diagne'),
  dropoff: Address(city: 'Ouakam', address: 'Cité Avion, villa 12'),
  parcel: Parcel(weightKg: 2),
));

// 2. Envoi — `externalOrderId` est VOTRE référence de commande.
final shipment = await rapidy.createShipment(
  CreateShipmentRequest.fromQuote(quoteId: quote.id, externalOrderId: 'CMD-2026-42'),
);

// 3. Prêt à enlever — SANS CE GESTE, AUCUNE COURSE NE PART.
await rapidy.markReady(shipmentId: shipment.id, by: 'mon-back-office');

Trois choses méritent votre attention dans cet extrait :

city est le quartier, pas la ville. C'est lui qui porte la zone tarifaire.
external_order_id est VOTRE référence. Elle vous permet de retrouver l'envoi plus tard sans stocker nos identifiants — voir getShipmentByExternalOrder.
markReady déclenche l'affectation. Sans lui, rien ne part.

5. Suivez la course

Deux surfaces, deux usages :

Vous interrogez getShipment avec votre clé, ou — mieux — vous recevez des webhooks plutôt que d'interroger en boucle.
Votre client ouvre l'URL de suivi public. Elle est anonyme, expurgée de toute donnée personnelle de tiers, et n'exige aucune clé.

Et ensuite

Un paiement à la livraison ? → Paiement
Recevoir les changements d'état ? → Webhooks
Gérer les refus proprement ? → Erreurs