Check the status of withholding now
Asks the SRI right now whether it has decided on a submitted document, without waiting for the next scheduled check; the answer arrives through the usual flow (the status changes and the webhook is sent). A pending document is already being signed or sent, and one the SRI has already decided has nothing to ask: both come back as they are, with nothing queued. Each document is checked at most once every 10 seconds: repeating it sooner answers 429 with Retry-After, and the SRI receives a single question however many times it is pressed.
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*stringuuididempotency-key?stringSend 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.
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.
Nothing to check (it is pending or the SRI has already decided): the document, as it is
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*"withholding"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}/…).
"withholding"issue_date*stringdatefiscal_period*stringsupplier*supplier_type*|"persona_natural""sociedad"nullrelated_party*boolean|nullsupport_documents*array<>renta*stringiva*stringisd*stringtotal*stringfiscal_machine*|nulladditional_info*array<>created_at*stringdate-timeupdated_at*stringdate-timecurl -X POST 'https://api.fiscalbase.io/v1/ec/withholdings/497f6eca-6276-4993-bfeb-53cbbbba6f08/refresh-status'{
"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": "withholding",
"issue_date": "2019-08-24",
"fiscal_period": "string",
"supplier": {
"identification_type": "ruc",
"identification": "string",
"name": "string",
"address": "string",
"email": "string"
},
"supplier_type": "persona_natural",
"related_party": true,
"support_documents": [
{
"document_type": "factura",
"number": "string",
"issue_date": "2019-08-24",
"authorization_number": "string",
"accounting_date": "string",
"tax_support": "10",
"foreign_payment": {
"regime": "general",
"country": "string",
"double_taxation_treaty": true,
"subject_to_withholding": true,
"preferential_regime_payment": true
},
"subtotal": "string",
"total": "string",
"taxes": [
{
"type": "iva",
"rate": "iva_15",
"base": "string",
"value": "string"
}
],
"withholdings": [
{
"tax": "renta",
"code": "string",
"percent": "string",
"base": "string",
"value": "string",
"dividends": {
"payment_date": "string",
"income_tax_paid": "string",
"fiscal_year": "string"
},
"banana_boxes": {
"boxes": 0,
"box_price": "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"
}
]
}
]
},
"payments": [
{
"method": "sin_sistema_financiero",
"amount": "string",
"term": {
"length": 0,
"unit": "days"
}
}
]
}
],
"renta": "string",
"iva": "string",
"isd": "string",
"total": "string",
"fiscal_machine": {
"brand": "string",
"model": "string",
"serial": "string"
},
"additional_info": [
{
"name": "string",
"value": "string"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}Renumber withholding POST
Only for a `returned` document with error 45, SECUENCIAL REGISTRADO: another document of the RUC already has that number at the SRI. It takes the next number in its series with a new access key, keeps its content and its issue date, gains a revision and goes back to `pending`. In `sandbox` and `test` this happens on its own; in `live` never, because that number belongs to an authorized document that Fiscalbase does not know about. It requires an `Idempotency-Key`.
Email withholding POST
Queues an email with the RIDE and the authorized XML. In every environment the document is already sent on its own when it is authorized, to its recipient; this send is for resending it, to its recipient or to the addresses you give.