Issue a draft
Issues the draft's document exactly as POST /v1/ec/{resource} issues a body: the same validation (refused at document.<path>), the same plan, quota and held sales, the same preview_id (preview its document with POST /v1/ec/{resource}/preview), and a required Idempotency-Key. The draft is gone once it is a document, deleted in the transaction that numbers it, or once the sale is held at the month's quota (402 plan_quota_reached with held_document_id); any other refusal leaves it as it was. A draft another request already issued is 404 draft_not_found, and nothing is numbered.
AuthorizationBearer <token>Your API key, which acts for the one business it was created for: fb_live_… keys work at api.fiscalbase.io and issue in live, and fb_sandbox_… keys work at api-sandbox.fiscalbase.io and issue in sandbox, on the simulated SRI. A key sent to the other host is refused with api_key_wrong_host, which names its host.
id*stringuuidpreview_id?stringThe preview_id of POST /v1/ec/{resource}/preview for the draft's document: if it isn't the document previewed, or the preview is from an earlier day, nothing is issued and the answer is 409 preview_mismatch.
^[0-9a-f]{64}$idempotency-key*stringRequired. Without it a retry could number another document or reach the SRI again. A retry with the same key and body answers the first answer instead; the same key with another body is 409 idempotency_key_reused.
1 <= length <= 255Fiscalbase-Environment?stringThe environment the call acts in. Required with a person's session; a key's own environment is the one that counts, so a key may leave it out, and naming another is 422 environment_mismatch.
"sandbox""test""live"Fiscalbase-Business?stringThe business the call acts for. With a person's session, the one the call is about (without it, a call about one business is 422 business_required and a list covers every business of the organization); a key acts for its own, so naming another is 422 business_mismatch.
uuidFiscalbase-Channel?stringWhich of Fiscalbase's own integrations a key's call comes from, recorded as the channel of the documents it issues: a record, not a permission. Without it, api. A person's call is always console.
"api""mcp"Fiscalbase-Agent?stringThe AI agent a key's call comes from, as its client names itself (the MCP server sets it); recorded with the request and shown in the console's request log.
Issued: the document, numbered; a repeat with the same Idempotency-Key answers the same
application/json- response
id*stringuuidcountry*"ec"The country, as its lowercase ISO 3166-1 alpha-2 code, the same as in the path (/v1/ec/…). New countries may appear.
"ec"currency*stringThe currency of the amounts, as its ISO 4217 code. New currencies may appear.
^[A-Z]{3}$environment*string"sandbox""test""live"status*string"pending""submitted""authorized""returned""not_authorized""annulled"status_transitions*When the document last reached each status.
business_id*stringuuidnumber*stringaccess_key*string49 <= length <= 49authorization*|nullsri_messages*array<>The messages of the SRI's latest response, each with its cause and what to do. A returned or not_authorized document says here why.
metadata*issued_at*|When it was issued, with date and time. On a document issued here it is the moment Fiscalbase accepted and numbered it, which sets its issue date (always today in Ecuador). SRI documents carry only the date, so on an imported one (channel imported) it is the time the SRI authorized it, and null if nothing dates it.
date-timedelivery_status*|How the emails of the current revision are doing, the heaviest outcome wins: complained (marked the email as spam) over bounced (bounced) over opened (opened it) over delivered (reached the mailbox) over sent (the email provider accepted it, no news yet). null if no email was sent. The email provider reports it; without its notices it stays at sent.
"sent""delivered""opened""bounced""complained"nullemails*array<>The emails sent with the document's current revision, one per recipient and per send, from first to last. Empty if none was sent.
portal_views*integerHow many times its recipient opened the document in the portal, signing in with their code or with the link in the email. Downloads of the RIDE and the XML do not count. 0 if it was never opened.
portal_last_viewed_at*|The last time it was opened in the portal; null if never.
date-timechannel*stringHow it arrived: api if your system issued it with a key, console if someone issued it on the platform, mcp if an agent issued it through the MCP server, cli if the command line issued it, imported if it came in an import from another system. It is recorded at issue and does not change.
"api""console""mcp""imported"import_id*|The import that brought it; null if it was issued here.
uuidverification*|Imported documents only, how we know it is authorized, from most to least certain: sri if the SRI confirmed it at import; listed if its key appears in an SRI listing you uploaded (the Facturador report or the issued-documents one from the SRI's online portal); signature if its file carries the authorization, which nobody signs; unconfirmed if it only has the issuer's signature and nothing shows that the SRI authorized it. unconfirmed documents do not appear in the portal until you upload the listing. Except for sri, the SRI no longer remembered it (or it was imported in sandbox) and its annulment cannot be detected. null if it was issued here.
"sri""listed""signature""unconfirmed"nulllisting*|With verification listed, the listing that shows it authorized and where it came from. Any listing of keys counts, so which one it was is recorded. null otherwise.
object*"document""document"type*"invoice"The family: invoice, credit_note, debit_note, withholding, delivery_note or purchase_settlement. Every other operation on the document is under its path (/v1/ec/invoices/{id}/…).
"invoice"lines*array<>taxes*array<||>subtotal*stringdiscount*stringiva*stringice*stringirbpnr*stringtotal*stringsubsidy*string|nulltip*stringissue_date*stringdatebuyer*payments*array<>plate*string|nulldelivery_note_number*string|nullexport*|nullreimbursement*|nullwithholdings*array<>withheld_iva*string|nullwithheld_renta*string|nullsubstitute_delivery_note*|nullthird_party_charges*array<>negotiable*|nullcompensations*array<>Solidarity compensation of 2 % of the IVA (2016), only on imported documents that carry it.
fiscal_machine*|nulladditional_info*array<>credit_balance*|Invoices only. What can still be credited: the total minus that of the credit notes that modify it and still stand (authorized or still on their way to the SRI; not the returned, not authorized or annulled ones). It never goes below zero. POST /v1/ec/credit-notes rejects a note that exceeds it. null for an invoice issued to consumidor_final, which takes no credit note (NAC-DGERCGC25-00000014, art. 3).
created_at*stringdate-timeupdated_at*stringdate-timecurl -X POST 'https://api.fiscalbase.io/v1/ec/drafts/497f6eca-6276-4993-bfeb-53cbbbba6f08/issue' \
-H 'idempotency-key: string'{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"country": "ec",
"currency": "string",
"environment": "sandbox",
"status": "pending",
"status_transitions": {
"pending": "2019-08-24T14:15:22Z",
"submitted": "2019-08-24T14:15:22Z",
"authorized": "2019-08-24T14:15:22Z",
"returned": "2019-08-24T14:15:22Z",
"not_authorized": "2019-08-24T14:15:22Z",
"annulled": "2019-08-24T14:15:22Z"
},
"business_id": "f59fcbb7-848d-4242-af07-a8bb7e3ab37c",
"number": "string",
"access_key": "stringstringstringstringstringstringstringstrings",
"authorization": {
"number": "string",
"authorized_at": "2019-08-24T14:15:22Z"
},
"sri_messages": [
{
"code": "string",
"message": "string",
"detail": "string",
"type": "error",
"cause": "string",
"remedy": "string"
}
],
"metadata": {
"property1": "string",
"property2": "string"
},
"issued_at": "2019-08-24T14:15:22Z",
"delivery_status": "sent",
"emails": [
{
"to": "string",
"status": "sent",
"sent_at": "2019-08-24T14:15:22Z",
"delivered_at": "2019-08-24T14:15:22Z",
"opened_at": "2019-08-24T14:15:22Z",
"bounced_at": "2019-08-24T14:15:22Z",
"complained_at": "2019-08-24T14:15:22Z",
"bounce_type": "permanent"
}
],
"portal_views": 0,
"portal_last_viewed_at": "2019-08-24T14:15:22Z",
"channel": "api",
"import_id": "13230382-dadc-41f2-963d-e123bd5c0585",
"verification": "sri",
"listing": {
"import_id": "13230382-dadc-41f2-963d-e123bd5c0585",
"file": "string",
"entry": "string",
"sha256": "stringstringstringstringstringstringstringstringstringstringstri",
"line": 1,
"authorized_at": "2019-08-24T14:15:22Z"
},
"object": "document",
"type": "invoice",
"lines": [
{
"code": "string",
"auxiliary_code": "string",
"description": "string",
"unit": "string",
"quantity": "string",
"unit_price": "string",
"discount": "string",
"net": "string",
"taxes": [
{
"type": "iva",
"rate": "iva_15",
"base": "string",
"value": "string"
}
],
"additional_info": [
{
"name": "string",
"value": "string"
}
],
"unsubsidized_price": "string"
}
],
"taxes": [
{
"type": "iva",
"rate": "iva_15",
"base": "string",
"value": "string",
"additional_discount": "string",
"refund": "string"
}
],
"subtotal": "string",
"discount": "string",
"iva": "string",
"ice": "string",
"irbpnr": "string",
"total": "string",
"subsidy": "string",
"tip": "string",
"issue_date": "2019-08-24",
"buyer": {
"identification_type": "ruc",
"identification": "string",
"name": "string",
"address": "string",
"email": "string"
},
"payments": [
{
"method": "sin_sistema_financiero",
"amount": "string",
"term": {
"length": 0,
"unit": "days"
}
}
],
"plate": "string",
"delivery_note_number": "string",
"export": {
"incoterm": "string",
"incoterm_place": "string",
"origin_country": "string",
"loading_port": "string",
"destination_port": "string",
"destination_country": "string",
"acquisition_country": "string",
"subtotal_incoterm": "string",
"international_freight": "string",
"international_insurance": "string",
"customs_costs": "string",
"other_transport_costs": "string"
},
"reimbursement": {
"document_type": "factura",
"total": "string",
"base": "string",
"tax": "string",
"documents": [
{
"supplier": {
"identification_type": "ruc",
"identification": "string"
},
"supplier_type": "persona_natural",
"payment_country": "string",
"document_type": "factura",
"number": "string",
"issue_date": "2019-08-24",
"authorization_number": "string",
"taxes": [
{
"type": "iva",
"rate": "iva_15",
"base": "string",
"value": "string"
}
],
"compensations": [
{
"code": "string",
"rate": "string",
"value": "string"
}
]
}
]
},
"withholdings": [
{
"type": "iva_100",
"value": "string"
}
],
"withheld_iva": "string",
"withheld_renta": "string",
"substitute_delivery_note": {
"origin_address": "string",
"destination_address": "string",
"transport_start": "string",
"transport_end": "string",
"carrier": {
"identification_type": "ruc",
"identification": "string",
"name": "string"
},
"plate": "string",
"destinations": [
{
"reason": "string",
"customs_document": "string",
"destination_establishment": "string",
"route": "string"
}
]
},
"third_party_charges": [
{
"concept": "string",
"amount": "string"
}
],
"negotiable": {
"notification_email": "string"
},
"compensations": [
{
"code": "string",
"rate": "string",
"value": "string"
}
],
"fiscal_machine": {
"brand": "string",
"model": "string",
"serial": "string"
},
"additional_info": [
{
"name": "string",
"value": "string"
}
],
"credit_balance": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}Delete a draft DELETE
Anterior
Import documents POST
Upload your key's business's authorized documents as `multipart/form-data`, or as JSON with each file in base64 for a client that can't send a form: XML, ZIP or the SRI's key listings, issued and received alike. What the business issued (its history from a previous system) becomes its documents, its numbering moving past them; what another RUC issued to it goes to its received documents (`received`), in `live`, checked against the issuer's signature and the SRI, or in `sandbox`, where any well-formed XML addressed to the business is kept unchecked, as `unconfirmed` and with no tax validity. They are stored and queued: it answers `201` with the import in `queued`. Retrieve it or wait for the `import.completed` event. The same files while their import is still running return that import with `200`, and a repeated `Idempotency-Key` answers the first response again.