> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Document types catalog

> The identification document types each country accepts — codes, validation rules, and what to stamp when the buyer was not identified.

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`  |

<Info>
  **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.
</Info>

## Query parameters

<ParamField query="countryCode" type="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`.
</ParamField>

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

## Response

<ResponseField name="countryCode" type="string">
  The requested country, normalized to uppercase.
</ResponseField>

<ResponseField name="documentTypes" type="array">
  The country's document types, in display order.

  <Expandable title="documentTypes[]">
    <ResponseField name="code" type="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).
    </ResponseField>

    <ResponseField name="name" type="string">
      Display label for the selector (`PASAPORTE`, `NÃO IDENTIFICADO`…). Show
      this; send `code`.
    </ResponseField>

    <ResponseField name="selectable" type="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.
    </ResponseField>

    <ResponseField name="isFinalConsumer" type="boolean">
      Marks the row that represents "buyer not identified". Check this flag, not
      `code === "FINAL_CONSUMER"`.
    </ResponseField>

    <ResponseField name="validation" type="object">
      Rules for validating the number the buyer types. All four fields can be
      `null` — a `null` rule means no constraint of that kind.

      <Expandable title="validation">
        <ResponseField name="minLength" type="integer | null">
          Minimum length, counted over the already-normalized digits.
        </ResponseField>

        <ResponseField name="maxLength" type="integer | null">
          Maximum length, same counting.
        </ResponseField>

        <ResponseField name="pattern" type="string | null">
          JavaScript regex, without delimiters (e.g. `^\d+$`).
        </ResponseField>

        <ResponseField name="checksumValidator" type="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.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="finalConsumer" type="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.

  <Expandable title="finalConsumer">
    <ResponseField name="govId" type="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`.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The buyer name to stamp (`CONSUMIDOR FINAL`). `null` in Brazil.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 — Ecuador theme={null}
  {
    "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" }
    }
  }
  ```

  ```json 200 — Brazil theme={null}
  {
    "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 }
    }
  }
  ```

  ```json 200 — Colombia theme={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" }
    }
  }
  ```
</ResponseExample>

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>

## 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      |

## Related

* [Inject order](/en/api-reference/orders) — where `client.govIdType` carries these codes
* [Request fiscal numbering](/en/api-reference/fiscal-documents) — the document the buyer identification ends up on