{"openapi":"3.1.0","info":{"title":"EOS Coretax Gateway API","version":"1.0.0","description":"Send e-Faktur (tax invoices) from any ERP or CoreTax Studio to DJP Coretax through an official PJAP channel. Bilingual errors (message = EN, message_id = ID).","contact":{"name":"EOS Teknologi","email":"info@eosteknologi.com"}},"servers":[{"url":"https://coretaxgateway.eosteknologi.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"ctg_test_… (simulator) or ctg_live_… (DJP)"}},"schemas":{"Document":{"type":"object","required":["externalRef","seller","invoiceDate","trxCode","buyer","items"],"properties":{"externalRef":{"type":"string","maxLength":100,"description":"Your ERP invoice number. Default idempotency key."},"idempotencyKey":{"type":"string","maxLength":120,"description":"Optional; overrides externalRef as idempotency key."},"seller":{"type":"object","required":["tin"],"properties":{"tin":{"type":"string","description":"Seller NPWP (16 digits)"},"idtku":{"type":"string","description":"Seller NITKU (22 digits) — must be a registered entity"}}},"invoiceDate":{"type":"string","format":"date"},"invoiceType":{"type":"string","default":"Normal"},"trxCode":{"type":"string","example":"04","description":"DJP transaction code 01–10"},"addInfo":{"type":"string"},"customDoc":{"type":"string"},"customDocMonthYear":{"type":"string"},"reference":{"type":"string"},"facilityStamp":{"type":"string"},"buyer":{"type":"object","required":["idType","name","address"],"properties":{"idType":{"type":"string","enum":["TIN","National ID","Passport","Other ID"]},"tin":{"type":"string","description":"Buyer NPWP (TIN) or 16 zeros for non-TIN"},"documentNumber":{"type":"string"},"country":{"type":"string","default":"IDN"},"name":{"type":"string"},"address":{"type":"string"},"email":{"type":"string"},"idtku":{"type":"string","description":"Buyer NITKU (22 digits) — required when idType = TIN"}}},"items":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["type","name","unit","unitPrice","qty","taxBase","otherTaxBase","vatRate","vat"],"properties":{"type":{"type":"string","enum":["A","B"],"description":"A = goods (Barang), B = services (Jasa)"},"code":{"type":"string","example":"000000","description":"DJP goods/service code (6 digits)"},"name":{"type":"string","maxLength":200},"unit":{"type":"string","example":"UM.0018","description":"DJP unit code (UM.xxxx)"},"unitPrice":{"type":"number"},"qty":{"type":"number"},"discount":{"type":"number","default":0},"taxBase":{"type":"number","description":"DPP"},"otherTaxBase":{"type":"number","description":"DPP Nilai Lain"},"vatRate":{"type":"number","example":12},"vat":{"type":"number","description":"PPN = vatRate × otherTaxBase / 100 (rounded half-to-even, 2 dp)"},"stlgRate":{"type":"number","default":0},"stlg":{"type":"number","default":0,"description":"PPnBM"}}}}}},"DocumentOut":{"type":"object","properties":{"id":{"type":"string","example":"doc_7k2m…"},"externalRef":{"type":"string"},"env":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["draft","queued","submitting","pending_djp","approved","rejected","failed","cancelled"]},"nsfp":{"type":["string","null"],"description":"Tax invoice serial number issued by DJP"},"djpMessage":{"type":["string","null"]},"taxPeriod":{"type":"string","example":"202610"},"totals":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Item":{"type":"object","required":["type","name","unit","unitPrice","qty","taxBase","otherTaxBase","vatRate","vat"],"properties":{"type":{"type":"string","enum":["A","B"],"description":"A = goods (Barang), B = services (Jasa)"},"code":{"type":"string","example":"000000","description":"DJP goods/service code (6 digits)"},"name":{"type":"string","maxLength":200},"unit":{"type":"string","example":"UM.0018","description":"DJP unit code (UM.xxxx)"},"unitPrice":{"type":"number"},"qty":{"type":"number"},"discount":{"type":"number","default":0},"taxBase":{"type":"number","description":"DPP"},"otherTaxBase":{"type":"number","description":"DPP Nilai Lain"},"vatRate":{"type":"number","example":12},"vat":{"type":"number","description":"PPN = vatRate × otherTaxBase / 100 (rounded half-to-even, 2 dp)"},"stlgRate":{"type":"number","default":0},"stlg":{"type":"number","default":0,"description":"PPnBM"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"message_id":{"type":"string"},"details":{"type":"array"}}},"requestId":{"type":"string"}}}}},"paths":{"/ping":{"get":{"summary":"Test connection","responses":{"200":{"description":"OK"},"401":{"description":"Invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents":{"post":{"summary":"Create 1–100 documents","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"For single-document requests"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"autoSubmit":{"type":"boolean"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"},"maxItems":100}}}]}}}},"responses":{"201":{"description":"All accepted"},"207":{"description":"Partially accepted (see results[])"},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List documents","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"updatedSince","in":"query","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ data: DocumentOut[], nextCursor }"}}}},"/documents/{id}":{"get":{"summary":"Get document + status history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"DocumentOut + events[]"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Correct a draft / rejected / failed document","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"responses":{"200":{"description":"Updated"},"409":{"description":"Wrong status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/submit":{"post":{"summary":"Approve & send to DJP","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Queued"},"402":{"description":"Quota reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Signer missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/cancel":{"post":{"summary":"Cancel before it is sent","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"409":{"description":"Wrong status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"summary":"Counts per status + plan quota for a tax period","responses":{"200":{"description":"OK"}}}}}}