{ "openapi": "3.1.0", "info": { "title": "CoreLink API", "version": "1.0.0-preview", "summary": "Design preview of the CoreLink public API v1. Not operational.", "description": "> **Design preview — not operational.** This document describes the planned public API of CoreLink. No server answers these requests yet, keys cannot be created, and the contract may still change. **Do not build integrations against it yet.**\n\nThe CoreLink API lets your servers read the data of one CoreLink company —third parties, products, invoices with their status before the Colombian tax authority (DIAN), received documents, receivables, the payment schedule and the company structure— and transmit invoices that are ready to issue.\n\n## Authentication\nEvery request carries an API key in `Authorization: Bearer `. A key belongs to **one company**:\n\n| Prefix | Company | Environment |\n|---|---|---|\n| `clk_test_` | Sandbox company | `test` — documents go to the tax authority's test set |\n| `clk_live_` | Production company | `live` — documents have fiscal effect |\n\nThe environment is not chosen per request: it is the environment of the key's company, and test and live data never mix. There is no company header; `GET /v1/me` tells you the company, environment and scopes of a key. Call it first.\n\n## Scopes\nEach operation states its required scope. A key never has more permissions than the person who created it.\n\n| Scope | Grants |\n|---|---|\n| `parties:read` | Read third parties (customers, suppliers and other parties). |\n| `products:read` | Read the product and service catalog. |\n| `invoices:read` | Read sales invoices, credit and debit notes, their tax authority status and their PDF/XML. |\n| `invoices:write` | Transmit existing invoices to the tax authority. |\n| `received:read` | Read electronic documents received from suppliers. |\n| `receivables:read` | Read accounts receivable (open customer balances). |\n| `payments:read` | Read the accounts payable payment schedule. |\n| `organization:read` | Read the organization, the company profile and its operating units. |\n\n## Errors\nErrors are RFC 7807 `application/problem+json` documents with a stable `code`. Program against `code`; `title` and `detail` may be reworded.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `validation_failed` | 400 | The request is not valid |\n| `idempotency_key_required` | 400 | Idempotency-Key header is required |\n| `unauthorized` | 401 | Missing or invalid API key |\n| `insufficient_scope` | 403 | The API key lacks the required scope |\n| `not_found` | 404 | Resource not found |\n| `document_not_available` | 404 | Electronic document not available |\n| `idempotency_conflict` | 409 | Idempotency-Key reused for a different request |\n| `invoice_not_issuable` | 422 | The invoice cannot be issued in its current status |\n| `invoice_validation_failed` | 422 | The invoice failed pre-transmission validation |\n| `rate_limited` | 429 | Too many requests |\n| `internal_error` | 500 | Unexpected error |\n| `service_unavailable` | 503 | Upstream service unavailable |\n\n## Idempotency\nEvery `POST` requires an `Idempotency-Key` header. Retrying with the same key and the same request returns the original response without repeating the operation; reusing the key for a different request returns `409 idempotency_conflict`.\n\n## Pagination and synchronization\nLists use cursor pagination: pass `limit` (1–100, default 50) and the `cursor` from the previous response's `next_cursor` until it is `null`. Responses look like `{ \"data\": [...], \"next_cursor\": \"...\" }`. Most lists accept `updated_since` to fetch only what changed since your last synchronization.\n\n## Rate limits\nRequests are limited per key. Over the limit the API answers `429 rate_limited` with a `Retry-After` header.\n\n## Versioning\nThe version is in the path (`/v1`). Additive changes (new fields, new operations, new enum values) do not change the version: ignore unknown fields.", "contact": { "name": "Piensa IT", "url": "https://piensait.com" } }, "servers": [ { "url": "https://corelink.piensait.com/api", "description": "Design preview — not operational. No server answers these requests yet." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Invoices", "description": "Sales invoices, credit notes and debit notes: read them with their tax authority status, CUFE and number, download their PDF and XML, and transmit invoices that are ready.", "x-module": "Sales and invoicing" }, { "name": "Receivables", "description": "Customer balances, document by document. Filter by customer to get the open portfolio of one party.", "x-module": "Accounts receivable" }, { "name": "Received documents", "description": "Electronic invoices and notes that suppliers issued to the company (reception inbox).", "x-module": "Purchasing" }, { "name": "Scheduled payments", "description": "Supplier documents ready to pay or scheduled for payment. Paying them is not part of v1.", "x-module": "Accounts payable" }, { "name": "Products", "description": "Products and services with their codes for electronic invoicing.", "x-module": "Inventory" }, { "name": "Treasury", "description": "**Not included in v1.** No operations are published for this module yet. In CoreLink this module manages bank accounts, payment vouchers to suppliers and bank reconciliation. Registering payments through the API is planned for a later phase, once payment calculation runs on the server (scope `payments:write`, reserved).", "x-module": "Treasury", "x-status": "not-included-in-v1" }, { "name": "Accounting and taxes", "description": "**Not included in v1.** No operations are published for this module yet. Accounting (chart of accounts, journal entries, closings) and tax configuration (rates, withholding rules, UVT) are out of scope for the public API for now.", "x-module": "Accounting and taxes", "x-status": "not-included-in-v1" }, { "name": "Payroll", "description": "**Not included in v1.** No operations are published for this module yet. Payroll data is personal and sensitive; it is explicitly out of scope for the public API.", "x-module": "Payroll", "x-status": "not-included-in-v1" }, { "name": "Parties", "description": "Customers, suppliers and other third parties of the company.", "x-module": "Third parties" }, { "name": "API key", "description": "Inspect the key in use: company, environment and scopes. Start every integration here.", "x-module": "Organization" }, { "name": "Company", "description": "The organization and the company the key acts for.", "x-module": "Organization" }, { "name": "Units", "description": "Operation centers and branches of the company. Documents reference them through `unit_id`.", "x-module": "Organization" } ], "x-tagGroups": [ { "name": "Sales and invoicing", "tags": [ "Invoices" ] }, { "name": "Accounts receivable", "tags": [ "Receivables" ] }, { "name": "Purchasing", "tags": [ "Received documents" ] }, { "name": "Accounts payable", "tags": [ "Scheduled payments" ] }, { "name": "Inventory", "tags": [ "Products" ] }, { "name": "Treasury", "tags": [ "Treasury" ] }, { "name": "Accounting and taxes", "tags": [ "Accounting and taxes" ] }, { "name": "Payroll", "tags": [ "Payroll" ] }, { "name": "Third parties", "tags": [ "Parties" ] }, { "name": "Organization", "tags": [ "API key", "Company", "Units" ] } ], "paths": { "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns sales invoices, credit notes and debit notes. Use `updated_since` to pick up tax authority status changes.\n\nRequired scope: `invoices:read`.", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "invoices:read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only documents in this status.", "schema": { "$ref": "#/components/schemas/InvoiceStatus" } }, { "name": "document_type", "in": "query", "required": false, "description": "Only documents of this type.", "schema": { "$ref": "#/components/schemas/InvoiceDocumentType" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Only documents of this customer.", "schema": { "type": "string" } }, { "name": "issued_from", "in": "query", "required": false, "description": "Issue date on or after (inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "issued_to", "in": "query", "required": false, "description": "Issue date on or before (inclusive).", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "A page of invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" }, "example": { "data": [ { "id": "inv_5KfT0a", "document_type": "01", "prefix": "FEV", "number": 1287, "document_number": "FEV1287", "cufe": "a1f3c9e2b7d84c0e9f6a2b5c8d1e4f7a0b3c6d9e2f5a8b1c4d7e0f3a6b9c2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a0b3c", "status": "validated", "issue_date": "2026-09-10", "due_date": "2026-10-10", "payment_condition": "credit", "currency": "COP", "customer_id": "pty_7Hc2Qm", "customer": { "name": "Comercializadora Andina S.A.S.", "document_type": "NIT", "document_number": "900123456", "check_digit": "7", "email": "facturacion@andina.example" }, "unit_id": "ou_bog_norte", "order_id": "ord_2Lr9Pe", "purchase_order_number": "OC-2026-0311", "lines": [ { "id": "ln_1", "product_id": "prd_Q81xZk", "code": "TUB-PVC-2-6M", "description": "Tubo PVC presión 2\" x 6 m", "quantity": 10, "unit_price": 84900, "discount_pct": 0, "subtotal": 849000 } ], "taxes": [ { "tax_type": "IVA", "nature": "tax", "name": "IVA 19 %", "rate_pct": 19, "base": 849000, "amount": 161310 } ], "subtotal": 849000, "tax_total": 161310, "withholding_total": 0, "total": 1010310, "notes": null, "reference_invoice_id": null, "voided_by_note_id": null, "tax_authority_messages": [], "customer_accepted_at": null, "created_at": "2026-09-10T14:02:31Z", "updated_at": "2026-09-10T14:03:58Z" } ], "next_cursor": null } } } }, "400": { "description": "`validation_failed` — The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "The request is not valid", "value": { "type": "https://corelink.piensait.com/developers/errors/#validation_failed", "title": "The request is not valid", "status": 400, "detail": "A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.", "instance": "/v1/invoices#req_01J9Z6Q4N8", "code": "validation_failed" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/invoices#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/invoices#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/invoices#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/invoices#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns one document with its status before the tax authority, CUFE and number.\n\nRequired scope: `invoices:read`.", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "invoices:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "inv_5KfT0a", "document_type": "01", "prefix": "FEV", "number": 1287, "document_number": "FEV1287", "cufe": "a1f3c9e2b7d84c0e9f6a2b5c8d1e4f7a0b3c6d9e2f5a8b1c4d7e0f3a6b9c2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a0b3c", "status": "validated", "issue_date": "2026-09-10", "due_date": "2026-10-10", "payment_condition": "credit", "currency": "COP", "customer_id": "pty_7Hc2Qm", "customer": { "name": "Comercializadora Andina S.A.S.", "document_type": "NIT", "document_number": "900123456", "check_digit": "7", "email": "facturacion@andina.example" }, "unit_id": "ou_bog_norte", "order_id": "ord_2Lr9Pe", "purchase_order_number": "OC-2026-0311", "lines": [ { "id": "ln_1", "product_id": "prd_Q81xZk", "code": "TUB-PVC-2-6M", "description": "Tubo PVC presión 2\" x 6 m", "quantity": 10, "unit_price": 84900, "discount_pct": 0, "subtotal": 849000 } ], "taxes": [ { "tax_type": "IVA", "nature": "tax", "name": "IVA 19 %", "rate_pct": 19, "base": 849000, "amount": 161310 } ], "subtotal": 849000, "tax_total": 161310, "withholding_total": 0, "total": 1010310, "notes": null, "reference_invoice_id": null, "voided_by_note_id": null, "tax_authority_messages": [], "customer_accepted_at": null, "created_at": "2026-09-10T14:02:31Z", "updated_at": "2026-09-10T14:03:58Z" } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/invoices/{id}#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/invoices/{id}#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/invoices/{id}#req_01J9Z6Q4N8", "code": "not_found" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/invoices/{id}#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/invoices/{id}#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/invoices/{id}/pdf": { "get": { "operationId": "downloadInvoicePdf", "summary": "Download the invoice PDF", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the graphic representation of a transmitted document.\n\nRequired scope: `invoices:read`.", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "invoices:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The PDF file.", "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/invoices/{id}/pdf#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/invoices/{id}/pdf#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found; `document_not_available` — Electronic document not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/invoices/{id}/pdf#req_01J9Z6Q4N8", "code": "not_found" } }, "document_not_available": { "summary": "Electronic document not available", "value": { "type": "https://corelink.piensait.com/developers/errors/#document_not_available", "title": "Electronic document not available", "status": 404, "detail": "The invoice exists but was never transmitted to the tax authority, so it has no PDF or XML representation yet.", "instance": "/v1/invoices/{id}/pdf#req_01J9Z6Q4N8", "code": "document_not_available" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/invoices/{id}/pdf#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/invoices/{id}/pdf#req_01J9Z6Q4N8", "code": "internal_error" } } } } } }, "503": { "description": "`service_unavailable` — Upstream service unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Upstream service unavailable", "value": { "type": "https://corelink.piensait.com/developers/errors/#service_unavailable", "title": "Upstream service unavailable", "status": 503, "detail": "The electronic invoicing provider or the tax authority could not be reached.", "instance": "/v1/invoices/{id}/pdf#req_01J9Z6Q4N8", "code": "service_unavailable" } } } } } } } } }, "/v1/invoices/{id}/xml": { "get": { "operationId": "downloadInvoiceXml", "summary": "Download the invoice XML", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the UBL XML of a transmitted document, as sent to the tax authority.\n\nRequired scope: `invoices:read`.", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "invoices:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The XML file.", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/invoices/{id}/xml#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/invoices/{id}/xml#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found; `document_not_available` — Electronic document not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/invoices/{id}/xml#req_01J9Z6Q4N8", "code": "not_found" } }, "document_not_available": { "summary": "Electronic document not available", "value": { "type": "https://corelink.piensait.com/developers/errors/#document_not_available", "title": "Electronic document not available", "status": 404, "detail": "The invoice exists but was never transmitted to the tax authority, so it has no PDF or XML representation yet.", "instance": "/v1/invoices/{id}/xml#req_01J9Z6Q4N8", "code": "document_not_available" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/invoices/{id}/xml#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/invoices/{id}/xml#req_01J9Z6Q4N8", "code": "internal_error" } } } } } }, "503": { "description": "`service_unavailable` — Upstream service unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Upstream service unavailable", "value": { "type": "https://corelink.piensait.com/developers/errors/#service_unavailable", "title": "Upstream service unavailable", "status": 503, "detail": "The electronic invoicing provider or the tax authority could not be reached.", "instance": "/v1/invoices/{id}/xml#req_01J9Z6Q4N8", "code": "service_unavailable" } } } } } } } } }, "/v1/invoices/{id}/issue": { "post": { "operationId": "issueInvoice", "summary": "Transmit an invoice", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nTransmits an existing invoice, credit note or debit note in status `issued` to the tax authority, in the environment of the key's company. It does not create or modify the document: drafts are finalized in CoreLink, where the business rules live.\n\nAnswers `202 Accepted` once queued. The tax authority decision arrives later: read the invoice (or list with `updated_since`) until its status is `validated`, `rejected` or `error`.\n\nThe request has no body. `Idempotency-Key` is required.\n\nRequired scope: `invoices:write`.", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "invoices:write", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Queued for transmission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueAccepted" }, "example": { "invoice_id": "inv_5KfT0a", "environment": "test", "status": "transmitting", "transaction_id": "txn_01J9Z7B3K2", "deduplicated": false, "correlation_id": "c0f1e2d3-4b5a-4c6d-8e7f-9a0b1c2d3e4f" } } } }, "400": { "description": "`idempotency_key_required` — Idempotency-Key header is required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_required": { "summary": "Idempotency-Key header is required", "value": { "type": "https://corelink.piensait.com/developers/errors/#idempotency_key_required", "title": "Idempotency-Key header is required", "status": 400, "detail": "A `POST` request arrived without an `Idempotency-Key` header.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "idempotency_key_required" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "not_found" } } } } } }, "409": { "description": "`idempotency_conflict` — Idempotency-Key reused for a different request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "Idempotency-Key reused for a different request", "value": { "type": "https://corelink.piensait.com/developers/errors/#idempotency_conflict", "title": "Idempotency-Key reused for a different request", "status": 409, "detail": "The `Idempotency-Key` was already used with a different request (another path or body). Replaying the same request with the same key returns the original response instead.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "idempotency_conflict" } } } } } }, "422": { "description": "`invoice_not_issuable` — The invoice cannot be issued in its current status; `invoice_validation_failed` — The invoice failed pre-transmission validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invoice_not_issuable": { "summary": "The invoice cannot be issued in its current status", "value": { "type": "https://corelink.piensait.com/developers/errors/#invoice_not_issuable", "title": "The invoice cannot be issued in its current status", "status": 422, "detail": "The invoice is not in status `issued` (ready to transmit): it is still a `draft`, already `transmitting` or `validated`, was `rejected` or ended in `error` (those require correction and a deliberate reissue in CoreLink), or was `voided` or `discarded`.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "invoice_not_issuable" } }, "invoice_validation_failed": { "summary": "The invoice failed pre-transmission validation", "value": { "type": "https://corelink.piensait.com/developers/errors/#invoice_validation_failed", "title": "The invoice failed pre-transmission validation", "status": 422, "detail": "Local checks before contacting the tax authority found missing or invalid data (for example a customer without identification document).", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "invoice_validation_failed" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "internal_error" } } } } } }, "503": { "description": "`service_unavailable` — Upstream service unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Upstream service unavailable", "value": { "type": "https://corelink.piensait.com/developers/errors/#service_unavailable", "title": "Upstream service unavailable", "status": 503, "detail": "The electronic invoicing provider or the tax authority could not be reached.", "instance": "/v1/invoices/{id}/issue#req_01J9Z6Q4N8", "code": "service_unavailable" } } } } } } } } }, "/v1/receivables": { "get": { "operationId": "listReceivables", "summary": "List receivables", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the company's receivables. Without `status` it returns all of them; use `status=open`, `partial` or `overdue` for the open portfolio.\n\nRequired scope: `receivables:read`.", "tags": [ "Receivables" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "receivables:read", "parameters": [ { "name": "party_id", "in": "query", "required": false, "description": "Only receivables of this customer.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Only receivables in these statuses (comma-separated).", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivableStatus" } }, "style": "form", "explode": false }, { "name": "due_before", "in": "query", "required": false, "description": "Due date on or before (inclusive).", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "A page of receivables.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableList" }, "example": { "data": [ { "id": "rcv_3Nq8Wd", "document_number": "FEV1287", "invoice_id": "inv_5KfT0a", "party_id": "pty_7Hc2Qm", "issue_date": "2026-09-10", "due_date": "2026-10-10", "amount": 1010310, "paid_amount": 400000, "balance": 610310, "status": "partial", "created_at": "2026-09-10T14:03:58Z", "updated_at": "2026-09-14T16:21:07Z" } ], "next_cursor": null } } } }, "400": { "description": "`validation_failed` — The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "The request is not valid", "value": { "type": "https://corelink.piensait.com/developers/errors/#validation_failed", "title": "The request is not valid", "status": 400, "detail": "A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.", "instance": "/v1/receivables#req_01J9Z6Q4N8", "code": "validation_failed" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/receivables#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/receivables#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/receivables#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/receivables#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/receivables/{id}": { "get": { "operationId": "getReceivable", "summary": "Get a receivable", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns one receivable with its balance.\n\nRequired scope: `receivables:read`.", "tags": [ "Receivables" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "receivables:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The receivable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receivable" }, "example": { "id": "rcv_3Nq8Wd", "document_number": "FEV1287", "invoice_id": "inv_5KfT0a", "party_id": "pty_7Hc2Qm", "issue_date": "2026-09-10", "due_date": "2026-10-10", "amount": 1010310, "paid_amount": 400000, "balance": 610310, "status": "partial", "created_at": "2026-09-10T14:03:58Z", "updated_at": "2026-09-14T16:21:07Z" } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/receivables/{id}#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/receivables/{id}#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/receivables/{id}#req_01J9Z6Q4N8", "code": "not_found" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/receivables/{id}#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/receivables/{id}#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/received-documents": { "get": { "operationId": "listReceivedDocuments", "summary": "List received documents", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns documents received from suppliers, read live from the electronic invoicing provider. Filter by issue date instead of `updated_since`: received documents carry no update timestamp. There is no single-document endpoint; filter by `cufe` to fetch one.\n\nRequired scope: `received:read`.", "tags": [ "Received documents" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "received:read", "parameters": [ { "name": "issued_from", "in": "query", "required": false, "description": "Issue date on or after (inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "issued_to", "in": "query", "required": false, "description": "Issue date on or before (inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "issuer_tax_id", "in": "query", "required": false, "description": "Supplier identity document number.", "schema": { "type": "string" } }, { "name": "number", "in": "query", "required": false, "description": "Document number.", "schema": { "type": "string" } }, { "name": "cufe", "in": "query", "required": false, "description": "Exact CUFE or CUDE.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of received documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedDocumentList" }, "example": { "data": [ { "id": "rd_01J9YQ2M7X", "cufe": "f7e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6", "document_type": "01", "prefix": "SETT", "number": "SETT4512", "issue_date": "2026-09-12", "received_at": "2026-09-12T18:40:03Z", "supplier": { "name": "Distribuciones del Valle S.A.S.", "document_type": "NIT", "document_number": "901987654", "check_digit": "3", "email": "facturas@delvalle.example" }, "currency": "COP", "subtotal": 2500000, "tax_total": 475000, "total": 2975000, "lines": [ { "code": "SRV-MANT", "description": "Mantenimiento preventivo", "quantity": 1, "unit_price": 2500000, "discount": 0, "taxes": [ { "code": "01", "rate": 19, "base": 2500000, "amount": 475000 } ], "total": 2975000 } ], "acknowledgement_state": "030", "events": [ { "event_code": "030", "issued_at": "2026-09-13T10:02:44Z" } ] } ], "next_cursor": null } } } }, "400": { "description": "`validation_failed` — The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "The request is not valid", "value": { "type": "https://corelink.piensait.com/developers/errors/#validation_failed", "title": "The request is not valid", "status": 400, "detail": "A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.", "instance": "/v1/received-documents#req_01J9Z6Q4N8", "code": "validation_failed" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/received-documents#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/received-documents#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/received-documents#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/received-documents#req_01J9Z6Q4N8", "code": "internal_error" } } } } } }, "503": { "description": "`service_unavailable` — Upstream service unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Upstream service unavailable", "value": { "type": "https://corelink.piensait.com/developers/errors/#service_unavailable", "title": "Upstream service unavailable", "status": 503, "detail": "The electronic invoicing provider or the tax authority could not be reached.", "instance": "/v1/received-documents#req_01J9Z6Q4N8", "code": "service_unavailable" } } } } } } } } }, "/v1/scheduled-payments": { "get": { "operationId": "listScheduledPayments", "summary": "List scheduled payments", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the payment schedule: accounted documents and documents scheduled for a date. Documents leave this list once paid.\n\nRequired scope: `payments:read`.", "tags": [ "Scheduled payments" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "payments:read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only documents in this status.", "schema": { "$ref": "#/components/schemas/ScheduledPaymentStatus" } }, { "name": "party_id", "in": "query", "required": false, "description": "Only documents of this supplier.", "schema": { "type": "string" } }, { "name": "scheduled_from", "in": "query", "required": false, "description": "Scheduled date on or after (inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "scheduled_to", "in": "query", "required": false, "description": "Scheduled date on or before (inclusive).", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "A page of scheduled payments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledPaymentList" }, "example": { "data": [ { "id": "pay_8Vt4Lc", "number": "SETT4512", "filing_number": "RAD-000187", "party_id": "pty_Dv91Xa", "issue_date": "2026-09-12", "due_date": "2026-10-12", "scheduled_for": "2026-10-10", "status": "scheduled", "currency": "COP", "total": 2975000, "withholding_total": 87500, "net_payable": 2887500, "paid_amount": 0, "balance": 2887500, "cufe": "f7e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6", "unit_id": "ou_med", "created_at": "2026-09-12T18:45:10Z", "updated_at": "2026-09-15T13:30:00Z" } ], "next_cursor": null } } } }, "400": { "description": "`validation_failed` — The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "The request is not valid", "value": { "type": "https://corelink.piensait.com/developers/errors/#validation_failed", "title": "The request is not valid", "status": 400, "detail": "A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.", "instance": "/v1/scheduled-payments#req_01J9Z6Q4N8", "code": "validation_failed" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/scheduled-payments#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/scheduled-payments#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/scheduled-payments#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/scheduled-payments#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/scheduled-payments/{id}": { "get": { "operationId": "getScheduledPayment", "summary": "Get a scheduled payment", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns one document of the payment schedule. Answers `not_found` if the document exists but is not in the schedule (for example, already paid).\n\nRequired scope: `payments:read`.", "tags": [ "Scheduled payments" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "payments:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The scheduled payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledPayment" }, "example": { "id": "pay_8Vt4Lc", "number": "SETT4512", "filing_number": "RAD-000187", "party_id": "pty_Dv91Xa", "issue_date": "2026-09-12", "due_date": "2026-10-12", "scheduled_for": "2026-10-10", "status": "scheduled", "currency": "COP", "total": 2975000, "withholding_total": 87500, "net_payable": 2887500, "paid_amount": 0, "balance": 2887500, "cufe": "f7e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6", "unit_id": "ou_med", "created_at": "2026-09-12T18:45:10Z", "updated_at": "2026-09-15T13:30:00Z" } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/scheduled-payments/{id}#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/scheduled-payments/{id}#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/scheduled-payments/{id}#req_01J9Z6Q4N8", "code": "not_found" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/scheduled-payments/{id}#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/scheduled-payments/{id}#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/products": { "get": { "operationId": "listProducts", "summary": "List products", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the company's product and service catalog.\n\nRequired scope: `products:read`.", "tags": [ "Products" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "products:read", "parameters": [ { "name": "sku", "in": "query", "required": false, "description": "Exact SKU.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Only products of this category.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Filter by active flag.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "A page of products.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" }, "example": { "data": [ { "id": "prd_Q81xZk", "sku": "TUB-PVC-2-6M", "name": "Tubo PVC presión 2\" x 6 m", "category_id": "cat_tuberia", "item_type": "tube", "unit_of_measure": "unit", "units_per_box": null, "base_price": 84900, "standard_code": "40142008", "unit_measure_code": "94", "gtin": "7701234567890", "brand": "Genérica", "model": "RDE 21", "is_active": true, "created_at": "2026-02-10T13:20:00Z", "updated_at": "2026-09-01T09:45:12Z" } ], "next_cursor": null } } } }, "400": { "description": "`validation_failed` — The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "The request is not valid", "value": { "type": "https://corelink.piensait.com/developers/errors/#validation_failed", "title": "The request is not valid", "status": 400, "detail": "A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.", "instance": "/v1/products#req_01J9Z6Q4N8", "code": "validation_failed" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/products#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/products#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/products#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/products#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get a product", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns one product or service.\n\nRequired scope: `products:read`.", "tags": [ "Products" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "products:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "prd_Q81xZk", "sku": "TUB-PVC-2-6M", "name": "Tubo PVC presión 2\" x 6 m", "category_id": "cat_tuberia", "item_type": "tube", "unit_of_measure": "unit", "units_per_box": null, "base_price": 84900, "standard_code": "40142008", "unit_measure_code": "94", "gtin": "7701234567890", "brand": "Genérica", "model": "RDE 21", "is_active": true, "created_at": "2026-02-10T13:20:00Z", "updated_at": "2026-09-01T09:45:12Z" } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/products/{id}#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/products/{id}#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/products/{id}#req_01J9Z6Q4N8", "code": "not_found" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/products/{id}#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/products/{id}#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/parties": { "get": { "operationId": "listParties", "summary": "List parties", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the company's third parties, most recently updated first. Filter by role with `kind` and synchronize with `updated_since`.\n\nRequired scope: `parties:read`.", "tags": [ "Parties" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "parties:read", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Only parties with this role.", "schema": { "$ref": "#/components/schemas/PartyKind" } }, { "name": "document_number", "in": "query", "required": false, "description": "Exact identity document number, without check digit.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Filter by active flag.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "A page of parties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyList" }, "example": { "data": [ { "id": "pty_7Hc2Qm", "code": "CLI-0042", "name": "Comercializadora Andina S.A.S.", "trade_name": "Andina Market", "kinds": [ "customer", "supplier" ], "fiscal": { "document_type": "NIT", "document_number": "900123456", "check_digit": "7", "person_type": "juridica", "tax_regime": "responsable_iva", "fiscal_responsibilities": [ "O-13" ], "city_code": "11001", "country_code": "CO", "address": "Carrera 7 #71-21, Bogotá" }, "email": "facturacion@andina.example", "phone": "+57 601 555 0142", "payment_terms_days": 30, "branches": [ { "id": "br_1", "code": "001", "name": "Sede principal", "is_main": true, "address": "Carrera 7 #71-21", "city_code": "11001", "phone": "+57 601 555 0142", "is_active": true } ], "contacts": [ { "id": "ct_1", "name": "Laura Gómez", "roles": [ "billing", "collections" ], "branch_id": null, "position": "Contadora", "email": "laura.gomez@andina.example", "phone": null, "mobile": "+57 310 555 0199", "is_primary": true, "is_active": true } ], "is_active": true, "created_at": "2026-03-02T15:04:11Z", "updated_at": "2026-08-28T20:13:45Z" } ], "next_cursor": "eyJ1IjoiMjAyNi0wOC0yOFQyMDoxMzo0NVoifQ" } } } }, "400": { "description": "`validation_failed` — The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "The request is not valid", "value": { "type": "https://corelink.piensait.com/developers/errors/#validation_failed", "title": "The request is not valid", "status": 400, "detail": "A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.", "instance": "/v1/parties#req_01J9Z6Q4N8", "code": "validation_failed" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/parties#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/parties#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/parties#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/parties#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/parties/{id}": { "get": { "operationId": "getParty", "summary": "Get a party", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns one third party with its locations and contacts.\n\nRequired scope: `parties:read`.", "tags": [ "Parties" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "parties:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The party.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" }, "example": { "id": "pty_7Hc2Qm", "code": "CLI-0042", "name": "Comercializadora Andina S.A.S.", "trade_name": "Andina Market", "kinds": [ "customer", "supplier" ], "fiscal": { "document_type": "NIT", "document_number": "900123456", "check_digit": "7", "person_type": "juridica", "tax_regime": "responsable_iva", "fiscal_responsibilities": [ "O-13" ], "city_code": "11001", "country_code": "CO", "address": "Carrera 7 #71-21, Bogotá" }, "email": "facturacion@andina.example", "phone": "+57 601 555 0142", "payment_terms_days": 30, "branches": [ { "id": "br_1", "code": "001", "name": "Sede principal", "is_main": true, "address": "Carrera 7 #71-21", "city_code": "11001", "phone": "+57 601 555 0142", "is_active": true } ], "contacts": [ { "id": "ct_1", "name": "Laura Gómez", "roles": [ "billing", "collections" ], "branch_id": null, "position": "Contadora", "email": "laura.gomez@andina.example", "phone": null, "mobile": "+57 310 555 0199", "is_primary": true, "is_active": true } ], "is_active": true, "created_at": "2026-03-02T15:04:11Z", "updated_at": "2026-08-28T20:13:45Z" } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/parties/{id}#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/parties/{id}#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/parties/{id}#req_01J9Z6Q4N8", "code": "not_found" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/parties/{id}#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/parties/{id}#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Get the current API key", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the company that owns the key, its environment (`test` or `live`) and the granted scopes. Use it to check a key before synchronizing.\n\nRequired scope: none (any valid API key).", "tags": [ "API key" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "responses": { "200": { "description": "The current key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "key": { "id": "key_2Wm7Rt", "prefix": "clk_test_4f9a", "name": "ERP sync — staging", "created_at": "2026-09-01T12:00:00Z" }, "company": { "id": "cmp_0c1d2e3f", "name": "Ferretería Horizonte S.A.S.", "trade_name": "Horizonte", "tax_id": "900555123", "check_digit": "4" }, "environment": "test", "scopes": [ "parties:read", "products:read", "invoices:read", "invoices:write" ] } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/me#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/me#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/me#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/organization": { "get": { "operationId": "getOrganization", "summary": "Get the organization", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the organization the key's company belongs to. It never lists the other companies of the organization: a key only reads its own company.\n\nRequired scope: `organization:read`.", "tags": [ "Company" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "organization:read", "responses": { "200": { "description": "The organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" }, "example": { "id": "org_9a8b7c6d", "name": "Grupo Horizonte", "environment": "test", "is_active": true } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/organization#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/organization#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/organization#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/organization#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/company": { "get": { "operationId": "getCompany", "summary": "Get the company", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the profile of the company that owns the key, with its tax identification.\n\nRequired scope: `organization:read`.", "tags": [ "Company" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "organization:read", "responses": { "200": { "description": "The company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" }, "example": { "id": "cmp_0c1d2e3f", "organization_id": "org_9a8b7c6d", "name": "Ferretería Horizonte S.A.S.", "trade_name": "Horizonte", "fiscal": { "document_type": "NIT", "document_number": "900555123", "check_digit": "4", "person_type": "juridica", "tax_regime": "responsable_iva", "fiscal_responsibilities": [ "O-13", "O-15" ], "city_code": "11001", "country_code": "CO", "address": "Calle 100 #15-20, Bogotá" }, "email": "contabilidad@horizonte.example", "phone": "+57 601 234 5678", "web": "https://horizonte.example", "economic_activity": "4752", "environment": "test", "is_active": true } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/company#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/company#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/company#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/company#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/units": { "get": { "operationId": "listUnits", "summary": "List units", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns the company's operation centers and branches. A company without units returns an empty list.\n\nRequired scope: `organization:read`.", "tags": [ "Units" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "organization:read", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Only units of this type.", "schema": { "$ref": "#/components/schemas/OrgUnitType" } }, { "name": "is_active", "in": "query", "required": false, "description": "Filter by active flag.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "A page of units.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnitList" }, "example": { "data": [ { "id": "ou_bog_norte", "type": "branch", "parent_id": "ou_reg_bog", "code": "BOG-NTE", "name": "Bogotá Norte", "address": "Calle 140 #9-45", "city_code": "11001", "phone": null, "is_active": true, "created_at": "2026-01-15T12:00:00Z", "updated_at": null } ], "next_cursor": null } } } }, "400": { "description": "`validation_failed` — The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "The request is not valid", "value": { "type": "https://corelink.piensait.com/developers/errors/#validation_failed", "title": "The request is not valid", "status": 400, "detail": "A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.", "instance": "/v1/units#req_01J9Z6Q4N8", "code": "validation_failed" } } } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/units#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/units#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/units#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/units#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } }, "/v1/units/{id}": { "get": { "operationId": "getUnit", "summary": "Get a unit", "description": "> **Design preview — not operational.** This endpoint is planned; no server answers it yet.\n\nReturns one operation center or branch.\n\nRequired scope: `organization:read`.", "tags": [ "Units" ], "security": [ { "bearerAuth": [] } ], "x-status": "planned", "x-required-scope": "organization:read", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "The unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unit" }, "example": { "id": "ou_bog_norte", "type": "branch", "parent_id": "ou_reg_bog", "code": "BOG-NTE", "name": "Bogotá Norte", "address": "Calle 140 #9-45", "city_code": "11001", "phone": null, "is_active": true, "created_at": "2026-01-15T12:00:00Z", "updated_at": null } } } }, "401": { "description": "`unauthorized` — Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "type": "https://corelink.piensait.com/developers/errors/#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.", "instance": "/v1/units/{id}#req_01J9Z6Q4N8", "code": "unauthorized" } } } } } }, "403": { "description": "`insufficient_scope` — The API key lacks the required scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "The API key lacks the required scope", "value": { "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope", "title": "The API key lacks the required scope", "status": 403, "detail": "The key is valid but was not granted the scope that the operation requires.", "instance": "/v1/units/{id}#req_01J9Z6Q4N8", "code": "insufficient_scope" } } } } } }, "404": { "description": "`not_found` — Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "https://corelink.piensait.com/developers/errors/#not_found", "title": "Resource not found", "status": 404, "detail": "No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.", "instance": "/v1/units/{id}#req_01J9Z6Q4N8", "code": "not_found" } } } } } }, "429": { "description": "`rate_limited` — Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://corelink.piensait.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "detail": "The key exceeded its request quota for the current window.", "instance": "/v1/units/{id}#req_01J9Z6Q4N8", "code": "rate_limited" } } } } } }, "500": { "description": "`internal_error` — Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Unexpected error", "value": { "type": "https://corelink.piensait.com/developers/errors/#internal_error", "title": "Unexpected error", "status": 500, "detail": "Something failed on CoreLink's side. It is logged with the `instance` identifier.", "instance": "/v1/units/{id}#req_01J9Z6Q4N8", "code": "internal_error" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "clk_test_… | clk_live_…", "description": "API key of one company, sent as `Authorization: Bearer `. `clk_test_` keys only exist for sandbox companies and `clk_live_` keys only for production companies. The company, environment and scopes come from the key; there is no company header." } }, "schemas": { "Problem": { "type": "object", "description": "RFC 7807 problem details. Program against `code`, which is stable; `title` and `detail` are for humans and may be reworded.", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "description": "URI that identifies the problem type. Resolves to its entry in the error guide.", "format": "uri" }, "title": { "type": "string", "description": "Short, human-readable summary of the problem type." }, "status": { "type": "integer", "description": "HTTP status code of this response." }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "description": "Identifier of this occurrence. Quote it when contacting support." }, "code": { "type": "string", "description": "Stable machine-readable error code from the error catalog.", "enum": [ "validation_failed", "idempotency_key_required", "unauthorized", "insufficient_scope", "not_found", "document_not_available", "idempotency_conflict", "invoice_not_issuable", "invoice_validation_failed", "rate_limited", "internal_error", "service_unavailable" ] }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Parameter or field that failed." }, "message": { "type": "string", "description": "What is wrong with it." } } }, "description": "Field-level problems. Present on `validation_failed` and `invoice_validation_failed`." } } }, "Environment": { "type": "string", "enum": [ "test", "live" ], "description": "Environment of the company that owns the key: `test` (sandbox company, tax authority test set) or `live` (production). It is not chosen per request." }, "FiscalProfile": { "type": "object", "description": "Tax identification as required by the Colombian tax authority (DIAN).", "required": [ "document_type", "document_number", "person_type", "tax_regime", "fiscal_responsibilities" ], "properties": { "document_type": { "type": "string", "enum": [ "NIT", "CC", "CE", "TI", "PP", "PEP", "NIT_EXT" ], "description": "Identity document type." }, "document_number": { "type": "string", "description": "Identity document number, without check digit." }, "check_digit": { "type": "string", "description": "NIT check digit (DV). Only for `NIT`." }, "person_type": { "type": "string", "enum": [ "natural", "juridica" ], "description": "`natural` person or `juridica` (legal entity)." }, "tax_regime": { "type": "string", "enum": [ "responsable_iva", "no_responsable_iva", "gran_contribuyente", "regimen_simple" ], "description": "VAT regime." }, "fiscal_responsibilities": { "type": "array", "items": { "type": "string", "enum": [ "O-13", "O-15", "O-23", "O-47", "R-99-PN" ] }, "description": "DIAN fiscal responsibility codes." }, "city_code": { "type": "string", "description": "DANE municipality code." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "address": { "type": "string", "description": "Tax address." } } }, "InvoiceStatus": { "type": "string", "enum": [ "draft", "issued", "transmitting", "validated", "rejected", "error", "accepted", "claimed", "voided", "discarded" ], "description": "Status of the document, including its status before the tax authority (DIAN):\n\n| Value | Meaning |\n|---|---|\n| `draft` | Draft, editable in CoreLink. Not sent. |\n| `issued` | Finalized and ready to transmit. |\n| `transmitting` | Sent to the tax authority; waiting for its answer. |\n| `validated` | Validated by the tax authority; has CUFE and final number. |\n| `rejected` | Rejected by the tax authority. See `tax_authority_messages`. |\n| `error` | Transmission failed before reaching a decision. |\n| `accepted` | Validated and later accepted by the customer (RADIAN). |\n| `claimed` | Validated and later claimed by the customer (RADIAN). |\n| `voided` | Voided by a credit note (`voided_by_note_id`). |\n| `discarded` | Draft discarded in CoreLink; never sent. |" }, "InvoiceDocumentType": { "type": "string", "enum": [ "01", "91", "92" ], "description": "DIAN document type code: `01` sales invoice, `91` credit note, `92` debit note." }, "InvoiceParty": { "type": "object", "description": "The customer as it was stamped on the document when transmitted. Absent on documents that were never transmitted or that predate stamping; read the party instead.", "required": [ "name", "document_type", "document_number" ], "properties": { "name": { "type": "string", "description": "Legal name." }, "trade_name": { "type": "string", "description": "Trade name." }, "document_type": { "type": "string", "description": "Identity document type." }, "document_number": { "type": "string", "description": "Identity document number." }, "check_digit": { "type": "string", "description": "NIT check digit." }, "address": { "type": "string", "description": "Address." }, "city_code": { "type": "string", "description": "DANE municipality code." }, "email": { "type": "string", "description": "Email address the document was sent to." } } }, "InvoiceLine": { "type": "object", "required": [ "id", "code", "description", "quantity", "unit_price", "discount_pct", "subtotal" ], "properties": { "id": { "type": "string", "description": "Line id." }, "product_id": { "type": [ "string", "null" ], "description": "Catalog product, if the line comes from one." }, "code": { "type": "string", "description": "Item code." }, "description": { "type": "string", "description": "Item description." }, "quantity": { "type": "number", "description": "Quantity." }, "unit_price": { "type": "number", "description": "Unit price before discount. Decimal amount in the document currency." }, "discount_pct": { "type": "number", "description": "Discount percentage." }, "subtotal": { "type": "number", "description": "Line subtotal before taxes. Decimal amount in the document currency." } } }, "InvoiceTax": { "type": "object", "required": [ "tax_type", "nature", "name", "rate_pct", "base", "amount" ], "properties": { "tax_type": { "type": "string", "enum": [ "IVA", "INC", "ICA", "RETEFUENTE", "RETEIVA", "RETEICA" ], "description": "Tax type." }, "nature": { "type": "string", "enum": [ "tax", "withholding" ], "description": "`tax` adds to the total; `withholding` is deducted from the payment." }, "name": { "type": "string", "description": "Display name." }, "rate_pct": { "type": "number", "description": "Rate, in percent." }, "base": { "type": "number", "description": "Taxable base. Decimal amount in the document currency." }, "amount": { "type": "number", "description": "Tax amount. Decimal amount in the document currency." } } }, "Invoice": { "type": "object", "description": "A sales invoice, credit note or debit note.", "required": [ "id", "document_type", "prefix", "number", "status", "issue_date", "payment_condition", "currency", "customer_id", "lines", "taxes", "subtotal", "tax_total", "withholding_total", "total", "created_at" ], "properties": { "id": { "type": "string", "description": "Invoice id." }, "document_type": { "$ref": "#/components/schemas/InvoiceDocumentType" }, "prefix": { "type": "string", "description": "Authorized numbering prefix." }, "number": { "type": "integer", "description": "Internal consecutive number within CoreLink." }, "document_number": { "type": [ "string", "null" ], "description": "Number assigned for the tax authority (for example `FEV1287`). `null` until transmitted." }, "cufe": { "type": [ "string", "null" ], "description": "Unique electronic invoice code (CUFE; CUDE for notes). `null` until validated." }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "issue_date": { "type": "string", "format": "date", "description": "Issue date." }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date for credit sales." }, "payment_condition": { "type": "string", "enum": [ "cash", "credit" ], "description": "Payment condition." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "customer_id": { "type": "string", "description": "Customer party id." }, "customer": { "$ref": "#/components/schemas/InvoiceParty" }, "unit_id": { "type": [ "string", "null" ], "description": "Operating unit (operation center or branch) that invoices." }, "order_id": { "type": [ "string", "null" ], "description": "Sales order the invoice came from." }, "purchase_order_number": { "type": [ "string", "null" ], "description": "The customer's own purchase order number." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "taxes": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceTax" } }, "subtotal": { "type": "number", "description": "Subtotal before taxes. Decimal amount in the document currency." }, "tax_total": { "type": "number", "description": "Sum of taxes. Decimal amount in the document currency." }, "withholding_total": { "type": "number", "description": "Sum of withholdings. Decimal amount in the document currency." }, "total": { "type": "number", "description": "Document total. Decimal amount in the document currency." }, "notes": { "type": [ "string", "null" ], "description": "Notes printed on the document." }, "reference_invoice_id": { "type": [ "string", "null" ], "description": "For credit and debit notes: the invoice being corrected." }, "voided_by_note_id": { "type": [ "string", "null" ], "description": "Credit note that voided this invoice." }, "tax_authority_messages": { "type": "array", "items": { "type": "string" }, "description": "Messages returned by the tax authority, including warnings on validated documents." }, "customer_accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the customer accepted the document through RADIAN." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation instant." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update instant." } } }, "InvoiceList": { "type": "object", "description": "A page of invoices.", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when this is the last page." } } }, "IssueAccepted": { "type": "object", "description": "The invoice was queued for transmission. This is not a tax authority decision: poll the invoice until its status is terminal.", "required": [ "invoice_id", "environment", "status", "deduplicated" ], "properties": { "invoice_id": { "type": "string", "description": "Invoice id." }, "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "type": "string", "enum": [ "transmitting" ], "description": "Always `transmitting` on acceptance." }, "transaction_id": { "type": [ "string", "null" ], "description": "Transaction id at the electronic invoicing provider." }, "deduplicated": { "type": "boolean", "description": "`true` when the provider recognized a retry and returned the original transmission instead of sending again. It is a success." }, "correlation_id": { "type": [ "string", "null" ], "description": "Correlation id for support." } } }, "ReceivableStatus": { "type": "string", "enum": [ "open", "partial", "paid", "overdue", "written_off", "annulled" ], "description": "`open` not yet paid · `partial` partially paid · `paid` fully paid · `overdue` past due with balance · `written_off` written off as uncollectible · `annulled` cancelled by a full credit note (never collected)." }, "Receivable": { "type": "object", "description": "An amount a customer owes, usually originated by a sales invoice.", "required": [ "id", "document_number", "party_id", "issue_date", "due_date", "amount", "paid_amount", "balance", "status", "created_at" ], "properties": { "id": { "type": "string", "description": "Receivable id." }, "document_number": { "type": "string", "description": "Number of the originating document." }, "invoice_id": { "type": [ "string", "null" ], "description": "Originating invoice, when it came from Sales." }, "party_id": { "type": "string", "description": "Customer party id." }, "issue_date": { "type": "string", "format": "date", "description": "Issue date." }, "due_date": { "type": "string", "format": "date", "description": "Due date." }, "amount": { "type": "number", "description": "Original amount. Decimal amount in the document currency." }, "paid_amount": { "type": "number", "description": "Amount collected so far. Decimal amount in the document currency." }, "balance": { "type": "number", "description": "Outstanding balance. Decimal amount in the document currency." }, "status": { "$ref": "#/components/schemas/ReceivableStatus" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation instant." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update instant." } } }, "ReceivableList": { "type": "object", "description": "A page of receivables.", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Receivable" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when this is the last page." } } }, "RadianEventCode": { "type": "string", "enum": [ "030", "031", "032", "033", "034" ], "description": "RADIAN event: `030` acknowledgement of receipt · `031` claim · `032` receipt of goods or services · `033` express acceptance · `034` tacit acceptance." }, "ReceivedDocumentLine": { "type": "object", "required": [ "code", "description", "quantity", "unit_price", "discount", "taxes", "total" ], "properties": { "code": { "type": "string", "description": "Supplier item code." }, "description": { "type": "string", "description": "Item description." }, "quantity": { "type": "number", "description": "Quantity." }, "unit_price": { "type": "number", "description": "Unit price. Decimal amount in the document currency." }, "discount": { "type": "number", "description": "Discount amount. Decimal amount in the document currency." }, "taxes": { "type": "array", "items": { "type": "object", "required": [ "code", "rate", "base", "amount" ], "properties": { "code": { "type": "string", "description": "DIAN tax code." }, "rate": { "type": "number", "description": "Rate, in percent." }, "base": { "type": "number", "description": "Taxable base. Decimal amount in the document currency." }, "amount": { "type": "number", "description": "Tax amount. Decimal amount in the document currency." } } } }, "total": { "type": "number", "description": "Line total. Decimal amount in the document currency." } } }, "ReceivedDocument": { "type": "object", "description": "An electronic document a supplier issued to the company, as reported by the electronic invoicing provider.", "required": [ "id", "cufe", "document_type", "prefix", "number", "issue_date", "received_at", "supplier", "currency", "subtotal", "tax_total", "total", "lines", "events" ], "properties": { "id": { "type": "string", "description": "Document id at the electronic invoicing provider." }, "cufe": { "type": "string", "description": "CUFE (or CUDE) of the document." }, "document_type": { "type": "string", "enum": [ "01", "91", "92", "05" ], "description": "DIAN document type code: `01` invoice, `91` credit note, `92` debit note, `05` support document." }, "prefix": { "type": "string", "description": "Supplier numbering prefix." }, "number": { "type": "string", "description": "Document number as issued by the supplier." }, "issue_date": { "type": "string", "format": "date", "description": "Issue date." }, "received_at": { "type": "string", "format": "date-time", "description": "When the document was received." }, "supplier": { "type": "object", "required": [ "name", "document_type", "document_number" ], "properties": { "name": { "type": "string", "description": "Supplier legal name." }, "document_type": { "type": "string", "description": "Identity document type." }, "document_number": { "type": "string", "description": "Identity document number." }, "check_digit": { "type": "string", "description": "NIT check digit." }, "email": { "type": "string", "description": "Supplier email." } } }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "subtotal": { "type": "number", "description": "Subtotal before taxes. Decimal amount in the document currency." }, "tax_total": { "type": "number", "description": "Sum of taxes. Decimal amount in the document currency." }, "total": { "type": "number", "description": "Document total. Decimal amount in the document currency." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedDocumentLine" } }, "acknowledgement_state": { "oneOf": [ { "$ref": "#/components/schemas/RadianEventCode" }, { "type": "null" } ], "description": "Latest RADIAN event recorded before the tax authority, whoever sent it. `null` if none. Prevails over `events` when they differ." }, "events": { "type": "array", "items": { "type": "object", "required": [ "event_code", "issued_at" ], "properties": { "event_code": { "$ref": "#/components/schemas/RadianEventCode" }, "issued_at": { "type": "string", "format": "date-time", "description": "When CoreLink sent the event." } } }, "description": "RADIAN events sent from CoreLink." } } }, "ReceivedDocumentList": { "type": "object", "description": "A page of received documents.", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedDocument" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when this is the last page." } } }, "ScheduledPaymentStatus": { "type": "string", "enum": [ "accounted", "scheduled" ], "description": "`accounted` recorded and ready to pay, without a date · `scheduled` scheduled for `scheduled_for`." }, "ScheduledPayment": { "type": "object", "description": "A payable document in the payment schedule.", "required": [ "id", "number", "party_id", "issue_date", "due_date", "status", "currency", "total", "withholding_total", "net_payable", "paid_amount", "balance", "created_at" ], "properties": { "id": { "type": "string", "description": "Payable document id." }, "number": { "type": "string", "description": "Supplier document number." }, "filing_number": { "type": [ "string", "null" ], "description": "Internal filing number assigned on reception." }, "party_id": { "type": "string", "description": "Supplier party id." }, "issue_date": { "type": "string", "format": "date", "description": "Issue date." }, "due_date": { "type": "string", "format": "date", "description": "Due date." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date", "description": "Planned payment date. `null` while `accounted`." }, "status": { "$ref": "#/components/schemas/ScheduledPaymentStatus" }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "total": { "type": "number", "description": "Document total. Decimal amount in the document currency." }, "withholding_total": { "type": "number", "description": "Withholdings applied to the supplier. Decimal amount in the document currency." }, "net_payable": { "type": "number", "description": "Amount to pay after withholdings. Decimal amount in the document currency." }, "paid_amount": { "type": "number", "description": "Amount paid so far. Decimal amount in the document currency." }, "balance": { "type": "number", "description": "Outstanding balance. Decimal amount in the document currency." }, "cufe": { "type": [ "string", "null" ], "description": "CUFE of the supplier's electronic document, when it has one." }, "unit_id": { "type": [ "string", "null" ], "description": "Operating unit the document is charged to." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation instant." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update instant." } } }, "ScheduledPaymentList": { "type": "object", "description": "A page of scheduled payments.", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledPayment" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when this is the last page." } } }, "Product": { "type": "object", "description": "A product or service of the catalog.", "required": [ "id", "sku", "name", "category_id", "unit_of_measure", "base_price", "is_active" ], "properties": { "id": { "type": "string", "description": "Product id." }, "sku": { "type": "string", "description": "Stock keeping unit, unique in the company." }, "name": { "type": "string", "description": "Product name." }, "category_id": { "type": "string", "description": "Category id." }, "item_type": { "type": "string", "enum": [ "product", "tube", "coupling", "fitting", "accessory", "service", "other" ], "description": "Item classification." }, "unit_of_measure": { "type": "string", "enum": [ "unit", "box", "package", "dozen", "kg", "liter" ], "description": "Unit of measure." }, "units_per_box": { "type": [ "integer", "null" ], "description": "Units per box, when sold by the box." }, "base_price": { "type": "number", "description": "List price before price lists and discounts." }, "standard_code": { "type": "string", "description": "UNSPSC standard code used in electronic documents." }, "unit_measure_code": { "type": "string", "description": "DIAN unit of measure code, when it differs from the one derived from `unit_of_measure`." }, "gtin": { "type": "string", "description": "GTIN of the package (EAN-13, UPC or GTIN-14)." }, "brand": { "type": "string", "description": "Brand." }, "model": { "type": "string", "description": "Model." }, "is_active": { "type": "boolean", "description": "Whether the product is active." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Creation instant. `null` for records older than audit stamps." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update instant." } } }, "ProductList": { "type": "object", "description": "A page of products.", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when this is the last page." } } }, "PartyKind": { "type": "string", "enum": [ "supplier", "establishment", "customer", "employee", "other" ], "description": "Role of the party. A party can hold several roles at once." }, "PartyBranch": { "type": "object", "description": "A location of the party (warehouse, store, office).", "required": [ "id", "name", "is_active" ], "properties": { "id": { "type": "string", "description": "Location id." }, "code": { "type": "string", "description": "Establishment code in the tax registry (RUT), when it has one." }, "name": { "type": "string", "description": "Location name." }, "is_main": { "type": "boolean", "description": "Whether this is the party's main location." }, "address": { "type": "string", "description": "Address." }, "city_code": { "type": "string", "description": "DANE municipality code." }, "phone": { "type": "string", "description": "Phone number." }, "is_active": { "type": "boolean", "description": "Whether the location is active." } } }, "PartyContact": { "type": "object", "description": "A person to talk to at the party.", "required": [ "id", "name", "roles", "is_active" ], "properties": { "id": { "type": "string", "description": "Contact id." }, "name": { "type": "string", "description": "Full name." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "billing", "commercial", "collections", "approver", "other" ] }, "description": "Roles of the contact. `billing` receives electronic invoices." }, "branch_id": { "type": [ "string", "null" ], "description": "Location the contact belongs to; `null` means the whole party." }, "position": { "type": "string", "description": "Job title." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email address." }, "phone": { "type": [ "string", "null" ], "description": "Landline." }, "mobile": { "type": [ "string", "null" ], "description": "Mobile phone." }, "is_primary": { "type": "boolean", "description": "Whether this is the primary contact." }, "is_active": { "type": "boolean", "description": "Whether the contact is active." } } }, "Party": { "type": "object", "description": "A third party: customer, supplier, employee or other.", "required": [ "id", "code", "name", "kinds", "fiscal", "payment_terms_days", "is_active", "created_at" ], "properties": { "id": { "type": "string", "description": "Party id." }, "code": { "type": "string", "description": "Internal code." }, "name": { "type": "string", "description": "Legal name." }, "trade_name": { "type": "string", "description": "Trade name." }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/PartyKind" }, "description": "Roles of the party." }, "fiscal": { "$ref": "#/components/schemas/FiscalProfile" }, "email": { "type": "string", "description": "General email address.", "format": "email" }, "phone": { "type": "string", "description": "General phone number." }, "payment_terms_days": { "type": "integer", "description": "Agreed payment terms, in days." }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/PartyBranch" }, "description": "Locations of the party." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/PartyContact" }, "description": "Contacts of the party." }, "is_active": { "type": "boolean", "description": "Whether the party is active." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation instant." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update instant." } } }, "PartyList": { "type": "object", "description": "A page of parties.", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Party" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when this is the last page." } } }, "Me": { "type": "object", "description": "The API key making the request and what it can do.", "required": [ "key", "company", "environment", "scopes" ], "properties": { "key": { "type": "object", "required": [ "id", "prefix", "created_at" ], "properties": { "id": { "type": "string", "description": "Key id." }, "prefix": { "type": "string", "description": "Visible prefix of the key. The full secret is never returned." }, "name": { "type": "string", "description": "Label given when the key was created." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation instant." } } }, "company": { "type": "object", "required": [ "id", "name", "tax_id" ], "properties": { "id": { "type": "string", "description": "Company id." }, "name": { "type": "string", "description": "Legal name." }, "trade_name": { "type": [ "string", "null" ], "description": "Trade name." }, "tax_id": { "type": "string", "description": "NIT, without check digit." }, "check_digit": { "type": [ "string", "null" ], "description": "NIT check digit." } } }, "environment": { "$ref": "#/components/schemas/Environment" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "parties:read", "products:read", "invoices:read", "invoices:write", "received:read", "receivables:read", "payments:read", "organization:read" ] }, "description": "Scopes granted to the key." } } }, "Organization": { "type": "object", "description": "The group the company belongs to. For a single company it is implicit and carries the company's name.", "required": [ "id", "name", "environment", "is_active" ], "properties": { "id": { "type": "string", "description": "Organization id." }, "name": { "type": "string", "description": "Organization name." }, "environment": { "$ref": "#/components/schemas/Environment" }, "is_active": { "type": "boolean", "description": "Whether the organization is active." } } }, "Company": { "type": "object", "description": "The company that owns the key, as the issuer of electronic documents.", "required": [ "id", "organization_id", "name", "fiscal", "environment", "is_active" ], "properties": { "id": { "type": "string", "description": "Company id." }, "organization_id": { "type": "string", "description": "Organization id." }, "name": { "type": "string", "description": "Legal name." }, "trade_name": { "type": [ "string", "null" ], "description": "Trade name." }, "fiscal": { "$ref": "#/components/schemas/FiscalProfile" }, "email": { "type": [ "string", "null" ], "description": "Company email." }, "phone": { "type": [ "string", "null" ], "description": "Company phone." }, "web": { "type": [ "string", "null" ], "description": "Company website as printed on invoices." }, "economic_activity": { "type": [ "string", "null" ], "description": "Main CIIU economic activity code." }, "environment": { "$ref": "#/components/schemas/Environment" }, "is_active": { "type": "boolean", "description": "Whether the company is active." } } }, "OrgUnitType": { "type": "string", "enum": [ "operation_center", "branch" ], "description": "`operation_center` groups branches (for example a region) · `branch` a branch of the company." }, "Unit": { "type": "object", "description": "An operating unit of the company: an operation center or a branch. Branches may hang from an operation center or directly from the company.", "required": [ "id", "type", "code", "name", "is_active" ], "properties": { "id": { "type": "string", "description": "Unit id." }, "type": { "$ref": "#/components/schemas/OrgUnitType" }, "parent_id": { "type": [ "string", "null" ], "description": "Operation center this unit hangs from; `null` means the company." }, "code": { "type": "string", "description": "Unit code." }, "name": { "type": "string", "description": "Unit name." }, "address": { "type": [ "string", "null" ], "description": "Address." }, "city_code": { "type": [ "string", "null" ], "description": "DANE municipality code." }, "phone": { "type": [ "string", "null" ], "description": "Phone number." }, "is_active": { "type": "boolean", "description": "Whether the unit is active." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Creation instant." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update instant." } } }, "UnitList": { "type": "object", "description": "A page of units.", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when this is the last page." } } } }, "parameters": { "Limit": { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response's `next_cursor`. Omit it to get the first page. Keep the other query parameters unchanged while paginating.", "schema": { "type": "string" } }, "UpdatedSince": { "name": "updated_since", "in": "query", "required": false, "description": "Only return items created or updated at or after this instant (ISO 8601). Use it to synchronize incrementally.", "schema": { "type": "string", "format": "date-time" } }, "Id": { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key for this operation (for example a UUID v4). Retrying with the same key and the same request returns the original response; reusing it for a different request returns `409 idempotency_conflict`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "headers": { "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } } }