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

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.

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.