Primeros pasos

Flujo completo

En producción el paso 2 lo reemplazás por webhooks (paso 6). La referencia de endpoints está en Facturas.

Sandbox vs producción

Antes de empezar

Para este quickstart solo necesitás:

• Cuenta activa en DiFACT
• Una API Key de sandbox (dk_test_)

Si aún no tenés cuenta, solicitá acceso. Para producción vas a necesitar RUC, timbrado y certificado P12 — ver checklist de go-live.

1. 1Creá una API Key de sandbox

   Ingresá a app.difact.co → Configuración → API y generá una key con prefijo dk_test_. Guardala en una variable de entorno — nunca la expongas en el frontend.

   BASHVariable de entorno

   export DIFACT_API_KEY="dk_test_xxxxxxxxxxxxxxxx"

2. 2Verificá la autenticación

   Hacé una petición de lectura para confirmar que la key funciona. Usá el header X-Environment: sandbox en todas las pruebas.

   BASHListar facturas (vacío al inicio)

   curl https://api.difact.co/v1/facturas \
     -H "Authorization: Bearer $DIFACT_API_KEY" \
     -H "X-Environment: sandbox"

   JSONRespuesta esperada (200)

   {
     "ok": true,
     "data": [],
     "meta": { "page": 1, "total": 0 }
   }

   Si recibís 401, revisá la key. Detalle en Autenticación.

3. 3Emití tu primera factura de prueba

   En sandbox podés simular la respuesta de SIFEN con _simulate: "approved" para obtener un CDC de inmediato sin esperar al procesamiento real.

   BASHPOST /v1/facturas

   curl https://api.difact.co/v1/facturas \
     -X POST \
     -H "Authorization: Bearer $DIFACT_API_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Environment: sandbox" \
     -d '{
     "tipo_documento": 1,
     "_simulate": "approved",
     "receptor": {
       "ruc": "80012345-6",
       "razon_social": "Empresa Ejemplo SRL",
       "email": "pagos@empresa.com"
     },
     "items": [
       {
         "descripcion": "Servicio de software mensual",
         "cantidad": 1,
         "precio_unitario": 500000,
         "iva": 10
       }
     ],
     "condicion_pago": 1
   }'

   Guardá el id de la respuesta — lo vas a usar en los pasos 4 y 5.

   JSONRespuesta esperada (201)

   {
     "ok": true,
     "data": {
       "id": "fact_01J3KZZXXYYY",
       "status": "approved",
       "cdc": "01800695631001001000101001000007942024060111111111",
       "numero": "001-001-0000001",
       "kude_url": "https://api.difact.co/v1/facturas/fact_01J3KZZXXYYY/kude"
     }
   }

   Error típico (422)

   JSONINVALID_TIMBRADO

   {
     "ok": false,
     "error": {
       "code": "INVALID_TIMBRADO",
       "message": "El timbrado está vencido o no corresponde al tipo de documento."
     }
   }

   Cómo solucionarlo: en sandbox esto no debería ocurrir con _simulate. Si lo ves en producción, cargá un timbrado vigente en el panel y verificá que coincida con el tipo_documento. Más errores en Errores comunes.

4. 4Consultá el estado del documento

   En producción el estado pasa por pending → sent → approved mientras SIFEN procesa. Podés consultarlo con polling o — recomendado — con webhooks.

   BASHGET /v1/facturas/:id

   curl https://api.difact.co/v1/facturas/fact_01J3KZZXXYYY \
     -H "Authorization: Bearer $DIFACT_API_KEY" \
     -H "X-Environment: sandbox"

   JSONRespuesta esperada (200)

   {
     "ok": true,
     "data": {
       "id": "fact_01J3KZZXXYYY",
       "status": "approved",
       "cdc": "01800695631001001000101001000007942024060111111111"
     }
   }

   status	Qué hacer
   pending / sent	Esperá unos segundos y volvé a consultar, o registrá un webhook.
   approved	Documento válido. Descargá KuDE y entregalo al cliente.
   rejected	Revisá sifen_errors y corregí los datos del body.

5. 5Descargá el KuDE (PDF)

   Cuando el estado es approved, descargá el comprobante visual para enviarlo por email, WhatsApp o impresión.

   BASHGET /v1/facturas/:id/kude

   curl https://api.difact.co/v1/facturas/fact_01J3KZZXXYYY/kude \
     -H "Authorization: Bearer $DIFACT_API_KEY" \
     -H "X-Environment: sandbox" \
     -o kude.pdf

   La respuesta es un archivo PDF (Content-Type: application/pdf).

6. 6Registrá un webhook (recomendado para producción)

   En lugar de consultar el estado cada pocos segundos, registrá una URL en tu servidor. DiFACT te avisa cuando SIFEN aprueba o rechaza el documento.

   BASHPOST /v1/webhooks

   curl https://api.difact.co/v1/webhooks \
     -X POST \
     -H "Authorization: Bearer $DIFACT_API_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Environment: sandbox" \
     -d '{
     "url": "https://tu-sistema.com/webhooks/difact",
     "events": ["factura.approved", "factura.rejected"],
     "description": "ERP integración"
   }'

   JSONPayload que recibirás en tu servidor

   {
     "type": "factura.approved",
     "data": {
       "id": "fact_01J3KZZXXYYY",
       "status": "approved",
       "cdc": "01800695631001001000101001000007942024060111111111"
     }
   }

   Verificación de firma, reintentos y todos los eventos en Webhooks.

Siguiente: producción

Cuando los 6 pasos funcionen en sandbox:

• Cargá certificado P12 y timbrado en el panel
• Generá una API Key dk_live_ y quitá el header sandbox
• Registrá webhooks para factura.approved y factura.rejected
• Probá con un documento real de bajo monto antes de abrir el tráfico

Seguí la guía completa en Pasar a producción.