Tu llave de APILas llaves las entrega un administrador. Solicitar acceso

Conceptos básicos

Autenticación

Envía tu llave en cada petición con la cabecera Authorization: Bearer gf_…. Las llaves las emite tu administrador y se muestran una sola vez: guárdala en un lugar seguro. Pueden limitarse por IP o dejarse en solo lectura. No hay registro público ni acceso anónimo.

Muestra el modo de tu cuenta, lo que falta para operar en cada ámbito y cuándo vence tu certificado. Úsala también para comprobar que tu llave funciona.

GET/v1/estado

Esta llamada no lleva cuerpo.

Respuesta

Ejemplo real, capturado en modo simulado.

{
  "empresa": "Empresa de ejemplo S.A.S.",
  "nit": "900123456",
  "modo": "simulado",
  "simulado": true,
  "produccion_desde": null,
  "faltantes": {
    "fe": [
      "Certificado digital",
      "Identificador del software",
      "PIN del software",
      "TestSetId"
    ],
    "nomina": [
      "Certificado digital",
      "Identificador del software",
      "PIN del software",
      "TestSetId"
    ],
    "ds": [
      "Certificado digital",
      "Identificador del software",
      "PIN del software",
      "TestSetId"
    ]
  },
  "certificado_vence": null
}

Los tres modos de una cuenta

Modo	Qué hace	Validez legal
`simulado`	Responde con el formato de la DIAN, sin validez fiscal y sin contactar a la DIAN. No aplica las reglas de validación de la DIAN a tus facturas y nunca envía correos a terceros. Es el modo inicial.	No
`habilitacion`	Opera contra el ambiente de pruebas de la DIAN. Solo se envía el set de pruebas; emitir responde 409.	No
`produccion`	Emite ante la DIAN y entrega al adquirente.	Sí

Idempotencia

Toda emisión exige la cabecera Idempotency-Key, hasta 120 caracteres. Si repites la petición con la misma llave y el mismo cuerpo, recibes la primera respuesta con la cabecera Idempotent-Replay: true, y no se crea otro documento. Con otro cuerpo responde 409.

Usa un valor ligado a tu operación, como el número de pedido. Así, un reintento tras un corte de red nunca factura dos veces.

Estados de un documento

Estado	Significa	Qué hacer
`aceptado`	La DIAN lo validó.	Nada.
`pendiente`	La DIAN no respondió. La API contestó 202.	Nada: Gemefact reintenta solo. Revisa `horas_restantes`.
`rechazado`	La DIAN encontró errores. Conserva su número.	Corrige y usa `/reintentar`.
`borrador`	No se pudo enviar por un problema de configuración.	Corrige la configuración y usa `/reintentar`.
`reemplazado`, `eliminado`	Nómina ajustada por una nota.	Nada.

Formatos y límites

JSON en UTF-8 y fechas AAAA-MM-DD. En Colombia la hora es UTC-5.
Envías cantidades y precios como números. Los totales los devolvemos como texto con 2 decimales, para no perder precisión.
Los totales los calcula siempre Gemefact; no necesitas enviarlos.
Máximo 120 peticiones por minuto por empresa.
Si la DIAN cae, el plazo para transmitir los pendientes es de 48 horas.