MH catalogs

The API Connect uses two kinds of reference catalogs:

• Live — exposed as endpoints, queryable in real time. Use them when you need the full list or a filtered subset.
• Static — fixed enumerated values that don't change. You send them as literals in your requests.

Live catalogs (endpoints)

Economic activities

List from MH CAT-019 catalog — required for activity_code on the CCF customer and for the issuer's activity_code.

Method	GET
URL	https://ocote.io/api/connect/catalogs/activities
Query params	search (optional) — filters by code or description. Case- and accent-insensitive: programacion matches PROGRAMACIÓN.
Authentication	Header Authorization: Bearer odt_...

Example:

curl "https://ocote.io/api/connect/catalogs/activities?search=software" \
  -H "Authorization: Bearer odt_xxx"

[
  { "code": "62010", "description": "Programación informática" },
  { "code": "62020", "description": "Consultoría de informática" },
  { "code": "62090", "description": "Otras actividades de tecnologías de la información y servicios informáticos" }
]

The endpoint returns at most 50 results per call. Without search, it returns the first 50. Descriptions are in Spanish (MH's operating language).

Departments and municipalities

List of CAT-012 (departments) and CAT-013 (municipalities) grouped together.

Method	GET
URL	https://ocote.io/api/connect/catalogs/departments
Query params	search (optional) — filters by department or municipality name. Case- and accent-insensitive: usulutan matches USULUTÁN.
Authentication	Header Authorization: Bearer odt_...

curl "https://ocote.io/api/connect/catalogs/departments?search=usulutan" \
  -H "Authorization: Bearer odt_xxx"

Response (abbreviated):

[
  {
    "code": "11",
    "name": "USULUTÁN",
    "municipalities": [
      { "code": "1124", "short_code": "24", "name": "USULUTÁN NORTE" },
      { "code": "1125", "short_code": "25", "name": "USULUTÁN ESTE" },
      { "code": "1126", "short_code": "26", "name": "USULUTÁN OESTE" }
    ]
  }
]

How to use these codes in requests

In the customer or excluded-subject payload they are sent separately as department + municipality. For municipality you can use either of the two formats exposed by the catalog:

• Long format — the full code as-is. Example: "department": "11", "municipality": "1124".
• Short format — just the short_code (last 2 digits). Example: "department": "11", "municipality": "24".

Both resolve to the same municipality. The long format is more convenient because you can copy it directly from the catalog; the short format is preserved for backward compatibility.

If you prefer an experience without codes, use Districts instead of this endpoint.

Districts

Districts are the most granular layer inside each municipality (e.g. Berlín inside Usulután Norte). Same concept you see in the Ocote desktop panel.

Using districts is the recommended flow: the integrator searches by name, gets a UUID, and sends it in the payload. API Connect automatically derives the MH department and municipality from the parent, so you don't deal with codes at all.

Method	GET
URL	https://ocote.io/api/connect/catalogs/districts/search
Query params	q (optional) — district name. Case- and accent-insensitive: berlin matches Berlín. page (optional, default 1) — 20 results per page.
Authentication	Header Authorization: Bearer odt_...

curl "https://ocote.io/api/connect/catalogs/districts/search?q=berlin" \
  -H "Authorization: Bearer odt_xxx"

Response:

{
  "results": [
    {
      "id": "155",
      "text": "Distrito de Berlín - USULUTÁN NORTE, USULUTÁN",
      "name": "Distrito de Berlín",
      "municipality": "USULUTÁN NORTE",
      "department": "USULUTÁN"
    }
  ],
  "pagination": { "more": false }
}

Then in the /invoice or /suex payload:

{
  "customer": {
    "name": "Customer in Berlín",
    "district": "155",
    "address": "Berlín, Usulután"
  }
}

When you send district, the department and municipality fields are ignored (even if present in the payload). See Invoice (01) for the full field table.

Measurement units

List of MH CAT-014 catalog.

Method	GET
URL	https://ocote.io/api/connect/catalogs/units
Query params	search (optional) — filters by code or description. Case- and accent-insensitive.
Authentication	Header Authorization: Bearer odt_...

curl https://ocote.io/api/connect/catalogs/units \
  -H "Authorization: Bearer odt_xxx"

Units are informational. The API Connect uses 99 (Other) by default for all issued lines, since wildcard items do not require specific units. The list is exposed for completeness.

Static catalogs

Contributor types

Used in customer.type_contributor on Invoice, CCF, and Export requests.

Value	Type
1	Small Contributor
2	Medium Contributor
3	Large Taxpayer — automatic 1% VAT withholding if base ≥ $100
4	Government — automatic 1% VAT withholding if base ≥ $100

See Wildcard items > VAT withholding.

Recipient/subject identifier document types

Used in customer.document_type and subject.document_type.

Code	Document
"02"	Resident Card
"03"	Passport
"13"	DUI (Salvadoran National ID)
"36"	NIT
"37"	Other — default when the consumer does not send document_type when creating a new customer via /invoice

SUEX accepts only these 5 values (the API validates explicitly). Invoice/CCF/Export allow these and other MH codes, but most integrations use 13 (individuals with DUI) or 36 (companies with NIT). If you send a customer without specifying document_type, the API uses 37 ("Other") to avoid MH rejections due to mismatch between declared type and number format.

Payment methods

Used in payment_method. MH CAT-017 catalog.

Code	Payment method
"01"	Bills and coins (Cash) — default
"02"	Debit Card
"03"	Credit Card
"04"	Check
"05"	Transfer / Bank Deposit
"08"	Electronic money
"09"	Electronic wallet
"10"	Non-bank transfer
"11"	Remittance
"12"	Barter
"13"	Other non-listed means
"14"	Accounts payable
"15"	Bank draft
"99"	Other

Operation conditions

Used in transaction_condition. MH CAT-016 catalog.

Value	Condition
1	Cash — default
2	Credit
3	Other

When transaction_condition: 2, the fields deadline and period become relevant to specify credit terms. deadline is the unit (catalog CAT-018) and period is the amount.

deadline	Unit
1	Days
2	Months
3	Years

Example: 30-day credit → "deadline": 1, "period": 30. 2-month credit → "deadline": 2, "period": 2.

Environments

Used in the signed DTE (identificacion.ambiente field). Not sent in the payload — derived from your company configuration.

Code	Environment
"00"	Test / QA
"01"	Production

See Environment and base URL for how this is configured.

DTE document types

Code	Document	Endpoint
"01"	Invoice	POST /invoice with doc_type: "01"
"03"	Tax Credit Voucher (CCF)	POST /invoice with doc_type: "03"
"05"	Credit Note	POST /credit-memo
"11"	Export Invoice	POST /invoice with doc_type: "11"
"14"	Excluded Subject	POST /suex

The current API Connect does not expose types 04 (Shipping Note), 06 (Debit Note), 07 (Withholding Voucher), 08 (Settlement Voucher), 09 (Accounting Settlement), 15 (Donation Voucher). If your integration needs them, contact Ocote.

See also

• Conventions — general use of enumerated values.
• Invoice (01) — request schema with fields using these catalogs.
• CCF (03) — recipient with type_contributor triggering withholding.
• Excluded Subject (14) — accepted document types.