Emitir Factura

Esta guía te mostrará cómo emitir una factura electrónica (código 01 del SRI) de manera asíncrona usando la API de Factio.

Requisitos Previos

Tener un Issuer (Emisor) configurado.
Tener un Certificado Digital activo subido a la plataforma.
Tener al menos un Establecimiento y un Punto de Emisión.
Una clave API Key de Factio (fct_test_ para Sandbox o fct_live_ para Producción).

1. Crear el Request de Emisión

Para emitir una factura, debes hacer un request POST al endpoint /documents. Factio se encarga de asignar y consumir el secuencial automáticamente. Usa el header Idempotency-Key (un UUID v4 aleatorio) para evitar comprobantes duplicados en caso de reintentos.

curl -X POST https://api.staging.factioapp.com/documents \
  -H "X-API-Key: fct_test_TU_API_KEY_AQUI" \
  -H "Idempotency-Key: c9d020e9-b5f7-410a-8a60-316279f5db76" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "01",
    "issue_date": "2024-01-15",
    "issuer_id": "TU_ISSUER_ID",
    "establishment_id": "TU_ESTABLISHMENT_ID",
    "emission_point_id": "TU_EMISSION_POINT_ID",
    "buyer_id_type": "04",
    "buyer_id": "1792146739001",
    "buyer_name": "Empresa de Pruebas S.A.",
    "subtotal": "100.00",
    "total_tax": "15.00",
    "total": "115.00",
    "lines": [
      {
        "code": "SRV-001",
        "description": "Desarrollo de Software",
        "quantity": "1.00",
        "unit_price": "100.00",
        "subtotal": "100.00",
        "taxes": [
          {
            "tax_code": "2",
            "tax_percentage_code": "4",
            "tax_rate": "15.00",
            "taxable_base": "100.00",
            "tax_amount": "15.00"
          }
        ]
      }
    ],
    "payments": [
      {
        "payment_method_code": "20",
        "total": "115.00"
      }
    ]
  }'

Explicación de los campos clave

Campo	Descripción
`document_type`	`"01"` indica que es una Factura.
`issue_date`	Fecha de emisión en formato `YYYY-MM-DD`. Debe ser actual o hasta días permitidos por SRI.
`buyer_id_type`	Tipo de identificación del comprador (e.g. `"04"` para RUC, `"05"` para Cédula).
`lines[].taxes`	Información impositiva detallada por línea de la factura.
`payments`	Métodos de pago usados.

2. Respuesta Asíncrona (202 Accepted)

Dado que la autorización con el SRI toma su tiempo, Factio valida la estructura y la integridad inicial, reserva el secuencial fiscal en la misma transacción y te devuelve un 202 Accepted de inmediato.

{
  "id": "doc_01HZ...",
  "status": "DRAFT",
  "sequential": "000000005",
  "message": "Document accepted for async processing"
}

A partir de este momento, Factio toma el control y realizará todos los pasos asíncronos en background: generar el XML, firmarlo con tu .p12 y enviarlo al SRI.

3. Consultar el estado final

Para saber si tu factura fue autorizada o rechazada, puedes realizar un polling al endpoint de detalle del documento.

curl -X GET https://api.staging.factioapp.com/documents/doc_01HZ... \
  -H "X-API-Key: fct_test_TU_API_KEY_AQUI"

El estado cambiará de DRAFT ➔ SUBMITTED_TO_SRI ➔ AUTHORIZATION_PENDING ➔ y finalmente AUTHORIZED (o un estado de error).

Importante: Nunca reenvíes la creación de la factura si hubo un timeout. Consulta el estado o usa la misma Idempotency-Key en el POST.

Introducción

Conceptos clave

Guías

Emitir Factura

Requisitos Previos

1. Crear el Request de Emisión

Explicación de los campos clave

2. Respuesta Asíncrona (202 Accepted)

3. Consultar el estado final

​Requisitos Previos

​1. Crear el Request de Emisión

​Explicación de los campos clave

​2. Respuesta Asíncrona (202 Accepted)

​3. Consultar el estado final

Requisitos Previos

1. Crear el Request de Emisión

Explicación de los campos clave

2. Respuesta Asíncrona (202 Accepted)

3. Consultar el estado final