Skip to Content

Import documents

POST
/v1/ec/imports

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.

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.

Header Parameters

idempotency-key?string

Send the same key to retry safely: a repeat of the same request answers what the first answered, without doing it again. Keys are scoped to your key's business and environment; the same key with another request 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.

Request Body

  1. body
file*array<>

From 1 to 20 files: authorized or merely signed XML (like those the SRI's Facturador downloads), ZIPs of XML, or text with access keys (the Facturador listing or the issued-documents report from the SRI's online portal, saved as text or CSV). A listed key confirms the signed XML of that key, in this import or an earlier one. A PDF will not do: the RIDE proves nothing. Neither will an Excel sheet: save it as CSV.

Response Body

The running import of the same files

application/json
  1. response
id*string
Formatuuid
object*"import"
Value in"import"
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"
environment*string
Value in"sandbox""test""live"
business_id*string
Formatuuid
status*string

queued until the files are read, processing while each document is decided, then completed. failed if the files could not be used; canceled if you canceled it.

Value in"queued""processing""completed""failed""canceled"
status_transitions*

When the import reached each status.

files*array<>
counts*

Documents by result: pending + imported + duplicate + received + skipped + failed = found.

verification*

The imported documents by what shows they are authorized, as this import decided: the SRI (sri), an SRI listing uploaded with them (listed), the authorization their file carries (signature) or nothing more than the issuer's signature (unconfirmed). They add up to counts.imported. A listing uploaded later upgrades them on their document, not here.

currency*string

The currency of sales_total.

Match^[A-Z]{3}$
sales_total*string

Sales in the documents this import brought, with cents: authorized invoices and debit notes minus credit notes. Those that were already there do not count. Withholdings, delivery notes and purchase settlements do not add up.

upgraded*

Documents imported earlier that this import's listings confirmed: they are now listed, counted by what they had (signature or unconfirmed). They are part of counts.duplicate, with the code evidence_added; the unconfirmed ones among them now appear in the portal.

numbering*array<>

Each series in which the import found used numbers. Numbering continues after the highest one, imported or reserved: uploading the SRI's issued-documents report is enough to continue the numbering, even if their XML can no longer be imported.

failure*|null
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
Example Request
curl -X POST 'https://api.fiscalbase.io/v1/ec/imports' \
  -H 'Content-Type: application/json' \
  -d '{
  "files": [
    {
      "name": "string",
      "content_base64": "string"
    }
  ]
}'
Example Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "object": "import",
  "country": "ec",
  "environment": "sandbox",
  "business_id": "f59fcbb7-848d-4242-af07-a8bb7e3ab37c",
  "status": "queued",
  "status_transitions": {
    "queued": "2019-08-24T14:15:22Z",
    "processing": "2019-08-24T14:15:22Z",
    "completed": "2019-08-24T14:15:22Z",
    "failed": "2019-08-24T14:15:22Z",
    "canceled": "2019-08-24T14:15:22Z"
  },
  "files": [
    {
      "name": "string",
      "kind": "xml",
      "size": 0,
      "sha256": "string",
      "ignored_entries": 0
    }
  ],
  "counts": {
    "found": 0,
    "pending": 0,
    "imported": 0,
    "duplicate": 0,
    "received": 0,
    "skipped": 0,
    "failed": 0
  },
  "verification": {
    "sri": 0,
    "listed": 0,
    "signature": 0,
    "unconfirmed": 0
  },
  "currency": "string",
  "sales_total": "string",
  "upgraded": {
    "signature": 0,
    "unconfirmed": 0
  },
  "numbering": [
    {
      "series_id": "0f6582ac-1e7e-41dc-a63a-24fccd074d0c",
      "type": "invoice",
      "establishment": "string",
      "emission_point": "string",
      "highest_imported": 0,
      "highest_reserved": 0,
      "next_number": 0,
      "active": true,
      "created": true
    }
  ],
  "failure": {
    "code": "unreadable_archive",
    "message": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}