Primera factura en 10 minutos

Esto es lo mínimo para emitir un documento y ver su CUFE. Todo lo demás —campos opcionales, tipos de documento, webhooks— viene después.

Qué necesitas antes

Un client_id y un client_secret, y un rango de numeración ya cargado para tu emisor. Si todavía no los tienes, escríbenos: el alta del emisor la hacemos nosotros.

1. Pide un token

   curl -X POST https://sandbox.facturacion.misofk.com/v1/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "client_credentials",
       "client_id": "fc_tu_client_id",
       "client_secret": "tu_client_secret"
     }'

   Respuesta:

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "token_type": "Bearer",
     "expires_in": 3600
   }

   El token dura una hora. Guárdalo y reúsalo: pedir uno por petición es la forma más rápida de chocar contra el límite de 300 por minuto.

2. Busca tu rango de numeración

   curl https://sandbox.facturacion.misofk.com/v1/numbering-ranges \
     -H "Authorization: Bearer $TOKEN"

   Quédate con el id del rango cuyo document_type sea INVOICE y que esté vigente. Ese UUID va en cada factura.

   La clave técnica

   Una factura necesita la clave técnica del rango para calcular el CUFE. Si el rango no la tiene, la emisión falla aunque el rango exista y esté vigente. En la respuesta lo ves como has_technical_key.

3. Emite la factura

   curl -X POST https://sandbox.facturacion.misofk.com/v1/invoices \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "reference_code": "FAC-2026-0001",
       "numbering_range_id": "9a76de2a-71c6-4020-aa54-255c58219283",
       "customer": {
         "identification_type": "31",
         "identification": "900123456",
         "dv": "7",
         "person_type": "1",
         "name": "Comercializadora del Norte SAS",
         "tax_regime": "48",
         "email": "facturacion@ejemplo.com",
         "municipality_code": "05001"
       },
       "items": [
         {
           "code": "CAF-500",
           "name": "Café molido 500 g",
           "quantity": 2,
           "unit_measure": "94",
           "price": 10000,
           "discount_rate": 10,
           "taxes": [{ "code": "01", "rate": 19 }]
         }
       ],
       "payment": { "form_code": "1", "means_code": "10" }
     }'

   La cuenta que hace el servidor con esos datos:

   base           2 × 10.000  = 20.000,00
   descuento 10%               −2.000,00
   línea                       18.000,00
   IVA 19%                      3.420,00
   ─────────────────────────────────────
   total a pagar               21.420,00

4. Lee la respuesta

   {
     "id": "48409b5f-337e-468c-88eb-cc828fe09dd7",
     "type": "01",
     "reference_code": "FAC-2026-0001",
     "full_number": null,
     "status": "QUEUED",
     "cufe": null,
     "qr_url": null
   }

   full_number y cufe llegan en null, y está bien. Numerar, armar el UBL, firmar y transmitir se hace en segundo plano: la respuesta confirma que el documento se aceptó, no que la DIAN ya lo validó.

5. Espera el resultado

   La forma correcta es un webhook. Mientras integras, consultar sirve:

   curl https://sandbox.facturacion.misofk.com/v1/documents/48409b5f-337e-468c-88eb-cc828fe09dd7 \
     -H "Authorization: Bearer $TOKEN"

   {
     "status": "VALIDATED",
     "full_number": "SETP990000001",
     "cufe": "a1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f801",
     "qr_url": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=...",
     "qr_image": "data:image/png;base64,..."
   }

   Ya tienes la factura. qr_image viene lista para pegar en tu representación gráfica.

Los tres tropiezos del primer día

«Property X should not exist» El API rechaza cualquier campo que no esté en el contrato, no lo ignora. Si mandas total o subtotal, falla — los montos los calcula siempre el servidor, nunca se envían.

Las tarifas van en porcentaje 19, no 0.19. Lo mismo discount_rate: es un porcentaje, no un monto.

Repetir un reference_code no crea otra factura Devuelve la que ya existe, sin gastar consecutivo. Es a propósito: un reintento tuyo por un timeout nunca debe producir dos facturas.

Después de esto

• Autenticación — las cuatro credenciales y para qué es cada una
• Facturas — todos los campos, uno por uno
• Webhooks — enterarte sin consultar en bucle
• Errores — qué significa cada código