Quickstart — Tu primera factura en 3 pasos

Ejemplo rápido con curl

curl -X POST "https://api.facturaya.com.do/v1/facturas" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -d '{
    "tipo_ecf": "31",
    "tipo_ingresos": "01",
    "tipo_pago": "1",
    "comprador": {
      "rnc": "131880681",
      "razon_social": "MI CLIENTE SRL",
      "direccion": "Calle Principal #100",
      "municipio": "010100",
      "provincia": "010000"
    },
    "pagos": [{"forma_pago": "1", "monto": 59000.00}],
    "items": [
      {
        "nombre": "Servicio de consultoría",
        "indicador_facturacion": 1,
        "indicador_bien_servicio": 2,
        "cantidad": 1,
        "unidad_medida": "43",
        "precio_unitario": 50000.00,
        "monto": 50000.00,
        "itbis_monto": 9000.00
      }
    ]
  }'

Autenticación

Todas las peticiones a la API requieren autenticación. Hay dos métodos:

Método 1: API Key + Secret (recomendado)

Envía dos headers en cada request:

X-Api-Key: fy_81e6059cf1d9c2e8a5123a856db080dd872246d6
X-Api-Secret: f192345d36a5e8ece325b6ed8c301042ebcae0f1089905629cedc0248ba8f828

Las credenciales se generan al registrar tu empresa. Contacta a ventas@facturaya.com.do o llama al 809-781-4887 / 1 (809) 395-1654.

Método 2: JWT Bearer Token (alternativo)

Para integraciones que prefieran tokens temporales:

# 1. Obtener tokens
POST /auth/login
{"email": "tu@email.com", "password": "tu_password"}

# 2. Usar el access_token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Idempotencia

Para evitar documentos duplicados al reintentar un request fallido, envía el header:

X-Idempotency-Key: mi-clave-unica-por-request-12345

Si se recibe un request con una clave ya procesada dentro de las últimas 24 horas, se devuelve la respuesta original sin crear un documento nuevo.

POST/facturas

Crea, firma digitalmente y envía un documento fiscal electrónico (e-CF) a la DGII.

Tipos de documento soportados

Campos del request

Objeto Comprador

Objeto Item

Objeto Pago

Objeto Referencia (E33/E34)

GET/facturas/{uuid}/status

Consulta el estado actual de un documento. Especialmente útil para documentos encolados.

curl "https://api.facturaya.com.do/v1/facturas/22b2636e-a3fe-453c-8de2-6f9e08787e4f/status" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret"

Respuesta exitosa

{
  "success": true,
  "data": {
    "uuid": "22b2636e-a3fe-453c-8de2-6f9e08787e4f",
    "encf": "E310000000138",
    "tipo_ecf": "31",
    "tipo_documento": "factura",
    "estado": "aceptado",
    "track_id": "78e54ba7-114f-45df-84f1-e11a8dd006cb",
    "codigo_seguridad": "ITgyFM",
    "mensaje_error": "",
    "fecha_emision": "2026-04-04",
    "monto_total": 42000,
    "fecha_firma": "2026-04-04 11:23:28",
    "fecha_envio": "2026-04-04 11:23:32",
    "fecha_respuesta": "2026-04-04 11:23:34",
    "intentos_envio": 0,
    "rnc_emisor": "04800833040",
    "rnc_comprador": "101893362",
    "razon_social_comprador": "CASO 1 EXENTO SIMPLE"
  },
  "message": "Estado del documento E310000000138."
}

Si el documento está encolado, la respuesta incluye un objeto cola con: estado, intentos, max_intentos, proximo_intento y ultimo_error.

POST/empresas/logo NUEVO

Sube el logo que aparecerá en la Representación Impresa (PDF). PNG o JPG, máximo 500KB.

curl -X POST "https://api.facturaya.com.do/v1/empresas/logo" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -F "logo=@mi_logo.png"

Eliminar logo:

curl -X DELETE "https://api.facturaya.com.do/v1/empresas/logo" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret"

Si no hay logo, el PDF funciona normalmente sin imagen. Recomendado: 400×160px, fondo transparente.

GET/facturas/{uuid}/pdf

Descarga la representación impresa (PDF) del e-CF con código QR según especificaciones DGII.

Formato carta (default)

curl "https://api.facturaya.com.do/v1/facturas/{uuid}/pdf" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  --output factura.pdf

Formato POS 80mm NUEVO

curl "https://api.facturaya.com.do/v1/facturas/{uuid}/pdf?formato=pos" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  --output ticket.pdf

Responde con Content-Type: application/pdf. El documento debe tener XML firmado. Ambos formatos cumplen especificaciones DGII y soportan los 10 tipos de e-CF.

Flujo de Estados

Cada documento pasa por estos estados durante su ciclo de vida:

Códigos de Error

Todas las respuestas de error siguen este formato:

{
  "success": false,
  "error": "CODIGO_ERROR",
  "message": "Descripción del error",
  "details": ["Error específico 1", "Error específico 2"]
}

Errores comunes de validación

Webhooks

Recibe notificaciones HTTP POST cuando cambia el estado de tus documentos.

Configuración

Configura webhooks desde el Panel de Administración. Especifica la URL de tu endpoint y los eventos que deseas recibir.

Eventos disponibles

Formato del payload

{
  "evento": "documento.aceptado",
  "timestamp": "2026-04-04T11:23:34-04:00",
  "datos": {
    "documento_id": 208,
    "estado": "aceptado",
    "uuid": "22b2636e-a3fe-453c-8de2-6f9e08787e4f",
    "encf": "E310000000138",
    "tipo_ecf": "31",
    "track_id": "78e54ba7-114f-45df-84f1-e11a8dd006cb",
    "mensaje": ""
  }
}

Headers del webhook

Nota: el header de firma se llama exactamente X-Webhook-Signature (con el prefijo literal sha256= antes del HMAC). No existe ningún header X-FacturaYa-Signature — es un nombre que algunos integradores intuyen pero no está implementado.

Verificación de firma HMAC-SHA256

Valida que el webhook venga de FacturaYa calculando el HMAC del body con tu secret:

// PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, 'tu_webhook_secret');

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    die('Firma inválida');
}

$data = json_decode($payload, true);
// Procesar evento...

El webhook se desactiva automáticamente después de 10 fallos consecutivos. Responde con HTTP 2xx para confirmar la recepción.

Referencia DGII — Catálogos Oficiales

Tablas oficiales DGII República Dominicana que aplican al desarrollo contra esta API. Si en algún momento ves discrepancia con la respuesta del API, prevalecen estas tablas (son las que DGII valida contra su norma).

Tabla de Formas de Pago (TBL_TIPO_FORMA_PAGO_ECF)

Catálogo oficial para el campo forma_pago dentro del array pagos al emitir un e-CF.

Fuente: Formato Comprobante Fiscal Electrónico (e-CF) V1.0, Sección 2.2 (A. Encabezado), campo N° 12 <FormaPago>, Pág. 8.

Tipos de e-CF (tipo_ecf)

Catálogo oficial para el campo tipo_ecf al emitir comprobantes.

Fuente: Formato Comprobante Fiscal Electrónico (e-CF) V1.0, Sección 1 (Introducción), Pág. 2. Informe Técnico e-CF v1.0, Sección 6.1, Pág. 12.

Mnemónico E33 vs E34: desde la perspectiva del emisor, la Nota de Crédito (E34) le da crédito al comprador (reduce su deuda); la Nota de Débito (E33) le genera un débito adicional al comprador (aumenta su deuda).

Campo indicador_nota_credito (solo E34)

Campo obligatorio únicamente para Nota de Crédito Electrónica (E34). No aplica al E33 (Nota de Débito).

Atención: solo 2 valores oficiales (0 y 1). Cualquier otro valor será rechazado por validación XSD.

Fuente: Formato e-CF V1.0, Sección 2.2 (A. Encabezado), campo N° 5 <IndicadorNotaCredito>, Pág. 7.

Campo fecha_vencimiento_secuencia

Obligatoriedad por tipo de e-CF:

Fuente: Formato e-CF V1.0, Sección 2.2 (A. Encabezado), campo N° 4 <FechaVencimientoSecuencia>, Pág. 6. Descripción Técnica de Facturación Electrónica, Pág. 5.

Flujo B2B Emisor-Receptor NUEVO

FacturaYa soporta el flujo B2B completo definido por la DGII, tanto como emisor (enviar facturas a receptores electrónicos) como receptor (recibir facturas de proveedores).

Flujo como Emisor

Cuando tu empresa emite una factura y el comprador es receptor electrónico:

Consulta el estado B2B con GET /v1/facturas/{uuid}/acuse.

Flujo como Receptor

Cuando un proveedor te envía una factura electrónica:

Endpoints B2B

Para detalles completos de cada endpoint (parámetros, schemas, respuestas), consulta la sección Swagger UI más abajo.

Ejemplos por Tipo de e-CF

63 casos reales ejecutados contra DGII TestECF. Todos aceptados excepto 1 rechazado esperado.

Todos los Endpoints — Swagger UI

Explorador interactivo de todos los endpoints de la API.

Guía de Integración Paso a Paso

1. Obtener credenciales

2. Subir certificado P12

curl -X POST "https://api.facturaya.com.do/v1/certificados" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -F "certificado=@tu_certificado.p12" \
  -F "password=password_del_certificado"

3. Crear secuencias NCF

POST /v1/secuencias
{
  "tipo_ecf": "31",
  "secuencia_desde": 1,
  "secuencia_hasta": 5000,
  "fecha_vencimiento": "2027-12-31"
}
// Repetir para cada tipo de e-CF que vayas a usar

4. Emitir facturas

Ya estás listo para emitir documentos con POST /v1/facturas. El sistema automáticamente:

• Asigna el NCF de la secuencia correspondiente
• Genera el XML según normativa DGII
• Firma digitalmente con tu certificado P12
• Envía a DGII y devuelve la respuesta
• Si DGII no responde, encola y reintenta automáticamente

5. Consultar estado

Usa GET /v1/facturas/{uuid}/status para verificar documentos encolados.

6. Descargar PDF

Usa GET /v1/facturas/{uuid}/pdf para obtener la representación impresa en formato carta, o agrega ?formato=pos para ticket 80mm térmico.

7. Configurar webhooks (opcional)

Desde el panel, configura webhooks para recibir notificaciones cuando tus documentos cambien de estado.