canonical: https://jentic.com/apis/facturacobra.com/facturacobra # Facturacobra Cobra · API de facturación electrónica SRI The Cobra API issues electronic tax documents authorized by Ecuador's SRI, including invoices, credit notes, debit notes, and withholding receipts, from a single REST surface. It signs each comprobante and transmits it to the SRI, exposes the authorization status, and can void an authorized document under the SRI rules. Contacts and products are maintained for reuse on documents, an SRI lookup resolves a RUC or cedula against the tax registry, and webhooks deliver authorization events. Authentication uses an API key sent in the X-API-Key header, with separate sandbox and production keys. ## For AI agents Issue SRI-authorized electronic documents for Ecuador through Cobra: emit invoices, credit notes, debit notes, and withholdings, check their authorization status, void them, and look up a RUC or cedula in the SRI registry. ## Scope Does not handle payment collection, bank reconciliation, or payroll. Use for issuing and managing SRI-authorized electronic tax documents in Ecuador only. ## Capabilities - Issue an SRI-authorized electronic document (invoice, credit note, debit note, or withholding) via POST /documents - Check a document's SRI authorization status via GET `/documents/{id}/status` - Void an authorized document under the SRI rules via POST `/documents/{id}/anular` - Resolve a RUC or cedula against the SRI registry via GET `/sri-lookup/{identificacion}` - Maintain reusable contacts and products via POST /contacts and POST /products - Register webhooks for authorization events via POST /webhooks and remove them when no longer needed ## Use cases ### AI agent invoicing assistant An AI billing assistant issues Ecuadorian electronic invoices on behalf of a business and reports back when the SRI authorizes them. Through Jentic it looks up the customer's RUC, emits the comprobante, and polls the authorization status, all without a person opening the Cobra dashboard. Jentic injects the API key at call time, so the agent never holds the secret. Example prompt: Search Jentic for 'issue an SRI-authorized invoice', validate the buyer with GET `/sri-lookup/{identificacion}`, issue the document with POST /documents, then poll GET `/documents/{id}/status` until it is authorized ### Issue and confirm a comprobante Businesses must get each sale authorized by the SRI before it is valid, and they need to know the moment that happens. Cobra signs and transmits the comprobante on POST /documents and exposes its authorization state on a status endpoint, so a workflow can emit the document and confirm authorization rather than assume it. Webhooks can push the same authorization event instead of polling. Example prompt: Call POST /documents to emit the invoice, then read GET `/documents/{id}/status` to confirm the SRI authorized it before sending the customer their copy ### Returns and voids When a sale is reversed, the business issues a credit note or voids the original document under the SRI's rules. Cobra creates the credit note through the same document endpoint and voids an authorized comprobante through a dedicated void action, keeping the fiscal trail correct. This lets an agent handle a return without hand-editing fiscal records. Example prompt: Issue a credit note with POST /documents, or void the original authorized document with POST `/documents/{id}/anular` when the sale is fully reversed ### Customer tax-ID validation Before invoicing, a business confirms the buyer's tax identity so the comprobante is issued against a valid RUC or cedula. Cobra's SRI lookup resolves the identifier against the official registry, so an onboarding or checkout flow can validate the buyer up front and avoid rejected documents. The reusable contacts endpoint then stores the validated party for future invoices. Example prompt: Call GET `/sri-lookup/{identificacion}` with the buyer's RUC, and on a valid result store the party with POST /contacts for reuse on future documents ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/documents` | Issue a comprobante (invoice, credit note, debit note, or withholding) | | GET | `/documents/{id}/status` | Get a document's SRI authorization status | | POST | `/documents/{id}/anular` | Void an authorized comprobante | | GET | `/sri-lookup/{identificacion}` | Look up a RUC or cedula in the SRI registry | | POST | `/contacts` | Create or update a contact | | POST | `/products` | Create a product | | POST | `/webhooks` | Register a webhook for authorization events | | GET | `/documents` | List comprobantes | ## Key resources - **Documents** — Issue, list, inspect, check the authorization status of, and void SRI electronic documents - **SRI lookup** — Resolve a RUC or cedula against the SRI tax registry - **Contacts and products** — Maintain reusable parties and catalogue items for use on documents - **Webhooks** — Register and remove webhooks that deliver authorization events ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 44 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 72 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 21 / 100 - Agent Usability: 94 / 100 - Security: 50 / 100 - AI Discoverability: 63 / 100 - **View full report:** https://jentic.com/apis/facturacobra.com/facturacobra/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Cobra API by hand means managing its X-API-Key header, keeping sandbox and production keys apart, and building the issue-then-poll-authorization loop against the SRI yourself. Through Jentic you install once, import Cobra from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Cobra puts each document id in the URL path, such as `/documents/{id}`, so a rule can let your agent read and check documents while keeping fiscal writes out. You choose the operations it may call, so issuing a comprobante with POST /documents or voiding one with POST `/documents/{id}/anular` is not included unless you add it. - **Credential handling:** Your Cobra API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'issue an SRI-authorized invoice' or 'look up a RUC', and Jentic returns the matching Cobra operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **AvaTax API** — Tax compliance and calculation platform with e-invoicing across many jurisdictions - **Faktoora API** — Invoicing API for creating and managing invoices without an SRI-specific authorization flow - **Altoviz API** — Accounting API that can hold the ledger behind the documents Cobra issues ## FAQ ### What authentication does the Cobra API use? The Cobra API authenticates with an API key sent in the X-API-Key header, in the format mfact__, per its OpenAPI spec, and a sandbox key runs against the test environment while a production key issues real documents. When you call it through Jentic, the key is stored encrypted by your own Jentic One instance and injected at execution time, so it never enters the agent's prompt, logs, or context. ### Can I issue an SRI-authorized invoice with the Cobra API? Yes. Call POST /documents with the document type and line items to emit an invoice, credit note, debit note, or withholding, and Cobra signs it and transmits it to the SRI. Confirm the outcome with GET `/documents/{id}/status`, which reports the SRI authorization state for that document. ### Can I void or credit an already-issued document with the Cobra API? Yes. Issue a credit note through POST /documents, or void an authorized document with POST `/documents/{id}/anular`, which applies the SRI's void rules. That keeps the fiscal record correct when a sale is reversed without hand-editing authorized documents. ### What are the rate limits for the Cobra API? The OpenAPI spec does not specify rate limits for the Cobra API. Check the Cobra documentation for current limits, design your agent to back off when the API signals that it is being throttled, and prefer webhooks over polling for authorization events. ### How do I issue an invoice through Jentic? Search Jentic for 'issue an SRI-authorized invoice' to load the Cobra document operation with its input schema, validate the buyer with GET `/sri-lookup/{identificacion}`, then call POST /documents and read GET `/documents/{id}/status` to confirm authorization. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the Cobra API? Yes. Because you run Jentic One yourself, you decide which Cobra operations the agent may call. You can allow read operations such as GET /documents and GET `/documents/{id}/status` so the agent can list and check comprobantes, while leaving out issuing or voiding documents unless you add them, and every call the agent makes is logged.