Developer notes

Part of the Colissimo Labels, Pickup Points & Tracking documentation. Previous: Troubleshooting. Next: Conformance with the Colissimo documents.

Add-on id kv_colissimo, namespace Tygh\Addons\KvColissimo, shipping service module kv_colissimo (class Tygh\Shippings\Services\KvColissimo). PHP 7.4 to 8.3, Smarty 4 and 5.

Source map

File	Role
Client/Api.php	The only HTTP code of the provider: SLS (generateLabel, checkGenerateLabel, getLabel), pickup point REST, widget token, timeline tracking, ping().
Client/Sls.php	MIME multipart parser of the label answer, message reader, parcel number reader.
Client/BaseClient.php	cURL (TLS verification on), logging with masking, error mapping.
Parcel.php	Field normalisation: accents, limits, phones, weights, cents, product code, CN23 need.
Customs.php	customsDeclarations block, HS codes, euro conversion, net values with OrderTax.
Shipments.php	Label flows, record-before-call, unknown result, return labels, tracking, request payload.
Points.php	Pickup point search, normalisation, server-side check of the choice, cart and order storage.
Installer.php, RateCalculator.php, Accounts.php, Queue.php, Jobs.php, Access.php	Services, merchant rates, credentials (AES-256-GCM sealed), job queue, vendor rules.

Recurring-defect rules in force: mb_substr for text cuts, per-order GET_LOCK and atomic claims (Idempotency), pending row written before the call, no automatic retry of unknown results or of authentication errors, vendor privilege per action (run_now, cron, backfill closed for vendors) and owner-mode checks (Access::canShip()), Paris time zone for depositDate and the pickup search date, OrderTax for customs values, tracking link with the real number.

PHP hooks: change_order_status_post, get_order_info, place_order, place_suborders, delete_order, template_document_order_context_init, init_templater_post (upgrade synchronizer). Template hooks: orders:tabs_extra, addons:manage, addons:tabs_content, checkout:shipping_method, orders:totals_shipping, index:scripts, index:styles. Pre-controller checkout.pre (a pickup point method needs a chosen point). Frontend dispatches (AJAX POST, never cached): kv_colissimo.widget_token, kv_colissimo.points, kv_colissimo.point_select, and kv_colissimo.cron?key=....

Test override: $config['kv_colissimo_base_url'] = 'http://127.0.0.1:PORT' in config.local.php replaces https://ws.colissimo.fr (and the widget script, jQuery and Mapbox addresses) for the mock server. Remove it afterwards.

Operations and fields

Status: D verified in the document, O verified in the OpenAPI / WADL / WSDL file of the service (saved in tests/fixtures/official), P verified by a live probe of the answer shape (no credentials), F flagged: not verifiable without a contract, see Conformance. Documents: SLS = “Flexibilite - Shipping Web Service”, october 2023 (EN); PR = “Flexibilite - Web service de choix de livraison”, november 2024; WID = “Pick-up Point V2 WIDGET” technical paper, feb 2026; TL = “Specifications timeline tracking web service” v2.6, 13 december 2024.

Shipping web service (REST, base https://ws.colissimo.fr/sls-ws/SlsServiceWSRest/2.0)

Item	Value in the add-on	Source	Status
Operations	POST /generateLabel, POST /checkGenerateLabel, POST /getLabel	WADL resources; OpenAPI paths; SLS II.5	O
Request headers	Content-Type: application/json; Accept: multipart/mixed (generate), application/json (check); header apiKey	WADL apiKey header param; OpenAPI; cxf example in the generateLabel description	O
Credentials in the body	contractNumber, password (marked deprecated in favour of the key)	SLS II.5.2; OpenAPI CheckGenerateLabelRequest	D / O
Key only (no contractNumber)	Header only, body without credentials	OpenAPI says the fields are deprecated; answer for a wrong key is [30000]	F (not provable without a valid key)
outputFormat.x, .y, .outputPrintingType	0, 0, one of PDF_10x15_300dpi, PDF_A4_300dpi, ZPL_10x15_203dpi, ZPL_10x15_300dpi and the _UL variants	SLS II.5.2.1, III.3	D
outputFormat.returnType	SendPDFLinkByMail for return labels with e-mail	SLS II.5.2.1 (“Colissimo Retour only”)	D
letter.service.productCode	DOM, DOS, COM, CDS, HD, CORE	SLS III.1	D
service.depositDate	Y-m-d, not before today (Paris)	SLS II.5.2.2; error 30002	D
service.orderNumber	O<order>-<row> / R<order>-<row>, AN1..30	SLS II.5.2.2	D
service.commercialName	AN, mandatory for HD	SLS II.5.2.2	D
service.transportationAmount, totalAmount	shipping cost in euro cents, CN23 parcels only	SLS II.5.2.2	D
service.returnTypeChoice	3 do not return, 2 priority paid return (outside the EU)	SLS III.5	D
parcel.weight	kg, two decimals, 0.01 to 30	SLS II.5.2.3, III.7	D
parcel.insuranceValue	euro cents, rounded up by Colissimo to 150 / 300 / 500 / 1000 / 2000 / 5000 EUR	SLS II.5.2.3, III.2	D
parcel.pickupLocationId	identifier of the pickup point (HD only)	SLS II.5.2.3	D
parcel.nonMachinable	false for HD	OpenAPI ParcelRequestV2	O
parcel.ftd	true for Overseas France	SLS III.2; OpenAPI	D
parcel.instructions	AN1..35, return reason	SLS II.5.2.3	D
sender.senderParcelRef	AN1..17	SLS II.5.2.5	D
addressee.addresseeParcelRef	AN1..15	SLS II.5.2.6	D
Address fields	companyName AN35, lastName A35, firstName A29, line1 / line2 / line3 AN35, city AN35, zipCode (cut to 10), countryCode A2, phoneNumber, mobileNumber, email AN5..80, language A2	SLS II.5.2.5 / II.5.2.6; OpenAPI Address	D / O (zip: F)
Accents	replaced by the service; non-Latin characters answer an error: the add-on transliterates first	SLS I.5	D
Phone rules	French 0NNNNNNNNN, no 8 equal digits, dummy numbers refused	SLS II.5.2.5	D
customsDeclarations.includeCustomsDeclarations, .numberOfCopies	true, 4	SLS II.5.2.4	D
contents.article[]	description AN1..64, quantity, weight (kg), value (EUR, 2 decimals), hsCode 6 / 8 / 10 digits, originCountry A2, currency EUR, artref AN1..35; at most 100	SLS II.5.2.4, III.5.1; OpenAPI Article	D
contents.category.value	1 gift, 2 sample, 3 commercial, 4 document, 5 other, 6 return	SLS III.5.1	D
contents.explanations	AN1..35 for categories 5 and 6	OpenAPI Contents	O
fields.customField[]	LENGTH, WIDTH, HEIGHT (cm), EORI	SLS II.5.2.7, VII.5 (customField)	D
Answer framing	multipart/related; type="application/json"; boundary="uuid:..."; start="<jsonInfos>"; JSON part Content-ID jsonInfos, binary part label	live probe; OpenAPI description (keys jsonInfos, label, cn23, proforma)	P
jsonInfos	messages[].id / type / messageContent, labelV2Response.parcelNumber / parcelNumberPartner / pdfUrl	SLS VII.2.1.1 sample; OpenAPI GenerateLabelV2Response	D / P
CN23 part	Content-ID cn23	OpenAPI description	O (F for the live Content-ID)
Errors	HTTP 400 with the same multipart framing and messages of type ERROR; check method: plain JSON; 30000, 30013, 50007	live probe; SLS IV	P
Success message	id 0, type INFOS	SLS IV	D
getLabel	body parcelNumber, outputPrintingType; headers apiKey or login + password, accountNumber	OpenAPI GetLabelRequest, WADL	O (answer body F)
pdfUrl	signed address on ws.colissimo.fr, fetched only for that host	SLS VI.2.1.3 sample	D (signature check F)

Pickup point web service (REST, base https://ws.colissimo.fr/pointretrait-ws-cxf/rest/v2/pointretrait)

Item	Value	Source	Status
Operations	POST /findRDVPointRetraitAcheminement, POST /findPointRetraitAcheminementByID	PR II.8 (first), live probe (both paths exist and answer errorCode 201 to a wrong login)	D / P
Credentials	accountNumber + password, or apikey	PR II.2	D
Search request	address, zipCode, city, countryCode, weight (grams), shippingDate (DD/MM/YYYY), filterRelay, requestId, lang, optionInter	PR II.5.1, II.8.1	D
By-id request	id, date, weight, filterRelay, reseau, langue	PR II.6.1	D
Answer	errorCode, errorMessage, listePointRetraitAcheminement[] / pointRetraitAcheminement	PR II.8.2 sample	D
Point fields	identifiant, nom, adresse1..3, codePostal, localite, codePays, typeDePoint, reseau, poidsMaxi, congesTotal, distanceEnMetre, horairesOuvertureLundi..Dimanche, coordGeolocalisationLatitude / Longitude	PR II.8.2 sample	D
Errors	HTTP 400 with errorCode (101 to 146, 201 to 203, 300, 301, 1000)	PR III; live probe (201)	D / P

Widget (browser) and token

Item	Value	Source	Status
Script	https://ws.colissimo.fr/widget-colissimo/js/jquery.plugin.colissimo.min.js, needs jQuery 3.6 and Mapbox GL JS 2.6.1	WID 2.1, 2.4, 2.8, 2.5	D
Token	POST https://ws.colissimo.fr/widget-colissimo/rest/authenticate.rest body {"apikey": "..."}, answer {"token": "..."}, valid 30 minutes, fetched on the server	WID 2.2	D
Parameters	URLColissimo, callBackFrame, ceCountry, ceCountryList, ceLang, ceAddress, ceZipCode, ceTown, origin: "WIDGET", filterRelay, token, dyPreparationTime	WID 2.5 (RG1 to RG11)	D
Callback object	identifiant, reseau read from the selected point	field names of the point web service; widget script	F

Timeline tracking (https://ws.colissimo.fr/tracking-timeline-ws/rest/tracking/timelineCompany)

Item	Value	Source	Status
Request	login + password or apiKey, parcelNumber, lang (en_GB)	TL II.3.1, II.4.2	D
Answer	status[0].code / message, parcel.step[].stepId / status (STEP_STATUS_ACTIVE), parcel.event[].date / code / labelLong / siteName	TL II.3.3, II.4.2	D
Errors	HTTP 200 with status[0].code other than 0: 101, 104 to 107, 303, 401, 403, 666, 1000; 202 / 401 / 403 = credentials refused (not retried, account paused), 666 / 1000 retried	TL II.4.1; live probe (code 202 answered with HTTP 200)	D / P

Tables

kv_colissimo_accounts, _log, _jobs, _shipments (state C created, T in transit, D delivered, P problem, X cancelled, W pending, U unknown), _points.