Document types catalog

curl --request GET \
  --url https://api.example.com/api/v1/external/fiscal/document-types

const options = {method: 'GET'};

fetch('https://api.example.com/api/v1/external/fiscal/document-types', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/external/fiscal/document-types",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/external/fiscal/document-types"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/external/fiscal/document-types")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "countryCode": "EC",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "CONSUMIDOR FINAL",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "RUC",
        "name": "RUC",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 13, "maxLength": 13, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "CEDULA",
        "name": "CEDULA",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 10, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "PASSPORT",
        "name": "PASAPORTE",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 1, "maxLength": 50, "pattern": null, "checksumValidator": null }
      }
    ],
    "finalConsumer": { "govId": "9999999999999", "name": "CONSUMIDOR FINAL" }
  }
}

{
  "success": true,
  "data": {
    "countryCode": "BR",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "NÃO IDENTIFICADO",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "CPF",
        "name": "CPF",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": null, "maxLength": 14, "pattern": null, "checksumValidator": "isCPFValid" }
      },
      {
        "code": "CNPJ",
        "name": "CNPJ",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": null, "maxLength": 18, "pattern": null, "checksumValidator": "isCNPJValid" }
      }
    ],
    "finalConsumer": { "govId": "NÃO IDENTIFICADO", "name": null }
  }
}

{
  "success": true,
  "data": {
    "countryCode": "CO",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "CONSUMIDOR FINAL",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "NIT",
        "name": "NIT",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 6, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "CEDULA",
        "name": "CEDULA",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 6, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      }
    ],
    "finalConsumer": { "govId": "222222222222", "name": "CONSUMIDOR FINAL" }
  }
}

GET

api

external

fiscal

document-types

Document types catalog

curl --request GET \
  --url https://api.example.com/api/v1/external/fiscal/document-types

const options = {method: 'GET'};

fetch('https://api.example.com/api/v1/external/fiscal/document-types', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/external/fiscal/document-types",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/external/fiscal/document-types"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/external/fiscal/document-types")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "countryCode": "EC",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "CONSUMIDOR FINAL",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "RUC",
        "name": "RUC",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 13, "maxLength": 13, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "CEDULA",
        "name": "CEDULA",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 10, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "PASSPORT",
        "name": "PASAPORTE",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 1, "maxLength": 50, "pattern": null, "checksumValidator": null }
      }
    ],
    "finalConsumer": { "govId": "9999999999999", "name": "CONSUMIDOR FINAL" }
  }
}

{
  "success": true,
  "data": {
    "countryCode": "BR",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "NÃO IDENTIFICADO",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "CPF",
        "name": "CPF",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": null, "maxLength": 14, "pattern": null, "checksumValidator": "isCPFValid" }
      },
      {
        "code": "CNPJ",
        "name": "CNPJ",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": null, "maxLength": 18, "pattern": null, "checksumValidator": "isCNPJValid" }
      }
    ],
    "finalConsumer": { "govId": "NÃO IDENTIFICADO", "name": null }
  }
}

{
  "success": true,
  "data": {
    "countryCode": "CO",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "CONSUMIDOR FINAL",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "NIT",
        "name": "NIT",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 6, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "CEDULA",
        "name": "CEDULA",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 6, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      }
    ],
    "finalConsumer": { "govId": "222222222222", "name": "CONSUMIDOR FINAL" }
  }
}

Returns the catalog of buyer identification document types for one country: which types exist (CEDULA, CPF, NIT…), how their number is validated, and the default values to use when the sale did not identify the buyer. This catalog used to live in an external provider’s API — and, for Brazil, in a hardcoded list inside the client app. Now FIRE serves it as the single source. The code values you receive here are exactly what you must send back in client.govIdType when injecting an order: there is no compatibility mapping, so a stale catalog on your side shows up as a code that does not match.

Authentication


Header	`x-api-key: pk_live_…`
Scope	`document-types:read`

This scope is not tied to an account. The catalog is shared, global data — it contains no tenant information — so the key does not need to belong to any account or vendor. Practical consequence: every integrator sees exactly the same catalog for a given country, and you can use a single key for all your deployments regardless of which accounts they serve.

Query parameters

string

required

ISO 3166-1 alpha-2 country code (BR, EC, CO…). Case-insensitive — it is normalized to uppercase. Missing or malformed (not exactly two letters) returns 400.

There are no other filters. Inactive types are never returned, and the list comes already sorted in the order it should be displayed.

Response

string

The requested country, normalized to uppercase.

array

The country’s document types, in display order.

Show documentTypes[]

string

The canonical code — uppercase, no spaces (CEDULA, CPF, NIT, FINAL_CONSUMER…). This is the value to send back in client.govIdType. Codes repeat across countries with different validation rules: CEDULA exists in Ecuador (10 digits) and Colombia (6–10 digits).

string

Display label for the selector (PASAPORTE, NÃO IDENTIFICADO…). Show this; send code.

boolean

Whether to offer it in the selector. false for types that exist but are not chosen by the buyer: FINAL_CONSUMER is the default applied when the customer does not ask for an invoice, and in Chile the document selector is disabled entirely.

boolean

Marks the row that represents “buyer not identified”. Check this flag, not code === "FINAL_CONSUMER".

object

Rules for validating the number the buyer types. All four fields can be null — a null rule means no constraint of that kind.

Show validation

integer | null

Minimum length, counted over the already-normalized digits.

integer | null

Maximum length, same counting.

string | null

JavaScript regex, without delimiters (e.g. ^\d+$).

string | null

Name of a check-digit validator to run on your side when length alone is not enough (isCPFValid, isCNPJValid). It is a label, not code: FIRE names the algorithm, your client implements it.

object | null

What to stamp on the receipt when the buyer was not identified. Delivered separately from the list because it answers a different question: the list is “what can the buyer choose”, this is “what to use when they chose nothing”.null when the country does not define it — today Argentina (has the type but no number declared), Venezuela and Chile.

Show finalConsumer

string | null

The document value to stamp. It is text, not a number, on purpose: in Brazil the value is NÃO IDENTIFICADO, in Ecuador 9999999999999, in Colombia 222222222222.

string | null

The buyer name to stamp (CONSUMIDOR FINAL). null in Brazil.

{
  "success": true,
  "data": {
    "countryCode": "EC",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "CONSUMIDOR FINAL",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "RUC",
        "name": "RUC",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 13, "maxLength": 13, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "CEDULA",
        "name": "CEDULA",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 10, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "PASSPORT",
        "name": "PASAPORTE",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 1, "maxLength": 50, "pattern": null, "checksumValidator": null }
      }
    ],
    "finalConsumer": { "govId": "9999999999999", "name": "CONSUMIDOR FINAL" }
  }
}

{
  "success": true,
  "data": {
    "countryCode": "BR",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "NÃO IDENTIFICADO",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "CPF",
        "name": "CPF",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": null, "maxLength": 14, "pattern": null, "checksumValidator": "isCPFValid" }
      },
      {
        "code": "CNPJ",
        "name": "CNPJ",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": null, "maxLength": 18, "pattern": null, "checksumValidator": "isCNPJValid" }
      }
    ],
    "finalConsumer": { "govId": "NÃO IDENTIFICADO", "name": null }
  }
}

{
  "success": true,
  "data": {
    "countryCode": "CO",
    "documentTypes": [
      {
        "code": "FINAL_CONSUMER",
        "name": "CONSUMIDOR FINAL",
        "selectable": false,
        "isFinalConsumer": true,
        "validation": { "minLength": null, "maxLength": null, "pattern": null, "checksumValidator": null }
      },
      {
        "code": "NIT",
        "name": "NIT",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 6, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      },
      {
        "code": "CEDULA",
        "name": "CEDULA",
        "selectable": true,
        "isFinalConsumer": false,
        "validation": { "minLength": 6, "maxLength": 10, "pattern": "^\\d+$", "checksumValidator": null }
      }
    ],
    "finalConsumer": { "govId": "222222222222", "name": "CONSUMIDOR FINAL" }
  }
}

A country with no catalog configured yet returns empty lists and finalConsumer: null — not a 404. “Not configured yet” is a legitimate answer, and you must be able to tell it apart from a failure.

The catalog changes rarely. Cache it per country and refresh periodically — but do refresh: sending a code that no longer exists in the catalog is exactly the drift this endpoint replaces.

Errors

Code	When
`400`	`countryCode` is missing or is not a 2-letter code
`401`	The API key is missing, unknown or revoked
`403`	The key lacks the `document-types:read` scope

Inject order — where client.govIdType carries these codes
Request fiscal numbering — the document the buyer identification ends up on

​Authentication

​Query parameters

​Response

​Errors

​Related

Authentication

Query parameters

Response

Errors

Related