# Nodiq e-CF

> Plataforma de facturación electrónica (Proveedor de Servicios de Facturación Electrónica, PSFE) para República Dominicana, de Nodiq Tech. Emite, recibe y aprueba comprobantes fiscales electrónicos (e-CF) validados por la DGII. Panel web en https://ecf.nodiqtech.com y API REST v1.

Documentación humana: https://ecf.nodiqtech.com/docs
Especificación OpenAPI 3.1: https://ecf.nodiqtech.com/openapi.json
Estado del servicio (JSON): https://ecf.nodiqtech.com/estado.json
Soporte: soporte@nodiqtech.com · WhatsApp +1 (809) 943-0625

## Autenticación
- Base: https://ecf.nodiqtech.com/api/v1
- Cabecera: `Authorization: Bearer nq_test_...` (ambiente de práctica/pre-certificación) o `Bearer nq_live_...` (producción).
- Cabecera opcional `Idempotency-Key: <texto único>` en POST: repetir la misma clave devuelve el mismo resultado sin emitir dos veces.
- Límite: 120 peticiones por minuto por clave (HTTP 429 al excederlo, con cabecera Retry-After).
- Cuerpos y respuestas en JSON UTF-8. Montos con punto decimal. Fechas YYYY-MM-DD.

## Errores
`{"error":{"codigo":"validacion","mensaje":"texto legible","detalles":[{"campo":"lineas.0.precio","mensaje":"..."}]}}`
Códigos HTTP: 400, 401 (clave inválida), 403, 404, 409 (conflicto/idempotencia), 422 (validación), 429, 500.

## Endpoints
- POST /comprobantes — crea, firma y envía a la DGII. `?validar=true` valida y calcula sin consumir e-NCF.
  Cuerpo: tipo (31,32,33,34,41,43,44,45,46,47), fecha_emision?, cliente_id? o comprador{rnc|extranjero, razon_social, correo, direccion, municipio, provincia, pais}, lineas[{nombre, descripcion?, cantidad, precio, indicador (0 no facturable,1 ITBIS 18%,2 ITBIS 16%,3 ITBIS 0%,4 exento), descuento?, codigo?, unidad?, tipo (1 bien|2 servicio), retencion_itbis_pct?, retencion_isr_pct?}], tipo_pago (1 contado|2 crédito|3 gratuito), fecha_limite_pago?, formas_pago[{forma,monto}]?, moneda?, tasa_cambio?, tipo_ingresos?, precios_con_itbis?, referencia{encf,fecha,codigo,razon}? (obligatoria en 33 y 34), referencia_externa?, notas?
- GET /comprobantes — filtros: estado, tipo, desde, hasta, pagina, por_pagina (máx. 100).
- GET /comprobantes/{id} — {id} es el uuid del comprobante.
- GET /comprobantes/{id}/pdf — representación impresa (application/pdf).
- GET /comprobantes/{id}/xml — XML firmado (application/xml).
- POST /comprobantes/{id}/reenviar — reintenta el envío a la DGII (contingencia o en proceso).
- POST /comprobantes/{id}/correo — cuerpo {"para":"correo@cliente.com"}.
- GET /recibidos, GET /recibidos/{id}
- POST /recibidos/{id}/aprobar, POST /recibidos/{id}/rechazar — cuerpo {"motivo":"..."}.
- GET /clientes, POST /clientes
- GET /secuencias — rangos de e-NCF autorizados y disponibles.
- GET /contribuyentes/{rnc} — consulta del padrón de la DGII.
- GET /estado — salud del servicio y de la DGII.

## Objeto comprobante
id (uuid), encf, tipo, estado (aceptado | aceptado_condicional | rechazado | en_proceso | contingencia | firmado | error | anulado), ambiente, fecha_emision, comprador, moneda, totales{gravado, exento, itbis, total, itbis_retenido, isr_retenido}, codigo_seguridad, fecha_firma, track_id, mensajes_dgii, url_pdf, url_xml, url_publica, url_qr, creado.

## Webhooks
Eventos: documento.creado, documento.aceptado, documento.aceptado_condicional, documento.rechazado, documento.anulado, documento.aprobacion_comercial, recibido.nuevo, secuencia.por_agotarse, certificado.por_vencer.
Cabeceras: Nodiq-Evento, Nodiq-Entrega (id único de la entrega), Nodiq-Firma: t=<unix>,v1=<hex>.
Firma: v1 = HMAC-SHA256(secreto_del_webhook, t + "." + cuerpo_crudo) en hexadecimal. Rechaza si |ahora - t| > 300 s. Compara en tiempo constante.
Responde 2xx en menos de 10 s. Reintentos: 9 con espera creciente durante ~72 horas.

## Servicios de recepción para la DGII (URL compartida; enruta por el RNC del comprador)
- https://ecf.nodiqtech.com/fe/autenticacion/api/semilla
- https://ecf.nodiqtech.com/fe/autenticacion/api/validacioncertificado
- https://ecf.nodiqtech.com/fe/recepcion/api/ecf
- https://ecf.nodiqtech.com/fe/aprobacioncomercial/api/ecf

## Ejemplo mínimo
curl -X POST https://ecf.nodiqtech.com/api/v1/comprobantes -H "Authorization: Bearer nq_test_xxx" -H "Content-Type: application/json" -H "Idempotency-Key: pedido-1001" -d '{"tipo":32,"tipo_pago":1,"lineas":[{"nombre":"Servicio","cantidad":1,"precio":1000,"indicador":1,"tipo":2}]}'