Skip to main content

Wildcard items

The API Connect is designed so you do not need to maintain a product catalog synchronized with Ocote. Your system has its own database of products/services; the API accepts any line description you send without validating it against an Ocote inventory.

This reduces integration to near-zero: send description, quantity, unit_price, and the API handles the rest.

How it works internally​

When you issue a document via the API Connect, Ocote internally maps each line to one of two wildcard items registered for your company:

WildcardInternal codeMH typeWhen used
Good/product__API_WILDCARD__1 (Goods)Lines in Invoice, CCF, Export. Also in SUEX if is_service: false.
Service__API_WILDCARD_SVC__2 (Services)Lines in SUEX when is_service: true (triggers 10% income-tax withholding).

These wildcards are created automatically in your company the first time an API key is issued. You do not have to do anything to activate them. They do not appear in your inventory reports either — they are just a mechanism to satisfy the internal reference Ocote maintains by design.

What you send​

Just the descriptive fields of the line:

{
  "lines": [
    {
      "description": "Strategic consulting service - April 2026",
      "quantity": 1,
      "unit_price": 2500.00,
      "discount_percentage": 10
    }
  ]
}

The description is free text up to 1,000 characters. It appears verbatim in the DTE signed JSON, the ticket, and the PDF. There is no catalog to validate against — MH does not require product codes in the documents.

1% VAT withholding — automatic​

For Invoice (01) and CCF (03), when the recipient is Large Taxpayer (type_contributor: 3) or Government (type_contributor: 4), Salvadoran regulations require a 1% withholding on the taxable amount if it exceeds $100.00.

The API calculates and applies this withholding automatically. You do not need to:

  • Know the contributor type before issuing.
  • Calculate the 1%.
  • Send withholding fields in the payload.

In the response you'll see:

{
  "amount_taxable":   1000.00,
  "amount_vat":        130.00,
  "amount_gross":     1130.00,
  "amount_retention":   10.00,
  "amount_total":     1120.00
}

amount_retention is computed as 1% × amount_taxable when it applies, 0.00 when not.

$100 threshold

If amount_taxable < 100.00, no withholding applies even if the customer is Large Taxpayer or Government. This is part of the regulation, not API behavior.

10% income tax on SUEX — automatic​

For Excluded Subject (14) with lines marked as services (is_service: true), regulations require 10% income-tax withholding on the amount.

The API also computes this automatically. In a SUEX response with services:

{
  "amount_total":       1000.00,
  "amount_retention":    100.00,
  "amount_to_pay":       900.00
}

amount_to_pay is what you effectively transfer to the excluded subject (gross amount minus withholding). Your company reports the withholding to MH monthly as usual.

If the SUEX line is is_service: false (sale of goods), there is no income-tax withholding.

What you do NOT get with wildcards​

Because they are wildcard items, two things you cannot do inside the API Connect:

  • Inventory tracking. The API does not deduct stock on issuance. Your ERP handles that.
  • Top-selling product reports from Ocote. Ocote reports group by the wildcard, not by your description. If you need that analysis, run it from your system (which has the real catalog).

These two limitations are exactly what makes synchronization-free integration viable. If you needed to cover them, the full Ocote DTE platform (not the API Connect) does handle inventory.

Relevant payload fields​

When sending a line, the only required fields are:

FieldTypeDescription
descriptionstringTextual line description. Appears in the DTE.
quantitynumberQuantity. Supports decimals.
unit_pricenumberUnit price with VAT included for local sales.

Optional:

FieldTypeDescription
discount_percentagenumberDiscount percentage (0–99).
is_servicebooleanSUEX only: marks the line as service (triggers 10% withholding).

The rest of the fields that appear in the DTE's signed JSON (internal code, measurement unit, MH type, etc.) are assigned by Ocote with standard values appropriate for the document type.

Example: CCF to Large Taxpayer​

curl
curl -X POST https://ocote.io/api/connect/invoice \
  -H "Authorization: Bearer odt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_type": "03",
    "external_ref": "CCF-2026-0042",
    "customer": {
      "name": "LARGE COMPANY, S.A. DE C.V.",
      "nit": "06140710141035",
      "nrc": "2360090",
      "type_contributor": 3,
      "activity_code": "86902",
      "municipality_code": "0614"
    },
    "lines": [
      { "description": "Software development", "quantity": 1, "unit_price": 5000.00 }
    ]
  }'

Response (excerpt):

{
  "success": true,
  "dte_success": true,
  "control_number": "DTE-03-M001P001-000000000000042",
  "amount_taxable":  4424.78,
  "amount_vat":       575.22,
  "amount_gross":    5000.00,
  "amount_retention":  44.25,
  "amount_total":    4955.75
}

Note that unit_price: 5000.00 was sent VAT-included; the API extracts the VAT (breaking it down to amount_taxable: 4424.78) and applies the 1% withholding on the taxable base. None of that you computed.

See also​