{"openapi":"3.1.0","info":{"title":"YAOKA Partners API","version":"1.0.0","description":"REST API used by YAOKA partners (Qualibox, DigiForma, etc.) to provision orgs and manage invoicing data on behalf of their customers.","contact":{"name":"YAOKA","email":"contact@yaoka.fr"}},"servers":[{"url":"https://app.yaoka.fr","description":"Production"},{"url":"http://localhost:3000","description":"Local dev"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Either a master key (`sk_qbx_test_*` or `sk_qbx_live_*`) or a per-org key (`sk_org_test_*` or `sk_org_live_*`). The prefix sets the mode (test = sandbox, live = production). Use `Authorization: Bearer <key>`."}},"parameters":{"OrgId":{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"YAOKA organization id (nanoid)."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-supplied idempotency key. Replays within 24h return the original response. Recommended on POST."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string"}}},"Org":{"type":"object","required":["id","name","mode","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"siret":{"type":"string","nullable":true},"mode":{"type":"string","enum":["test","live"]},"createdAt":{"type":"string","format":"date-time"}}},"OrgProvisionRequest":{"type":"object","required":["name","ownerEmail"],"properties":{"name":{"type":"string"},"siret":{"type":"string","nullable":true},"ownerEmail":{"type":"string","format":"email"},"ownerName":{"type":"string"},"externalRef":{"type":"string","description":"Your internal id for this OF."}}},"OrgProvisionResponse":{"type":"object","required":["org","apiKey"],"properties":{"org":{"$ref":"#/components/schemas/Org"},"apiKey":{"type":"object","required":["raw","preview"],"properties":{"raw":{"type":"string","description":"Plaintext per-org key. Shown ONLY ONCE."},"preview":{"type":"string"}}}}},"Invoice":{"type":"object","required":["id","number","status","totalCents","currency"],"properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string","enum":["draft","sent","paid","cancelled"]},"totalCents":{"type":"integer"},"currency":{"type":"string","example":"EUR"},"customer":{"type":"object"},"lines":{"type":"array","items":{"type":"object"}},"createdAt":{"type":"string","format":"date-time"}}},"InvoiceCreateRequest":{"type":"object","required":["customerId","lines"],"properties":{"customerId":{"type":"string"},"dueDate":{"type":"string","format":"date"},"lines":{"type":"array","items":{"type":"object","required":["label","quantity","unitPriceCents"],"properties":{"label":{"type":"string"},"quantity":{"type":"number"},"unitPriceCents":{"type":"integer"},"vatRate":{"type":"number"}}}}}},"Quote":{"type":"object","required":["id","number","status"],"properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string","enum":["draft","sent","accepted","refused","expired"]},"totalCents":{"type":"integer"}}},"Customer":{"type":"object","required":["id","name","email"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"siret":{"type":"string","nullable":true}}}}},"paths":{"/api/v1/orgs":{"post":{"summary":"Provision a new OF (organization)","description":"Creates an Organization on behalf of the partner and returns a per-org API key (sk_org_*). The org inherits the mode from the calling master key.","operationId":"createOrg","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgProvisionRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgProvisionResponse"}}}},"401":{"description":"Invalid or missing API key."},"409":{"description":"An org with this externalRef already exists."}}}},"/api/v1/orgs/{orgId}":{"get":{"summary":"Get an org by id","operationId":"getOrg","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"Org details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}},"404":{"description":"Not found."}}}},"/api/v1/orgs/{orgId}/customers":{"get":{"summary":"List customers","operationId":"listCustomers","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"Paginated list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}}}}}}}},"post":{"summary":"Create a customer","operationId":"createCustomer","parameters":[{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"responses":{"201":{"description":"Created."}}}},"/api/v1/orgs/{orgId}/invoices":{"get":{"summary":"List invoices","operationId":"listInvoices","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"Paginated list of invoices.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}}}}}},"post":{"summary":"Create an invoice (draft)","operationId":"createInvoice","parameters":[{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreateRequest"}}}},"responses":{"201":{"description":"Created draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}}}}},"/api/v1/orgs/{orgId}/invoices/{id}":{"get":{"summary":"Get an invoice","operationId":"getInvoice","parameters":[{"$ref":"#/components/parameters/OrgId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice."}}},"patch":{"summary":"Update an invoice (finalize, mark paid, etc.)","operationId":"updateInvoice","parameters":[{"$ref":"#/components/parameters/OrgId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["finalize","mark_paid","cancel"]}}}}}},"responses":{"200":{"description":"Updated invoice."}}}},"/api/v1/orgs/{orgId}/invoices/{id}/credit-note":{"post":{"summary":"Create a credit note for an invoice","operationId":"createCreditNote","parameters":[{"$ref":"#/components/parameters/OrgId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Credit note created."}}}},"/api/v1/orgs/{orgId}/quotes":{"get":{"summary":"List quotes","operationId":"listQuotes","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"Quotes list."}}},"post":{"summary":"Create a quote","operationId":"createQuote","parameters":[{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Quote created."}}}},"/api/v1/orgs/{orgId}/quotes/{id}/convert":{"post":{"summary":"Convert a quote into an invoice (deposit or balance)","operationId":"convertQuote","parameters":[{"$ref":"#/components/parameters/OrgId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Invoice created from quote."}}}},"/api/v1/orgs/{orgId}/supplier-invoices":{"get":{"summary":"List supplier invoices","operationId":"listSupplierInvoices","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"Supplier invoices."}}},"post":{"summary":"Upload a supplier invoice (Factur-X friendly)","operationId":"createSupplierInvoice","parameters":[{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Created."}}}},"/api/v1/orgs/{orgId}/expense-reports":{"get":{"summary":"List expense reports","operationId":"listExpenseReports","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"Expense reports."}}},"post":{"summary":"Create an expense report","operationId":"createExpenseReport","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"201":{"description":"Created."}}}},"/api/v1/orgs/{orgId}/pennylane/oauth/start":{"post":{"summary":"Start Pennylane OAuth flow for an org","operationId":"pennylaneOauthStart","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"Returns the OAuth authorize URL.","content":{"application/json":{"schema":{"type":"object","properties":{"authUrl":{"type":"string"},"state":{"type":"string"},"sandbox":{"type":"boolean"}}}}}}}}}}}