Skip to Content

Issue a draft

POST
/v1/ec/drafts/{id}/issue

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.

Authorization

headerAuthorizationBearer <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.

Path Parameters

id*string
Formatuuid

Query Parameters

preview_id?string

The 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.

Match^[0-9a-f]{64}$

Header Parameters

idempotency-key*string

Required. 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.

Length1 <= length <= 255
Fiscalbase-Environment?string

The 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.

Value in"sandbox""test""live"
Fiscalbase-Business?string

The 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.

Formatuuid
Fiscalbase-Channel?string

Which 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.

Value in"api""mcp"
Fiscalbase-Agent?string

The 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.

Response Body

Issued: the document, numbered; a repeat with the same Idempotency-Key answers the same

application/json
  1. response
id*string
Formatuuid
country*"ec"

The country, as its lowercase ISO 3166-1 alpha-2 code, the same as in the path (/v1/ec/…). New countries may appear.

Value in"ec"
currency*string

The currency of the amounts, as its ISO 4217 code. New currencies may appear.

Match^[A-Z]{3}$
environment*string
Value in"sandbox""test""live"
status*string
Value in"pending""submitted""authorized""returned""not_authorized""annulled"
status_transitions*

When the document last reached each status.

business_id*string
Formatuuid
number*string
access_key*string
Length49 <= length <= 49
authorization*|null
sri_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.

Formatdate-time
delivery_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.

Value in"sent""delivered""opened""bounced""complained"null
emails*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*integer

How 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.

Formatdate-time
channel*string

How 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.

Value in"api""console""mcp""imported"
import_id*|

The import that brought it; null if it was issued here.

Formatuuid
verification*|

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.

Value in"sri""listed""signature""unconfirmed"null
listing*|

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"
Value in"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}/…).

Value in"invoice"
lines*array<>
taxes*array<||>
subtotal*string
discount*string
iva*string
ice*string
irbpnr*string
total*string
subsidy*string|null
tip*string
issue_date*string
Formatdate
buyer*
payments*array<>
plate*string|null
delivery_note_number*string|null
export*|null
reimbursement*|null
withholdings*array<>
withheld_iva*string|null
withheld_renta*string|null
substitute_delivery_note*|null
third_party_charges*array<>
negotiable*|null
compensations*array<>

Solidarity compensation of 2 % of the IVA (2016), only on imported documents that carry it.

fiscal_machine*|null
additional_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*string
Formatdate-time
updated_at*string
Formatdate-time
Example Request
curl -X POST 'https://api.fiscalbase.io/v1/ec/drafts/497f6eca-6276-4993-bfeb-53cbbbba6f08/issue' \
  -H 'idempotency-key: string'
Example Response
{
  "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"
}