### Invoice Creation Example

Source: https://factuplan.com.ec/docs/api

Example cURL command for creating an invoice, demonstrating required headers and content type.

```APIDOC
## POST /v1/developer/invoices

### Description
This endpoint is used to create an invoice. It requires specific headers for authentication and taxpayer identification.

### Method
POST

### Endpoint
/v1/developer/invoices

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key (`ak_test_*` or `ak_live_*`). Identifies the workspace and plan.
- **x-taxpayer-ruc** (string) - Required - The RUC of the issuing taxpayer (13 digits). Required when issuing or querying documents.
- **Content-Type** (string) - Required - Specifies the format of the request body, typically `application/json`.

### Request Example
```json
{
  "example": "curl https://api-rest.factuplan.com.ec/v1/developer/invoices \
  -H \"X-API-Key: $FACTUPLAN_API_KEY\" \
  -H \"x-taxpayer-ruc: 0950194407001\" \
  -H \"Content-Type: application/json\" \
  -d @factura.json"
}
```

### Response
#### Success Response (200/201)
- **data** (object) - Contains the created resource or list of resources.
- **meta** (object) - Metadata about the request, including `requestId` and `timestamp`.
  - **requestId** (string) - Unique identifier for the request.
  - **timestamp** (string) - Timestamp of the response in ISO 8601 format.

If the response is a paginated list, `meta.pagination` will be included:
- **pagination** (object) - Pagination details for the list.
  - **total** (integer) - Total number of items.
  - **page** (integer) - Current page number.
  - **limit** (integer) - Number of items per page.
  - **totalPages** (integer) - Total number of pages.

#### Response Example
```json
{
  "data": { /* resource or list */ },
  "meta": {
    "requestId": "req_1a2b3c",
    "timestamp": "2026-05-13T12:34:56.789Z"
  }
}
```

### Error Handling
- **statusCode** (integer) - The HTTP status code of the error.
- **message** (string) - A human-readable error message.
- **code** (string) - An internal error code.
- **details** (array) - An array of specific error details.

**HTTP Status Codes:**
- `200` / `201`: Operation successful.
- `400`: Validation error or malformed body.
- `401`: Missing, invalid, or expired API key.
- `403`: Insufficient permissions or incompatible plan.
- `404`: Resource not found.
- `422`: Data syntactically valid but rejected by business rules or SRI.
- `429`: Rate limit or monthly quota exceeded.
- `500`: Internal error — retry with backoff.
```

--------------------------------

### Usage and Quota Response (200 OK)

Source: https://factuplan.com.ec/docs/api

Example JSON response for a successful request to the usage endpoint.

```json
{
  "data": {
    "currentMonth": "2026-05",
    "plan": "growth",
    "monthlyQuota": 1000,
    "monthlyUsed": 273
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```

--------------------------------

### Upload Certificate Response (200 OK)

Source: https://factuplan.com.ec/docs/api

Example JSON response after successfully uploading a digital certificate.

```json
{
  "data": {
    "hasCertificate": true,
    "isExpired": false,
    "daysUntilExpiry": 87,
    "ruc": "0950194407001",
    "legalName": "Mi Empresa S.A.",
    "expiresAt": "2026-08-08T00:00:00.000Z",
    "created": true
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```

--------------------------------

### List Invoices Response

Source: https://factuplan.com.ec/docs/api

Example response for listing invoices. Includes pagination details and a list of invoice objects.

```json
{
  "data": [
    {
      "id": "rcpt_01HABC",
      "accessKey": "0104202601099337815000110010010000000011234567890",
      "sequential": "000000007",
      "status": "AUTHORIZED",
      "total": 172.5,
      "createdAt": "2026-05-13T12:34:56.789Z"
    }
  ],
  "meta": {
    "requestId": "req_1a2b3c",
    "timestamp": "2026-05-13T12:34:56.789Z",
    "pagination": { "total": 120, "page": 1, "limit": 20, "totalPages": 6 }
  }
}
```

--------------------------------

### GET /v1/developer/usage

Source: https://factuplan.com.ec/docs/api

Retrieves the current month's document consumption, plan limit, and estimated cost.

```APIDOC
## GET /v1/developer/usage

### Description
Returns the document consumption for the current month, your plan's limit, and the estimated cost.

### Method
GET

### Endpoint
/v1/developer/usage

### Response
#### Success Response (200 OK)
- **currentMonth** (string) - Current period (YYYY-MM).
- **plan** (string) - Workspace's current plan.
- **monthlyQuota** (number) - Monthly plan limit.
- **monthlyUsed** (number) - Documents consumed in the period.

### Response Example
```json
{
  "data": {
    "currentMonth": "2026-05",
    "plan": "growth",
    "monthlyQuota": 1000,
    "monthlyUsed": 273
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### Making an API Request with cURL

Source: https://factuplan.com.ec/docs/api

This example demonstrates how to make a POST request to the invoices endpoint using cURL. Ensure you replace $FACTUPLAN_API_KEY with your actual API key and provide the correct taxpayer RUC.

```shell
curl https://api-rest.factuplan.com.ec/v1/developer/invoices \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001" \
  -H "Content-Type: application/json" \
  -d @factura.json
```

--------------------------------

### Create Invoice with cURL

Source: https://factuplan.com.ec/docs/api

Example of how to create an invoice using a cURL request. Ensure to replace placeholders with your actual API key and customer/item details.

```curl
curl https://api-rest.factuplan.com.ec/v1/developer/invoices \
  -X POST \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "identificationType": "RUC",
      "identification": "0993378150001",
      "legalName": "Empresa Demo S.A.",
      "email": "facturas@empresademo.ec"
    },
    "items": [
      {
        "code": "SERV-001",
        "description": "Servicio de consultoría",
        "quantity": 1,
        "unitPrice": 150.0,
        "taxType": "IVA_RATE",
        "tax": 15
      }
    ],
    "payments": [
      { "method": "20", "amount": 172.5 }
    ]
  }'
```

--------------------------------

### Listar guías de remisión

Source: https://factuplan.com.ec/docs/api

Retrieves a list of electronic dispatch guides with filtering and pagination options.

```APIDOC
## GET /v1/developer/waybills

### Description
Retrieves a list of electronic dispatch guides, supporting pagination and filtering by status, date range, and search terms.

### Method
GET

### Endpoint
/v1/developer/waybills

### Parameters
#### Query Parameters
- **page** (number) - Optional - Defaults to `1`. The requested page number.
- **limit** (number) - Optional - Defaults to `20`. Maximum number of items per page (max `100`).
- **search** (string) - Optional - General search term (sequential, access key, recipient).
- **status** (enum) - Optional - Filter by status. Possible values: `PROCESSING`, `AUTHORIZED`, `REJECTED`, `VOIDED`, `ERROR`.
- **dateFrom** (string) - Optional - Start date for filtering in ISO 8601 format (e.g., `2026-01-01`).
- **dateTo** (string) - Optional - End date for filtering in ISO 8601 format (e.g., `2026-12-31`).
```

--------------------------------

### Digital Certificate Status Response (200 OK)

Source: https://factuplan.com.ec/docs/api

Example JSON response for a successful request to the certificate status endpoint.

```json
{
  "data": {
    "hasCertificate": true,
    "isExpired": false,
    "daysUntilExpiry": 87,
    "ruc": "0950194407001",
    "legalName": "Mi Empresa S.A.",
    "issuedAt": "2025-05-13T00:00:00.000Z",
    "expiresAt": "2026-08-08T00:00:00.000Z",
    "issuer": "Banco Central del Ecuador"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```

--------------------------------

### Emitir guía de remisión

Source: https://factuplan.com.ec/docs/api

Issues an electronic dispatch guide. The system generates the XML, signs it with your P12 certificate, and authorizes it with the SRI asynchronously.

```APIDOC
## POST /v1/developer/waybills

### Description
Issues an electronic dispatch guide (codDoc `06`). The system generates the XML, signs it with your P12 certificate, and authorizes it with the SRI asynchronously.

### Method
POST

### Endpoint
/v1/developer/waybills

### Parameters
#### Request Body
- **emissionPointId** (string) - Optional - UUID of the emission point (auto-detected if omitted).
- **customer** (object) - Required - Main recipient, same structure as in invoices.
  - **identificationType** (string) - Required - Type of identification (e.g., RUC).
  - **identification** (string) - Required - Identification number.
  - **legalName** (string) - Required - Legal name of the customer.
  - **email** (string) - Required - Email address of the customer.
- **transporterRuc** (string) - Required - RUC of the transporter.
- **transporterName** (string) - Required - Name or legal name of the transporter.
- **vehiclePlate** (string) - Required - Vehicle plate number (e.g., `ABC-1234`).
- **departureAddress** (string) - Required - Departure address.
- **transportStartDate** (string) - Required - Start date of transport (ISO 8601 format).
- **transportEndDate** (string) - Required - End date of transport (ISO 8601 format).
- **items** (array) - Required - Merchandise being transported. Each item should have:
  - **code** (string) - Required - Item code.
  - **description** (string) - Required - Item description.
  - **quantity** (number) - Required - Quantity of the item.
- **destinations** (array) - Required - Delivery points. Each destination object should contain:
  - **receiverIdentification** (string) - Required - Receiver's RUC or ID.
  - **receiverName** (string) - Required - Receiver's name.
  - **address** (string) - Required - Destination address.
  - **transferReason** (string) - Required - Reason for transfer (e.g., "Venta de mercadería").
  - **codDocSustento** (string) - Optional - Code of the supporting document (e.g., `01` for invoice).
  - **numDocSustento** (string) - Optional - Number of the supporting document (e.g., `001-001-000000001`).
- **additionalInfo** (object) - Optional - Additional key-value fields.

### Response
#### Success Response (201 Created)
- **data** (object) - Contains details of the created dispatch guide.
  - **id** (string) - The unique identifier for the dispatch guide.
  - **accessKey** (string) - The access key generated for the dispatch guide.
  - **sequential** (string) - The sequential number of the dispatch guide.
  - **status** (string) - The current processing status (e.g., `PROCESSING`).
- **meta** (object) - Metadata about the request.
  - **requestId** (string) - The unique identifier for the request.
  - **timestamp** (string) - The timestamp of the response.

### Request Example
```json
{
  "emissionPointId": "ep_id (opcional)",
  "customer": {
    "identificationType": "RUC",
    "identification": "0993378150001",
    "legalName": "Empresa Demo S.A.",
    "email": "facturas@empresademo.ec"
  },
  "transporterRuc": "0950194407001",
  "transporterName": "Transportes Demo S.A.",
  "vehiclePlate": "ABC-1234",
  "departureAddress": "Av. de las Américas, Guayaquil",
  "transportStartDate": "2026-06-10",
  "transportEndDate": "2026-06-11",
  "items": [
    {
      "code": "PROD-001",
      "description": "Descripción de la mercadería",
      "quantity": 10
    }
  ],
  "destinations": [
    {
      "receiverIdentification": "0993378150001",
      "receiverName": "Empresa Receptora S.A.",
      "address": "Av. Amazonas, Quito",
      "transferReason": "Venta de mercadería",
      "codDocSustento": "01",
      "numDocSustento": "001-001-000000001"
    }
  ],
  "additionalInfo": {}
}
```

### Response Example
```json
{
  "data": {
    "id": "rcpt_01HABCDEF",
    "accessKey": "0612202404179214289100110010060000001231234567816",
    "sequential": "000000001",
    "status": "PROCESSING"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### Consultar, descargar y anular guías de remisión

Source: https://factuplan.com.ec/docs/api

Provides endpoints to get details, status, XML, PDF, or void an electronic dispatch guide.

```APIDOC
## Generic Receipt Endpoints

### Description
Once a dispatch guide is issued, you can use these generic endpoints to manage it.

### Method
GET, POST

### Endpoints
- **GET /v1/developer/receipts/:id**: Retrieves the detail of a specific dispatch guide.
- **GET /v1/developer/receipts/:id/status**: Retrieves the current status of a specific dispatch guide.
- **GET /v1/developer/receipts/:id/xml**: Downloads the authorized XML of a specific dispatch guide.
- **GET /v1/developer/receipts/:id/pdf**: Downloads the PDF (RIDE) of a specific dispatch guide.
- **POST /v1/developer/receipts/:id/void**: Marks the dispatch guide as `VOIDED` within the Factuplan system. Note: This action does not void the guide with the SRI; that is the issuer's responsibility.
```

--------------------------------

### Upload Digital Certificate using cURL

Source: https://factuplan.com.ec/docs/api

Example of how to upload a P12 certificate using cURL, including the API key, file path, and password.

```bash
curl -X POST https://api-rest.factuplan.com.ec/v1/developer/certificate \
  -H "x-api-key: ak_live_TU_CLAVE" \
  -F "file=@/ruta/firma.p12" \
  -F "password=MiContraseña"
```

--------------------------------

### GET /v1/developer/customers/{id}

Source: https://factuplan.com.ec/docs/api

Retrieves the complete details of a specific customer using their unique ID.

```APIDOC
## GET /v1/developer/customers/{id}

### Description
Retrieves the complete details of a specific customer by their ID.

### Method
GET

### Endpoint
/v1/developer/customers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.

#### Response
#### Success Response (200 OK)
- **data.id** (string) - The unique identifier for the customer.
- **data.taxpayerId** (string) - The taxpayer ID associated with the customer.
- **data.identificationType** (string) - The type of identification provided.
- **data.identification** (string) - The customer's identification number.
- **data.legalName** (string) - The legal name of the customer.
- **data.email** (string) - The customer's email address.
- **data.isActive** (boolean) - Indicates if the customer is active.
- **data.createdAt** (string) - The timestamp when the customer was created.
- **data.updatedAt** (string) - The timestamp when the customer was last updated.
- **meta.requestId** (string) - The ID of the request.
- **meta.timestamp** (string) - The timestamp of the response.

### Response Example
```json
{
  "data": {
    "id": "cust_01HABC",
    "taxpayerId": "tax_01H...",
    "identificationType": "RUC",
    "identification": "0993378150001",
    "legalName": "Empresa Demo S.A.",
    "email": "facturas@empresademo.ec",
    "isActive": true,
    "createdAt": "2026-05-13T12:34:56.789Z",
    "updatedAt": "2026-05-13T12:34:56.789Z"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### Get Monthly Usage and Quota

Source: https://factuplan.com.ec/docs/api

Retrieves the current month's document consumption, plan limit, and estimated cost.

```http
GET /v1/developer/usage
```

--------------------------------

### Get Customer Request

Source: https://factuplan.com.ec/docs/api

Fetch the complete details of a specific customer using their unique ID.

```http
GET /v1/developer/customers/{id}
```

--------------------------------

### Sign and Authorize XML with cURL

Source: https://factuplan.com.ec/docs/api

Example using cURL to send an unsigned invoice XML for signing and authorization by Factuplan. Ensure your API key and taxpayer RUC are correctly set.

```shell
curl -X POST https://api-rest.factuplan.com.ec/v1/developer/sign-and-authorize \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001" \
  -H "Content-Type: application/json" \
  -d '{ "xml": "<factura>...</factura>"}'
```

--------------------------------

### Python Example for Emitting Invoices with Exponential Backoff

Source: https://factuplan.com.ec/docs/api

This Python snippet demonstrates how to emit an invoice using the requests library, implementing exponential backoff for retries when encountering rate limit errors (HTTP 429). It includes setting up API endpoint, headers, and handling retries with a sleep strategy.

```python
import os, time, requests


API = "https://api-rest.factuplan.com.ec/v1/developer"
HEADERS = {
    "X-API-Key": os.environ["FACTUPLAN_API_KEY"],
    "x-taxpayer-ruc": "0950194407001",
    "Content-Type": "application/json",
}


def emit_invoice(body, intentos=3):
    for i in range(intentos):
        r = requests.post(f"{API}/invoices", json=body, headers=HEADERS, timeout=30)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        time.sleep(0.5 * (2 ** i))
    r.raise_for_status()

```

--------------------------------

### Get, Update, and Delete Product or Service

Source: https://factuplan.com.ec/docs/api

Allows retrieving a specific product or service by its ID, updating its details, or deleting it. Updates can be partial.

```APIDOC
## GET, PATCH, DELETE /v1/developer/products/{id}

### Description
Allows retrieving a specific product or service by its ID, updating its details, or deleting it. Updates can be partial.

### Method
GET, PATCH, DELETE

### Endpoint
/v1/developer/products/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the product or service.

#### Request Body (for PATCH)
- **code** (string) - Optional - Unique identifier in your workspace.
- **type** (enum) - Optional - `PRODUCT`, `SERVICE`.
- **name** (string) - Optional - Appears on the RIDE.
- **unitPrice** (number) - Optional - Up to 4 decimal places of precision.
- **taxType** (enum) - Optional - `IVA_0`, `IVA_RATE`, `NOT_TAXABLE`, `EXEMPT`.
- **auxiliaryCode** (string) - Optional - Secondary code (SKU, barcode…).
- **description** (string) - Optional - Long description.
- **iceCode** (string) - Optional - SRI ICE code.
- **iceRate** (number) - Optional - Applicable ICE rate.
- **irbpnr** (boolean) - Optional - `true` if the item applies IRBPNR.
- **unitOfMeasure** (string) - Optional - E.g., `unidad`, `kg`, `hora`.
- **isActive** (boolean) - Optional - `true` to activate, `false` to deactivate.

### Request Example (PATCH)
{
  "unitPrice": 160.0,
  "isActive": false
}

### Response
#### Success Response (200 - GET)
- **code** (string) - Unique identifier in your workspace.
- **type** (enum) - `PRODUCT`, `SERVICE`.
- **name** (string) - Appears on the RIDE.
- **unitPrice** (number) - Up to 4 decimal places of precision.
- **taxType** (enum) - `IVA_0`, `IVA_RATE`, `NOT_TAXABLE`, `EXEMPT`.
- **auxiliaryCode** (string) - Secondary code (SKU, barcode…).
- **description** (string) - Long description.
- **iceCode** (string) - SRI ICE code.
- **iceRate** (number) - Applicable ICE rate.
- **irbpnr** (boolean) - `true` if the item applies IRBPNR.
- **unitOfMeasure** (string) - E.g., `unidad`, `kg`, `hora`.
- **isActive** (boolean) - Indicates if the item is active.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.

#### Success Response (200 - PATCH/DELETE)
- **message** (string) - Confirmation message.

### Notes
- `PATCH` accepts any subset of creation fields plus `isActive: boolean`.
- `DELETE` does not affect historical receipts that already reference the item.
```

--------------------------------

### Download PDF (RIDE)

Source: https://factuplan.com.ec/docs/api

Get a pre-signed URL for the receipt's PDF (RIDE), which expires in 5 minutes. A permanent preview URL is also included.

```http
GET /v1/developer/receipts/{id}/pdf
```

```json
{
  "data": {
    "url": "https://files.factuplan.com.ec/...?sig=...",
    "previewUrl": "https://files.factuplan.com.ec/preview/rcpt_01HABC.pdf"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```

--------------------------------

### Query Receipt by Access Key

Source: https://factuplan.com.ec/docs/api

Query any SRI-authorized receipt (Invoice, Credit Note, Guide) using its access key. The system automatically creates the issuer if they don't exist in your workspace. This endpoint is only available for live API keys (`ak_live_*`).

```http
POST /v1/developer/receipts/query
```

```json
{
  "accessKey": "0104202601019999999900110010010000000011234567813",
  "save": true
}
```

--------------------------------

### GET /v1/developer/receipts/{id}/xml

Source: https://factuplan.com.ec/docs/api

Download the authorized XML of a receipt. This endpoint provides a pre-signed URL for the XML file that expires in 5 minutes, and a permanent preview URL.

```APIDOC
## GET /v1/developer/receipts/{id}/xml

### Description
Returns a pre-signed URL of the SRI-authorized XML (expires in **5 minutes**) and a permanent preview URL (`previewUrl`) that does not expire.

### Method
GET

### Endpoint
/v1/developer/receipts/{id}/xml

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the receipt.

### Response
#### Success Response (200 OK)
- **data.url** (string) - A pre-signed URL for the XML file.
- **data.previewUrl** (string) - A permanent URL for previewing the XML.
- **meta.requestId** (string) - The ID of the request.
- **meta.timestamp** (string) - The timestamp of the request.

#### Response Example
```json
{
  "data": {
    "url": "https://files.factuplan.com.ec/...?sig=...",
    "previewUrl": "https://files.factuplan.com.ec/preview/rcpt_01HABC.xml"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### POST /v1/developer/receipts/query

Source: https://factuplan.com.ec/docs/api

Query any receipt authorized by the SRI (Invoices 01, Credit Notes 04, Guides 06), regardless of the issuing system. If the issuing taxpayer does not exist in your workspace, it is automatically created with an empty signature. This endpoint is only available with `ak_live_*` keys and not with test keys. The credit is deducted when the receipt is authorized, not when `save` is set to false.

```APIDOC
## POST /v1/developer/receipts/query

### Description
Query any receipt authorized by the SRI (Invoices `01`, Credit Notes `04`, Guides `06`), regardless of the issuing system. If the issuing taxpayer does not exist in your workspace, it is automatically created with an empty signature. This endpoint is only available with `ak_live_*` keys and not with test keys. The credit is deducted when the receipt is authorized, not when `save` is set to false.

### Method
POST

### Endpoint
/v1/developer/receipts/query

### Parameters
#### Request Body
- **accessKey** (string) - Required - SRI access key (49 digits).
- **save** (boolean) - Optional (default `true`) - If `false`, it only verifies without saving to the database or generating a PDF.

### Request Example
```json
{
  "accessKey": "0104202601019999999900110010010000000011234567813",
  "save": true
}
```
```

--------------------------------

### GET /v1/developer/receipts/{id}/pdf

Source: https://factuplan.com.ec/docs/api

Download the PDF (RIDE) of a receipt. This endpoint provides a pre-signed URL for the PDF that expires in 5 minutes, and a permanent preview URL.

```APIDOC
## GET /v1/developer/receipts/{id}/pdf

### Description
Returns a pre-signed URL of the receipt's PDF (RIDE) (expires in **5 minutes**) and a permanent preview URL (`previewUrl`).

### Method
GET

### Endpoint
/v1/developer/receipts/{id}/pdf

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the receipt.

### Response
#### Success Response (200 OK)
- **data.url** (string) - A pre-signed URL for the PDF file.
- **data.previewUrl** (string) - A permanent URL for previewing the PDF.
- **meta.requestId** (string) - The ID of the request.
- **meta.timestamp** (string) - The timestamp of the request.

#### Response Example
```json
{
  "data": {
    "url": "https://files.factuplan.com.ec/...?sig=...",
    "previewUrl": "https://files.factuplan.com.ec/preview/rcpt_01HABC.pdf"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### Get, Update, and Delete Product

Source: https://factuplan.com.ec/docs/api

Manage individual products or services using their unique ID. PATCH allows partial updates including the `isActive` status, while DELETE removes the item. Historical records are unaffected by deletion.

```http
GET /v1/developer/products/{id}
PATCH /v1/developer/products/{id}
DELETE /v1/developer/products/{id}
```

--------------------------------

### GET /v1/developer/receipts/{id}/status

Source: https://factuplan.com.ec/docs/api

Get the current status of a receipt, which can be `PROCESSING`, `AUTHORIZED`, `COMPLETED`, `ERROR`, or `REJECTED`.

```APIDOC
## GET /v1/developer/receipts/{id}/status

### Description
Returns the current status of the receipt: `PROCESSING`, `AUTHORIZED`, `COMPLETED`, `ERROR`, or `REJECTED`.

### Method
GET

### Endpoint
/v1/developer/receipts/{id}/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the receipt.

### Response
#### Success Response (200 OK)
- **data.status** (string) - The current status of the receipt.
- **data.authorizationNumber** (string) - The authorization number, if applicable.
- **data.messages** (array) - A list of messages related to the status.
- **meta.requestId** (string) - The ID of the request.
- **meta.timestamp** (string) - The timestamp of the request.

#### Response Example
```json
{
  "data": {
    "status": "AUTHORIZED",
    "authorizationNumber": "0104202601...",
    "messages": []
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### Create Product or Service

Source: https://factuplan.com.ec/docs/api

Use this endpoint to add new products or services to your catalog. The request body specifies details like code, type, name, price, and tax information.

```http
POST /v1/developer/products
```

```json
{
  "code": "SERV-001",
  "type": "SERVICE",
  "name": "Servicio de consultoría",
  "unitPrice": 150.0,
  "taxType": "IVA_RATE",
  "auxiliaryCode": "AUX-001",
  "description": "Hora de consultoría técnica",
  "iceCode": "",
  "iceRate": 0,
  "irbpnr": false,
  "unitOfMeasure": "hora"
}
```

--------------------------------

### Quick Test with cURL

Source: https://factuplan.com.ec/docs/api

This snippet demonstrates how to quickly test the API's usage endpoint using cURL. Ensure your API key is stored in the FACTUPLAN_API_KEY environment variable.

```bash
curl https://api-rest.factuplan.com.ec/v1/developer/usage \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "Accept: application/json"
```

--------------------------------

### GET /v1/developer/certificate/status

Source: https://factuplan.com.ec/docs/api

Indicates if the configured P12 certificate is valid, its expiration date, and the holder's RUC.

```APIDOC
## GET /v1/developer/certificate/status

### Description
Indicates if the P12 certificate configured in your account is valid, its expiration date, and the holder's RUC. If it's not valid, invoices cannot be signed.

### Method
GET

### Endpoint
/v1/developer/certificate/status

### Response
#### Success Response (200 OK)
- **hasCertificate** (boolean) - Whether a certificate is uploaded.
- **isExpired** (boolean) - `true` if the certificate has expired.
- **daysUntilExpiry** (number) - Days remaining until expiration.
- **ruc** (string) - Certificate holder's RUC.
- **legalName** (string) - Legal name registered on the certificate.
- **issuedAt** (string) - Issue date (ISO 8601).
- **expiresAt** (string) - Expiration date (ISO 8601).
- **issuer** (string) - Issuing certification authority.

### Response Example
```json
{
  "data": {
    "hasCertificate": true,
    "isExpired": false,
    "daysUntilExpiry": 87,
    "ruc": "0950194407001",
    "legalName": "Mi Empresa S.A.",
    "issuedAt": "2025-05-13T00:00:00.000Z",
    "expiresAt": "2026-08-08T00:00:00.000Z",
    "issuer": "Banco Central del Ecuador"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### POST /v1/developer/customers

Source: https://factuplan.com.ec/docs/api

Creates a new customer record in the system. This endpoint allows for the registration of new clients with their identification details, contact information, and addresses.

```APIDOC
## POST /v1/developer/customers

### Description
Creates a new customer record.

### Method
POST

### Endpoint
/v1/developer/customers

### Parameters
#### Request Body
- **identificationType** (enum) - Required - `RUC`, `CEDULA`, `PASSPORT`, `FINAL_CONSUMER`.
- **identification** (string) - Required - Validates length and check digit.
- **legalName** (string) - Required - Company name or full name.
- **email** (string) - Optional - For automatic RIDE sending.
- **address** (string) - Optional - Appears on the RIDE.
- **phone** (string) - Optional - Free format.
- **additionalEmail** (string) - Optional - Optional copy for RIDE sending.

### Request Example
```json
{
  "identificationType": "RUC",
  "identification": "0993378150001",
  "legalName": "Empresa Demo S.A.",
  "email": "facturas@empresademo.ec",
  "address": "Guayaquil, Ecuador",
  "phone": "+593985691039",
  "additionalEmail": "contabilidad@empresademo.ec"
}
```

### Response
#### Success Response (201 Created)
- **data.id** (string) - The unique identifier for the created customer.
- **data.taxpayerId** (string) - The taxpayer ID associated with the customer.
- **data.identificationType** (string) - The type of identification provided.
- **data.identification** (string) - The customer's identification number.
- **data.legalName** (string) - The legal name of the customer.
- **data.email** (string) - The customer's email address.
- **data.isActive** (boolean) - Indicates if the customer is active.
- **data.createdAt** (string) - The timestamp when the customer was created.
- **data.updatedAt** (string) - The timestamp when the customer was last updated.
- **meta.requestId** (string) - The ID of the request.
- **meta.timestamp** (string) - The timestamp of the response.

### Response Example
```json
{
  "data": {
    "id": "cust_01HABC",
    "taxpayerId": "tax_01H...",
    "identificationType": "RUC",
    "identification": "0993378150001",
    "legalName": "Empresa Demo S.A.",
    "email": "facturas@empresademo.ec",
    "isActive": true,
    "createdAt": "2026-05-13T12:34:56.789Z",
    "updatedAt": "2026-05-13T12:34:56.789Z"
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### Import Invoice for Signing

Source: https://factuplan.com.ec/docs/api

Step 1: Import the linked invoice into Factuplan if it doesn't already exist. This endpoint is idempotent.

```cURL
curl -X POST https://api-rest.factuplan.com.ec/v1/developer/invoices/import \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001" \
  -H "Content-Type: application/json" \
  -d '{ "accessKey": "0102202401179213650600120010010000000011234567813" }'
```

--------------------------------

### GET /v1/developer/customers

Source: https://factuplan.com.ec/docs/api

Retrieves a list of customers. Supports pagination, searching, and filtering by identification type and active status.

```APIDOC
## GET /v1/developer/customers

### Description
Retrieves a list of customers with support for pagination and filtering.

### Method
GET

### Endpoint
/v1/developer/customers

### Parameters
#### Query Parameters
- **page** (number) - Optional - Default: `1` - The requested page number.
- **limit** (number) - Optional - Default: `20` - The number of elements per page.
- **search** (string) - Optional - Searches by name, identification, or email.
- **identificationType** (enum) - Optional - `RUC`, `CEDULA`, `PASSPORT`, `FINAL_CONSUMER`.
- **isActive** (boolean) - Optional - Filters by active status.

#### Response
#### Success Response (200 OK)
- **data** (array) - An array of customer objects.
  - **data[].id** (string) - The unique identifier for the customer.
  - **data[].taxpayerId** (string) - The taxpayer ID associated with the customer.
  - **data[].identificationType** (string) - The type of identification provided.
  - **data[].identification** (string) - The customer's identification number.
  - **data[].legalName** (string) - The legal name of the customer.
  - **data[].email** (string) - The customer's email address.
  - **data[].isActive** (boolean) - Indicates if the customer is active.
  - **data[].createdAt** (string) - The timestamp when the customer was created.
  - **data[].updatedAt** (string) - The timestamp when the customer was last updated.
- **meta.requestId** (string) - The ID of the request.
- **meta.timestamp** (string) - The timestamp of the response.
- **meta.pagination.total** (number) - The total number of customers.
- **meta.pagination.page** (number) - The current page number.
- **meta.pagination.limit** (number) - The number of customers per page.
- **meta.pagination.totalPages** (number) - The total number of pages.

### Response Example
```json
{
  "data": [
    {
      "id": "cust_01HABC",
      "taxpayerId": "tax_01H...",
      "identificationType": "RUC",
      "identification": "0993378150001",
      "legalName": "Empresa Demo S.A.",
      "email": "facturas@empresademo.ec",
      "isActive": true,
      "createdAt": "2026-05-13T12:34:56.789Z",
      "updatedAt": "2026-05-13T12:34:56.789Z"
    }
  ],
  "meta": {
    "requestId": "req_1a2b3c",
    "timestamp": "2026-05-13T12:34:56.789Z",
    "pagination": { "total": 120, "page": 1, "limit": 20, "totalPages": 6 }
  }
}
```
```

--------------------------------

### POST /v1/developer/certificate

Source: https://factuplan.com.ec/docs/api

Uploads a P12 certificate. If the certificate's RUC does not exist as a taxpayer in your account and your plan allows it, the taxpayer is automatically created and linked to your API key.

```APIDOC
## POST /v1/developer/certificate

### Description
Uploads a P12 certificate. If the RUC of the certificate does not yet exist as a taxpayer in your account and your plan allows it, the taxpayer is automatically created and linked to your API key.

### Method
POST

### Endpoint
/v1/developer/certificate

### Parameters
#### Request Body
- **file** (file) - Required - P12 file (.p12 or .pfx).
- **password** (string) - Required - Certificate password.

### Request Example
```bash
curl -X POST https://api-rest.factuplan.com.ec/v1/developer/certificate \
  -H "x-api-key: ak_live_TU_CLAVE" \
  -F "file=@/ruta/firma.p12" \
  -F "password=MiContraseña"
```

### Response
#### Success Response (200 OK)
- **hasCertificate** (boolean) - `true` if the certificate was uploaded successfully.
- **isExpired** (boolean) - If the certificate has already expired.
- **daysUntilExpiry** (number) - Days remaining until expiration.
- **ruc** (string) - RUC extracted from the certificate.
- **legalName** (string) - Legal name extracted from the certificate.
- **expiresAt** (string) - Expiration date (ISO 8601).
- **created** (boolean) - `true` if a new taxpayer was automatically created. Only present when created.

### Response Example
```json
{
  "data": {
    "hasCertificate": true,
    "isExpired": false,
    "daysUntilExpiry": 87,
    "ruc": "0950194407001",
    "legalName": "Mi Empresa S.A.",
    "expiresAt": "2026-08-08T00:00:00.000Z",
    "created": true
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```

--------------------------------

### GET /v1/developer/receipts/{id}

Source: https://factuplan.com.ec/docs/api

Retrieve all data for a receipt, including its status, access key, sequential number, totals, and dates.

```APIDOC
## GET /v1/developer/receipts/{id}

### Description
Returns all data for the receipt: status, access key, sequential number, totals, and dates.

### Method
GET

### Endpoint
/v1/developer/receipts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the receipt.

### Response
#### Success Response (200 OK)
- **data.id** (string) - The unique identifier of the receipt.
- **data.accessKey** (string) - The SRI access key.
- **data.sequential** (string) - The sequential number of the receipt.
- **data.status** (string) - The status of the receipt (e.g., `COMPLETED`).
- **data.total** (number) - The total amount of the receipt.
- **data.source** (string) - The source of the receipt (e.g., `API`).
- **data.apiKeyId** (string) - The ID of the associated API key.
- **meta.requestId** (string) - The ID of the request.
- **meta.timestamp** (string) - The timestamp of the request.

#### Response Example
```json
{
  "data": {
    "id": "rcpt_01HABC",
    "accessKey": "0104202601099337815000110010010000000011234567890",
    "sequential": "000000001",
    "status": "COMPLETED",
    "total": 172.5,
    "source": "API",
    "apiKeyId": "ak_01H..."
  },
  "meta": { "requestId": "req_1a2b3c", "timestamp": "2026-05-13T12:34:56.789Z" }
}
```
```