Skip to main content
API docs by Redocly

Quetzal Invoicing API (0.1.0-draft)

Download OpenAPI specification:Download

URL: https://github.com/mattilda-education/quetzal

Radically abstract invoicing service. Receives line items, receiver, and issuer data, then produces fiscal documents through country tax-authority integrations.

Documents

Fiscal documents: invoices, credit notes, debit notes, payment complements, cancellations

Create Document

Create Document

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
required
string <uuid> (Idempotency-Key)
X-Flow-Id (string) or X-Flow-Id (null) (X-Flow-Id)
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
tenant_id
required
string (Tenant Id)
country
required
string (Country)
Enum: "CO" "MX" "EC" "PE"
document_type
required
string (Document Type)
Enum: "INVOICE" "CREDIT_NOTE" "DEBIT_NOTE" "PAYMENT_COMPLEMENT" "CANCELLATION"
intent
required
string (Intent)
Enum: "DRAFT" "SUBMIT"
required
object (PartyDTO)
required
object (PartyDTO)
Array of objects (Line Items)
Array of objects (References)
CountrySpecificDTO (object) or null
PaymentDTO (object) or null
Emission Date (string) or Emission Date (null) (Emission Date)
Issuer Profile Id (string) or Issuer Profile Id (null) (Issuer Profile Id)
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "string",
  • "country": "CO",
  • "document_type": "INVOICE",
  • "intent": "DRAFT",
  • "issuer": {
    },
  • "receiver": {
    },
  • "line_items": [
    ],
  • "references": [
    ],
  • "country_specific": {
    },
  • "payment": {
    },
  • "emission_date": "2019-08-24",
  • "issuer_profile_id": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "country": "CO",
  • "document_type": "INVOICE",
  • "status": "DRAFT",
  • "fiscal_status": "not_submitted",
  • "lifecycle_status": "draft",
  • "issuer": {
    },
  • "receiver": {
    },
  • "line_items": [
    ],
  • "references": [
    ],
  • "country_specific": {
    },
  • "payment": {
    },
  • "fiscal_id": "string",
  • "fiscal_document_urls": {
    },
  • "superseded_by": "string",
  • "emission_date": "2019-08-24",
  • "cancellation_reason": "string",
  • "failure_reason": "string",
  • "failure": {
    },
  • "provider_operation_id": "string",
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Documents

List Documents

Authorizations:
bearerAuth
query Parameters
Country (string) or Country (null) (Country)
Fiscal Status (string) or Fiscal Status (null) (Fiscal Status)
Lifecycle Status (string) or Lifecycle Status (null) (Lifecycle Status)
Document Type (string) or Document Type (null) (Document Type)
Provider Operation Id (string) or Provider Operation Id (null) (Provider Operation Id)
Fiscal Id (string) or Fiscal Id (null) (Fiscal Id)
After (string) or After (null) (After)
limit
integer (Limit)
Default: 50
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_after": "2019-08-24T14:15:22Z"
}

Get Document

Get Document

Authorizations:
bearerAuth
path Parameters
document_id
required
string (Document Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "country": "CO",
  • "document_type": "INVOICE",
  • "status": "DRAFT",
  • "fiscal_status": "not_submitted",
  • "lifecycle_status": "draft",
  • "issuer": {
    },
  • "receiver": {
    },
  • "line_items": [
    ],
  • "references": [
    ],
  • "country_specific": {
    },
  • "payment": {
    },
  • "fiscal_id": "string",
  • "fiscal_document_urls": {
    },
  • "superseded_by": "string",
  • "emission_date": "2019-08-24",
  • "cancellation_reason": "string",
  • "failure_reason": "string",
  • "failure": {
    },
  • "provider_operation_id": "string",
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Patch Document

Patch Document

Authorizations:
bearerAuth
path Parameters
document_id
required
string (Document Id)
header Parameters
Idempotency-Key
required
string <uuid> (Idempotency-Key)
If-Match (string) or If-Match (null) (If-Match)
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/merge-patch+json
required
Status (string) or Status (null) (Status)
Fiscal Id (string) or Fiscal Id (null) (Fiscal Id)
Fiscal Document Urls (object) or Fiscal Document Urls (null) (Fiscal Document Urls)
Cancellation Reason (string) or Cancellation Reason (null) (Cancellation Reason)
Failure Reason (string) or Failure Reason (null) (Failure Reason)
Metadata (object) or Metadata (null) (Metadata)

Responses

Request samples

Content type
application/merge-patch+json
{
  • "status": "DRAFT",
  • "fiscal_id": "string",
  • "fiscal_document_urls": {
    },
  • "cancellation_reason": "string",
  • "failure_reason": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "country": "CO",
  • "document_type": "INVOICE",
  • "status": "DRAFT",
  • "fiscal_status": "not_submitted",
  • "lifecycle_status": "draft",
  • "issuer": {
    },
  • "receiver": {
    },
  • "line_items": [
    ],
  • "references": [
    ],
  • "country_specific": {
    },
  • "payment": {
    },
  • "fiscal_id": "string",
  • "fiscal_document_urls": {
    },
  • "superseded_by": "string",
  • "emission_date": "2019-08-24",
  • "cancellation_reason": "string",
  • "failure_reason": "string",
  • "failure": {
    },
  • "provider_operation_id": "string",
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Document Events

Get Document Events

Authorizations:
bearerAuth
path Parameters
document_id
required
string (Document Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Cancel Document

Cancel Document

Authorizations:
bearerAuth
path Parameters
document_id
required
string (Document Id)
header Parameters
Idempotency-Key
required
string <uuid> (Idempotency-Key)
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
Reason (string) or Reason (null) (Reason)
CountrySpecificDTO (object) or null

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "country_specific": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "country": "CO",
  • "document_type": "INVOICE",
  • "status": "DRAFT",
  • "fiscal_status": "not_submitted",
  • "lifecycle_status": "draft",
  • "issuer": {
    },
  • "receiver": {
    },
  • "line_items": [
    ],
  • "references": [
    ],
  • "country_specific": {
    },
  • "payment": {
    },
  • "fiscal_id": "string",
  • "fiscal_document_urls": {
    },
  • "superseded_by": "string",
  • "emission_date": "2019-08-24",
  • "cancellation_reason": "string",
  • "failure_reason": "string",
  • "failure": {
    },
  • "provider_operation_id": "string",
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Void Document

Void Document

Authorizations:
bearerAuth
path Parameters
document_id
required
string (Document Id)
header Parameters
Idempotency-Key
required
string <uuid> (Idempotency-Key)
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
Reason (string) or Reason (null) (Reason)
Any of
string (Reason)

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "country": "CO",
  • "document_type": "INVOICE",
  • "status": "DRAFT",
  • "fiscal_status": "not_submitted",
  • "lifecycle_status": "draft",
  • "issuer": {
    },
  • "receiver": {
    },
  • "line_items": [
    ],
  • "references": [
    ],
  • "country_specific": {
    },
  • "payment": {
    },
  • "fiscal_id": "string",
  • "fiscal_document_urls": {
    },
  • "superseded_by": "string",
  • "emission_date": "2019-08-24",
  • "cancellation_reason": "string",
  • "failure_reason": "string",
  • "failure": {
    },
  • "provider_operation_id": "string",
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Document Evidence

Get Document Evidence

Authorizations:
bearerAuth
path Parameters
document_id
required
string (Document Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Parties

Issuer and receiver registry

Create Party

Create Party

Authorizations:
bearerAuth
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
tenant_id
required
string (Tenant Id)
kind
required
string (Kind)
Enum: "issuer" "receiver" "both"
tax_id
required
string (Tax Id)
tax_id_type
required
string (Tax Id Type)
Enum: "RFC" "NIT" "RUC" "GENERIC_ID"
name
required
string (Name)
country
required
string (Country)
Enum: "CO" "MX" "EC" "PE"
Email (string) or Email (null) (Email)
AddressDTO (object) or null
CountrySpecificDTO (object) or null
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "string",
  • "kind": "issuer",
  • "tax_id": "string",
  • "tax_id_type": "RFC",
  • "name": "string",
  • "country": "CO",
  • "email": "string",
  • "address": {
    },
  • "country_specific": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "kind": "string",
  • "tax_id": "string",
  • "tax_id_type": "RFC",
  • "name": "string",
  • "country": "CO",
  • "email": "string",
  • "address": {
    },
  • "country_specific": {
    },
  • "metadata": {
    },
  • "deactivated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Parties

List Parties

Authorizations:
bearerAuth
query Parameters
include_deactivated
boolean (Include Deactivated)
Default: false
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get Party

Get Party

Authorizations:
bearerAuth
path Parameters
party_id
required
string (Party Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "kind": "string",
  • "tax_id": "string",
  • "tax_id_type": "RFC",
  • "name": "string",
  • "country": "CO",
  • "email": "string",
  • "address": {
    },
  • "country_specific": {
    },
  • "metadata": {
    },
  • "deactivated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Deactivate Party

Deactivate Party

Authorizations:
bearerAuth
path Parameters
party_id
required
string (Party Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "kind": "string",
  • "tax_id": "string",
  • "tax_id_type": "RFC",
  • "name": "string",
  • "country": "CO",
  • "email": "string",
  • "address": {
    },
  • "country_specific": {
    },
  • "metadata": {
    },
  • "deactivated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Issuer Profiles

Issuer fiscal credentials and numbering profiles

Create Issuer Profile

Create Issuer Profile

Authorizations:
bearerAuth
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
tenant_id
required
string (Tenant Id)
party_id
required
string (Party Id)
country
required
string (Country)
Enum: "CO" "MX" "EC" "PE"
issuer_series
required
string (Issuer Series)
Secret Arn (string) or Secret Arn (null) (Secret Arn)
External Ref (string) or External Ref (null) (External Ref)
object (Provider Config)
Numerator Prefix (string) or Numerator Prefix (null) (Numerator Prefix)
numerator_range_min
integer (Numerator Range Min)
Default: 1
numerator_range_max
integer (Numerator Range Max)
Default: 9223372036854776000

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "string",
  • "party_id": "string",
  • "country": "CO",
  • "issuer_series": "string",
  • "secret_arn": "string",
  • "external_ref": "string",
  • "provider_config": {
    },
  • "numerator_prefix": "string",
  • "numerator_range_min": 1,
  • "numerator_range_max": 9223372036854776000
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "party_id": "string",
  • "country": "CO",
  • "issuer_series": "string",
  • "external_ref": "string",
  • "provider_config": {
    },
  • "numerator_prefix": "string",
  • "numerator_range_min": 0,
  • "numerator_range_max": 0,
  • "numerator_current": 0,
  • "deactivated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Issuer Profiles

List Issuer Profiles

Authorizations:
bearerAuth
query Parameters
Country (string) or Country (null) (Country)
Issuer Series (string) or Issuer Series (null) (Issuer Series)
External Ref (string) or External Ref (null) (External Ref)
include_deactivated
boolean (Include Deactivated)
Default: false
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get Issuer Profile

Get Issuer Profile

Authorizations:
bearerAuth
path Parameters
profile_id
required
string (Profile Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "party_id": "string",
  • "country": "CO",
  • "issuer_series": "string",
  • "external_ref": "string",
  • "provider_config": {
    },
  • "numerator_prefix": "string",
  • "numerator_range_min": 0,
  • "numerator_range_max": 0,
  • "numerator_current": 0,
  • "deactivated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Deactivate Issuer Profile

Deactivate Issuer Profile

Authorizations:
bearerAuth
path Parameters
profile_id
required
string (Profile Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "party_id": "string",
  • "country": "CO",
  • "issuer_series": "string",
  • "external_ref": "string",
  • "provider_config": {
    },
  • "numerator_prefix": "string",
  • "numerator_range_min": 0,
  • "numerator_range_max": 0,
  • "numerator_current": 0,
  • "deactivated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Webhook Subscriptions

Outbound webhook delivery configuration

Create Webhook Subscription

Create Webhook Subscription

Authorizations:
bearerAuth
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
tenant_id
required
string (Tenant Id)
name
required
string (Name)
url
required
string (Url)
event_types
required
Array of strings (Event Types) non-empty
Secret (string) or Secret (null) (Secret)

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "string",
  • "name": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "secret": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "name": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "active": true,
  • "last_published_offset": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "secret": "string"
}

List Webhook Subscriptions

List Webhook Subscriptions

Authorizations:
bearerAuth
query Parameters
include_inactive
boolean (Include Inactive)
Default: false
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get Webhook Subscription

Get Webhook Subscription

Authorizations:
bearerAuth
path Parameters
subscription_id
required
string (Subscription Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "name": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "active": true,
  • "last_published_offset": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Webhook Subscription

Update Webhook Subscription

Authorizations:
bearerAuth
path Parameters
subscription_id
required
string (Subscription Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Url (string) or Url (null) (Url)
Array of Event Types (strings) or Event Types (null) (Event Types)
Active (boolean) or Active (null) (Active)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "name": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "active": true,
  • "last_published_offset": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Webhook Subscription

Delete Webhook Subscription

Authorizations:
bearerAuth
path Parameters
subscription_id
required
string (Subscription Id)
header Parameters
X-Tenant-Id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "name": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "active": true,
  • "last_published_offset": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

FacturaGreen Webhooks

Inbound FacturaGreen lifecycle callbacks

Receive Fg Webhook

Receive Fg Webhook

Request Body schema: application/json
required
required
object (FacturaGreenWebhookEvent)
required
object (FacturaGreenWebhookData)

Responses

Request samples

Content type
application/json
{
  • "event": {
    },
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Health

Service probes

Liveness

Liveness

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "checks": {
    }
}

Readiness

Readiness

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "checks": {
    }
}