Invoice (01)

The Invoice (type 01) is issued to final consumers — individuals without NRC, or customers that do not require tax credit. It is the most common DTE type in retail, restaurants, and public services.

Technical details

Method	POST
URL	https://ocote.io/api/connect/invoice
Content-Type	application/json
Authentication	Header Authorization: Bearer odt_...

Request

Main fields

Field	Type	Required	Description
doc_type	string	No (default "01")	DTE type. For Invoice: "01".
lines	array	Yes	Document lines. At least one. See LineIn.
customer	object	No	Customer data. Optional for Invoice 01. See CustomerIn.
customer_name	string	No	Consumer name for invoices without a customer object. Default: "Consumidor Final".
payment_method	string	No (default "01")	Payment method. See MH catalogs.
transaction_condition	int	No (default 1)	1 = Cash, 2 = Credit, 3 = Other.
deadline	int	No (default 1)	Credit term unit (MH CAT-018): 1 = Days, 2 = Months, 3 = Years. Only applies to transaction_condition: 2.
period	int	No (default 1)	Numeric amount of the term. E.g., deadline: 1, period: 30 = 30 days; deadline: 2, period: 2 = 2 months. Only applies to transaction_condition: 2.
activity_code	string	No	Issuer economic activity code for this document. Overrides company default.
redirect_email	string	No	Additional email to which a copy is sent (besides customer.email).
external_ref	string	No	Your idempotent identifier. See Retry and idempotency.

Lines (lines)

Field	Type	Required	Description
description	string	Yes	Product/service description. Max 1,000 characters.
quantity	float	Yes	Quantity. Must be greater than zero.
unit_price	float	Yes	Unit price VAT included. Must be greater than zero.
discount_percentage	float	No (default 0)	Discount percentage (0–99).

Customer (customer)

Fully optional on Invoice 01. If you omit it or send it incomplete, Ocote applies sensible defaults:

Field	Type	Required	Default (on create)	Description
name	string	Yes (if you send customer)	—	Name or business name.
nit	string	No	—	Customer NIT (if applicable).
nrc	string	No	—	Customer NRC (only if VAT contributor).
dui	string	No	—	DUI for individuals.
document_type	string	No	"37"	MH identifier document type.
type_contributor	int	No	1 (Small)	Contributor type. See Conventions.
favorite_doc	string	No	"01"	Customer's preferred DTE type.
address	string	No	"San Salvador"	Address.
activity_code	string	No	—	Customer economic activity code.
district	string	No	—	District UUID — look it up in /catalogs/districts/search. If sent, department and municipality are ignored. Recommended flow because you don't deal with MH codes.
department	string	No	—	MH department code. See MH catalogs. If you send it, municipality is also required. Ignored if district is provided.
municipality	string	No	—	MH municipality code. Accepts short format ("24") or long format ("1124") — see MH catalogs. Ignored if district is provided.
email	string	No	—	Email address for DTE delivery.
phone	string	No	—	Phone.

New vs existing customers

If customer.nit (or customer.dui) already exists in your Ocote company, the API only updates the fields you explicitly sent. If it does not exist, it creates the customer with the defaults from the table above. Sensitive fiscal fields (type_contributor, favorite_doc, document_type, nit, nrc, dui) are audited in Ocote's internal log when they change.

Response

See Responses and states for the full flags semantics. /invoice-specific fields:

Field	Type	Description
document_id	string (UUID)	Internal Ocote identifier.
external_ref	string	The one you sent (or auto-generated).
control_number	string	MH DTE correlative. Never regenerated.
generation_code	string	MH generation code (same as UUID in uppercase).
reception_stamp	string	MH reception stamp. Empty if contingency: true or rejected: true.
amount_taxable	float	Taxable base (price without VAT).
amount_vat	float	VAT 13%.
amount_gross	float	VAT-included total, before withholding.
amount_retention	float	1% VAT withholding (applies only if recipient is type_contributor 3 or 4 and amount_taxable >= 100).
amount_total	float	Net total = amount_gross − amount_retention.
ticket_url	string	URL to the thermal PDF ticket (8×21 cm). Available once the document was processed (is_dte: true). Applies to Invoice 01 and CCF 03.
invoice_url	string	URL to the letter-sized PDF. Only if dte_success: true.
json_url	string	URL to signed JSON. Only if dte_success: true.
dte	object	Full signed DTE schema (only if dte_success: true).

Minimal example: simple sale

curl

curl -X POST https://ocote.io/api/connect/invoice \
  -H "Authorization: Bearer odt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "SALE-2026-0042",
    "lines": [
      { "description": "Americano coffee",  "quantity": 2, "unit_price": 2.50 },
      { "description": "Chicken empanada",  "quantity": 1, "unit_price": 3.00 }
    ]
  }'

Node.js (axios)

const { data } = await axios.post(
  'https://ocote.io/api/connect/invoice',
  {
    external_ref: 'SALE-2026-0042',
    lines: [
      { description: 'Americano coffee',  quantity: 2, unit_price: 2.50 },
      { description: 'Chicken empanada',  quantity: 1, unit_price: 3.00 },
    ],
  },
  { headers: { Authorization: `Bearer ${process.env.OCOTE_API_KEY}` } }
);

Python (requests)

r = requests.post(
    "https://ocote.io/api/connect/invoice",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "external_ref": "SALE-2026-0042",
        "lines": [
            {"description": "Americano coffee",  "quantity": 2, "unit_price": 2.50},
            {"description": "Chicken empanada",  "quantity": 1, "unit_price": 3.00},
        ],
    },
)

Full example: with customer and credit terms

curl

curl -X POST https://ocote.io/api/connect/invoice \
  -H "Authorization: Bearer odt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "SALE-2026-0043",
    "customer": {
      "name": "Juan Pérez",
      "dui": "01234567-8",
      "email": "juan@example.com",
      "phone": "2222-3333",
      "address": "Colonia Escalón, San Salvador"
    },
    "lines": [
      {
        "description": "Marketing consulting - 8 hours",
        "quantity": 8,
        "unit_price": 50.00,
        "discount_percentage": 10
      }
    ],
    "payment_method": "05",
    "transaction_condition": 2,
    "deadline": 1,
    "period": 30,
    "redirect_email": "accounting@mycompany.com"
  }'

payment_method: "05" = Transfer. transaction_condition: 2 = Credit. deadline: 1, period: 30 = 30 days of credit. See MH catalogs for the full list of codes.

Successful response

{
  "success": true,
  "dte_success": true,
  "contingency": false,
  "rejected": false,
  "posted": true,
  "is_duplicate": false,

  "document_id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "external_ref": "SALE-2026-0042",
  "control_number": "DTE-01-M001P001-000000000000123",
  "generation_code": "A1B2C3D4-1234-5678-9ABC-DEF012345678",
  "reception_stamp": "20260421154532...",

  "amount_taxable": 7.96,
  "amount_vat":     1.04,
  "amount_gross":   9.00,
  "amount_retention": 0.00,
  "amount_total":   9.00,

  "ticket_url":  "https://ocote.io/api/connect/file/a1b2c3d4-1234-5678-9abc-def012345678?type=ticket",
  "invoice_url": "https://ocote.io/api/connect/file/a1b2c3d4-1234-5678-9abc-def012345678?type=invoice",
  "json_url":    "https://ocote.io/api/connect/file/a1b2c3d4-1234-5678-9abc-def012345678?type=json"
}

Specific validation errors

HTTP 400 with the detail field populated:

Message	Cause
doc_type debe ser uno de: 01, 03, 11	Invalid doc_type value.
Debe incluir al menos una línea	lines empty or absent.
Línea N: cantidad debe ser mayor a cero	Some item has quantity <= 0.
Línea N: precio unitario debe ser mayor a cero	Some item has unit_price <= 0.
Línea N: descripción es requerida	Empty description.
Departamento/municipio no encontrado: X/Y	department/municipality combination does not exist in the MH catalog.

Error messages are returned in Spanish — the language MH operates in.

See also

• Conventions — VAT-included pricing, timezone, enumerated values.
• CCF (03) — issuance to VAT contributors with NIT and NRC.
• Wildcard items — how the internal catalog works and automatic withholding.
• MH catalogs — activity, department, municipality, payment method codes.
• Responses and states — full response semantics.