Manual Técnico & API

Configuración Inicial

Antes de enviar su primera factura, debe configurar los siguientes parámetros en la interfaz de usuario: /config

Datos Generales

En la primera pestaña, defina cómo operará su facturación:

Nombre Comercial: El nombre público de su negocio (aparecerá en el PDF).
Dirección Matriz: La dirección física registrada en el RUC.
Ambiente:
- Pruebas: Para desarrollo. Los documentos no tienen validez legal.
- Producción: Documentos reales autorizados por el SRI.
Obligado a llevar contabilidad:
- Sí: El contribuyente está legalmente obligado a llevar contabilidad.
- No: El contribuyente no está obligado a llevar contabilidad.
Establecimiento y Pto. Emisión: Códigos de 3 dígitos asignados por el SRI (ej: 001-001).

Firma Electrónica

Es indispensable subir su archivo de firma para sellar los XMLs.

Requisitos:

Formato archivo: .p12.
Debe conocer la contraseña del archivo.
El archivo debe estar vigente (no caducado).

El sistema validará automáticamente que el RUC dentro de la firma coincida con su cuenta.

Correo SMTP (Notificaciones)

Para que sus clientes reciban el PDF y XML por correo, configure su servidor de salida.

Campo	Descripción / Ejemplo
Host	Dirección del servidor (ej: `smtp.gmail.com`).
Puerto	Generalmente `587` (TLS) o `465` (SSL).
Usuario	Su correo completo (ej: `facturacion@empresa.com`).
Contraseña	La clave de su correo. Importante: Si usa Gmail, debe generar una "Contraseña de Aplicación".

Utilice el botón "Probar Conexión" en la interfaz para verificar que los correos salen correctamente.

Credenciales de Consumo

Endpoint (URL)

Token de Autorización

Token único, creado exclusivamente para su acceso, No lo comparta.

Diccionario de Datos

1. Estructura Raíz

Campo	Tipo	Req.	Descripción y Reglas
token	String	SÍ	Token encriptado obtenido en este panel.
cliente	Object	SÍ	Objeto con los datos del comprador/receptor.
items	Array	SÍ	Lista de productos o servicios a facturar.

2. Objeto: cliente

Campo	Tipo	Req.	Formato y Valores
identificacion	String	SÍ	- 10 dígitos: Cédula. - 13 dígitos: RUC. - 9999999999999: Consumidor Final. Solo números, sin guiones.
razon_social	String	SÍ	Nombre completo del cliente. Evitar caracteres especiales.
email	String	SÍ	Correo válido para envío de notificación. Puede separar múltiples con punto y coma (;).
direccion	String	SÍ	Dirección domiciliaria del cliente.
telefono	String	NO	Número telefónico (Opcional).

3. Array: items (Detalle)

Campo	Tipo	Req.	Descripción
codigo	String	SÍ	Código principal (SKU) del producto. Max 25 car.
descripcion	String	SÍ	Nombre o descripción del servicio/bien.
cantidad	Number	SÍ	Cantidad vendida. Admite decimales (ej: 1.5).
precio_unitario	Number	SÍ	Precio unitario SIN IMPUESTOS.
descuento	Number	NO	Valor monetario del descuento por unidad (Default: 0.00).
iva_tarifa	Int	SÍ	Porcentaje de IVA aplicable. Valores permitidos: `0`, `5`, `8`, `12`, `15`.

Ejemplo de Petición (Request)

{
  "token": "a7x9... (SU TOKEN DE PRODUCCION)",
  "cliente": {
    "identificacion": "1710000000",
    "razon_social": "Juan Pérez",
    "email": "juan.perez@email.com",
    "direccion": "Av. Amazonas y Naciones Unidas",
    "telefono": "0991234567"
  },
  "items": [
    {
      "codigo": "SERV-001",
      "descripcion": "Desarrollo Web",
      "cantidad": 1,
      "precio_unitario": 1500.00,
      "descuento": 0.00,
      "iva_tarifa": 15
    },
    {
      "codigo": "HOST-002",
      "descripcion": "Hosting Anual",
      "cantidad": 1,
      "precio_unitario": 120.00,
      "descuento": 10.00,
      "iva_tarifa": 15
    }
  ]
}

Respuesta Exitosa (HTTP 200)

Si la factura es autorizada por el SRI, recibirá:

{
  "status": "success",
  "mensaje": "Factura creada exitosamente",
  "clave_acceso": "1301202501179001234567001...",
  "numero_factura": "001-001-000000123",
  "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmN...",
  "pdf_url": "https://api.dosto.ec/descargar/pdf/13012025011...",
  "email_estado": "Enviado exitosamente"
}

Posibles Errores

401 Unauthorized: Token inválido.

402 Payment Required: Licencia del sistema caducada.

403 Forbidden: Cliente inactivo o suspendido.

412 Precondition Failed: Falta firma electrónica o clave en configuración.

400 Bad Request: Error devuelto por el SRI (ej: RUC incorrecto).

Manual de Integración