{"openapi":"3.0.0","info":{"title":"Tiendy Factu API","version":"0.1.0"},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer"}},"schemas":{"IssuedDocument":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"documentType":{"type":"string"},"number":{"type":"string","nullable":true,"example":"001-001-0000001"},"cdc":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true}},"required":["id","status","documentType","number","cdc","externalReference"]}},"required":["document"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"detail":{"type":"object","additionalProperties":{"nullable":true}}},"required":["error","code"]},"UploadedCertificate":{"type":"object","properties":{"certificate":{"type":"object","properties":{"subject":{"type":"string"},"ruc":{"type":"string","example":"80012345-6"},"expiresAt":{"type":"string","format":"date-time"}},"required":["subject","ruc","expiresAt"]}},"required":["certificate"]},"Issuer":{"type":"object","properties":{"id":{"type":"string"},"ruc":{"type":"string","example":"80012345-6"},"businessName":{"type":"string"},"tradeName":{"type":"string","nullable":true},"taxpayerType":{"type":"string","enum":["FISICA","JURIDICA"]},"environment":{"type":"string","enum":["STAGING","PRODUCTION"]},"address":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"cityCode":{"type":"number","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"activities":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string"},"primary":{"type":"boolean"}},"required":["code","description","primary"]}},"kude":{"type":"object","properties":{"accentColor":{"type":"string"},"footerText":{"type":"string"}},"required":["accentColor","footerText"]},"certificate":{"type":"object","nullable":true,"properties":{"subject":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time"}},"required":["subject","expiresAt"]},"timbrado":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"number":{"type":"string"},"validFrom":{"type":"string","format":"date"},"validUntil":{"type":"string","nullable":true,"format":"date"}},"required":["id","number","validFrom","validUntil"]},"establishments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","example":"001"},"name":{"type":"string"},"address":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"cityCode":{"type":"number","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"active":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string","nullable":true},"active":{"type":"boolean"}},"required":["id","code","name","active"]}}},"required":["id","code","name","address","houseNumber","cityCode","phone","email","active","points"]}},"readiness":{"type":"object","properties":{"ready":{"type":"boolean"},"missing":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"detail":{"type":"string"}},"required":["key","label"]}}},"required":["ready","missing"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","ruc","businessName","tradeName","taxpayerType","environment","address","houseNumber","cityCode","phone","email","activities","kude","certificate","timbrado","establishments","readiness","createdAt"]},"Document":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"issuerId":{"type":"string"},"documentType":{"type":"string","enum":["FACTURA","AUTOFACTURA","NOTA_CREDITO","NOTA_DEBITO","NOTA_REMISION"]},"status":{"type":"string","enum":["DRAFT","QUEUED","SENT","APPROVED","REJECTED","CANCELLED","INUTILIZED"]},"number":{"type":"string","nullable":true,"example":"001-001-0000001"},"cdc":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"totalAmount":{"type":"integer"},"receptor":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"example":"taxpayer"},"name":{"type":"string","nullable":true},"taxId":{"type":"string","nullable":true,"example":"80012345-6"}},"required":["kind","name","taxId"]},"sifen":{"type":"object","properties":{"code":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}},"required":["code","message"]},"emittedAt":{"type":"string","nullable":true,"format":"date-time"},"approvedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"innominada":{"type":"boolean"},"currency":{"type":"string","example":"PYG"},"totalIva":{"type":"integer"},"associatedDocumentId":{"type":"string","nullable":true},"halted":{"type":"string","nullable":true,"enum":["issue","poll","xml","cancel","nomination",null],"description":"The phase the outbox gave up on; `POST …/retry` resumes it."},"kudeAvailable":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"outcome":{"type":"string"},"sifenCode":{"type":"string","nullable":true},"sifenMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["type","outcome","sifenCode","sifenMessage","createdAt"]}},"actions":{"type":"object","properties":{"cancellation":{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"],"additionalProperties":{"nullable":true}},"creditNote":{"type":"object","nullable":true,"properties":{"availability":{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"],"additionalProperties":{"nullable":true}},"remaining":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"}},"required":["position"],"additionalProperties":{"nullable":true}}},"remainingTotal":{"type":"integer"}},"required":["availability","remaining","remainingTotal"]},"debitNote":{"type":"object","nullable":true,"properties":{"kind":{"type":"string"}},"required":["kind"],"additionalProperties":{"nullable":true}},"nomination":{"type":"object","nullable":true,"properties":{"kind":{"type":"string"}},"required":["kind"],"additionalProperties":{"nullable":true}}},"required":["cancellation","creditNote","debitNote","nomination"],"description":"What can be done with the document now, and why not."}},"required":["id","issuerId","documentType","status","number","cdc","externalReference","totalAmount","receptor","sifen","emittedAt","approvedAt","createdAt","innominada","currency","totalIva","associatedDocumentId","halted","kudeAvailable","updatedAt","events","actions"]}},"required":["document"]},"DocumentPage":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"issuerId":{"type":"string"},"documentType":{"type":"string","enum":["FACTURA","AUTOFACTURA","NOTA_CREDITO","NOTA_DEBITO","NOTA_REMISION"]},"status":{"type":"string","enum":["DRAFT","QUEUED","SENT","APPROVED","REJECTED","CANCELLED","INUTILIZED"]},"number":{"type":"string","nullable":true,"example":"001-001-0000001"},"cdc":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"totalAmount":{"type":"integer"},"receptor":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"example":"taxpayer"},"name":{"type":"string","nullable":true},"taxId":{"type":"string","nullable":true,"example":"80012345-6"}},"required":["kind","name","taxId"]},"sifen":{"type":"object","properties":{"code":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}},"required":["code","message"]},"emittedAt":{"type":"string","nullable":true,"format":"date-time"},"approvedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","issuerId","documentType","status","number","cdc","externalReference","totalAmount","receptor","sifen","emittedAt","approvedAt","createdAt"]}},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page; null on the last one."}},"required":["documents","nextCursor"]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","example":"https://example.com/hooks/factu"},"events":{"type":"array","items":{"type":"string"},"example":["document.approved"]},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","url","events","description","active","createdAt","updatedAt"]},"WebhookDeliveryPage":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page; null on the last one."}},"required":["deliveries","nextCursor"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"type":{"type":"string","example":"document.approved"},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED"]},"attempts":{"type":"integer"},"lastStatusCode":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true},"nextAttemptAt":{"type":"string","nullable":true,"format":"date-time"},"deliveredAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","eventId","type","status","attempts","lastStatusCode","lastError","nextAttemptAt","deliveredAt","createdAt"]}},"parameters":{}},"paths":{"/v1/documents":{"post":{"summary":"Issue an invoice (factura electrónica) from the caller's items","description":"Numbers the invoice and queues it for SIFEN. Send an `Idempotency-Key` to retry safely: the same key on the same RUC answers 200 with the document issued first, even if the new body differs (it must still be a valid body), and consumes no number.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expeditionPointId":{"type":"string","minLength":1,"maxLength":64},"receptor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["RUC"]},"taxId":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","taxId","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["CI"]},"taxId":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","taxId","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["INNOMINADA"]}},"required":["kind"],"additionalProperties":false}]},"email":{"type":"string","maxLength":254},"items":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","minLength":1,"maxLength":64},"itemCode":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","minLength":1,"maxLength":2000},"quantity":{"type":"integer","minimum":0,"exclusiveMinimum":true},"unitPrice":{"type":"integer","minimum":0},"discount":{"type":"integer","minimum":0},"ivaRate":{"type":"string","enum":["IVA_10","IVA_5","EXENTO"]}},"required":["description","quantity","unitPrice","ivaRate"],"additionalProperties":false},"maxItems":999},"discount":{"type":"integer","minimum":0},"condition":{"type":"string","enum":["CONTADO","CREDITO"]},"creditDueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"presence":{"type":"string","enum":["IN_PERSON","ONLINE"],"default":"ONLINE"},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["CASH","TRANSFER","CARD","OTHER"]},"description":{"type":"string","maxLength":30}},"required":["method"],"additionalProperties":false},"externalReference":{"type":"string","minLength":1,"maxLength":100}},"required":["expeditionPointId","receptor","items","condition","payment"],"additionalProperties":false}}}},"responses":{"200":{"description":"Already issued under this Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuedDocument"}}}},"202":{"description":"Numbered and queued for SIFEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuedDocument"}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List the caller's documents, newest first","description":"Keyset pagination: pass the page's `nextCursor` as `cursor` for the next one. An `issuerId` of another account filters to nothing.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"issuerId","in":"query"},{"schema":{"type":"string","enum":["DRAFT","QUEUED","SENT","APPROVED","REJECTED","CANCELLED","INUTILIZED"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["FACTURA","AUTOFACTURA","NOTA_CREDITO","NOTA_DEBITO","NOTA_REMISION"]},"required":false,"name":"documentType","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"externalReference","in":"query"},{"schema":{"type":"integer","default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The previous page's `nextCursor`."},"required":false,"description":"The previous page's `nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPage"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid filter, limit or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{documentId}/notes":{"post":{"summary":"Issue a credit or a debit note (nota de crédito o débito) on an approved invoice","description":"Numbers the note and queues it for SIFEN. It is numbered on the invoice's expedition point unless `expeditionPointId` names another point of the same RUC. A credit note never exceeds what the earlier credit notes left creditable; the note copies the invoice's receptor and `externalReference`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"documentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"documentType":{"type":"string","enum":["NOTA_CREDITO"]},"motive":{"type":"integer"},"credit":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["total"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["lines"]},"lines":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","minimum":0,"exclusiveMinimum":true},"quantity":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["position","quantity"],"additionalProperties":false},"minItems":1,"maxItems":999}},"required":["mode","lines"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["amount"]},"amount":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["mode","amount"],"additionalProperties":false}]},"expeditionPointId":{"type":"string","minLength":1,"maxLength":64}},"required":["documentType","motive","credit"],"additionalProperties":false},{"type":"object","properties":{"documentType":{"type":"string","enum":["NOTA_DEBITO"]},"motive":{"type":"integer"},"amount":{"type":"integer","minimum":0,"exclusiveMinimum":true},"expeditionPointId":{"type":"string","minLength":1,"maxLength":64}},"required":["documentType","motive","amount"],"additionalProperties":false}]}}}},"responses":{"202":{"description":"Numbered and queued for SIFEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuedDocument"}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/remissions":{"post":{"summary":"Issue a nota de remisión for goods moved by road","description":"Numbers the remisión on its own sequence and queues it for SIFEN. The items carry no price or IVA. `invoiceId` names the approved invoice of the same RUC the goods travel for; a sale (motive 1) without one carries `futureInvoiceDate`, within the current month and not before today.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expeditionPointId":{"type":"string","minLength":1,"maxLength":64},"receptor":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["RUC"]},"taxId":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","taxId","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["CI"]},"taxId":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","taxId","name"],"additionalProperties":false}]},"email":{"type":"string","maxLength":254},"items":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","minLength":1,"maxLength":64},"itemCode":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","minLength":1,"maxLength":2000},"quantity":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":2147483647}},"required":["description","quantity"],"additionalProperties":false},"minItems":1,"maxItems":999},"invoiceId":{"type":"string","minLength":1,"maxLength":64},"motive":{"type":"integer"},"motiveDescription":{"type":"string","maxLength":60},"emissionResponsible":{"type":"integer","minimum":1,"maximum":5},"transportType":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"freightResponsible":{"type":"integer","minimum":1,"maximum":5},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"estimatedKm":{"type":"integer","minimum":1,"maximum":99999},"futureInvoiceDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"origin":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":255},"houseNumber":{"type":"string","pattern":"^\\d{1,6}$"},"sifenCityCode":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["address","houseNumber","sifenCityCode"],"additionalProperties":false},"destination":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":255},"houseNumber":{"type":"string","pattern":"^\\d{1,6}$"},"sifenCityCode":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["address","houseNumber","sifenCityCode"],"additionalProperties":false},"vehicle":{"type":"object","properties":{"type":{"type":"string","minLength":1,"maxLength":50},"brand":{"type":"string","minLength":1,"maxLength":10},"idType":{"type":"string","enum":["PLATE","CHASSIS"]},"number":{"type":"string","minLength":1,"maxLength":20}},"required":["type","brand","idType","number"],"additionalProperties":false},"carrier":{"type":"object","properties":{"kind":{"type":"string","enum":["RUC","CI"]},"name":{"type":"string","minLength":1,"maxLength":255},"taxId":{"type":"string","minLength":1,"maxLength":20},"driverName":{"type":"string","minLength":1,"maxLength":255},"driverDocument":{"type":"string","minLength":1,"maxLength":20},"fiscalAddress":{"type":"string","maxLength":150},"driverAddress":{"type":"string","maxLength":255}},"required":["kind","name","taxId","driverName","driverDocument"],"additionalProperties":false},"fiscalInfo":{"type":"string","minLength":1,"maxLength":3000},"externalReference":{"type":"string","minLength":1,"maxLength":100}},"required":["expeditionPointId","receptor","items","motive","emissionResponsible","transportType","freightResponsible","startDate","endDate","origin","destination","vehicle","carrier","fiscalInfo"],"additionalProperties":false}}}},"responses":{"202":{"description":"Numbered and queued for SIFEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuedDocument"}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{documentId}/cancel":{"post":{"summary":"Request the cancellation (anulación) of an approved document","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"documentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued for SIFEN","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"cancellation":{"type":"string","enum":["pending"]}},"required":["id","status","cancellation"]}},"required":["document"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{documentId}/nomination":{"post":{"summary":"Nominate the buyer of an innominada invoice","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"documentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"receptor":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["RUC"]},"taxId":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","taxId","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["CI"]},"taxId":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","taxId","name"],"additionalProperties":false}]},"email":{"type":"string","maxLength":254}},"required":["receptor"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued for SIFEN","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"nomination":{"type":"string","enum":["pending"]}},"required":["id","nomination"]}},"required":["document"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{documentId}/retry":{"post":{"summary":"Requeue a document the outbox halted","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"documentId","in":"path"}],"responses":{"202":{"description":"Requeued","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"phase":{"type":"string"}},"required":["id","phase"]}},"required":["document"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inutilizations":{"post":{"summary":"Inutilize one number or a range of up to 1000","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timbradoId":{"type":"string","minLength":1},"expeditionPointId":{"type":"string","minLength":1},"documentType":{"type":"string","enum":["FACTURA","NOTA_CREDITO","NOTA_DEBITO","NOTA_REMISION"]},"numberFrom":{"type":"number"},"numberTo":{"type":"number"},"reason":{"type":"string"}},"required":["timbradoId","expeditionPointId","documentType","numberFrom","numberTo","reason"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued for SIFEN","content":{"application/json":{"schema":{"type":"object","properties":{"inutilization":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["QUEUED"]}},"required":["id","status"]}},"required":["inutilization"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inutilizations/{inutilizationId}/retry":{"post":{"summary":"Requeue an inutilization the outbox halted","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"inutilizationId","in":"path"}],"responses":{"202":{"description":"Requeued","content":{"application/json":{"schema":{"type":"object","properties":{"inutilization":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["QUEUED"]}},"required":["id","status"]}},"required":["inutilization"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, or refused by a SIFEN rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers/{issuerId}/certificate":{"put":{"summary":"Load or renew a RUC's signing certificate (.p12) and CSC","description":"Checks that the password opens the `.p12` and that it is password-protected, that the certificate is issued for this RUC (MT v150 §7.5) and that it has not expired, then stores the `.p12`, its password and the CSC encrypted and records the certificate's subject and expiry. Replaces what the RUC had. The secrets are never answered back.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"p12":{"type":"string","pattern":"^(?:[A-Za-z0-9+/]{4})+(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$|^[A-Za-z0-9+/]{2}==$|^[A-Za-z0-9+/]{3}=$"},"password":{"type":"string","maxLength":256},"csc":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d{4}$"},"secret":{"type":"string","pattern":"^[A-Za-z0-9]{32}$"}},"required":["id","secret"],"additionalProperties":false}},"required":["p12","password","csc"],"additionalProperties":false}}}},"responses":{"200":{"description":"Stored; the certificate the RUC signs with from now on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadedCertificate"}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such RUC in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body, or a certificate that does not open, is not password-protected, is another RUC's or has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers":{"post":{"summary":"Register a RUC in the caller's account","description":"Registers the RUC with its fiscal data and economic activities. The field bounds are the SIFEN v150 XSD's. `environment` defaults to STAGING (sifen-test). The answer lists what the RUC still lacks to issue: its certificate, a timbrado and an active expedition point.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ruc":{"type":"string"},"businessName":{"type":"string","minLength":4,"maxLength":255},"tradeName":{"type":"string","minLength":4,"maxLength":255},"taxpayerType":{"type":"string","enum":["FISICA","JURIDICA"]},"environment":{"type":"string","enum":["STAGING","PRODUCTION"],"default":"STAGING"},"address":{"type":"string","minLength":1,"maxLength":255},"houseNumber":{"type":"string","pattern":"^\\d{1,6}$"},"cityCode":{"type":"integer"},"phone":{"type":"string","minLength":6,"maxLength":15},"email":{"type":"string","maxLength":80,"pattern":"^[0-9a-zA-Z][0-9a-zA-Z.\\-_]*@(?:[0-9a-zA-Z][0-9a-zA-Z\\-_]*\\.)+[a-zA-Z]{2,9}$"},"activities":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[0-9A-Z]{1,8}$"},"description":{"type":"string","minLength":1,"maxLength":300},"primary":{"type":"boolean"}},"required":["code","description"],"additionalProperties":false},"minItems":1,"maxItems":9}},"required":["ruc","businessName","taxpayerType","address","cityCode","phone","email","activities"],"additionalProperties":false}}}},"responses":{"201":{"description":"Registered","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"$ref":"#/components/schemas/Issuer"}},"required":["issuer"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The account already registered this RUC","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List the caller's RUCs","security":[{"apiKey":[]}],"responses":{"200":{"description":"The account's RUCs, oldest first","content":{"application/json":{"schema":{"type":"object","properties":{"issuers":{"type":"array","items":{"$ref":"#/components/schemas/Issuer"}}},"required":["issuers"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers/{issuerId}":{"get":{"summary":"Read one RUC: its data, establishments, points, timbrado and what it still lacks to issue","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"}],"responses":{"200":{"description":"The RUC","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"$ref":"#/components/schemas/Issuer"}},"required":["issuer"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such RUC in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Edit a RUC's fiscal data, activities, KuDE branding or environment","description":"Changes only the fields sent; `null` clears `tradeName` or `houseNumber`; `activities` replaces the whole list. The RUC and its check digit never change. Switching `environment` answers 409 while any document or inutilización of the RUC is in process with SIFEN, and otherwise deactivates the active timbrado: load the new environment's timbrado before issuing again.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessName":{"type":"string","minLength":4,"maxLength":255},"tradeName":{"type":"string","nullable":true,"minLength":4,"maxLength":255},"taxpayerType":{"type":"string","enum":["FISICA","JURIDICA"]},"environment":{"type":"string","enum":["STAGING","PRODUCTION"]},"address":{"type":"string","minLength":1,"maxLength":255},"houseNumber":{"type":"string","nullable":true,"pattern":"^\\d{1,6}$"},"cityCode":{"type":"integer"},"phone":{"type":"string","minLength":6,"maxLength":15},"email":{"type":"string","maxLength":80,"pattern":"^[0-9a-zA-Z][0-9a-zA-Z.\\-_]*@(?:[0-9a-zA-Z][0-9a-zA-Z\\-_]*\\.)+[a-zA-Z]{2,9}$"},"activities":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[0-9A-Z]{1,8}$"},"description":{"type":"string","minLength":1,"maxLength":300},"primary":{"type":"boolean"}},"required":["code","description"],"additionalProperties":false},"minItems":1,"maxItems":9},"kude":{"type":"object","properties":{"accentColor":{"type":"string","pattern":"^#[0-9A-F]{6}$"},"footerText":{"type":"string","maxLength":280}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"$ref":"#/components/schemas/Issuer"}},"required":["issuer"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such RUC in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An environment switch while documents or inutilizaciones are in process with SIFEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers/{issuerId}/establishments":{"post":{"summary":"Add an establishment (C005) to a RUC","description":"`code` is the three-digit code DNIT assigned. A code the RUC already has answers 409.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","pattern":"^[0-9]{3}$"},"name":{"type":"string","minLength":1,"maxLength":255},"address":{"type":"string","minLength":1,"maxLength":255},"houseNumber":{"type":"string","pattern":"^\\d{1,6}$"},"cityCode":{"type":"integer"},"phone":{"type":"string","minLength":6,"maxLength":15},"email":{"type":"string","maxLength":80,"pattern":"^[0-9a-zA-Z][0-9a-zA-Z.\\-_]*@(?:[0-9a-zA-Z][0-9a-zA-Z\\-_]*\\.)+[a-zA-Z]{2,9}$"}},"required":["code","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"establishment":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","example":"001"},"name":{"type":"string"},"address":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"cityCode":{"type":"number","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"active":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string","nullable":true},"active":{"type":"boolean"}},"required":["id","code","name","active"]}}},"required":["id","code","name","address","houseNumber","cityCode","phone","email","active","points"]}},"required":["establishment"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such RUC in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The RUC already has an establishment with this code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers/{issuerId}/establishments/{establishmentId}":{"patch":{"summary":"Edit or deactivate an establishment","description":"Changes only the fields sent; `null` clears an optional one. The code never changes, and an establishment is never deleted: `active: false` stops numbering on all its points.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"establishmentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"address":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"houseNumber":{"type":"string","nullable":true,"pattern":"^\\d{1,6}$"},"cityCode":{"type":"integer","nullable":true},"phone":{"type":"string","nullable":true,"minLength":6,"maxLength":15},"email":{"type":"string","nullable":true,"maxLength":80,"pattern":"^[0-9a-zA-Z][0-9a-zA-Z.\\-_]*@(?:[0-9a-zA-Z][0-9a-zA-Z\\-_]*\\.)+[a-zA-Z]{2,9}$"},"active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"establishment":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","example":"001"},"name":{"type":"string"},"address":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"cityCode":{"type":"number","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"active":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string","nullable":true},"active":{"type":"boolean"}},"required":["id","code","name","active"]}}},"required":["id","code","name","address","houseNumber","cityCode","phone","email","active","points"]}},"required":["establishment"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such establishment in that RUC of the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers/{issuerId}/establishments/{establishmentId}/points":{"post":{"summary":"Add an expedition point (C006) to an establishment","description":"`code` is the three-digit code DNIT assigned. A code the establishment already has answers 409.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"establishmentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","pattern":"^[0-9]{3}$"},"name":{"type":"string","minLength":1,"maxLength":100}},"required":["code"],"additionalProperties":false}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"point":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string","nullable":true},"active":{"type":"boolean"}},"required":["id","code","name","active"]}},"required":["point"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such establishment in that RUC of the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The establishment already has a point with this code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers/{issuerId}/establishments/{establishmentId}/points/{pointId}":{"patch":{"summary":"Rename or deactivate an expedition point","description":"A point is never deleted (it keeps its numbering counters): `active: false` stops numbering on it.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"establishmentId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"pointId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true,"minLength":1,"maxLength":100},"active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"point":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string","nullable":true},"active":{"type":"boolean"}},"required":["id","code","name","active"]}},"required":["point"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such expedition point in that establishment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers/{issuerId}/timbrado":{"put":{"summary":"Load the RUC's timbrado (C004), replacing the active one","description":"A new number becomes the RUC's only active timbrado; the previous one stays, inactive, because its documents point at it. The active timbrado's own number only updates its dates. A number the RUC used before in its current environment is reactivated (the same timbrado, with its numbering); one loaded in the other environment answers 409.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"issuerId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","pattern":"^\\d{8}$"},"validFrom":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"validUntil":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["number","validFrom"],"additionalProperties":false}}}},"responses":{"200":{"description":"The active timbrado; `replaced` tells whether another one was deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"replaced":{"type":"boolean"},"timbrado":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"validFrom":{"type":"string","format":"date"},"validUntil":{"type":"string","nullable":true,"format":"date"}},"required":["id","number","validFrom","validUntil"]}},"required":["replaced","timbrado"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such RUC in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The timbrado number was loaded in the RUC's other environment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{documentId}":{"get":{"summary":"Read one document: its SIFEN status, its history and what can be done with it","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"documentId","in":"path"}],"responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{documentId}/kude":{"get":{"summary":"Download the KuDE (printed representation) of an approved or cancelled document","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"documentId","in":"path"},{"schema":{"type":"string","enum":["attachment","inline"]},"required":false,"name":"disposition","in":"query"}],"responses":{"200":{"description":"The KuDE as an A4 PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not approved yet, or its signed XML is not archived yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The archived signed XML cannot be read or belongs to another document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"post":{"summary":"Register a webhook endpoint","description":"The endpoint receives the subscribed events, signed with its secret (`whsec_…`). The secret is answered only here: store it. `url` is HTTPS, without user or password, up to 2048 characters; `events` is non-empty, without repeats. An account holds at most 10 live endpoints.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["document.approved","document.rejected","document.cancelled","document.inutilized","document.halted","cancellation.rejected","nomination.accepted","nomination.rejected","inutilization.approved","inutilization.rejected","inutilization.halted"]},"minItems":1,"maxItems":11},"description":{"type":"string","maxLength":255}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"Registered; `secret` is never answered again","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string","example":"whsec_..."}},"required":["webhook","secret"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The account already holds 10 live webhook endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List the caller's webhook endpoints","security":[{"apiKey":[]}],"responses":{"200":{"description":"The account's live endpoints, oldest first","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["webhooks"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhookId}":{"get":{"summary":"Read one webhook endpoint","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"webhookId","in":"path"}],"responses":{"200":{"description":"The endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}},"required":["webhook"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such live webhook in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Edit a webhook endpoint","description":"Changes only the fields sent; `null` clears `description`; `events` replaces the whole list. An inactive endpoint receives nothing; its pending deliveries wait until it is active again.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"webhookId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["document.approved","document.rejected","document.cancelled","document.inutilized","document.halted","cancellation.rejected","nomination.accepted","nomination.rejected","inutilization.approved","inutilization.rejected","inutilization.halted"]},"minItems":1,"maxItems":11},"description":{"type":"string","nullable":true,"maxLength":255},"active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}},"required":["webhook"]}}}},"400":{"description":"The body is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such live webhook in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused by the current state of the document or the numbering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 1 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a webhook endpoint","description":"Its delivery history stays, its pending deliveries fail, and it answers 404 from then on. To rotate the secret, delete the endpoint and register it again.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"webhookId","in":"path"}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such live webhook in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhookId}/deliveries":{"get":{"summary":"List a webhook endpoint's deliveries, newest first","description":"Keyset pagination: pass the page's `nextCursor` as `cursor` for the next one.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"webhookId","in":"path"},{"schema":{"type":"integer","default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The previous page's `nextCursor`."},"required":false,"description":"The previous page's `nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryPage"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such live webhook in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid limit or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver":{"post":{"summary":"Send a delivered or failed delivery again","description":"Puts the delivery back in the queue, due now, with its attempts and retry window reset. The body sent is the event's, frozen when it happened.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"webhookId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"deliveryId","in":"path"}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/WebhookDelivery"}},"required":["delivery"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such live webhook, or no such delivery of it, in the caller's account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The delivery is already pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}