API externa — Documentación | FACTUskill
Documentación técnica

API externa de comprobantes

Integrá tu sistema con FACTUskill para emitir, consultar y anular comprobantes con CAE de ARCA (AFIP) automáticamente, sin carga manual. Disponible según el plan contratado.

Versión 2 · octubre 2026

Autenticación y requisitos

Antes de integrar, confirmá con tu estudio contable que se cumplen estos requisitos:

  1. Plan con API. La empresa tiene asignado un plan de FACTUskill que incluye la API externa.
  2. Plan vigente. La vigencia del plan no está vencida y queda cupo de comprobantes en el ciclo.
  3. Empresa activa dentro del sistema.

Si alguno no se cumple, emitir y anular responden 403 con un codigo que indica cuál falla. En cualquier momento podés consultar el estado con GET /me.

API Key. El administrador del estudio contable genera la key desde el panel de FACTUskill, en la edición de la empresa. Cada key corresponde a una empresa, es decir, a un CUIT y punto de venta. Hay como máximo una key real y una de prueba activas por empresa: generar una nueva revoca la anterior del mismo tipo. La key se muestra completa una única vez, al generarla; después solo se ve su prefijo.

Cada request debe incluir:

Authorization: Bearer <api_key>
Content-Type: application/json

El body se envía como JSON en UTF-8. Si una tilde o una eñe llega en otra codificación, la request se rechaza con 400 body_invalido.

Keys de prueba

Para desarrollar sin generar comprobantes reales, pedile al estudio una key de prueba. Empieza con test_ y funciona en la misma URL que la real.

  • Pasa por las mismas validaciones que la real: autenticación, plan, vigencia, cupo, padrón de AFIP, condición IVA (RG 5616) e ítems.
  • No envía nada a AFIP: devuelve un CAE ficticio (empieza con 99), con numeración propia, url_publica: null y sin consumir cupo.
  • Todas las respuestas traen "prueba": true. Idempotencia, consulta y anulación funcionan igual que con la key real.
  • Para probar tu manejo de errores, agregá al body "simular_resultado": "rechazo_afip" (responde como un rechazo de AFIP) o "error_afip" (responde 500). Con una key real este campo se ignora.

Endpoints

Base: https://admin.factuskill.com.ar/api/v1

Método y rutaPara qué
POST /comprobantes/emitirEmitir una factura (u otro comprobante) y obtener el CAE.
GET /comprobantes?referencia_externa=…Consultar un comprobante por tu referencia: estado, CAE y nota de crédito si fue anulado.
POST /comprobantes/anularAnular un comprobante emitido por la API con una Nota de Crédito total.
GET /meDatos de la empresa de la key, plan, cupo y si puede emitir.

Emitir

POST https://admin.factuskill.com.ar/api/v1/comprobantes/emitir
CampoTipoObligatorioDescripción
referencia_externastring (máx. 100)SíIdentificador único propio de esta operación (pedido, venta, cobro). Es la clave de idempotencia: ver más abajo.
cbte_tipoint o "auto"SíTipo de comprobante AFIP (ver catálogo), o "auto" para que FACTUskill elija según la condición IVA del emisor y del receptor: un Responsable Inscripto emite A a inscriptos y monotributistas y B al resto; cualquier otro emisor emite C. "auto" no elige comprobantes M ni FCE.
conceptointNo (default 2)1 = Productos, 2 = Servicios, 3 = Productos y Servicios.
fecha_emisionstring (AAAA-MM-DD)No (default hoy)
doc_tipointSíTipo de documento del receptor (ver catálogo).
doc_nrostringSíNúmero de documento del receptor (solo dígitos). Para Consumidor Final sin identificar: "0".
cliente_idintNoId de Cliente ya cargado en FACTUskill, si se conoce.
cliente_nombrestringSíRazón social o nombre del receptor.
cliente_domiciliostringNo
cliente_emailstringNoSe guarda en el comprobante. FACTUskill no envía emails por las emisiones hechas vía API.
cliente_telefonostringNo
fecha_serv_desde, fecha_serv_hasta, fecha_vto_pagostring (AAAA-MM-DD)Sí si concepto > 1Obligatorias para Servicios. fecha_vto_pago no puede ser anterior a fecha_emision.
itemsarraySí (mín. 1)Ver tabla de abajo.
simular_resultadostringNoSolo con key de prueba: "rechazo_afip" o "error_afip".

Cada elemento de items:

CampoTipoObligatorioDescripción
descripcionstringSí
cantidadfloatNo (default 1)
precio_unitariofloatSíPrecio con IVA incluido.
iva_idintNo (default 5 = 21%)Ver catálogo.
unidad_medidastringNo (default 07 = unidades)

Ejemplo de body:

{
  "referencia_externa": "pedido-00458",
  "cbte_tipo": "auto",
  "concepto": 2,
  "doc_tipo": 99,
  "doc_nro": "0",
  "cliente_nombre": "Consumidor Final",
  "fecha_serv_desde": "2026-10-01",
  "fecha_serv_hasta": "2026-10-31",
  "fecha_vto_pago": "2026-10-31",
  "items": [
    {
      "descripcion": "Servicio de consultoría",
      "cantidad": 1,
      "precio_unitario": 15000,
      "iva_id": 5
    }
  ]
}

Respuestas:

HTTPSignificado
201Emitido. El body es el comprobante con "ok": true.
200 con "idempotente": trueEsa referencia_externa ya se había emitido: se devuelve el mismo comprobante, sin volver a tocar AFIP.
200 con "ok": falseAFIP rechazó el comprobante. La request era válida, pero no se emitió nada y la referencia queda libre para reintentar después de corregir. Ver abajo.
4xx / 5xxError: ver la tabla de errores.

Rechazo de AFIP:

{
  "ok": false,
  "codigo": "afip_rechazo",
  "error": "AFIP rechazó el comprobante.",
  "error_code": 10000,
  "observaciones": "[10000] NO AUTORIZADO A EMITIR COMPROBANTES..."
}

error_code es el código numérico de AFIP y solo aparece en los rechazos de AFIP.

Formato del comprobante

Emitir, consultar y anular devuelven siempre el mismo objeto:

{
  "ok": true,
  "prueba": false,
  "comprobante_id": 13212,
  "referencia_externa": "pedido-00458",
  "tipo": "factura",
  "cbte_tipo": 11,
  "estado": "EMITIDO",
  "fecha_emision": "2026-10-28",
  "nro_formateado": "1001-00000109",
  "cae": "86439804454723",
  "cae_vto": "2026-11-07",
  "imp_total": 15000,
  "url_publica": "https://admin.factuskill.com.ar/comprobante/ver?h=...",
  "cliente_email": null,
  "nota_credito": null,
  "comprobante_asociado": null
}
CampoDescripción
pruebatrue si se emitió con una key de prueba (CAE ficticio).
tipofactura o nota_credito.
cbte_tipoTipo AFIP del comprobante. Con "auto", es el tipo que eligió FACTUskill.
estadoEMITIDO, o ANULADO si se emitió una Nota de Crédito que lo anula (por la API o desde el panel de FACTUskill).
url_publicaLink permanente al PDF del comprobante, listo para compartir o descargar. null con keys de prueba.
nota_creditoSi el comprobante fue anulado: comprobante_id, referencia_externa, nro_formateado, cae, fecha_emision y url_publica de la NC. Si la NC se hizo desde el panel, su referencia_externa es null.
comprobante_asociadoEn una Nota de Crédito: comprobante_id, referencia_externa y nro_formateado del comprobante que anula.

Consultar

GET https://admin.factuskill.com.ar/api/v1/comprobantes?referencia_externa=pedido-00458
  • 200: el comprobante. Si pasás la referencia de una Nota de Crédito, devuelve la NC.
  • 404 no_encontrado: no hay ningún comprobante con esa referencia en la empresa de la key.
  • Funciona aunque el plan esté vencido: siempre podés consultar lo ya emitido.

Usala para reconciliar: si una emisión terminó en timeout y no sabés si se emitió, consultá antes de reintentar. Si devuelve 200, el comprobante ya está emitido; si devuelve 404, no se emitió.

Anular (Nota de Crédito)

POST https://admin.factuskill.com.ar/api/v1/comprobantes/anular

{
  "referencia_externa": "pedido-00458",
  "referencia_externa_nc": "pedido-00458-NC"
}

Emite una Nota de Crédito por el total del comprobante, asociada a él ante AFIP, y lo marca como ANULADO. referencia_externa_nc es la referencia propia de la NC y también es la clave de idempotencia de la anulación. No se admiten notas de crédito parciales.

HTTPSignificado
201NC emitida. El body es la NC ("tipo": "nota_credito", con comprobante_asociado), más pagos_mp_liberados: cuántos cobros de MercadoPago vinculados volvieron a quedar pendientes de facturar.
200 con "idempotente": trueEsa referencia_externa_nc ya había anulado ese mismo comprobante.
409 ya_anuladoEl comprobante ya tenía una NC, por ejemplo hecha desde el panel. El body trae nota_credito con sus datos.
409 referencia_en_usoreferencia_externa_nc ya pertenece a otro comprobante.
409 no_anulableEl tipo de comprobante no admite anulación por NC (solo Facturas A, B, C, M y Recibos C), o no está en estado EMITIDO.
404 no_encontradoNo hay ningún comprobante con referencia_externa.

Los rechazos de AFIP y el resto de los errores se comportan igual que en la emisión.

Estado de la key

GET https://admin.factuskill.com.ar/api/v1/me
{
  "ok": true,
  "modo": "produccion",
  "empresa": {
    "id": 5, "estudio_id": 1,
    "cuit": "20123456789", "razon_social": "...", "nombre_fantasia": "...",
    "punto_venta": 3,
    "condicion_iva": { "id": 6, "descripcion": "Responsable Monotributo" },
    "clases_comprobante": ["C"],
    "cbte_tipos_habilitados": [11, 13],
    "activa": true
  },
  "plan": {
    "nombre": "...", "vigente_hasta": "2026-11-30", "api_habilitada": true,
    "ciclo_desde": "2026-10-30", "cupo_usado": 12, "cupo_total": 200
  },
  "rate_limit_por_minuto": 30,
  "puede_emitir": true,
  "motivo": null
}
  • modo: produccion o prueba.
  • clases_comprobante: clases que puede emitir la empresa con cbte_tipo: "auto".
  • cupo_total: null significa plan sin tope de comprobantes.
  • puede_emitir y motivo resumen si hoy se puede emitir. Si no, motivo trae el mismo código que devolvería el 403 (empresa_inactiva, api_deshabilitada, sin_plan, plan_vencido, sin_cupo).
  • No responde 403 aunque el plan esté vencido: sirve como chequeo de salud y para validar una key al cargarla en tu sistema.

Errores

Todo error responde con este formato:

{ "codigo": "sin_cupo", "error": "Límite del plan alcanzado: ..." }

codigo es estable y está pensado para que tu sistema decida qué hacer. error es un texto para personas y puede cambiar.

codigoHTTPQué hacer
api_key_faltante, api_key_invalida401Revisar la key configurada (puede haber sido revocada). No reintentar.
empresa_inactiva, api_deshabilitada, sin_plan, plan_vencido403Requiere acción del estudio contable. No reintentar en loop; consultar /me para saber cuándo se resolvió.
sin_cupo403Se resuelve al empezar el ciclo siguiente o al renovar el plan. Reintentar más tarde, después de consultar /me.
rate_limit429Esperar los segundos que indica el header Retry-After y reintentar.
body_invalido, referencia_faltante, referencia_invalida, datos_faltantes, fechas_invalidas, items_invalidos400Error en los datos enviados. Corregir antes de reintentar.
condicion_iva_receptor_desconocida400No se pudo determinar la condición IVA del receptor (RG 5616). Corregir el documento o cargar el cliente en FACTUskill.
cbte_tipo_incompatible400El tipo de comprobante no corresponde a la condición IVA del receptor (RG 5616). Usá otro tipo o "auto".
afip_rechazo200 (ok: false)AFIP rechazó el comprobante. Revisar observaciones y corregir antes de reintentar.
no_encontrado404No existe esa referencia en la empresa.
ya_anulado, referencia_en_uso, no_anulable409Ver Anular.
afip_error, error_interno500Transitorio (timeout, servicio de AFIP caído). Reintentar con la misma referencia.

Pueden agregarse códigos nuevos. Si tu sistema recibe uno que no conoce, que lo trate según el código HTTP.

Idempotencia y rate limiting

Idempotencia. referencia_externa debe ser única por empresa: un pedido, una venta, un cobro, lo que identifique la operación en tu sistema. Si se repite una request con la misma referencia_externa, FACTUskill no vuelve a emitir en AFIP: devuelve el mismo comprobante, marcado con "idempotente": true. Por eso podés reintentar sin riesgo ante un timeout o un corte de red: no se duplica ninguna factura real. Lo mismo vale para referencia_externa_nc al anular.

Si la emisión no se completó, ya sea por un error 400 o un rechazo de AFIP, la referencia no queda registrada y podés volver a usarla después de corregir los datos.

Rate limiting. Cada API Key tiene un límite de requests por minuto, configurado por el estudio contable (default 30). Todas las respuestas autenticadas traen los headers X-RateLimit-Limit y X-RateLimit-Remaining. Al superar el límite, la respuesta es 429 rate_limit con el header Retry-After, que indica los segundos que hay que esperar. Si procesás lotes, distribuí las llamadas en el tiempo en lugar de enviarlas todas juntas.

Ejemplos y buenas prácticas

cURL: emitir

curl -X POST https://admin.factuskill.com.ar/api/v1/comprobantes/emitir \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia_externa": "pedido-00458",
    "cbte_tipo": "auto",
    "concepto": 1,
    "doc_tipo": 99,
    "doc_nro": "0",
    "cliente_nombre": "Consumidor Final",
    "items": [{ "descripcion": "Servicio", "cantidad": 1, "precio_unitario": 15000, "iva_id": 5 }]
  }'

cURL: consultar y anular

curl "https://admin.factuskill.com.ar/api/v1/comprobantes?referencia_externa=pedido-00458" \
  -H "Authorization: Bearer TU_API_KEY"

curl -X POST https://admin.factuskill.com.ar/api/v1/comprobantes/anular \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "referencia_externa": "pedido-00458", "referencia_externa_nc": "pedido-00458-NC" }'

PowerShell: emitir

$headers = @{ "Authorization" = "Bearer TU_API_KEY" }
$body = @{
    referencia_externa = "pedido-00458"
    cbte_tipo = "auto"
    concepto = 1
    doc_tipo = 99
    doc_nro = "0"
    cliente_nombre = "Consumidor Final"
    items = @(@{ descripcion = "Servicio"; cantidad = 1; precio_unitario = 15000; iva_id = 5 })
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://admin.factuskill.com.ar/api/v1/comprobantes/emitir" -Method Post -Headers $headers `
    -ContentType "application/json; charset=utf-8" -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

En PowerShell 5, el envío como bytes UTF-8 evita que las tildes lleguen mal codificadas.

Manejo de errores recomendado:

  • Generá referencia_externa a partir de tu propia operación, siempre igual para la misma operación y nunca un valor aleatorio en cada intento. Así un reintento automático después de un timeout es seguro.
  • Decidí según codigo, no según el texto de error.
  • Ante 500 o un timeout: consultá con GET /comprobantes o reintentá con la misma referencia. Las dos cosas son seguras.
  • Ante 400 o afip_rechazo: no reintentes sin corregir los datos. La referencia queda libre para el reintento.
  • Ante 401 o 403: el problema es de configuración (key, plan o empresa), no del comprobante. Pausá los envíos de esa empresa y avisá al responsable. /me te dice cuándo vuelve a estar habilitada.
  • Ante 429: respetá Retry-After.
  • Desarrollá y probá con una key de prueba antes de pasar a la real.
¿Tu empresa todavía no tiene la API habilitada, o necesitás ayuda para integrarla? Consultanos.