{
  "info": {
    "_postman_id": "a1b2c3d4-e5f6-7890-abcd-comerdial-fh",
    "name": "Comerdial Fiscal Hub API",
    "description": "# Comerdial — Fiscal Hub API (documentos electronicos Colombia)\n\n## Introduccion\n\nAPI REST para enviar documentos electronicos al flujo fiscal del tenant: prevalidacion (`validate`), envio, consulta de estado y reproceso. El gateway publico enruta segun el token; no envie el parametro `db` en la URL.\n\n## Documentos soportados (Fiscal Hub)\n\n- **Factura de venta** — `invoices` / `invoices/validate`\n- **Nota credito** — `credit-notes` / `credit-notes/validate`\n- **Nota debito** — `debit-notes` / `debit-notes/validate`\n- **Documento soporte** — `support-documents` / `support-documents/validate`\n- **Nota de ajuste (soporte)** — `support-document-adjustment-notes` / `.../validate`\n\n## Base URL\n\n`https://api.comerdial.cloud`\n\nTodas las rutas bajo `/api/fiscal-hub/`.\n\n## Autenticacion\n\n**Bearer Token** en cada peticion: cabecera `Authorization: Bearer <token>`. Use el token tecnico de API del tenant (no el JWT de sesion del panel web).\n\n## Formato\n\n- `Content-Type: application/json` en POST con cuerpo\n- `Accept: application/json`\n- Cuerpos en **UTF-8**\n\n## Campos habituales en el JSON\n\n- `external_id` — id estable en su sistema\n- `source_system` — codigo de su integracion (mismo valor en validate, envio, status y retry)\n- `company_ref` — opcional; si se envia, debe coincidir con el tenant (valor que le indique soporte)\n\n## Codigos HTTP (resumen)\n\n| Codigo | Descripcion |\n| --- | --- |\n| 200 | OK / idempotente |\n| 201 | Creado o aceptado para procesamiento |\n| 400 | JSON o payload invalido |\n| 401 | Token faltante o invalido |\n| 404 | No encontrado |\n| 409 | Conflicto (idempotencia o company_ref) |\n| 422 | Error de negocio o configuracion fiscal |\n| 500 | Error tecnico |\n| 502 | Gateway no alcanza el motor fiscal |\n| 503 | Tenant o gateway no disponible |\n\n## Configuracion rapida\n\n1. Importe esta coleccion en Postman.\n2. Edite variables de coleccion: `base_url`, `token`, `source_system`, `external_id_demo`.\n3. La coleccion usa autenticacion Bearer heredada; los requests usan `Inherit auth`.\n4. Flujo recomendado: **Prevalidar** → **Enviar** → **Estado**.\n\n## Consulta de estado\n\n`GET /api/fiscal-hub/status/{external_id}?source_system=...&document_type=...`\n\nValores tipicos de `document_type`: `invoice`, `credit_note`, `debit_note`, `support_document`, `support_document_adjustment_note`.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "base_url", "value": "https://api.comerdial.cloud" },
    { "key": "token", "value": "" },
    { "key": "source_system", "value": "mi_integracion" },
    { "key": "external_id_demo", "value": "DEMO-001" }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{token}}", "type": "string" }]
  },
  "item": [
    {
      "name": "Facturas",
      "item": [
        {
          "name": "Prevalidar factura",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}\",\n  \"document_type\": \"invoice\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"customer\": {\n    \"vat\": \"900123456-1\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Cliente Demo SAS\",\n    \"street\": \"Cra 1 # 2-3\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Servicio profesional\",\n      \"quantity\": 1,\n      \"price_unit\": 100000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 119000\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/invoices/validate"
          }
        },
        {
          "name": "Enviar factura",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}\",\n  \"document_type\": \"invoice\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"customer\": {\n    \"vat\": \"900123456-1\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Cliente Demo SAS\",\n    \"street\": \"Cra 1 # 2-3\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Servicio profesional\",\n      \"quantity\": 1,\n      \"price_unit\": 100000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 119000\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/invoices"
          }
        }
      ]
    },
    {
      "name": "Notas credito",
      "item": [
        {
          "name": "Prevalidar nota credito",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-NC\",\n  \"document_type\": \"credit_note\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"reason\": \"Devolucion de mercancia conforme acuerdo comercial\",\n  \"reference\": {\n    \"document_number\": \"FV-00001\",\n    \"issue_date\": \"2026-03-01\"\n  },\n  \"customer\": {\n    \"vat\": \"900123456-1\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Cliente Demo SAS\",\n    \"street\": \"Cra 1 # 2-3\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Devolucion parcial\",\n      \"quantity\": 1,\n      \"price_unit\": 50000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 59500\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/credit-notes/validate"
          }
        },
        {
          "name": "Enviar nota credito",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-NC\",\n  \"document_type\": \"credit_note\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"reason\": \"Devolucion de mercancia conforme acuerdo comercial\",\n  \"reference\": {\n    \"document_number\": \"FV-00001\",\n    \"issue_date\": \"2026-03-01\"\n  },\n  \"customer\": {\n    \"vat\": \"900123456-1\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Cliente Demo SAS\",\n    \"street\": \"Cra 1 # 2-3\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Devolucion parcial\",\n      \"quantity\": 1,\n      \"price_unit\": 50000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 59500\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/credit-notes"
          }
        }
      ]
    },
    {
      "name": "Notas debito",
      "item": [
        {
          "name": "Prevalidar nota debito",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-ND\",\n  \"document_type\": \"debit_note\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"reason\": \"Ajuste de valores conforme clausula contractual\",\n  \"reference\": {\n    \"document_number\": \"FV-00001\",\n    \"issue_date\": \"2026-03-01\"\n  },\n  \"customer\": {\n    \"vat\": \"900123456-1\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Cliente Demo SAS\",\n    \"street\": \"Cra 1 # 2-3\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Ajuste a la factura\",\n      \"quantity\": 1,\n      \"price_unit\": 25000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 29750\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/debit-notes/validate"
          }
        },
        {
          "name": "Enviar nota debito",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-ND\",\n  \"document_type\": \"debit_note\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"reason\": \"Ajuste de valores conforme clausula contractual\",\n  \"reference\": {\n    \"document_number\": \"FV-00001\",\n    \"issue_date\": \"2026-03-01\"\n  },\n  \"customer\": {\n    \"vat\": \"900123456-1\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Cliente Demo SAS\",\n    \"street\": \"Cra 1 # 2-3\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Ajuste a la factura\",\n      \"quantity\": 1,\n      \"price_unit\": 25000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 29750\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/debit-notes"
          }
        }
      ]
    },
    {
      "name": "Documento soporte",
      "item": [
        {
          "name": "Prevalidar documento soporte",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-DS\",\n  \"document_type\": \"support_document\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"supplier\": {\n    \"vat\": \"901111222\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Proveedor no obligado Demo\",\n    \"street\": \"Cl 10 # 5-30\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\"\n  },\n  \"lines\": [\n    {\n      \"description\": \"Compra a no obligado\",\n      \"quantity\": 1,\n      \"price_unit\": 50000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 59500\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/support-documents/validate"
          }
        },
        {
          "name": "Enviar documento soporte",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-DS\",\n  \"document_type\": \"support_document\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"supplier\": {\n    \"vat\": \"901111222\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Proveedor no obligado Demo\",\n    \"street\": \"Cl 10 # 5-30\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\"\n  },\n  \"lines\": [\n    {\n      \"description\": \"Compra a no obligado\",\n      \"quantity\": 1,\n      \"price_unit\": 50000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 59500\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/support-documents"
          }
        }
      ]
    },
    {
      "name": "Nota ajuste documento soporte",
      "item": [
        {
          "name": "Prevalidar nota de ajuste",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-DSA\",\n  \"document_type\": \"support_document_adjustment_note\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"support_document_adjustment_note_number\": \"NAS00123\",\n  \"reason\": \"Ajuste por diferencia de valor reportada por el proveedor\",\n  \"reference\": {\n    \"document_number\": \"DS-00001\",\n    \"issue_date\": \"2026-03-01\"\n  },\n  \"supplier\": {\n    \"vat\": \"901111222\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Proveedor no obligado Demo\",\n    \"street\": \"Cl 10 # 5-30\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Ajuste documento soporte\",\n      \"quantity\": 1,\n      \"price_unit\": 10000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 11900\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/support-document-adjustment-notes/validate"
          }
        },
        {
          "name": "Enviar nota de ajuste",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{external_id_demo}}-DSA\",\n  \"document_type\": \"support_document_adjustment_note\",\n  \"source_system\": \"{{source_system}}\",\n  \"invoice_date\": \"2026-03-21\",\n  \"due_date\": \"2026-03-21\",\n  \"currency\": \"COP\",\n  \"support_document_adjustment_note_number\": \"NAS00123\",\n  \"reason\": \"Ajuste por diferencia de valor reportada por el proveedor\",\n  \"reference\": {\n    \"document_number\": \"DS-00001\",\n    \"issue_date\": \"2026-03-01\"\n  },\n  \"supplier\": {\n    \"vat\": \"901111222\",\n    \"id_type\": \"NIT\",\n    \"name\": \"Proveedor no obligado Demo\",\n    \"street\": \"Cl 10 # 5-30\",\n    \"city\": \"Bogota D.C.\",\n    \"state\": \"DC\",\n    \"country_code\": \"CO\",\n    \"municipality_code\": \"11001\",\n    \"fiscal_responsibilities\": [\"R-99-PN\"]\n  },\n  \"lines\": [\n    {\n      \"description\": \"Ajuste documento soporte\",\n      \"quantity\": 1,\n      \"price_unit\": 10000,\n      \"tax_type\": \"IVA\",\n      \"tax_treatment\": \"gravado\",\n      \"tax_code\": \"IVA_19\",\n      \"tax_rate\": 19\n    }\n  ],\n  \"total\": 11900\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/support-document-adjustment-notes"
          }
        }
      ]
    },
    {
      "name": "Seguimiento",
      "item": [
        {
          "name": "Estado por external_id",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": "{{base_url}}/api/fiscal-hub/status/{{external_id_demo}}?source_system={{source_system}}&document_type=invoice"
          }
        },
        {
          "name": "Reintentar procesamiento",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/api/fiscal-hub/retry/{{external_id_demo}}"
          }
        }
      ]
    }
  ]
}