Saltar al contenido principal

Consultar estado

El API expone cinco endpoints de consulta de solo lectura, uno por tipo de documento. Todos aceptan el identificador como UUID o external_ref y no tienen efectos secundarios (no cuentan como reintento ni disparan operaciones MH).

EndpointPara consultar
GET /status/{id_or_ref}Facturas (01), CCF (03), Exportación (11), NC (05)
GET /credit-memo/status/{id_or_ref}Alias específico para NC (05) — devuelve info adicional del CCF ajustado
GET /suex/status/{id_or_ref}Sujeto Excluido (14)
GET /invalidate/status/{id_or_ref}Estado de invalidación de venta/CCF
GET /invalidate/suex/status/{id_or_ref}Estado de invalidación de SUEX

Endpoint principal: /status/{id_or_ref}​

El más usado. Sirve para cualquier documento de venta (incluyendo NC, aunque para NC el endpoint dedicado /credit-memo/status trae metadatos extra).

Detalles técnicos​

MétodoGET
URLhttps://ocote.io/api/connect/status/{id_or_ref}
Query paramsinclude_dte (bool, default false)
AutenticaciónHeader Authorization: Bearer odt_...

Query param include_dte​

Por defecto el response no incluye el DTE firmado completo ni la respuesta cruda de MH — esos campos pueden ser varios KB y la mayoría de consultas (polling, conciliación) no los necesitan. Agrégalos explícitamente solo cuando los necesites:

GET /api/connect/status/VENTA-2026-0042?include_dte=1

Con include_dte=1, el response incluye dos campos adicionales:

  • schema (object) — el JSON firmado completo del DTE.
  • response (object) — la respuesta cruda del MH (sello o estructura de rechazo).

Ejemplo​

curl
curl "https://ocote.io/api/connect/status/VENTA-2026-0042" \
  -H "Authorization: Bearer odt_xxx"
Node.js (axios)
const { data } = await axios.get(
  'https://ocote.io/api/connect/status/VENTA-2026-0042',
  { headers: { Authorization: `Bearer ${process.env.OCOTE_API_KEY}` } }
);
Python (requests)
r = requests.get(
    "https://ocote.io/api/connect/status/VENTA-2026-0042",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

Response​

{
  "document_id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "external_ref": "VENTA-2026-0042",
  "doc_type": "01",
  "control_number": "DTE-01-M001P001-000000000000123",
  "reception_stamp": "20260421154532...",

  "success": true,
  "posted": true,
  "invalidated": false,

  "customer_name": "Juan Pérez",
  "created": "2026-04-21T10:42:00-06:00",
  "posted_date": "2026-04-21T10:42:15-06:00",

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

  "amount":           9.00,
  "amount_ret":       0.00,

  "ticket_url": "https://ocote.io/api/connect/file/a1b2c3d4-.../...?type=ticket&key=odt_xxx",
  "json_url":   "https://ocote.io/api/connect/file/a1b2c3d4-.../...?type=json&key=odt_xxx",

  "dte_success": true,
  "contingency": false,
  "rejected": false,
  "dte_state": "",
  "dte_message": "",
  "observaciones": [],
  "codigo_msg": ""
}

Ver Respuestas y estados para la semántica completa de cada flag.

Campos deprecados​

amount y amount_ret son alias de amount_total y amount_retention respectivamente. Mantenidos por compatibilidad hacia atrás para clientes que ya consumen el endpoint. Para integraciones nuevas usa los nombres canónicos.

/credit-memo/status/{id_or_ref}​

Dedicado a Notas de Crédito. El response incluye referencias al CCF que esta NC ajustó:

{
  "document_id": "63e82935-9d98-43db-b2b8-bc669364885c",
  "external_ref": "NC-ENLACES-TEST-001",
  "doc_type": "05",
  "control_number": "DTE-05-M001P002-000000000000001",
  "reception_stamp": "20260421145823...",

  "success": true,
  "posted": true,

  "ccf_document_id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "ccf_external_ref": "CCF-ENLACES-TEST-001",
  "ccf_control_number": "DTE-03-M001P002-000000000000008",
  "ccf_adjusted_amount": 339.00,
  "ccf_fully_adjusted": false,

  "amount_taxable":   300.00,
  "amount_vat":        39.00,
  "amount_gross":     339.00,
  "amount_retention":   0.00,
  "amount_total":     339.00,

  "dte_success": true,
  "contingency": false,
  "rejected": false
}

Si consultas un CCF o una factura con /credit-memo/status/..., el API responde 404. El endpoint es específico para NC.

/suex/status/{id_or_ref}​

Dedicado a Sujeto Excluido. Los campos de montos son distintos:

{
  "document_id": "b2c3d4e5-...",
  "external_ref": "SUEX-2026-0015",
  "doc_type": "14",
  "control_number": "DTE-14-M001P001-000000000000015",

  "success": true,
  "posted": true,
  "invalidated": false,

  "amount":     1500.00,
  "amount_irs":  150.00,
  "total_pay":  1350.00,

  "suex_name": "Ana María González Rodríguez",
  "created": "2026-04-21T10:42:15-06:00",
  "posted_date": "2026-04-21T10:42:18-06:00",

  "invoice_url": "https://ocote.io/api/v2/suex-history/b2c3d4e5-.../file?type=invoice",
  "json_url":    "https://ocote.io/api/v2/suex-history/b2c3d4e5-.../file?type=json",

  "dte_success": true,
  "contingency": false,
  "rejected": false
}

Ver Sujeto Excluido (14) para el detalle de amount_irs (retención renta 10%) y total_pay (neto a transferir al sujeto).

Endpoints de estado de invalidación​

Tras invalidar un documento, puedes consultar el estado de esa operación específica (distinta del estado general del documento).

/invalidate/status/{id_or_ref} (ventas)​

Devuelve si la invalidación fue exitosa, si generó NC automática, y el estado MH de la invalidación.

curl "https://ocote.io/api/connect/invalidate/status/VENTA-2026-0042" \
  -H "Authorization: Bearer odt_xxx"

Campos relevantes del response:

CampoDescripción
invalidatedtrue si el documento fue marcado como invalidado.
created_credit_memotrue si se generó NC automática (caso CCF fuera de ventana).
credit_memo_id, credit_memo_control_numberIDs de la NC generada.
dte_successEl MH aceptó la invalidación.
contingency, rejectedEstado de la invalidación en MH.

/invalidate/suex/status/{id_or_ref} (SUEX)​

Misma estructura, sin el bloque de credit_memo_* (SUEX no usa NC).

Uso recomendado​

  • Tras emitir un documento exitosamente, no necesitas consultar — el response del POST ya trae todo.
  • Para documentos en contingencia, polling cada hora es suficiente. Ver Contingencia > Polling responsable.
  • Para conciliar documentos en tu BD contra Ocote, itera sobre tus external_ref y consulta cada uno — no hay endpoint batch.
  • No uses /status como reemplazo de tu BD. Persiste los document_id/external_ref localmente; el API está para consultas puntuales, no para ser tu fuente de verdad primaria.

Ver también​