Envoyer les commandes de cueillette à Aillo

Cette API transmet les commandes attendues à une succursale. Elle ne crée pas de demande d’arrivée et n’envoie pas de texto à l’équipe à elle seule.

Adresse et authentification

POST /api/v1/expected-pickups

Authorization: Bearer ak_YOUR_PICKUP_KEY
Content-Type: application/json

Créez la clé de succursale dans API et webhooks. Copiez-la une seule fois et gardez-la sur votre serveur, jamais dans le code public du navigateur. Une clé révoquée reçoit immédiatement 401. La succursale provient de la clé; les identifiants d’entreprise et autres champs inconnus du corps sont ignorés.

Champs de la commande

Champ	Présence	Règles
`order_number`	Obligatoire	Chaîne sans espaces aux extrémités, de 1 à 40 caractères. Conservez les zéros initiaux.
`customer_name`	Obligatoire pour upsert	Chaîne sans espaces aux extrémités, de 1 à 80 caractères. Facultative pour cancel; maximum 80 si fournie.
`phone`	Facultatif	Téléphone nord-américain, chaîne de 40 caractères maximum. Absent, null ou vide signifie aucun téléphone. Une valeur inutilisable est ignorée, sans rejet de la commande.
`pickup_date`	Facultatif	YYYY-MM-DD. Absent, null ou vide : aujourd’hui dans business_settings.timezone (Toronto par défaut).
`action`	Facultatif	"upsert" par défaut, ou "cancel".

Formats de téléphone et avertissements

(263) 555-0101, 263-555-0101, +1 263 555 0101 → +12635550101

Les caractères non numériques sont retirés. Dix chiffres reçoivent +1; onze chiffres commençant par 1 reçoivent +. L’indicatif régional doit commencer par 2 à 9. Les autres valeurs, dont les chaînes de plus de 40 caractères, sont enregistrées comme null. Pour un upsert avec un téléphone fourni mais inutilisable, la commande est enregistrée avec HTTP 200 et phone_ignored. Sans téléphone, cette commande ne peut pas être reconnue par le numéro de l’appelant.

{"ok":true,"upserted":1,"cancelled":0,"orders":[{"order_number":"1001","pickup_date":"2026-10-13","warnings":["phone_ignored"]}]}

Le tableau orders est présent seulement si au moins un élément a un avertissement. Il contient alors tous les éléments traités avec order_number, pickup_date et warnings (vide pour les autres). Un téléphone absent, null ou vide et une action cancel ne produisent pas cet avertissement.

Lots, mise à jour et annulation

Envoyez un objet JSON ou un tableau non vide de 500 objets maximum. Tous les éléments sont validés avant une transaction unique; un élément invalide rejette le lot entier.

upsert crée ou met à jour la même succursale + order_number + pickup_date, sans doublon. Renvoyez le nom et le téléphone actuels; omettre phone lors d’une mise à jour efface le téléphone enregistré. cancel supprime la commande de cette succursale à cette date précise; customer_name et phone ne sont pas nécessaires.

{"order_number":"1001","action":"cancel"}

Fenêtre de dates incluse : aujourd’hui moins 1 jour jusqu’à aujourd’hui plus 14 jours, dans le fuseau configuré de la succursale. Réussite : HTTP 200 avec ok, upserted et cancelled; annuler une commande absente donne cancelled: 0.

Limites et erreurs

Limite du corps : 256000 pour Content-Length déclaré (octets) et la longueur du texte JavaScript décodé. Les valeurs Content-Type commençant par application/json sont acceptées, y compris les paramètres charset.

400 — invalid_json, too_many_items, invalid_request: les erreurs de validation ont un tableau fields avec des chemins comme items[0].customer_name; rien n’est enregistré.
401 — unauthorized: clé Bearer absente, incorrecte ou révoquée.
413 — payload_too_large (maxBytes).
415 — invalid_content_type.
500 — server_error: échec de l’écriture en base de données.

Exemple : une commande pour aujourd’hui

curl -X POST 'https://app.aillo.ca/api/v1/expected-pickups' \
  -H 'Authorization: Bearer ak_YOUR_PICKUP_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"order_number":"1001","customer_name":"Test","phone":"(263) 555-0101"}'

Remplacez l’adresse et la clé fictive par votre adresse Aillo et la clé de succursale.