Desarrolladores API v1

Endpoints de la API. Especificación exacta de cada operación de la API v1 (parámetros, cuerpo, respuestas y ejemplos), generada del documento OpenAPI con el que se valida cada respuesta real. Los procedimientos completos están en Guías.

POST /entry-documents

Crear un documento de entrada

Manda a recibir mercancía (orden de compra, entrada). Se valida con las mismas reglas que la plantilla de carga masiva: productos, almacén, ubicación destino, lotes y series. La cabecera Idempotency-Key es obligatoria.

Si ya existe un documento del mismo type con ese external_ref, responde 200 con ese documento en lugar de crear otro; uno nuevo responde 201.

Alcance (cliente de integración)
receipts:write
Permiso (token de usuario)
entries.manage
Idempotency-Key
Obligatoria

Cabeceras

  • Idempotency-Key string obligatorio

    Obligatoria en esta ruta. Llave única por operación (UUID v4); los reintentos repiten la misma.

Cuerpo de la solicitud application/json

  • external_ref string obligatorio

    Referencia externa (folio del ERP). Con el mismo type, no se crea dos veces.

  • type string obligatorio

    Tipo de documento: la clave (purchase_order) o su nombre (Orden de Compra).

  • doc_date string obligatorio

    Fecha del documento: AAAA-MM-DD o dd/mm/aaaa.

  • due_date string | null
  • partner_code string obligatorio

    Código del proveedor o del cliente.

  • partner_name string | null
  • warehouse_code string obligatorio
  • comments string | null
  • lines array de objetos obligatorio
    6 campos de lines
    • item_code string obligatorio
    • qty number obligatorio
    • batch string | null

      Lote (obligatorio si el producto se maneja por lotes al recibir).

    • expiry_date string | null
    • serials array de textos | null
    • destination_bin string | null

      Ubicación destino (solo entradas).

Respuestas

200 Ya existía un documento con ese type y external_ref; se devuelve ese.
  • data objeto obligatorio
    14 campos de data
    • id integer obligatorio
    • doc_num string | null obligatorio
    • type string obligatorio
    • external_ref string | null
    • source string | null

      api, import, web o sap.

    • status string | null obligatorio
    • card_code string | null
    • card_name string | null
    • doc_date string (date) | null
    • due_date string (date) | null
    • comments string | null
    • created_at string (date-time) | null
    • updated_at string (date-time) | null
    • lines array de objetos obligatorio
      7 campos de lines
      • line_num integer | null
      • item_code string | null obligatorio
      • qty number obligatorio
      • open_qty number obligatorio

        Lo que falta por recibir.

      • received_qty number obligatorio
      • whs_code string | null
      • status string | null
201 Documento creado. Location apunta al nuevo recurso.
  • data objeto obligatorio
    14 campos de data
    • id integer obligatorio
    • doc_num string | null obligatorio
    • type string obligatorio
    • external_ref string | null
    • source string | null

      api, import, web o sap.

    • status string | null obligatorio
    • card_code string | null
    • card_name string | null
    • doc_date string (date) | null
    • due_date string (date) | null
    • comments string | null
    • created_at string (date-time) | null
    • updated_at string (date-time) | null
    • lines array de objetos obligatorio
      7 campos de lines
      • line_num integer | null
      • item_code string | null obligatorio
      • qty number obligatorio
      • open_qty number obligatorio

        Lo que falta por recibir.

      • received_qty number obligatorio
      • whs_code string | null
      • status string | null
400 Falta la cabecera Idempotency-Key.

Cuerpo: el sobre de error.

401 Falta el token o no es válido.

Cuerpo: el sobre de error.

402 La función no está en el plan de la empresa, o la cuenta está suspendida o cancelada.

Cuerpo: el sobre de error.

403 Al cliente le falta el alcance (missing_scope), al usuario el permiso (forbidden), o el token de usuario no tiene acceso a la ruta (client_not_allowed: aplicación móvil o usuario con verificación en dos pasos).

Cuerpo: el sobre de error.

409 Otra solicitud con la misma Idempotency-Key sigue en proceso.

Cuerpo: el sobre de error.

422 Datos no válidos (validation_failed), una llave de idempotencia reutilizada con otra solicitud (idempotency_key_reused) o una regla de negocio que bloquea la operación (rule_blocked).

Cuerpo: el sobre de error.

429 Se superó el límite por minuto. Reintente después de los segundos de Retry-After.

Cuerpo: el sobre de error.

Probar

Probar con una instancia

La solicitud sale del navegador hacia la instancia indicada; nada pasa por chainlink.mx. El token se conserva solo en esta pestaña.

Obtener un token con un cliente de integración

Credenciales de Configuración › Clientes API (grant client_credentials). El secreto se usa una vez y no se guarda. Los tokens de usuario se obtienen fuera de la consola; ver Autenticación.

Solicitud 
curl -X POST "https://empresa.chainlink.mx/api/v1/entry-documents" \
  -H "Authorization: Bearer $CHAINLINK_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "OC-2026-0042",
    "type": "Orden de Compra",
    "doc_date": "2026-10-06",
    "due_date": "2026-10-09",
    "partner_code": "PRV-001",
    "partner_name": "Distribuidora del Bajío",
    "warehouse_code": "CEDIS-GDL",
    "lines": [
        {
            "item_code": "P-1001",
            "qty": 48,
            "batch": "L2610",
            "expiry_date": "2027-04-30",
            "destination_bin": "A-01-01-1"
        },
        {
            "item_code": "P-1002",
            "qty": 120
        }
    ]
}'
Respuesta 
{
    "data": {
        "id": 1,
        "doc_num": "OC-000001",
        "type": "purchase_order",
        "external_ref": "OC-2026-0042",
        "source": "api",
        "status": "open",
        "card_code": "PRV-001",
        "card_name": null,
        "doc_date": "2026-10-06",
        "due_date": "2026-10-06",
        "comments": null,
        "lines": [
            {
                "line_num": 0,
                "item_code": "P-1001",
                "qty": 48,
                "open_qty": 48,
                "received_qty": 0,
                "whs_code": "CEDIS-GDL",
                "status": "open"
            },
            {
                "line_num": 1,
                "item_code": "P-1002",
                "qty": 120,
                "open_qty": 120,
                "received_qty": 0,
                "whs_code": "CEDIS-GDL",
                "status": "open"
            }
        ],
        "created_at": "2026-10-06T16:20:11.000000Z",
        "updated_at": "2026-10-06T16:20:11.000000Z"
    }
}