Comerdial - Documentacion API

Que hace esta API

Esta pagina resume de forma ejecutiva y tecnica lo que un integrador necesita para comenzar a consumir la API de Comerdial.

01

Facturas electronicas

Recepcion de facturas con prevalidacion antes de crear el documento fiscal definitivo.

02

Notas credito y debito

Procesamiento documental con el mismo contrato de autenticacion, validacion y seguimiento.

03

Documento soporte y ajustes

Documento soporte de adquisicion y notas de ajuste, con validate y envio dedicados.

04

Validacion previa

Endpoints de validate para detectar errores estructurales antes del envio real.

05

Estado consolidado

Consulta unificada de recepcion API, procesamiento interno y estado DIAN del documento.

06

Reproceso controlado

Reintento de documentos por external_id para escenarios de error o procesamiento pendiente.

Comienza en minutos

Mismo enfoque que usan muchas APIs de facturacion electronica: credenciales claras, variables de entorno (o Postman), JSON UTF-8 y un flujo validar antes de enviar. Aqui solo necesita Fiscal Hub y el gateway Comerdial.

1

Credenciales

Solicite el token de API del tenant y el codigo source_system autorizado para su integracion.

2

Postman (recomendado)

Descargue la coleccion, importela en Postman y complete las variables token, source_system y external_id_demo. base_url ya apunta a produccion.

3

Prevalidar y enviar

Ejecute primero el request de Prevalidar del tipo de documento; si la respuesta es correcta, ejecute Enviar.

4

Estado y retry

Use Estado por external_id con el mismo source_system y el document_type adecuado. Reintentar solo si el flujo lo requiere.

Descargar coleccion Postman (JSON) Ir a la tabla de endpoints

Resumen tecnico rapido

Lo esencial para levantar una integracion sin confundir credenciales, host o rutas.

Host oficial (integradores)

https://api.comerdial.cloud

Todas las rutas bajo /api/fiscal-hub/. El ERP fiscal puede estar en otro host; el gateway resuelve la base de datos del tenant.

Header obligatorio

Authorization: Bearer <token_fiscal_api>

Content-Type

application/json

Identificador de integracion

external_id + source_system + document_type

URL, autenticacion y campos comunes

Como debe llamar el integrador y que datos van siempre en el cuerpo JSON.

Token: cabecera Authorization: Bearer <token>. Es el token de API tecnico asociado al tenant (el mismo valor que autoriza contra Fiscal Hub en la suite del cliente). No use el JWT de sesion del dashboard web.
external_id: identificador unico del documento en su sistema. Debe ser estable entre reintentos.
source_system: codigo acordado para su integracion (ERP, POS, conector). Debe ser el mismo en validate, envio, consulta de estado y retry.
company_ref (opcional): si lo envia, debe coincidir con el tenant: identificador de base de datos del cliente que le indique soporte, UUID del tenant, o tenant_<uuid>. Si no lo envia, el gateway no valida este campo.
Idempotencia: el sistema arma una clave interna a partir de la compañía fiscal del tenant, mas source_system, external_id y el tipo de documento (segun la ruta que llame: factura, nota, etc.). Usted no envia company_id en el JSON para esto: basta con usar siempre el mismo external_id y source_system por documento. Reenviar la misma combinacion no duplica registros; puede recibir 200 con el estado ya existente.
Diferencia validate vs envio: .../validate comprueba el payload sin crear el documento definitivo en el flujo normal; el POST sin /validate es el envio real. El JSON suele ser el mismo en ambos pasos.
Content-Type: application/json en todos los POST con cuerpo.
Accept: application/json en todas las peticiones (recomendado).
Encoding: cuerpos y respuestas en UTF-8.

Formato de las peticiones

Cabeceras que debe enviar el cliente HTTP (igual si usa Postman, curl o su lenguaje).

Cabecera	Valor	Notas
`Authorization`	`Bearer <token>`	Obligatoria. Token tecnico del tenant.
`Content-Type`	`application/json`	En POST con cuerpo.
`Accept`	`application/json`	Recomendada para recibir JSON en errores y exitos.

Donde obtener el token y ambientes

El integrador necesita un token de API emitido para el tenant del cliente. Si no lo tiene, debe pedirlo al administrador del cliente o a soporte Comerdial; no es el mismo token de sesion que el login web del panel. Si su proyecto requiere un host distinto para pruebas (sandbox), confirme la URL con soporte; en esta pagina se documenta el endpoint de produccion https://api.comerdial.cloud.

Referencia de endpoints

Prefijo completo: https://api.comerdial.cloud + ruta de la tabla. Cada tipo de documento tiene par validate (solo validacion) y envio (crea o actualiza segun idempotencia).

Metodo	Endpoint	Uso principal
POST	`/api/fiscal-hub/invoices/validate`	Prevalidar factura (mismo JSON que envio, sin crear documento definitivo).
POST	`/api/fiscal-hub/invoices`	Crear y procesar factura electronica.
POST	`/api/fiscal-hub/credit-notes/validate`	Prevalidar nota credito.
POST	`/api/fiscal-hub/credit-notes`	Procesar nota credito.
POST	`/api/fiscal-hub/debit-notes/validate`	Prevalidar nota debito.
POST	`/api/fiscal-hub/debit-notes`	Procesar nota debito.
POST	`/api/fiscal-hub/support-documents/validate`	Prevalidar documento soporte.
POST	`/api/fiscal-hub/support-documents`	Procesar documento soporte.
POST	`/api/fiscal-hub/support-document-adjustment-notes/validate`	Prevalidar nota de ajuste al documento soporte.
POST	`/api/fiscal-hub/support-document-adjustment-notes`	Procesar nota de ajuste al documento soporte.
GET	`/api/fiscal-hub/status/<external_id>`	Estado consolidado. Query: `source_system` (recomendado) y `document_type` (ver tabla abajo).
POST	`/api/fiscal-hub/retry/<external_id>`	Reprocesar. Cuerpo JSON opcional (puede ser `{}`); incluya en el payload lo que exija su flujo si soporte lo indica.

Valores de `document_type` (consulta de estado)

Use el mismo valor en ?document_type=... que corresponda al documento consultado.

document_type	Documento
`invoice`	Factura de venta
`credit_note`	Nota credito
`debit_note`	Nota debito
`support_document`	Documento soporte
`support_document_adjustment_note`	Nota de ajuste (soporte)

Codigos HTTP (resumen)

Respuestas del motor fiscal y del gateway. Trate siempre el cuerpo JSON (o mensaje) para el detalle del error.

Codigo	Estado	Significado
200	OK	Consulta correcta o respuesta idempotente (documento ya existente).
201	Created	Documento creado o aceptado para procesamiento.
400	Bad Request	JSON invalido o payload rechazado en validacion estructural.
401	Unauthorized	Falta Bearer, token vacio, token invalido o inactivo (gateway).
404	Not Found	Recurso no encontrado (por ejemplo estado sin registro para ese `external_id`).
409	Conflict	Conflicto de idempotencia o `company_ref` no coincide con el token (gateway).
422	Unprocessable	Error de negocio o configuracion fiscal en la plataforma.
500	Server Error	Error tecnico en el motor fiscal.
502	Bad Gateway	Gateway no pudo contactar el motor fiscal.
503	Unavailable	ERP del tenant no habilitado o sin base asignada; o configuracion del gateway incompleta.

Ejemplos de JSON (cuerpo del POST)

Use el mismo JSON primero en .../validate y, si la respuesta es valida, en el endpoint de envio (sin /validate). Incluya siempre external_id y source_system acordado con Comerdial. El campo document_type en el JSON ayuda al trazado; el tipo real lo define la ruta (invoices, credit-notes, etc.). Si su tenant exige datos extra (resolucion, medio de pago, etc.), el validate devolvera el detalle: complete segun validation.errors o consulte a soporte.

Tercero (cliente o proveedor)

Para facturas y notas de venta use el objeto customer. Para documento soporte y su nota de ajuste use supplier. El ejemplo de factura incluye direccion y codigos de ubicacion; en modo estricto el tenant puede exigirlos siempre. Valores tipicos: id_type (ej. NIT), country_code CO, state codigo departamento (ej. DC), municipality_code DIAN (ej. 11001 Bogota), fiscal_responsibilities arreglo (ej. ["R-99-PN"]).

Lineas e impuestos

Cada elemento de lines lleva al menos description, quantity, price_unit. Para IVA recomendado:

`tax_code`	Significado
`IVA_19`	IVA 19 % gravado
`IVA_5`	IVA 5 % gravado
`IVA_0_EXENTO`	IVA 0 % exento
`IVA_EXCLUIDO`	Excluido
`IVA_NO_SUJETO`	No sujeto

Alternativa: enviar solo tax_rate (numero, ej. 19) para que el sistema resuelva el impuesto cuando sea posible. Combinar tax_type, tax_treatment, tax_code y tax_rate como en los ejemplos es lo mas predecible.

1. Factura de venta — `POST /api/fiscal-hub/invoices/validate` o `.../invoices`

{
  "external_id": "FEC-2026-0001",
  "document_type": "invoice",
  "source_system": "erp_externo",
  "invoice_date": "2026-03-21",
  "due_date": "2026-03-21",
  "currency": "COP",
  "customer": {
    "vat": "900123456-1",
    "id_type": "NIT",
    "name": "Cliente Demo SAS",
    "street": "Cra 1 # 2-3",
    "city": "Bogota D.C.",
    "state": "DC",
    "country_code": "CO",
    "municipality_code": "11001",
    "fiscal_responsibilities": ["R-99-PN"]
  },
  "lines": [
    {
      "description": "Servicio profesional",
      "quantity": 1,
      "price_unit": 100000,
      "tax_type": "IVA",
      "tax_treatment": "gravado",
      "tax_code": "IVA_19",
      "tax_rate": 19
    }
  ],
  "total": 119000
}

2. Nota credito — `POST .../credit-notes/validate` o `.../credit-notes`

Obligatorio: reference.document_number debe ser el nombre/numero interno de la factura origen ya publicada en el ERP fiscal del tenant (el mismo valor que identifica el movimiento contable de la factura, no el external_id de la API salvo que coincida). Obligatorio: reason (motivo), minimo 5 caracteres. Mismo contrato para nota debito cambiando ruta a debit-notes, document_type a debit_note y opcional debit_note_number.

{
  "external_id": "NC-2026-0001",
  "document_type": "credit_note",
  "source_system": "erp_externo",
  "invoice_date": "2026-03-21",
  "due_date": "2026-03-21",
  "currency": "COP",
  "credit_note_number": "NC9001234560001",
  "reason": "Devolucion de mercancia conforme acuerdo comercial",
  "reference": {
    "document_number": "FV-00001",
    "issue_date": "2026-03-01",
    "uuid": "CUFe-o-CUDE-de-la-factura-origen-si-lo-tiene"
  },
  "customer": {
    "vat": "900123456-1",
    "id_type": "NIT",
    "name": "Cliente Demo SAS",
    "street": "Cra 1 # 2-3",
    "city": "Bogota D.C.",
    "state": "DC",
    "country_code": "CO",
    "municipality_code": "11001",
    "fiscal_responsibilities": ["R-99-PN"]
  },
  "lines": [
    {
      "description": "Devolucion parcial",
      "quantity": 1,
      "price_unit": 50000,
      "tax_type": "IVA",
      "tax_treatment": "gravado",
      "tax_code": "IVA_19",
      "tax_rate": 19
    }
  ],
  "total": 59500
}

3. Documento soporte — `POST .../support-documents/validate` o `.../support-documents`

{
  "external_id": "DS-2026-0001",
  "document_type": "support_document",
  "source_system": "erp_externo",
  "invoice_date": "2026-03-21",
  "due_date": "2026-03-21",
  "currency": "COP",
  "supplier": {
    "vat": "901111222",
    "id_type": "NIT",
    "name": "Proveedor no obligado Demo",
    "street": "Cl 10 # 5-30",
    "city": "Bogota D.C.",
    "state": "DC",
    "country_code": "CO",
    "municipality_code": "11001"
  },
  "lines": [
    {
      "description": "Compra a no obligado",
      "quantity": 1,
      "price_unit": 50000,
      "tax_type": "IVA",
      "tax_treatment": "gravado",
      "tax_code": "IVA_19",
      "tax_rate": 19
    }
  ],
  "total": 59500
}

4. Nota de ajuste (documento soporte) — `POST .../support-document-adjustment-notes/validate` o envio

reference.document_number debe ser el nombre del documento soporte origen publicado (misma regla que en notas de venta: identificador del movimiento en el ERP). Incluya reason (motivo) y datos del proveedor.

{
  "external_id": "NAS-2026-0001",
  "document_type": "support_document_adjustment_note",
  "source_system": "erp_externo",
  "invoice_date": "2026-03-21",
  "due_date": "2026-03-21",
  "currency": "COP",
  "support_document_adjustment_note_number": "NAS00123",
  "reason": "Ajuste por diferencia de valor reportada por el proveedor",
  "reference": {
    "document_number": "DS-00001",
    "issue_date": "2026-03-01",
    "uuid": "CUDE-del-documento-soporte-origen"
  },
  "supplier": {
    "vat": "901111222",
    "id_type": "NIT",
    "name": "Proveedor no obligado Demo",
    "street": "Cl 10 # 5-30",
    "city": "Bogota D.C.",
    "state": "DC",
    "country_code": "CO",
    "municipality_code": "11001",
    "fiscal_responsibilities": ["R-99-PN"]
  },
  "lines": [
    {
      "description": "Ajuste documento soporte",
      "quantity": 1,
      "price_unit": 10000,
      "tax_type": "IVA",
      "tax_treatment": "gravado",
      "tax_code": "IVA_19",
      "tax_rate": 19
    }
  ],
  "total": 11900
}

Respuesta exitosa (forma general API v2)

{
  "ok": true,
  "api_version": "2.0",
  "decision": {
    "reception_state": "accepted",
    "accepted_by_dian": false
  },
  "document": {
    "external_id": "FEC-2026-0001",
    "document_type": "invoice",
    "status": "processing",
    "dian_state": "sent"
  },
  "validation": {
    "errors": [],
    "warnings": []
  }
}

Si ok es false, revise error y validation.errors. En decision puede aparecer un booleano adicional de aceptacion para registro contable; el nombre exacto viene en la respuesta.

Ejemplo cURL (factura validate)

curl -sS -X POST "https://api.comerdial.cloud/api/fiscal-hub/invoices/validate" \
  -H "Authorization: Bearer SU_TOKEN_AQUI" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @factura.json

Guarde el JSON en un archivo factura.json o pegue el cuerpo con -d '...'. Para estado: GET .../status/FEC-2026-0001?source_system=erp_externo&document_type=invoice.

Estados que debe entender el integrador

El contrato de respuesta distingue recepcion, procesamiento interno y aceptacion oficial DIAN.

received

La API recibio el documento y lo dejo listo para analisis.

in_review

El payload paso recepcion y esta siendo procesado o validado internamente.

accepted

El documento fue aceptado para creacion/proceso y puede avanzar hacia DIAN.

rejected

El payload fue rechazado en recepcion o prevalidacion y requiere correccion.

Flujo de integracion

Vista simple del proceso tecnico que sigue un documento desde el ERP hasta DIAN.

ERP / POS externo

Gateway api.comerdial.cloud

Validate / Envio

Motor fiscal

Procesamiento

DIAN

Status / Retry

Checklist de arranque

Antes de pasar a produccion, valida estos puntos minimos.

Confirmar https://api.comerdial.cloud y rutas /api/fiscal-hub/... (sin 404 por prefijo incorrecto).
Usar token tecnico de Fiscal Hub, no JWT de login.
Verificar que source_system este permitido por el token.
Enviar primero a validate antes de publicar en el endpoint de envio (por ejemplo invoices).
Usar external_id consistente para idempotencia y seguimiento.
En GET .../status/<external_id> enviar siempre el mismo source_system y el document_type acorde al documento.
Consultar status para recepcion API, estado documental y estado DIAN.

Necesitas apoyo para integrar?

Nuestro equipo puede ayudarte con credenciales, validacion del payload, pruebas end-to-end y salida a produccion.

Solicitar soporte info@comerdial.cloud