{ "basePath": "/v1", "definitions": {}, "host": "sandbox.api.dropcolis.ca", "info": { "contact": { "email": "info@dropcolis.ca", "name": "Dropcolis Support", "url": "https://dropcolis.ca" }, "description": "API de livraison de colis pour partenaires - Service de livraison innovant au Qu\u00e9bec", "termsOfService": "https://dropcolis.ca/terms", "title": "Dropcolis Partner API (Sandbox)", "version": "1.0.0", "x-logo": { "altText": "Dropcolis", "url": "/static/images/logo.png" } }, "paths": { "/auth/api-keys": { "get": { "description": "Requires partner authentication (session or headers)
", "parameters": [ { "in": "header", "name": "X-Partner-Email", "schema": { "type": "string" } }, { "in": "header", "name": "X-Partner-Password", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of API keys" }, "401": { "description": "Authentication required" } }, "summary": "List API keys for a partner", "tags": [ "Authentication" ] }, "post": { "description": "Requires partner authentication (session or email/password)
", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "format": "email", "type": "string" }, "name": { "description": "Optional name for the API key", "type": "string" }, "password": { "format": "password", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "description": "API key created successfully" }, "401": { "description": "Authentication required" } }, "summary": "Create a new API key for a partner", "tags": [ "Authentication" ] } }, "/auth/api-keys/{key_id}": { "delete": { "description": "Requires partner authentication
", "parameters": [ { "in": "path", "name": "key_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Partner-Email", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Partner-Password", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key revoked successfully" }, "401": { "description": "Authentication required" }, "404": { "description": "API key not found" } }, "summary": "Revoke an API key", "tags": [ "Authentication" ] } }, "/auth/login": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "example": "contact@pivohub.com", "format": "email", "type": "string" }, "password": { "example": "securepassword123", "format": "password", "type": "string" } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Login successful" }, "401": { "description": "Invalid credentials" } }, "summary": "Partner login", "tags": [ "Authentication" ] } }, "/auth/logout": { "get": { "responses": { "200": { "description": "Logout successful" } }, "summary": "Partner logout", "tags": [ "Authentication" ] }, "post": { "responses": { "200": { "description": "Logout successful" } }, "summary": "Partner logout", "tags": [ "Authentication" ] } }, "/auth/me": { "get": { "responses": { "200": { "description": "Partner information" }, "401": { "description": "Not authenticated" } }, "summary": "Get current partner info", "tags": [ "Authentication" ] } }, "/auth/register": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "example": "contact@pivohub.com", "format": "email", "type": "string" }, "name": { "example": "PivoHub", "type": "string" }, "password": { "example": "securepassword123", "format": "password", "type": "string" } }, "required": [ "name", "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Partner registered successfully" }, "400": { "description": "Validation error or email already exists" } }, "summary": "Register a new partner", "tags": [ "Authentication" ] } }, "/health": { "get": { "responses": { "200": { "description": "Service is healthy", "schema": { "properties": { "status": { "example": "ok", "type": "string" }, "time": { "example": "Thu, 06 Nov 2025 20:00:00 GMT", "format": "date-time", "type": "string" } }, "type": "object" } } }, "summary": "Health check endpoint", "tags": [ "Health" ] } }, "/orders": { "get": { "parameters": [ { "in": "header", "name": "X-Api-Key", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "integer" } }, { "in": "header", "name": "X-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Filter by status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Maximum number of orders to return", "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer" } }, { "description": "Number of orders to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "description": "List of orders", "schema": { "properties": { "count": { "description": "Number of orders returned", "example": 10, "type": "integer" }, "limit": { "description": "Limit used in query", "example": 50, "type": "integer" }, "offset": { "description": "Offset used in query", "example": 0, "type": "integer" }, "orders": { "description": "Array of order objects", "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "dropoff": { "type": "object" }, "estimated_delivery": { "format": "date-time", "type": "string" }, "order_id": { "example": "dc_9f7a1f2e3d4c5b6a", "type": "string" }, "parcels": { "items": { "type": "object" }, "type": "array" }, "partner_order_id": { "example": "PH-2025-000123", "type": "string" }, "pickup": { "type": "object" }, "rate_cents": { "type": "integer" }, "service_level": { "enum": [ "standard", "express", "same_day" ], "type": "string" }, "status": { "enum": [ "pending", "accepted", "courier_assigned", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed", "cancelled" ], "type": "string" }, "tracking_url": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "401": { "description": "Unauthorized", "schema": { "properties": { "error": { "properties": { "code": { "example": "unauthorized", "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "request_id": { "type": "string" } }, "type": "object" } } }, "security": [ { "ApiKeyAuth": [] }, { "TimestampAuth": [] }, { "SignatureAuth": [] } ], "summary": "List orders for partner", "tags": [ "Orders" ] }, "post": { "description": "
Authentication required: HMAC-SHA256 signature with X-Api-Key, X-Timestamp, and X-Signature headers.

Code examples available in CONSUMER_GUIDE.md (JavaScript, Python, Java, PHP)

", "externalDocs": { "description": "View complete code examples with authentication", "url": "/api-reference" }, "parameters": [ { "description": "Partner API key", "in": "header", "name": "X-Api-Key", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "integer" } }, { "description": "HMAC signature (v1=hex)", "in": "header", "name": "X-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Unique idempotency key", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cod": { "description": "Cash on delivery amount", "properties": { "amount_cents": { "description": "Amount in cents (0 if no COD)", "example": 0, "type": "integer" }, "currency": { "description": "Currency code", "enum": [ "CAD", "USD" ], "example": "CAD", "type": "string" } }, "required": [ "amount_cents", "currency" ], "type": "object" }, "dropoff": { "description": "Delivery destination details", "properties": { "address": { "description": "Delivery address", "properties": { "city": { "description": "City name", "example": "Montr\u00e9al", "type": "string" }, "country": { "description": "Country code (ISO 3166-1 alpha-2)", "enum": [ "CA" ], "example": "CA", "type": "string" }, "line1": { "description": "Street address line 1", "example": "789 Oak Avenue", "type": "string" }, "line2": { "description": "Street address line 2 (optional)", "example": "Apt 5B", "type": "string" }, "notes": { "description": "Delivery instructions", "example": "Ring doorbell, back entrance", "type": "string" }, "postal_code": { "description": "Postal code (Canadian format A1A 1A1)", "example": "H2L1P1", "type": "string" }, "province": { "description": "Province/state code (2 letters)", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", true, "PE", "QC", "SK", "YT" ], "example": "QC", "type": "string" } }, "required": [ "line1", "city", "province", "postal_code", "country" ], "type": "object" }, "email": { "description": "Recipient email address", "example": "john.doe@customer.com", "format": "email", "type": "string" }, "name": { "description": "Recipient name", "example": "John Doe", "type": "string" }, "phone": { "description": "Phone number in E.164 format", "example": "+1-438-555-0002", "type": "string" }, "time_window": { "description": "Delivery time window", "properties": { "end": { "description": "Delivery window end time (ISO 8601)", "example": "2025-11-08T17:00:00-05:00", "format": "date-time", "type": "string" }, "start": { "description": "Delivery window start time (ISO 8601)", "example": "2025-11-08T13:00:00-05:00", "format": "date-time", "type": "string" } }, "required": [ "start", "end" ], "type": "object" } }, "required": [ "name", "phone", "email", "address", "time_window" ], "type": "object" }, "instructions": { "description": "Special delivery instructions (max 1000 characters)", "example": "Call 10 minutes before arrival", "maxLength": 1000, "type": "string" }, "insurance": { "description": "Insurance coverage amount", "properties": { "amount_cents": { "description": "Insurance value in cents (0 if no insurance)", "example": 5000, "type": "integer" }, "currency": { "description": "Currency code", "enum": [ "CAD", "USD" ], "example": "CAD", "type": "string" } }, "required": [ "amount_cents", "currency" ], "type": "object" }, "metadata": { "additionalProperties": true, "description": "Custom metadata key-value pairs (optional)", "example": { "campaign": "summer_sale", "customer_id": "CUST-12345", "order_source": "web", "priority": "high" }, "type": "object" }, "parcels": { "description": "List of packages to be delivered (1-50 parcels)", "items": { "properties": { "barcode": { "description": "Package barcode or tracking number (optional)", "example": "TRACK-12345", "type": "string" }, "description": { "description": "Description of package contents", "example": "Electronics - Laptop", "type": "string" }, "fragile": { "default": false, "description": "Whether package contains fragile items", "example": true, "type": "boolean" }, "height_cm": { "description": "Height in centimeters (0.1-300 cm)", "example": 25, "format": "float", "maximum": 300, "minimum": 0.1, "type": "number" }, "length_cm": { "description": "Length in centimeters (0.1-300 cm)", "example": 40, "format": "float", "maximum": 300, "minimum": 0.1, "type": "number" }, "parcel_id": { "description": "Unique identifier for this parcel", "example": "PKG-001", "type": "string" }, "value_cents": { "description": "Declared value in cents", "example": 150000, "minimum": 0, "type": "integer" }, "weight_kg": { "description": "Weight in kilograms (0.01-70 kg)", "example": 5.5, "format": "float", "maximum": 70, "minimum": 0.01, "type": "number" }, "width_cm": { "description": "Width in centimeters (0.1-300 cm)", "example": 30, "format": "float", "maximum": 300, "minimum": 0.1, "type": "number" } }, "required": [ "parcel_id", "description", "length_cm", "width_cm", "height_cm", "weight_kg", "value_cents" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "partner_order_id": { "example": "PH-2025-000123", "type": "string" }, "pickup": { "description": "Pickup location details", "properties": { "address": { "description": "Pickup address", "properties": { "city": { "description": "City name", "example": "Montr\u00e9al", "type": "string" }, "country": { "description": "Country code (ISO 3166-1 alpha-2)", "enum": [ "CA" ], "example": "CA", "type": "string" }, "line1": { "description": "Street address line 1", "example": "123 Main Street", "type": "string" }, "line2": { "description": "Street address line 2 (optional)", "example": "Suite 100", "type": "string" }, "notes": { "description": "Additional delivery notes or instructions", "example": "Loading dock 3", "type": "string" }, "postal_code": { "description": "Postal code (Canadian format A1A 1A1)", "example": "H1A1A1", "type": "string" }, "province": { "description": "Province/state code (2 letters)", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", true, "PE", "QC", "SK", "YT" ], "example": "QC", "type": "string" } }, "required": [ "line1", "city", "province", "postal_code", "country" ], "type": "object" }, "email": { "description": "Contact email address", "example": "warehouse@company.com", "format": "email", "type": "string" }, "name": { "description": "Business or contact name", "example": "Warehouse Montreal", "type": "string" }, "phone": { "description": "Phone number in E.164 format", "example": "+1-514-555-0001", "type": "string" }, "time_window": { "description": "Pickup time window", "properties": { "end": { "description": "Pickup window end time (ISO 8601)", "example": "2025-11-08T12:00:00-05:00", "format": "date-time", "type": "string" }, "start": { "description": "Pickup window start time (ISO 8601)", "example": "2025-11-08T09:00:00-05:00", "format": "date-time", "type": "string" } }, "required": [ "start", "end" ], "type": "object" } }, "required": [ "name", "phone", "email", "address", "time_window" ], "type": "object" }, "reference": { "example": "SO-55555", "type": "string" }, "service_level": { "enum": [ "standard", "express", "same_day" ], "example": "standard", "type": "string" } }, "required": [ "partner_order_id", "service_level", "pickup", "dropoff", "parcels" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Order created successfully", "schema": { "properties": { "created_at": { "description": "Order creation timestamp", "example": "2025-11-08T08:30:00Z", "format": "date-time", "type": "string" }, "currency": { "description": "Currency code", "example": "CAD", "type": "string" }, "dropoff": { "description": "Delivery location details", "properties": { "address": { "properties": { "city": { "example": "Montreal", "type": "string" }, "country": { "example": "CA", "type": "string" }, "line1": { "example": "789 Oak Avenue", "type": "string" }, "postal_code": { "example": "H2L1P1", "type": "string" }, "province": { "example": "QC", "type": "string" } }, "type": "object" }, "email": { "example": "john.doe@customer.com", "type": "string" }, "name": { "example": "John Doe", "type": "string" }, "phone": { "example": "+1-438-555-0002", "type": "string" }, "time_window": { "properties": { "end": { "example": "2025-11-08T17:00:00-05:00", "format": "date-time", "type": "string" }, "start": { "example": "2025-11-08T13:00:00-05:00", "format": "date-time", "type": "string" } }, "type": "object" } }, "type": "object" }, "estimated_delivery": { "description": "Estimated delivery time", "example": "2025-11-08T17:00:00-05:00", "format": "date-time", "type": "string" }, "order_id": { "description": "Dropcolis order ID", "example": "dc_9f7a1f2e3d4c5b6a", "type": "string" }, "parcels": { "description": "List of parcels", "items": { "properties": { "description": { "example": "Electronics - Laptop", "type": "string" }, "dimensions": { "properties": { "height_cm": { "example": 25, "type": "number" }, "length_cm": { "example": 40, "type": "number" }, "width_cm": { "example": 30, "type": "number" } }, "type": "object" }, "parcel_id": { "example": "PKG-001", "type": "string" }, "value_cents": { "example": 150000, "type": "integer" }, "weight_kg": { "example": 5.5, "type": "number" } }, "type": "object" }, "type": "array" }, "partner_order_id": { "description": "Your order reference", "example": "PH-2025-000123", "type": "string" }, "pickup": { "description": "Pickup location details", "properties": { "address": { "properties": { "city": { "example": "Montreal", "type": "string" }, "country": { "example": "CA", "type": "string" }, "line1": { "example": "123 Main Street", "type": "string" }, "postal_code": { "example": "H1A1A1", "type": "string" }, "province": { "example": "QC", "type": "string" } }, "type": "object" }, "email": { "example": "warehouse@company.com", "type": "string" }, "name": { "example": "Warehouse Montreal", "type": "string" }, "phone": { "example": "+1-514-555-0001", "type": "string" }, "time_window": { "properties": { "end": { "example": "2025-11-08T12:00:00-05:00", "format": "date-time", "type": "string" }, "start": { "example": "2025-11-08T09:00:00-05:00", "format": "date-time", "type": "string" } }, "type": "object" } }, "type": "object" }, "rate_cents": { "description": "Delivery rate in cents", "example": 1499, "type": "integer" }, "service_level": { "description": "Service level", "enum": [ "standard", "express", "same_day" ], "example": "standard", "type": "string" }, "status": { "description": "Order status", "enum": [ "pending", "accepted", "courier_assigned", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed", "cancelled" ], "example": "pending", "type": "string" }, "tracking_url": { "description": "Public tracking URL", "example": "https://api.dropcolis.ca/track/dc_9f7a1f2e3d4c5b6a", "type": "string" }, "updated_at": { "description": "Last update timestamp", "example": "2025-11-08T08:30:00Z", "format": "date-time", "type": "string" } }, "type": "object" } }, "401": { "description": "Unauthorized - Invalid or missing authentication", "schema": { "properties": { "error": { "properties": { "code": { "example": "unauthorized", "type": "string" }, "message": { "example": "Invalid API key or signature", "type": "string" } }, "type": "object" }, "request_id": { "example": "req_abc123def456", "type": "string" } }, "type": "object" } }, "409": { "description": "Order with this partner_order_id already exists", "schema": { "properties": { "error": { "properties": { "code": { "example": "conflict", "type": "string" }, "message": { "example": "Order with partner_order_id 'PH-2025-000123' already exists", "type": "string" } }, "type": "object" }, "request_id": { "example": "req_abc123def456", "type": "string" } }, "type": "object" } }, "422": { "description": "Validation error", "schema": { "properties": { "error": { "properties": { "code": { "example": "validation_error", "type": "string" }, "details": { "description": "Field-specific validation errors", "type": "object" }, "message": { "example": "Invalid request data", "type": "string" } }, "type": "object" }, "request_id": { "example": "req_abc123def456", "type": "string" } }, "type": "object" } } }, "security": [ { "ApiKeyAuth": [] }, { "TimestampAuth": [] }, { "SignatureAuth": [] } ], "summary": "Create a new delivery order", "tags": [ "Orders" ] } }, "/orders/{order_id}": { "get": { "parameters": [ { "description": "Order ID", "in": "path", "name": "order_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Api-Key", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "integer" } }, { "in": "header", "name": "X-Signature", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order details", "schema": { "properties": { "courier": { "description": "Assigned courier details (if assigned)", "properties": { "name": { "example": "Marc Tremblay", "type": "string" }, "phone": { "example": "+1-514-555-9999", "type": "string" }, "vehicle": { "example": "White Van - ABC123", "type": "string" } }, "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "example": "CAD", "type": "string" }, "dropoff": { "properties": { "address": { "type": "object" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "time_window": { "type": "object" } }, "type": "object" }, "estimated_delivery": { "format": "date-time", "type": "string" }, "order_id": { "example": "dc_9f7a1f2e3d4c5b6a", "type": "string" }, "parcels": { "items": { "type": "object" }, "type": "array" }, "partner_order_id": { "example": "PH-2025-000123", "type": "string" }, "pickup": { "properties": { "address": { "type": "object" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "time_window": { "type": "object" } }, "type": "object" }, "rate_cents": { "example": 1499, "type": "integer" }, "service_level": { "enum": [ "standard", "express", "same_day" ], "example": "standard", "type": "string" }, "status": { "enum": [ "pending", "accepted", "courier_assigned", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed", "cancelled" ], "example": "in_transit", "type": "string" }, "status_history": { "description": "Order status history", "items": { "properties": { "notes": { "type": "string" }, "status": { "example": "picked_up", "type": "string" }, "timestamp": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "tracking_url": { "example": "https://api.dropcolis.ca/track/dc_9f7a1f2e3d4c5b6a", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" } }, "401": { "description": "Unauthorized", "schema": { "properties": { "error": { "properties": { "code": { "example": "unauthorized", "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "request_id": { "type": "string" } }, "type": "object" } }, "404": { "description": "Order not found", "schema": { "properties": { "error": { "properties": { "code": { "example": "not_found", "type": "string" }, "message": { "example": "Order dc_9f7a1f2e3d4c5b6a not found", "type": "string" } }, "type": "object" }, "request_id": { "type": "string" } }, "type": "object" } } }, "security": [ { "ApiKeyAuth": [] }, { "TimestampAuth": [] }, { "SignatureAuth": [] } ], "summary": "Get order by ID", "tags": [ "Orders" ] } }, "/orders/{order_id}/cancel": { "post": { "parameters": [ { "description": "Order ID", "in": "path", "name": "order_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Api-Key", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "integer" } }, { "in": "header", "name": "X-Signature", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Order cancelled successfully", "schema": { "properties": { "cancellation_reason": { "description": "Reason for cancellation", "example": "Customer request", "type": "string" }, "cancelled_at": { "description": "Cancellation timestamp", "format": "date-time", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "dropoff": { "type": "object" }, "order_id": { "example": "dc_9f7a1f2e3d4c5b6a", "type": "string" }, "parcels": { "items": { "type": "object" }, "type": "array" }, "partner_order_id": { "example": "PH-2025-000123", "type": "string" }, "pickup": { "type": "object" }, "rate_cents": { "type": "integer" }, "service_level": { "type": "string" }, "status": { "example": "cancelled", "type": "string" }, "tracking_url": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" } }, "400": { "description": "Cannot cancel order in current status", "schema": { "properties": { "error": { "properties": { "code": { "example": "invalid_status", "type": "string" }, "message": { "example": "Cannot cancel order in status 'delivered'", "type": "string" } }, "type": "object" }, "request_id": { "type": "string" } }, "type": "object" } }, "401": { "description": "Unauthorized", "schema": { "properties": { "error": { "properties": { "code": { "example": "unauthorized", "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "request_id": { "type": "string" } }, "type": "object" } }, "404": { "description": "Order not found", "schema": { "properties": { "error": { "properties": { "code": { "example": "not_found", "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "request_id": { "type": "string" } }, "type": "object" } } }, "security": [ { "ApiKeyAuth": [] }, { "TimestampAuth": [] }, { "SignatureAuth": [] } ], "summary": "Cancel an order", "tags": [ "Orders" ] } }, "/partner/orders": { "get": { "responses": { "200": { "description": "List of orders for the partner" }, "401": { "description": "Unauthorized" } }, "summary": "List orders for the currently authenticated partner (session-based)", "tags": [ "Orders" ] } }, "/partner/orders/export": { "get": { "parameters": [ { "description": "Start date (YYYY-MM-DD)", "in": "query", "name": "start_date", "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD)", "in": "query", "name": "end_date", "schema": { "format": "date", "type": "string" } }, { "description": "Filter by status (comma-separated for multiple)", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Filter by service level", "in": "query", "name": "service_level", "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV file download" }, "401": { "description": "Unauthorized" } }, "summary": "Export orders as CSV with flexible filters", "tags": [ "Reports" ] } }, "/partner/reports/monthly": { "get": { "parameters": [ { "description": "Year for report (defaults to current year)", "in": "query", "name": "year", "schema": { "type": "integer" } }, { "description": "Month for report (1-12, defaults to current month)", "in": "query", "name": "month", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Monthly report data" }, "401": { "description": "Unauthorized" } }, "summary": "Get monthly report for billing (volumes, zones, delays)", "tags": [ "Reports" ] } }, "/partner/reports/monthly/export": { "get": { "parameters": [ { "description": "Year for report", "in": "query", "name": "year", "schema": { "type": "integer" } }, { "description": "Month for report (1-12)", "in": "query", "name": "month", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "CSV file download" }, "401": { "description": "Unauthorized" } }, "summary": "Export monthly report as CSV", "tags": [ "Reports" ] } }, "/partner/reports/summary": { "get": { "responses": { "200": { "description": "Summary report data" }, "401": { "description": "Unauthorized" } }, "summary": "Get overall summary report for the partner", "tags": [ "Reports" ] } }, "/rates/quote": { "post": { "parameters": [ { "in": "header", "name": "X-Api-Key", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "integer" } }, { "in": "header", "name": "X-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "dropoff": { "type": "object" }, "parcels": { "type": "array" }, "pickup": { "type": "object" }, "service_level": { "enum": [ "standard", "express", "same_day" ], "type": "string" } }, "required": [ "service_level", "pickup", "dropoff", "parcels" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Rate quote calculated successfully", "schema": { "properties": { "currency": { "description": "Currency code", "example": "CAD", "type": "string" }, "estimated_delivery": { "description": "Estimated delivery date/time", "example": "2025-11-10T17:00:00Z", "format": "date-time", "type": "string" }, "quote_id": { "description": "Unique quote identifier", "example": "qt_abc123def456", "type": "string" }, "rate_cents": { "description": "Delivery rate in cents", "example": 1299, "type": "integer" }, "service_level": { "description": "Service level requested", "enum": [ "standard", "express", "same_day" ], "example": "standard", "type": "string" }, "transit_days": { "description": "Estimated transit time in days", "example": 2, "type": "integer" }, "valid_until": { "description": "Quote expiration time", "example": "2025-11-08T23:59:59Z", "format": "date-time", "type": "string" } }, "type": "object" } }, "401": { "description": "Unauthorized", "schema": { "properties": { "error": { "properties": { "code": { "example": "unauthorized", "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "request_id": { "type": "string" } }, "type": "object" } }, "422": { "description": "Validation error", "schema": { "properties": { "error": { "properties": { "code": { "example": "validation_error", "type": "string" }, "details": { "type": "object" }, "message": { "example": "Invalid request data", "type": "string" } }, "type": "object" }, "request_id": { "example": "req_abc123def456", "type": "string" } }, "type": "object" } } }, "security": [ { "ApiKeyAuth": [] }, { "TimestampAuth": [] }, { "SignatureAuth": [] } ], "summary": "Get rate quote for delivery", "tags": [ "Rates" ] } }, "/shopify/v1/rates": { "post": { "responses": { "200": { "description": "Carrier rates returned." } }, "summary": "5.2 Shopify Carrier Service callback - returns shipping rates at checkout.", "tags": [ "Shopify" ] } }, "/shopify/v1/shops": { "post": { "responses": { "201": { "description": "Shop linked to partner." } }, "summary": "5.1 Link a Shopify shop to a Dropcolis partner via email/password.", "tags": [ "Shopify" ] } }, "/shopify/v1/shops/installed": { "post": { "responses": { "200": { "description": "Shop install state recorded." } }, "summary": "5.0 Idempotent install hook called by Remix app afterAuth.", "tags": [ "Shopify" ] } }, "/shopify/v1/webhooks/app-uninstalled": { "post": { "responses": { "200": { "description": "Uninstall recorded." } }, "summary": "5.5 Shopify app/uninstalled - purge token, keep history.", "tags": [ "Shopify" ] } }, "/shopify/v1/webhooks/dropcolis": { "post": { "responses": { "200": { "description": "Event processed." } }, "summary": "5.4 Dropcolis event-out -> propagate fulfillment to Shopify Admin.", "tags": [ "Shopify" ] } }, "/shopify/v1/webhooks/orders-paid": { "post": { "responses": { "200": { "description": "Order created or already exists." } }, "summary": "5.3 Shopify orders/paid webhook - create a Dropcolis order.", "tags": [ "Shopify" ] } }, "/support": { "get": { "parameters": [ { "in": "query", "name": "status", "schema": { "enum": [ "open", "in_progress", "resolved", "closed" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "description": "List of support tickets" }, "401": { "description": "Authentication required" } }, "summary": "List support tickets for the authenticated partner", "tags": [ "Support" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "message": { "example": "My order dc_abc123 was not delivered on time...", "type": "string" }, "priority": { "default": "medium", "enum": [ "low", "medium", "high", "urgent" ], "type": "string" }, "subject": { "example": "Issue with order delivery", "type": "string" } }, "required": [ "subject", "message" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Support ticket created successfully" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } }, "summary": "Create a new support ticket", "tags": [ "Support" ] } }, "/support/{ticket_id}": { "get": { "parameters": [ { "in": "path", "name": "ticket_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Support ticket details" }, "401": { "description": "Authentication required" }, "404": { "description": "Ticket not found" } }, "summary": "Get a specific support ticket", "tags": [ "Support" ] } }, "/track/{order_id}": { "get": { "parameters": [ { "description": "Order ID", "in": "path", "name": "order_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order tracking information", "schema": { "properties": { "courier": { "description": "Courier information (if assigned)", "properties": { "name": { "description": "Courier name", "example": "Marc Tremblay", "type": "string" }, "phone": { "description": "Courier phone", "example": "+1-514-555-9999", "type": "string" } }, "type": "object" }, "created_at": { "description": "Order creation time", "example": "2025-11-08T08:30:00Z", "format": "date-time", "type": "string" }, "estimated_delivery": { "description": "Estimated delivery time", "example": "2025-11-08T17:00:00Z", "format": "date-time", "type": "string" }, "order_id": { "description": "Dropcolis order ID", "example": "dc_9f7a1f2e3d4c5b6a", "type": "string" }, "partner_order_id": { "description": "Partner's order reference", "example": "PH-2025-000123", "type": "string" }, "service_level": { "description": "Service level", "enum": [ "standard", "express", "same_day" ], "example": "standard", "type": "string" }, "status": { "description": "Current order status", "enum": [ "pending", "accepted", "courier_assigned", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed", "cancelled" ], "example": "in_transit", "type": "string" }, "status_display": { "description": "Human-readable status", "example": "In Transit", "type": "string" }, "status_history": { "description": "Order status history", "items": { "properties": { "notes": { "description": "Additional notes", "example": "Package collected from warehouse", "type": "string" }, "status": { "description": "Status at this point", "example": "picked_up", "type": "string" }, "timestamp": { "description": "When status changed", "example": "2025-11-08T10:30:00Z", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "tracking_url": { "description": "Public tracking page URL", "example": "https://api.dropcolis.ca/track/dc_9f7a1f2e3d4c5b6a/html", "type": "string" }, "updated_at": { "description": "Last update time", "example": "2025-11-08T14:45:00Z", "format": "date-time", "type": "string" } }, "type": "object" } }, "404": { "description": "Order not found", "schema": { "properties": { "error": { "properties": { "code": { "example": "not_found", "type": "string" }, "message": { "example": "Order dc_9f7a1f2e3d4c5b6a not found", "type": "string" } }, "type": "object" } }, "type": "object" } } }, "summary": "Public order tracking endpoint", "tags": [ "Tracking" ] } }, "/track/{order_id}/html": { "get": { "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "Order tracking page" } }, "summary": "Public order tracking page (HTML) - Shareable link for customers", "tags": [ "Tracking" ] } }, "/webhooks/status-update": { "post": { "description": "
This endpoint allows external services (like Dropcolis service) to update
order status in real-time. The webhook must be signed with the WEBHOOK_SECRET.

Security:
- Webhook signature verification using WEBHOOK_SECRET
- If partner_id is provided in the webhook payload, verifies the order belongs to that partner
- This ensures partners can only update their own orders

Webhook Payload Structure:
{
\"type\": \"order.out_for_delivery\",
\"event_id\": \"evt_550e8400...\",
\"created_at\": \"2025-11-08T14:30:00Z\",
\"data\": {
\"order_id\": \"dc_9f7a1f3b2e4d5c6a\",
\"partner_order_id\": \"YOUR-ORDER-123\",
\"status\": \"out_for_delivery\",
\"estimated_delivery\": \"2025-11-08T17:00:00-05:00\",
\"courier\": {
\"name\": \"Jean Dupont\",
\"phone\": \"+1-514-555-1234\"
},
\"note\": \"Optional status update note\"
}
}

Headers:
- Drop-Signature: v1= (required)
- Drop-Event-Id: Unique event identifier
- Drop-Event-Timestamp: Event timestamp

", "parameters": [ { "description": "HMAC-SHA256 signature of the request body", "in": "header", "name": "Drop-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Unique event identifier", "in": "header", "name": "Drop-Event-Id", "required": false, "schema": { "type": "string" } }, { "description": "Event timestamp", "in": "header", "name": "Drop-Event-Timestamp", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Event creation timestamp", "example": "2025-11-08T14:30:00Z", "format": "date-time", "type": "string" }, "data": { "properties": { "courier": { "description": "Courier information", "properties": { "name": { "example": "Jean Dupont", "type": "string" }, "phone": { "example": "+1-514-555-1234", "type": "string" } }, "type": "object" }, "estimated_delivery": { "description": "Estimated delivery time", "example": "2025-11-08T17:00:00-05:00", "format": "date-time", "type": "string" }, "note": { "description": "Optional status update note", "example": "Package is on the way", "type": "string" }, "order_id": { "description": "Dropcolis order ID", "example": "dc_9f7a1f3b2e4d5c6a", "type": "string" }, "partner_id": { "description": "Optional partner ID for ownership verification", "example": "partner-123", "type": "string" }, "partner_order_id": { "description": "Partner's order reference", "example": "YOUR-ORDER-123", "type": "string" }, "status": { "description": "New order status", "enum": [ "pending", "accepted", "courier_assigned", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed", "cancelled" ], "example": "out_for_delivery", "type": "string" } }, "required": [ "order_id", "status" ], "type": "object" }, "event_id": { "description": "Unique event identifier", "example": "evt_550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "type": { "description": "Event type (e.g., order.out_for_delivery)", "example": "order.out_for_delivery", "type": "string" } }, "required": [ "type", "data" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "example": "Order status updated successfully", "type": "string" }, "order_id": { "example": "dc_9f7a1f3b2e4d5c6a", "type": "string" }, "status": { "example": "out_for_delivery", "type": "string" } }, "type": "object" } } }, "description": "Order status updated successfully" }, "400": { "description": "Bad request (invalid payload or missing fields)" }, "401": { "description": "Unauthorized (invalid signature)" }, "403": { "description": "Forbidden (order does not belong to specified partner)" }, "404": { "description": "Order not found" }, "500": { "description": "Server error" } }, "summary": "Webhook endpoint to receive order status updates from external services", "tags": [ "Webhooks" ] } }, "/webhooks/test": { "post": { "description": "
Webhooks notify you in real-time when order status changes. Dropcolis sends webhook
events to your configured endpoint URL with HMAC-SHA256 signature verification.

Webhook Event Types:
- order.accepted: Order accepted by Dropcolis system
- courier.assigned: Courier has been assigned to the order
- order.picked_up: Package has been picked up from origin
- order.in_transit: Package is in transit
- order.out_for_delivery: Package is out for delivery
- order.delivered: Package successfully delivered
- order.failed: Delivery attempt failed
- order.cancelled: Order was cancelled

Webhook Payload Structure:
All webhooks contain:
- type: Event type (e.g., \"order.out_for_delivery\")
- event_id: Unique event identifier (UUID)
- created_at: Event timestamp (ISO 8601)
- data: Event-specific data (order details, status, courier info, etc.)

Webhook Headers:
- Drop-Event-Id: Unique event UUID
- Drop-Event-Timestamp: Event creation time
- Drop-Signature: HMAC-SHA256 signature (v1=hex) for verification
- Content-Type: application/json

Signature Verification:
signature = HMAC_SHA256(webhook_secret, request_body)
Compare with Drop-Signature header to verify authenticity

Example Webhook Payload (order.out_for_delivery):
{
\"type\": \"order.out_for_delivery\",
\"event_id\": \"3e4c2d0a-29c0-4ab5-9f3b-9e77f7c3f9f1\",
\"created_at\": \"2025-11-07T13:15:10Z\",
\"data\": {
\"order_id\": \"dc_9f7a1f3b2e4d5c6a\",
\"partner_order_id\": \"PH-2025-000123\",
\"status\": \"out_for_delivery\",
\"eta\": \"2025-11-07T16:00:00-05:00\",
\"courier\": {
\"name\": \"S. Diop\",
\"phone\": \"+1-514-111-2222\"
}
}
}

Retry Policy:
- Webhooks are retried automatically for up to 24 hours
- Exponential backoff between retries
- Your endpoint should respond with 2xx status code to acknowledge receipt

", "parameters": [ { "in": "header", "name": "X-Api-Key", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "integer" } }, { "in": "header", "name": "X-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "webhook_url": { "description": "URL to send test webhook to", "example": "https://hooks.pivohub.com/dropcolis", "format": "uri", "type": "string" } }, "required": [ "webhook_url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "example": "Test webhook sent", "type": "string" }, "response_code": { "example": 200, "type": "integer" }, "success": { "example": true, "type": "boolean" }, "webhook_payload": { "description": "Example of the webhook payload that was sent", "properties": { "created_at": { "description": "Event creation timestamp (timezone.utc)", "example": "2025-11-07T13:15:10Z", "format": "date-time", "type": "string" }, "data": { "description": "Event-specific data", "properties": { "courier": { "description": "Courier information (when available)", "properties": { "name": { "description": "Courier name", "example": "S. Diop", "type": "string" }, "phone": { "description": "Courier phone number", "example": "+1-514-111-2222", "type": "string" } }, "type": "object" }, "eta": { "description": "Estimated delivery time", "example": "2025-11-07T16:00:00-05:00", "format": "date-time", "type": "string" }, "order_id": { "description": "Dropcolis order ID", "example": "dc_9f7a1f3b2e4d5c6a", "type": "string" }, "partner_order_id": { "description": "Partner's order reference", "example": "PH-2025-000123", "type": "string" }, "status": { "description": "Current order status", "enum": [ "pending", "accepted", "courier_assigned", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed", "cancelled" ], "example": "out_for_delivery", "type": "string" } }, "type": "object" }, "event_id": { "description": "Unique event identifier", "example": "3e4c2d0a-29c0-4ab5-9f3b-9e77f7c3f9f1", "format": "uuid", "type": "string" }, "type": { "description": "Webhook event type", "example": "order.out_for_delivery", "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Test webhook sent successfully" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] }, { "TimestampAuth": [] }, { "SignatureAuth": [] } ], "summary": "Send a test webhook event to your endpoint", "tags": [ "Webhooks" ] } } }, "schemes": [ "https" ], "security": [ { "ApiKeyAuth": [], "SignatureAuth": [], "TimestampAuth": [] } ], "securityDefinitions": { "ApiKeyAuth": { "description": "Partner API key (e.g., pk_test_dropcolis_partner)", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "SignatureAuth": { "description": "HMAC SHA256 signature (v1=hex) - not needed if X-Swagger-Test is true", "in": "header", "name": "X-Signature", "type": "apiKey" }, "TimestampAuth": { "description": "Unix timestamp (seconds) - not needed if X-Swagger-Test is true", "in": "header", "name": "X-Timestamp", "type": "apiKey" } }, "swagger": "2.0", "tags": [ { "description": "Health check endpoints", "name": "Health" }, { "description": "Partner authentication and API key management", "name": "Authentication" }, { "description": "Order management endpoints", "name": "Orders" }, { "description": "Rate quote endpoints", "name": "Rates" }, { "description": "Webhook testing endpoints", "name": "Webhooks" }, { "description": "Public order tracking endpoints", "name": "Tracking" }, { "description": "Support ticket management for partners", "name": "Support" }, { "description": "Shopify integration endpoints (install, rates, webhooks)", "name": "Shopify" } ] }