Devis

L’API Devis couvre tout le cycle : création, modification du brouillon, finalisation, téléchargement du PDF, changement de statut et conversion en facture.

Sandbox et production utilisent https://api.yaoka.fr. Pour passer en production, remplacez la clé test et l’identifiant de l’organisation sandbox par la clé live et l’organisation cliente.

Le workflow recommandé

1. Créez le devis avec finalize: false.
2. Enregistrez le quoteId retourné dans votre logiciel.
3. Modifiez le brouillon si nécessaire avec PATCH /api/v1/quotes/{id}.
4. Finalisez-le avec POST /api/v1/quotes/{id}/finalize.
5. Passez-le à sent, puis accepted ou declined.
6. Convertissez un devis accepté avec POST /api/v1/quotes/{id}/convert.

Les 7 opérations disponibles

Toutes les requêtes demandent Authorization. Ajoutez X-Yaoka-Organization-Id uniquement avec une clé partenaire ; une clé client sk_org_... déduit automatiquement son organisation. Les trois opérations POST demandent aussi une Idempotency-Key.

Créer un devis

POST /api/v1/quotes retourne directement le devis créé avec le statut HTTP 201.

Corps de la requête

Une ligne de devis

N’envoyez pas les totaux : YAOKA calcule totalHt, totalTax et totalTtc côté serveur.

Lister et retrouver un devis

GET /api/v1/quotes?status=draft&customerId=cus_6xA...&limit=20&cursor=...
GET /api/v1/quotes/quo_9pL...

limit accepte de 1 à 100. La liste retourne data et nextCursor. Les statuts filtrables sont draft, finalized, sent, accepted, declined, partially_invoiced, invoiced et expired.

Modifier le brouillon

PATCH /api/v1/quotes/{id} remplace uniquement les champs envoyés. Tant que le devis est draft, vous pouvez modifier customerId, lines, expiresAt, paymentConditions et specialMention.

{
  "lines": [
    {
      "label": "Prestation mensuelle révisée",
      "quantity": 2,
      "unitPrice": "120.00",
      "unit": "piece",
      "vatRate": "20.00"
    }
  ]
}

Envoyer lines remplace toutes les lignes existantes. Cette requête PATCH ne demande pas de clé d’idempotence.

Finaliser et récupérer le PDF

curl -X POST "$YAOKA_BASE_URL/api/v1/quotes/$QUOTE_ID/finalize" \
  -H "Authorization: Bearer $YAOKA_API_KEY" \
  -H "X-Yaoka-Organization-Id: $YAOKA_ORG_ID" \
  -H "Idempotency-Key: finalize-$QUOTE_ID-v1"

La finalisation attribue un numéro légal, verrouille les montants et lance la génération du PDF. Le descripteur pdf et l’état pdfStatus sont présents dans la réponse lorsqu’ils sont disponibles.

Pour télécharger le binaire :

GET /api/v1/quotes/{id}/pdf

Modifier le statut

PATCH /api/v1/quotes/{id}
Content-Type: application/json

{"status":"accepted"}

Transitions autorisées :

• finalized → sent, accepted, declined ou expired
• sent → accepted, declined ou expired

Un brouillon doit être finalisé avant ces transitions. Un devis déjà facturé n’est plus modifiable.

Convertir en facture

curl -X POST "$YAOKA_BASE_URL/api/v1/quotes/$QUOTE_ID/convert" \
  -H "Authorization: Bearer $YAOKA_API_KEY" \
  -H "X-Yaoka-Organization-Id: $YAOKA_ORG_ID" \
  -H "Idempotency-Key: convert-$QUOTE_ID-v1" \
  -H "Content-Type: application/json" \
  -d '{"dueInDays":30,"finalize":false}'

La réponse HTTP 201 est la facture créée. finalize vaut false par défaut : vous pouvez donc vérifier la facture avant sa finalisation. Cette opération exige les deux scopes quotes:write et invoices:write.

La conversion est refusée si le devis est encore en brouillon, refusé, expiré ou déjà facturé.

Idempotence sans doublons

Choisissez une clé stable liée à l’action de votre logiciel, par exemple quote-order-847-v1. En cas de timeout, relancez exactement la même requête avec la même clé. Pour une nouvelle opération, utilisez une nouvelle clé.

Erreurs à traiter

Conservez error.requestId : le support YAOKA peut l’utiliser pour retrouver l’appel exact.