Pedidos

La integración permite enviar pedidos a NinoxNet.

Sucursal de la preventa

La preventa se crea en la sucursal del punto de venta configurado para tu integración, y esa sucursal tiene que estar dentro de las habilitadas para el canal. En la práctica esto solo falla si el administrador del ERP habilitó sucursales que no incluyen la del punto de venta del canal: es un aviso de configuración incoherente, no algo que dependa de lo que mandes en el body.

Si el canal no tiene sucursales cargadas, no se restringe nada: se usa la sucursal de sus depósitos o de su punto de venta.

Crear pedido

POST/integraciones/Terceros/Pedido

Request:

PedidoTerceros

Respuesta:

PedidoResultado

El detalle de ambos tipos está en Esquema de datos.

Según la configuración de tu integración, el pedido puede generar:

• un pedido de venta
• una preventa o reserva

Validación de totales

El campo total debe coincidir con la fórmula subtotal + envio + recargo - descuento. Si no cuadra, la API responde 200 con errores: true y datos.error igual a "Los totales no coinciden". Siempre revisá errores en la respuesta.

Idempotencia

Usá un ordenId único y estable por orden para poder reintentar sin duplicar. Persistí la correlación entre tu orden local y la respuesta de NinoxNet.

Vendedor del comprobante (opcional)

pedidoTerceros acepta un empleadoId opcional para atribuir el comprobante a un vendedor. Si no lo mandás se usa el vendedor por defecto configurado en tu integración. Los ids válidos salen de GET /empleados.

Cliente explícito (opcional)

pedidoTerceros acepta un entidadId opcional con el id de un cliente ya existente en NinoxNet. Si lo mandás, se usa esa entidad directo y no se busca por documento/CUIT/email ni se crea un cliente nuevo — en ese caso usuario pasa a ser opcional. Sin entidadId, seguís necesitando usuario con al menos dni, cuit o email para identificar o dar de alta al cliente; sin ninguno de los dos la API responde 400. Un entidadId que no corresponde a un cliente activo responde 403. Los ids válidos salen de GET /entidades.

Actualizar pedido

Un pedido se actualiza reenviando el mismo POST /pedido con el mismo ordenId. No hay un endpoint aparte: NinoxNet reconoce el ordenId, reemplaza el contenido del pedido (productos, totales, cliente, medio de pago y estado de pago) y conserva el mismo facturaId.

POST/integraciones/Terceros/Pedido

El body es el mismo que para crear el pedido y se manda completo: no hay actualización parcial, y lo que no mandes se pierde. Por ejemplo, para cambiar la cantidad de un producto reenviás todos los productos con la cantidad nueva y los totales recalculados.

Ejemplo: cambiar la cantidad de un producto

curl --request POST \
  --url https://api.test-ninox.com.ar/integraciones/terceros/pedido \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "ordenId": 12345,
    "numero": 12345,
    "detalle": "Pedido web - cantidad corregida",
    "usuario": {
      "nombre": "Juan Perez",
      "email": "juan@example.com",
      "dni": "12345678",
      "condicion": 1
    },
    "productos": [
      { "articuloId": 100, "precio": 1500.5, "cantidad": 3 }
    ],
    "subtotal": 4501.5,
    "descuento": 0,
    "recargo": 0,
    "envio": 500,
    "total": 5001.5
  }'

Respuesta (se muestran los campos que usa un pedido; el resto de PedidoResultado, como cae u observaciones, no aplica):

{
  "facturaId": 456,
  "numero": 12345,
  "pvNumero": 1,
  "estado": 0,
  "datos": {},
  "errores": false
}

El facturaId es el mismo que devolvió el alta. Es el que usás para cancelar, facturar o consultar el comprobante.

El estado de esta respuesta no es el del pedido

En la respuesta del alta y de la actualización estado viene en 0: no refleja el estado del pedido. Para conocerlo consultá GET /comprobante/{id}, campo estado.

Cuándo se puede actualizar

Estado del pedido	¿Se actualiza?
PENDIENTE o PAGADO	Sí
ANULADO (cancelado)	No
Ya facturado (comprobanteTipo = VENTA)	No

Si no se puede actualizar, la respuesta no es un error

Reenviar un pedido anulado o ya facturado responde 200 con los datos del pedido existente y errores: false, sin modificar nada. Si necesitás confirmar que el cambio se aplicó, consultá el pedido con GET /comprobante/{id}.

Reintentos: ventana de 30 segundos

Un reenvío con el mismo numero dentro de los 30 segundos del anterior (incluido el alta) responde 403 con "La solicitud ya se esta procesando". Esperá la ventana antes de actualizar.

Qué no se puede cambiar

El punto de venta sale siempre de la configuración de tu integración, así que no cambia con la actualización. Si el pedido ya entró en el circuito de despacho de NinoxNet, la actualización se rechaza: la respuesta trae errores: true y el motivo en datos.error.

Cancelar pedido

Anula el pedido. Aplica a pedidos PENDIENTE y PAGADO: libera el stock reservado y revierte el cobro registrado. El pedido no se borra, queda en estado ANULADO.

POST/integraciones/Terceros/Pedido/cancelar

Parámetros:

• facturaid (number): identificador del comprobante a cancelar. El nombre va en minúsculas.

Respuesta:

NxResultado

Ejemplo

curl --request POST \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/pedido/cancelar?facturaid=456' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Respuesta:

{
  "tipo": 1,
  "id": 0,
  "data": null,
  "valores": [],
  "mensajes": [],
  "errores": []
}

tipo: 1 indica que se canceló. Cuando no se puede, la API responde 200 igual y explica el motivo en mensajes:

Situación	tipo	mensajes
El facturaid no existe o es de otra integración	2	"No se encuentra el pedido"
El pedido ya está facturado	2	"El pedido no se puede cancelar porque no es una preventa"
El pedido ya estaba cancelado	2	"El pedido ya se encuentra anulado"
Error inesperado	0	"Error al cancelar el pedido"

Con el reparto entre varios depósitos activado en el canal, el pedido se cancela aunque la mercadería ya se haya transferido al depósito de despacho: queda libre en ese depósito. Si ya está en preparación, despachada o viajando entre depósitos, no se cancela y la respuesta es tipo: 0 con "Error al cancelar el pedido": hay que anularlo desde el ERP.

Una cancelación repetida dentro de los 30 segundos responde 403 con "La solicitud ya se esta procesando".

Estado del pedido

El estado de un pedido cambia con estas acciones de la API:

Acción	Cómo	Estado resultante
Crear o actualizar sin cobro	POST /pedido con pagado: false, o sin medioPago	PENDIENTE (1)
Crear o actualizar con cobro	POST /pedido con pagado: true y medioPago	PAGADO (101)
Cancelar	POST /pedido/cancelar	ANULADO (3)
Facturar	POST /facturar	FACTURADO (2)

Los valores de estado están en Enums y códigos. Para leer el estado actual de un pedido usá GET /comprobante/{id}.

PAGADO requiere gestión de pedidos y medio de pago

pagado: true deja el pedido en PAGADO solo si el pedido trae medioPago y la empresa tiene activa la gestión de pedidos online en NinoxNet. Si falta alguna de las dos cosas, el pedido queda PENDIENTE.

Ejemplo: marcar un pedido como pagado

Reenviá el pedido con pagado: true y el medioPago. El resto del body es el mismo que usaste al crearlo. Los medios soportados son EFECTIVO (1), DEPOSITO_BANCO (9, requiere cuentaBancariaId) y VIRTUAL (11). Las cuentas bancarias válidas salen de GET /medios-pago.

curl --request POST \
  --url https://api.test-ninox.com.ar/integraciones/terceros/pedido \
  --header 'X-NX-TOKEN: {TU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "ordenId": 12345,
    "numero": 12345,
    "detalle": "Pedido web - pago acreditado",
    "usuario": {
      "nombre": "Juan Perez",
      "email": "juan@example.com",
      "dni": "12345678",
      "condicion": 1
    },
    "productos": [
      { "articuloId": 100, "precio": 1500.5, "cantidad": 3 }
    ],
    "subtotal": 4501.5,
    "descuento": 0,
    "recargo": 0,
    "envio": 500,
    "total": 5001.5,
    "pagado": true,
    "medioPago": { "tipo": 9, "cuentaBancariaId": 12 }
  }'

Después de este reenvío, GET /comprobante/456 devuelve "estado": 101.

Para volver el pedido a PENDIENTE, reenvialo con pagado: false y sin medioPago: se deshace el cobro registrado.

Transiciones

 alta ──► PENDIENTE ◄──► PAGADO     (reenviando POST /pedido con pagado: true / false)
            │   │
            │   └── POST /facturar ──────────► FACTURADO   (ya no se actualiza ni se cancela)
            │
            └────── POST /pedido/cancelar ───► ANULADO     (final)

Un pedido ANULADO no se puede reactivar: para volver a enviarlo, creá uno nuevo con otro ordenId.

Consultar comprobante

Devuelve un comprobante creado por tu integración: preventa, venta o nota de crédito. Los tres salen por el mismo endpoint y se distinguen por comprobanteTipo.

GETBETA/integraciones/terceros/comprobante/{id}

Parámetros de ruta:

• id (number): el facturaId que devolvió el alta del comprobante

Respuesta:

Comprobante

Incluye cabecera, cliente, ítems, totales y medios de pago. El detalle está en Esquema de datos.

Solo tus comprobantes

El endpoint devuelve únicamente comprobantes creados por tu integración. Un id inexistente, de otra integración o cargado desde el ERP responde 404 — no 403, para no confirmar que ese comprobante existe en el sistema.

Para qué sirve en la práctica

Es la forma de reconciliar cuando perdiste la respuesta del alta (timeout, reintento, corte de red) o cuando necesitás el estado actual de una preventa antes de facturarla. Para volúmenes grandes seguí usando las exportaciones, que están pensadas para lote.

Ejemplo

curl --request GET \
  --url 'https://api.test-ninox.com.ar/integraciones/terceros/comprobante/12345' \
  --header 'X-NX-TOKEN: {TU_TOKEN}'

Ventas y facturación

Para crear una venta directa (sin preventa) o facturar una preventa existente, mirá Ventas (BETA).