Issue invoice
An invoice ("factura") records a sale. Its body needs the buyer (identified by ruc, cedula, pasaporte or exterior, or consumidor_final for a sale of at most USD 50), the lines, each with its taxes (one iva, and an ice or irbpnr where they apply), and the payments, which add up to the total (a single payment may leave out its amount). Fiscalbase computes every total from the lines. Look up codes with GET /v1/ec/catalogs/{table} (payment_methods, iva_rates, ice). To cancel or reduce an invoice later, issue a credit note; to add charges, a debit note.
Issuing numbers the document, stores it and queues it to be signed and sent to the SRI, all at once: the issue date is today in Ecuador. The status then advances on its own (pending, submitted, then authorized, returned or not_authorized): send wait to answer once the SRI decides, or retrieve it or receive a webhook. A refused document says why in sri_messages, each with its remedy. Check the body first with POST /v1/ec/invoices/preview, which spends no number, and pass its preview_id to issue exactly what was previewed. Send an Idempotency-Key to retry without duplicating.
Your API key, which acts for the one business it was created for: fb_sandbox_… issues in sandbox, fb_test_… in test, the tax authority's testing service, and fb_live_… in live.
In: header
Query Parameters
Seconds, up to 25, to wait for the SRI's decision before answering: the answer comes as soon as the document leaves pending and submitted (authorized, returned or not_authorized), or when the time runs out, still undecided. Without it, at once. The SRI usually decides within seconds; when it is slow, keep the webhook or retrieve the document later.
0 <= value <= 25The preview_id of POST /v1/ec/invoices/preview for this same body: if the body isn't the one previewed, or the preview is from an earlier day, nothing is issued and the answer is 409 preview_mismatch.
^[0-9a-f]{64}$Header Parameters
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The issue date is always today in Ecuador: documents are transmitted when issued.
1 <= items1 <= itemsVehicle plate (placa): of the commercial transport service (tabla 33) or the vehicle fuel was dispatched to (tabla 29). No spaces.
^[A-Z0-9-]{1,20}$Tip (propina), up to 10 % of the subtotal before taxes. It adds to the total.
^\d+(\.\d{1,2})?$Number of the delivery note that accompanies the goods (guiaRemision).
^\d{3}-\d{3}-\d{9}$Export invoice (annex 4). The buyer needs an address.
Expense reimbursement (annex 5): the documents being reimbursed. We compute their totals.
Withholdings the invoice itself declares (retenciones, tablas 22 and 23): fuel marketers and press.
Invoice that replaces a delivery note (annex 9): the transfer of the goods it sells.
Other third-party items (annex 8): amounts you collect on behalf of third parties. They aren't part of the invoice's total.
Negotiable commercial document (annex 11): requires the counterparty's address and a term on each payment.
Additional discount on the IVA base of a rate (descuentoAdicional), applied after the lines: the IVA of that rate is computed on the base minus the discount.
IVA refunded to an older adult (valorDevolucionIva, annex 20), by rate, as the SRI's DIG service authorized it. It is subtracted from the total; the buyer must identify with a cedula.
The fiscal machine the document is issued from (annex 13). Only when one issues it.
[]The establishment whose series numbers it, such as 001. Without it, the first active series of the document type.
^\d{3}$The emission point of that establishment, such as 001. Without it, the first active one.
^\d{3}$Up to 20 pairs of your own, such as your order id, returned as sent and never interpreted; lists filter by them (metadata[key]=value).
{}Only with a sandbox key (422 in test and live, where the SRI decides): the outcome the simulator gives this revision, to rehearse how your system handles each one. Without it, it is authorized.
Response Body
application/json
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/v1/ec/invoices" \ -H "Content-Type: application/json" \ -d '{ "buyer": { "identification_type": "consumidor_final" }, "lines": [ { "description": "string", "quantity": "string", "unit_price": "string", "taxes": [ { "type": "iva", "rate": "iva_15" } ] } ], "payments": [ { "method": "sin_sistema_financiero" } ] }'{ "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" }, "entity_id": "8161163a-f227-466f-bc01-090a01e80165", "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": "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": "string", "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": "string", "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"}Record the annulment of invoice POST
Only records an annulment you already made in the SRI's online portal; it does not request it from the SRI. The document goes to `annulled`, keeps its files, leaves your customer's portal and `<object>.annulled` is sent to your webhooks. Only for an `authorized` one, and never for one issued to a `consumidor_final` buyer, which the SRI does not annul.
List invoices GET
From newest to oldest, in your key's environment.