{"openapi":"3.1.0","info":{"title":"Qivo API","version":"1.0.0","description":"Invoicing API for one company. Amounts are decimal strings. Webhooks: see docs (HMAC-SHA256 signed, header Qivo-Signature). RO e-Factura sending through the API is for Romanian B2B invoices only (scope efactura.send)."},"servers":[{"url":"https://app.qivo.ro/api/v1"}],"security":[{"bearer":[]}],"paths":{"/me":{"get":{"summary":"Company and key scopes","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"cui":{"type":"string"}}},"apiKey":{"type":"object","properties":{"id":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers":{"get":{"summary":"List customers (scope customers.read)","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"enum":["COMPANY","INDIVIDUAL"]}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a customer (scope customers.write)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Replays the first response for 24 hours; a different request with the same key is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}":{"get":{"summary":"Get a customer (scope customers.read)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices":{"get":{"summary":"List documents (scope invoices.read)","parameters":[{"name":"type","in":"query","schema":{"enum":["invoice","proforma","credit_note"]}},{"name":"status","in":"query","schema":{"enum":["all","draft","issued","unpaid","partial","paid","overdue","cancelled"]}},{"name":"customerId","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceSummary"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a draft invoice or proforma (scope invoices.write)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Replays the first response for 24 hours; a different request with the same key is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}":{"get":{"summary":"Get a document (scope invoices.read)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/issue":{"post":{"summary":"Issue a draft: fiscal checks, numbering, immutable snapshot (scope invoices.issue)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Replays the first response for 24 hours; a different request with the same key is a 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sendToEfactura":{"type":"boolean","description":"Also queue the invoice for RO e-Factura (B2B only; needs scope efactura.send and an ANAF connection). These checks run before issuing. If queueing fails after issuing, the invoice stays issued and efacturaError explains why."}}}}}},"responses":{"200":{"description":"Issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not a draft, not B2B, or not connected to ANAF","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/efactura":{"get":{"summary":"RO e-Factura sends of a document, newest first (scope invoices.read)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EfacturaSubmission"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Queue an issued B2B invoice for RO e-Factura (scopes efactura.send and invoices.issue). Idempotent: an existing live send is returned. The result arrives as the efactura.submission_finalized webhook.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Replays the first response for 24 hours; a different request with the same key is a 409."}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EfacturaSubmission"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not issued, not B2B, or not connected to ANAF","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/payments":{"get":{"summary":"Payments of an invoice (scope payments.read)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Record a payment, in the invoice currency (scope payments.write)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Replays the first response for 24 hours; a different request with the same key is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments":{"get":{"summary":"List payments (scope payments.read)","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"includeVoided","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or role does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also for other companies' ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"qv_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}},"rules":{"type":"array","items":{"type":"string"},"description":"Official e-Factura validation rules that failed (e.g. BR-RO-010)"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"}}}}}}}},"CustomerInput":{"type":"object","additionalProperties":false,"required":["kind","name"],"properties":{"kind":{"enum":["COMPANY","INDIVIDUAL"]},"name":{"type":"string"},"cui":{"type":["string","null"]},"vatPayer":{"type":"boolean"},"vatNumber":{"type":["string","null"]},"tradeRegisterNumber":{"type":["string","null"]},"addressLine1":{"type":["string","null"]},"addressLine2":{"type":["string","null"]},"city":{"type":["string","null"]},"county":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"country":{"type":"string","minLength":2,"maxLength":2},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"defaultCurrency":{"type":"string","minLength":3,"maxLength":3},"notes":{"type":["string","null"]}}},"Customer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"enum":["COMPANY","INDIVIDUAL"]},"name":{"type":"string"},"cui":{"type":["string","null"]},"vatPayer":{"type":"boolean"},"cnpLast4":{"type":["string","null"]},"address":{"type":"object"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"defaultCurrency":{"type":"string"},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"LineInput":{"type":"object","additionalProperties":false,"required":["name","quantity","unitPrice","vatCategoryCode","vatRate"],"properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"unit":{"type":"string"},"quantity":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"unitPrice":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"discountType":{"enum":["PERCENT","AMOUNT",null]},"discountValue":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"vatCategoryCode":{"enum":["S","AE","E","K","G","O"]},"vatRate":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"vatExemptionReason":{"type":["string","null"]}}},"InvoiceInput":{"type":"object","additionalProperties":false,"required":["customerId","lines"],"properties":{"documentType":{"enum":["INVOICE","PROFORMA"]},"customerId":{"type":"string"},"seriesId":{"type":["string","null"]},"issueDate":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"supplyDate":{"type":"string","format":"date"},"currency":{"type":"string","minLength":3,"maxLength":3},"exchangeRate":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"notes":{"type":["string","null"]},"paymentTerms":{"type":["string","null"]},"lines":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/LineInput"}}}},"InvoiceSummary":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"enum":["INVOICE","PROFORMA","CREDIT_NOTE"]},"status":{"enum":["DRAFT","ISSUED","CANCELLED"]},"paymentStatus":{"type":"string"},"number":{"type":["string","null"]},"issueDate":{"type":["string","null"],"format":"date"},"dueDate":{"type":["string","null"],"format":"date"},"currency":{"type":"string"},"total":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"amountPaid":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"overdue":{"type":"boolean"}}},"Invoice":{"allOf":[{"$ref":"#/components/schemas/InvoiceSummary"},{"type":"object","properties":{"subtotal":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"vatTotal":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"outstanding":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"exchangeRate":{"type":["string","null"]},"customer":{"type":["object","null"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/LineInput"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"issuedAt":{"type":["string","null"],"format":"date-time"},"efactura":{"oneOf":[{"$ref":"#/components/schemas/EfacturaSubmission"},{"type":"null"}]},"efacturaError":{"type":"object","description":"Only on issue with sendToEfactura, when queueing failed","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}]},"EfacturaSubmission":{"type":"object","properties":{"id":{"type":"string"},"environment":{"enum":["MOCK","TEST","PROD"]},"state":{"enum":["PREPARED","UPLOADED","PROCESSING","ACCEPTED","REJECTED","INVALID_XML","UPLOAD_REJECTED"]},"uploadIndex":{"type":["string","null"],"description":"ANAF index_incarcare"},"downloadId":{"type":["string","null"]},"errorCode":{"type":["string","null"]},"uploadedAt":{"type":["string","null"],"format":"date-time"},"finalizedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"PaymentInput":{"type":"object","additionalProperties":false,"required":["amount","paidAt","method"],"properties":{"amount":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"paidAt":{"type":"string","format":"date"},"method":{"enum":["BANK_TRANSFER","CASH","CARD","OTHER"]},"reference":{"type":["string","null"]},"notes":{"type":["string","null"]}}},"Payment":{"type":"object","properties":{"id":{"type":"string"},"invoiceId":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+(\\.\\d{1,4})?$","examples":["121.00"]},"paidAt":{"type":"string","format":"date"},"method":{"type":"string"},"reference":{"type":["string","null"]},"voided":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}}}}