Documentacion tecnica

API de facturacion electronica

Guia para crear facturas, registrar anulaciones y emitir notas credito mediante solicitudes JSON. Los valores de prueba son placeholders; solicite a su asesor la URL, clave API y datos de produccion.

Configuracion inicial

URL base, endpoint y autenticacion

URL base

https://api-test.oficinapro.co/api/

Endpoint

/invoice/create

Metodo

POST

La URL base y la clave API de esta pagina son ejemplos. Para ambientes reales, use las credenciales entregadas por el asesor.

Encabezado	Valor	Requerido	Descripcion
`Authorization`	`key_0000001`	Si	Clave API entregada por el asesor o equipo de soporte para autenticar cada solicitud.
`Content-Type`	`application/json`	Si	Indica que el cuerpo de la solicitud se envia en JSON.

Operacion principal

Creacion de factura

Envie un objeto JSON con los datos del emisor, adquirente, totales e items facturados. El servicio retorna el estado del documento y los identificadores necesarios para consultas, anulaciones o ajustes posteriores.

Campo	Tipo	Requerido	Descripcion
`Ambiente`	`string`	Si	Use pruebas para integracion o produccion para operacion real.
`NitEmisor`	`integer`	Si	NIT del emisor autorizado para facturar.
`Oficina`	`integer`	Si	Identificador interno de la oficina que emite la factura.
`FechaEmision`	`string`	Si	Fecha de emision en formato YYYY-MM-DD.
`HoraEmision`	`string`	Si	Hora de emision en formato HH:MM:SS.
`CustomerName`	`string`	Si	Nombre o razon social del adquirente.
`CustomerCity`	`string`	Si	Ciudad del adquirente.
`CustomerDepto`	`string`	Si	Departamento del adquirente.
`CustomerAddress`	`string`	Si	Direccion fiscal o comercial del adquirente.
`CustomerNit`	`integer`	Si	Identificacion tributaria del adquirente.
`CustomerEmail`	`string`	Si	Correo para envio y notificacion de la factura.
`CustomerIdCode`	`integer`	Si	Codigo del tipo de identificacion. Ejemplo: 13 para cedula, 31 para NIT.
`CustomerPhone`	`string`	Si	Telefono de contacto del adquirente.
`ValorBaseGravada`	`decimal`	Si	Base gravable acumulada de los productos o servicios.
`Subtotal`	`decimal`	Si	Valor antes de impuestos.
`Iva`	`decimal`	Si	Total de IVA de la factura.
`Total`	`decimal`	Si	Total final del documento.
`Productos`	`array`	Si	Lista de items facturados con descripcion, cantidad, precio e impuestos.

Campos de productos

Campo	Tipo	Requerido	Descripcion
`Codigo`	`string`	Si	Codigo interno o referencia del producto.
`Nombre`	`string`	Si	Descripcion del producto o servicio.
`Cantidad`	`decimal`	Si	Cantidad facturada.
`PrecioUnitario`	`decimal`	Si	Valor unitario antes de impuestos.
`Iva`	`decimal`	Si	IVA calculado para el item.
`Total`	`decimal`	Si	Total del item.

Ejemplo de solicitud JSON

{
  "Ambiente": "pruebas",
  "NitEmisor": 901711544,
  "Oficina": 1,
  "FechaEmision": "2026-01-09",
  "HoraEmision": "10:30:00",
  "CustomerName": "Cliente Demo SAS",
  "CustomerCity": "Bogota",
  "CustomerDepto": "Cundinamarca",
  "CustomerAddress": "Calle 100 # 10-20",
  "CustomerNit": 900711566,
  "CustomerEmail": "cliente@example.com",
  "CustomerIdCode": 31,
  "CustomerPhone": "3001234567",
  "ValorBaseGravada": 500000,
  "Subtotal": 500000,
  "Iva": 95000,
  "Total": 595000,
  "Productos": [
    {
      "Codigo": "SERV-001",
      "Nombre": "Servicio de integracion",
      "Cantidad": 1,
      "PrecioUnitario": 500000,
      "Iva": 95000,
      "Total": 595000
    }
  ]
}

Respuesta exitosa

{
  "codigo": "ACEPTADA",
  "invoice_id": 3048,
  "cufe": "CUFE123456789",
  "mensaje": "Documento procesado correctamente"
}

Ejemplo PHP con cURL

<?php
$url = "https://api-test.oficinapro.co/api/invoice/create";

$headers = [
  "Content-Type: application/json",
  "Authorization: key_0000001"
];

$data = [
  "Ambiente" => "pruebas",
  "NitEmisor" => 901711544,
  "Oficina" => 1,
  "FechaEmision" => "2026-01-09",
  "HoraEmision" => "10:30:00",
  "CustomerName" => "Cliente Demo SAS",
  "CustomerNit" => 900711566,
  "CustomerEmail" => "cliente@example.com",
  "CustomerIdCode" => 31,
  "Subtotal" => 500000,
  "Iva" => 95000,
  "Total" => 595000
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Documento existente

Anulacion de factura

Para anular una factura, envie el identificador devuelto durante la creacion junto con los datos del emisor y cliente. El campoAnulaciondebe marcarse con valor 1.

Campo	Tipo	Requerido	Descripcion
`Ambiente`	`string`	Si	Ambiente pruebas o produccion.
`Anulacion`	`integer`	Si	Enviar el valor 1 para indicar anulacion.
`NitEmisor`	`integer`	Si	NIT del emisor del documento.
`CustomerNit`	`integer`	Si	Identificacion del cliente relacionado con la factura.
`ID`	`integer`	Si	Identificador de la factura obtenido al crearla.

Ejemplo de solicitud JSON

{
  "Ambiente": "pruebas",
  "Anulacion": 1,
  "CustomerNit": 900711566,
  "NitEmisor": 901711544,
  "ID": 3048
}

Respuesta exitosa

{
  "codigo": "ANULADA",
  "invoice_id": 3048,
  "mensaje": "Anulacion registrada correctamente"
}

Nota credito

Ajuste sobre factura

Use esta operacion cuando necesite generar una nota credito asociada a una factura previa. El request debe incluir el ID original y los valores del ajuste.

Campo	Tipo	Requerido	Descripcion
`Ambiente`	`string`	Si	Ambiente pruebas o produccion.
`Ajuste`	`integer`	Si	Enviar el valor 1 para indicar ajuste o nota credito.
`NitEmisor`	`integer`	Si	NIT del emisor del documento.
`CustomerNit`	`integer`	Si	Identificacion del cliente de la factura original.
`ID`	`integer`	Si	Identificador de la factura que se ajusta.
`SubTotalAjuste`	`decimal`	Si	Subtotal de la nota credito.
`IvaAjuste`	`decimal`	Si	IVA de la nota credito.
`TotalAjuste`	`decimal`	Si	Total final de la nota credito.

Ejemplo de solicitud JSON

{
  "Ambiente": "pruebas",
  "Ajuste": 1,
  "CustomerNit": 900711566,
  "NitEmisor": 901711544,
  "ID": 3048,
  "SubTotalAjuste": 500000,
  "IvaAjuste": 95000,
  "TotalAjuste": 595000
}

Respuesta exitosa

{
  "codigo": "ACEPTADA",
  "credit_note_id": 152,
  "cude": "CUDE123456789"
}

Validacion

Respuestas de error frecuentes

Codigo	Causa posible	Accion sugerida	Descripcion
`N99`	`Factura inexistente`	Revise el ID enviado	El documento solicitado no fue encontrado para el emisor o ambiente indicado.
`AUTH`	`Clave API invalida`	Verifique Authorization	La clave esta ausente, vencida o no pertenece al ambiente usado.
`VALIDATION`	`Datos incompletos`	Revise campos requeridos	Uno o mas campos obligatorios no fueron enviados o tienen formato invalido.

Operacion

Acceso al panel administrativo

Las facturas enviadas por API pueden consultarse y validarse desde el panel administrativo de la cuenta. Para ambientes de prueba, solicite usuario y clave de demo al asesor asignado.

Panel de pruebas

https://api-test.oficinapro.co/admin