Tutorial: Generar nota de remisión (Manual)

Este tutorial explica cómo emitir una nota de remisión electrónica en modo manual: enviás en una sola llamada todos los datos (cliente, transportista, chofer, transporte, vehículo, salida, destino e ítems con mercaderías y/o servicios). No se usa un carrito existente; los ítems se envían como objetos completos dentro de items.mercaderias e items.servicios.

Podés emitir la nota sin documento asociado, con documento electrónico asociado (CDC ya emitido) o con documento manual asociado (factura impresa).

Entorno

URL Base: https://api.guarani.app

¿Qué vamos a hacer?

Consultar el timbrado (autorización de la SET)
Construir el body completo (datos de emisión, cliente, transportista, chofer, transporte, vehículo, salida, destino e ítems)
Enviar todo al endpoint de nota de remisión manual

Endpoint: POST /simplificado/notas/remision/manual

Paso 1: Consultar el timbrado

¿Por qué necesitás consultar el timbrado?

El timbrado es la autorización que te da la SET (Secretaría de Estado de Tributación) para emitir documentos electrónicos. Contiene información importante que necesitás incluir en cada nota de remisión:

numero_timbrado: El número de autorización de la SET
numero_establecimiento: El código de tu local o sucursal
punto_expedicion: El punto desde donde emitís los documentos

¿Cómo consultar el timbrado?

Hacé una consulta al endpoint de timbrados:

curl -X GET "https://api.guarani.app/timbrados?page=1&limit=100" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | jq

Nota: Reemplazá <access_token> con un token JWT válido proporcionado por el equipo Guarani.

Para más información sobre timbrados, consultá la documentación completa en Obtener lista de timbrados.

Paso 2: Estructura del body (nota remisión manual)

En el flujo manual no hay carrito: enviás cliente completo y items como objeto con arrays mercaderias y servicios, cada uno con todos los datos del producto o servicio.

datos_emision

Campo	Tipo	Requerido	Descripción
`numero_timbrado`	string	Sí	Número de timbrado.
`punto_expedicion`	string	Sí	Punto de expedición.
`numero_establecimiento`	string	Sí	Número de establecimiento.

cliente

Datos del cliente receptor de la remisión.

Campo	Tipo	Requerido	Descripción
`tipo_persona`	number	Sí	Tipo de persona (ver Tipos de personas).
`tipo_documento`	number	Sí	Tipo de documento (ver Tipos de documentos).
`documento`	string	Sí	Número de documento.
`nombre`	string	Sí	Nombre completo.
`nombre_fantasia`	string	No	Nombre de fantasía.
`nacionalidad`	string	Sí	Código de nacionalidad (ej. PRY).
`fecha_nacimiento`	string	No	Fecha de nacimiento (formato DD/MM/YYYY).
`whatsapp`	string	No	WhatsApp (ej. +595981234567).
`email`	string	No	Email.
`direccion`	string	No	Dirección.
`numero_casa`	string	No	Número de casa.
`barrio`	string	No	Barrio.
`ciudad_id`	string	Sí	UUID de la ciudad (ver `ciudades`).

Datos generales (raíz)

Campo	Tipo	Requerido	Descripción
`jsonDE`	boolean	No	Si `true`, respuesta incluye XML.
`motivo_codigo`	number	Sí	Código del motivo del traslado (ver Motivo código).
`factura_fecha_futura_emision`	string	No	Fecha de emisión de la factura (formato DD/MM/YYYY).
`responsable_emision`	number	Sí	Quién es responsable de la emisión (ver Responsable de emisión).
`kilometros_estimados`	number	Sí	Kilómetros estimados.
`transportista`	object	Sí	Datos transportista (como cliente).

transportista

Campo	Tipo	Requerido	Descripción
`tipo_persona`	number	Sí	Tipo de persona (ver Tipos de personas).
`tipo_documento`	number	Sí	Tipo de documento (ver Tipos de documentos).
`documento`	string	Sí	Número de documento.
`nombre`	string	Sí	Nombre completo.
`nombre_fantasia`	string	No	Nombre de fantasía.
`nacionalidad`	string	Sí	Código de nacionalidad (ej. PRY).
`fecha_nacimiento`	string	No	Fecha de nacimiento (formato DD/MM/YYYY).
`whatsapp`	string	No	WhatsApp (ej. +595981234567).
`email`	string	No	Email.
`direccion`	string	No	Dirección.
`numero_casa`	string	No	Número de casa.
`barrio`	string	No	Barrio.
`ciudad_id`	string	Sí	UUID de la ciudad (ver `ciudades`).

chofer

Campo	Tipo	Requerido	Descripción
`numero_documento`	string	Sí	Número de documento (CI u otro).
`nombre`	string	Sí	Nombre completo del chofer.
`domicilio_fiscal`	string	Sí	Domicilio fiscal del chofer.

transporte

Campo	Tipo	Requerido	Descripción
`tipo`	number	Sí	Tipo de transporte (ver Tipo de transporte).
`modalidad`	number	Sí	Modalidad del transporte (ver Modalidad de transporte).
`responsable_costo_flete`	number	Sí	Quién asume el costo del flete (ver Responsable costo flete).
`codigo_condicion_negocio`	string	Sí	Código de la condición de negocio (ver Códigos de las condiciones de negocio). Ej. “FOB”, “CIF”.
`fecha_inicio_traslado`	string	Sí	Fecha de inicio (DD/MM/YYYY).
`fecha_fin_traslado`	string	Sí	Fecha de fin (DD/MM/YYYY).

vehiculo

Campo	Tipo	Requerido	Descripción
`tipo_vehiculo`	number	Sí	Tipo de vehículo (ver Tipos de vehiculos).
`marca`	string	Sí	Marca del vehículo.
`tipo_identificacion`	number	Sí	Tipo de identificación (ver Tipo de identificación del vehiculo).
`numero_identificacion`	string	Condicional	Si `tipo_identificacion` es 1, obligatorio. Número de identificación del vehículo.
`numero_matricula`	string	Condicional	Si `tipo_identificacion` es 2, obligatorio. Número de matrícula del vehículo.

salida y destino

Para ambos:

Campo	Tipo	Requerido	Descripción
`direccion`	string	Sí	Dirección.
`ciudad_id`	string	Sí	UUID de la ciudad.
`whatsapp`	string	No	WhatsApp (ej. +595981234567).

Documento asociado (opcional)

La nota de remisión puede ir sin documento asociado, o asociada a un documento electrónico (por CDC) o a un documento manual (impreso). Solo podés enviar uno de los dos cuando querés asociar: documento_electronico o documento_manual, no ambos.

Importante: el documento asociado va dentro del objeto principal del body: documento_electronico o documento_manual son propiedades del mismo JSON que contiene datos_emision, cliente, transporte, items, etc. (mismo nivel, no anidados en otro objeto).

No enviés nunca documento_electronico y documento_manual en el mismo request. Solo uno de los dos, o ninguno.

Sin documentos asociados

No enviás ni documento_electronico ni documento_manual. Es el caso por defecto cuando la remisión no está vinculada a una factura previa.

Con documento electrónico asociado

Cuando la remisión se asocia a una factura (u otro DE) ya emitida en el sistema, enviás el objeto documento_electronico con el CDC de ese documento:

Campo	Tipo	Requerido	Descripción
`cdc`	string	Sí	Código de control del documento (44 caracteres).

Ejemplo:

"documento_electronico": {
  "cdc": "01801580404001002000092212026020516358891390"
}

Con documento manual asociado

Cuando la remisión se asocia a una factura impresa (no electrónica), enviás el objeto documento_manual con los datos del documento impreso:

Ver Tipos de documentos impresos asociados para tipo_documento_impreso.

Campo	Tipo	Requerido	Descripción
`numero_timbrado`	string	Sí	Número de timbrado del documento asociado.
`numero_establecimiento`	string	Sí	Número de establecimiento.
`punto_expedicion`	string	Sí	Punto de expedición.
`numero_documento`	string	Sí	Número del documento (ej. “0000007”).
`fecha_emision`	string	Sí	Fecha de emisión (DD/MM/YYYY).
`tipo_documento_impreso`	number	Sí	Tipo documento impreso (1-4, ver tablas).

Ejemplo:

"documento_manual": {
  "numero_timbrado": "12345678",
  "numero_establecimiento": "001",
  "punto_expedicion": "001",
  "numero_documento": "0000007",
  "fecha_emision": "17/03/2025",
  "tipo_documento_impreso": 1
}

items (objeto con mercaderias y servicios)

En el flujo manual, items es un objeto con dos propiedades: mercaderias (array) y servicios (array). No se repite la palabra “mercaderia” o “servicio” en cada elemento; cada elemento es directamente el objeto de producto o servicio.

items.mercaderias (array)

Cada elemento del array es un objeto con los siguientes campos:

Campo	Tipo	Requerido	Descripción
`codigo_interno`	string	Sí	Formato `01-` + 7 caracteres (mercadería; ver Código interno). Ej: `01-1234567`.
`codigo_original`	string	Sí	Código original del producto.
`codigo_barra`	string	Sí	Código de barra.
`codigo_fabricante`	string	Sí	Código del fabricante.
`descripcion`	string	Sí	Descripción.
`descripcion_larga`	string	Sí	Descripción larga.
`observacion`	string	Sí	Observación.
`unidad_medida_venta_id`	string	Sí	UUID de la unidad de medida (ver Unidades de medida de venta).
`marca`	string	Sí	Marca.
`clasificacion`	object	Sí	`{ "codigo": "01", "nombre": "Electrónica" }`.
`cantidad`	number	Sí	Cantidad (mayor a 0).
`precio_unitario_original`	number	Sí	Precio unitario original.
`precio_unitario`	object	Sí	Precios por tasa IVA: `{ "0": number, "5": number, "10": number }`.

items.servicios (array)

Si incluís servicios, cada elemento sigue la estructura de servicio.

Campo	Tipo	Requerido	Descripción
`codigo_interno`	string	Sí	Formato `02-` + 7 caracteres (servicio; ver Código interno). Ej: `02-1234567`.
`descripcion`	string	Sí	Descripción.
`descripcion_larga`	string	Sí	Descripción larga.
`observacion`	string	Sí	Observación.
`unidad_medida_venta_id`	string	Sí	UUID de la unidad de medida (ver Unidades de medida de venta).
`clasificacion`	object	Sí	`{ "codigo": "01", "nombre": "Electrónica" }`.
`cantidad`	number	Sí	Cantidad (mayor a 0).
`precio_unitario_original`	number	Sí	Precio unitario original.
`precio_unitario`	object	Sí	Precios por tasa IVA: `{ "0": number, "5": number, "10": number }`.

Paso 3: Envío completo (una sola llamada)

Juntás todos los objetos anteriores en un solo JSON y enviás a POST /simplificado/notas/remision/manual.

Asegurate de usar exactamente los nombres de las propiedades que figuran en el Paso 1. En el vehículo: si tipo_identificacion es 1 enviá numero_identificacion; si es 2 enviá numero_matricula. Un typo en una clave puede hacer que la API rechace el body o interprete mal el dato.

Ejemplo de body completo (sin documentos asociados)

En este ejemplo no se envía ni documento_electronico ni documento_manual.

{
  "jsonDE": false,
  "datos_emision": {
    "numero_timbrado": "12345678",
    "punto_expedicion": "001",
    "numero_establecimiento": "001"
  },
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "1234567-8",
    "nombre": "Cliente Ejemplo",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Barrio Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "motivo_codigo": 1,
  "factura_fecha_futura_emision": "02/02/2026",
  "responsable_emision": 1,
  "kilometros_estimados": 12,
  "transportista": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "1234567-8",
    "nombre": "Transportista Ejemplo",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Barrio Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "chofer": {
    "numero_documento": "1234567",
    "nombre": "Chofer Ejemplo",
    "domicilio_fiscal": "Domicilio fiscal del chofer"
  },
  "transporte": {
    "tipo": 1,
    "modalidad": 1,
    "responsable_costo_flete": 1,
    "codigo_condicion_negocio": "FOB",
    "fecha_inicio_traslado": "02/02/2026",
    "fecha_fin_traslado": "02/02/2026"
  },
  "vehiculo": {
    "tipo_vehiculo": 1,
    "marca": "TOYOTA",
    "tipo_identificacion": 2,
    "numero_matricula": "ABC123"
  },
  "salida": {
    "direccion": "Dirección de salida Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
    "whatsapp": "+595981234567"
  },
  "destino": {
    "direccion": "Dirección de destino Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
    "whatsapp": "+595981234567"
  },
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "01-1234567",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Mercadería Ejemplo",
        "descripcion_larga": "Mercadería Ejemplo con descripción larga",
        "observacion": "Observación Ejemplo",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "Marca Ejemplo",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Clasificación Ejemplo"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ],
    "servicios": []
  }
}

Ejemplo con curl (sin documentos asociados)

curl -X POST 'https://api.guarani.app/simplificado/notas/remision/manual' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: Bearer <access_token>' \
  -d '{
    "jsonDE": false,
    "datos_emision": {
      "numero_timbrado": "12345678",
      "punto_expedicion": "001",
      "numero_establecimiento": "001"
    },
    "cliente": {
      "tipo_persona": 1,
      "tipo_documento": 0,
      "documento": "1234567-8",
      "nombre": "Cliente Ejemplo",
      "nombre_fantasia": "",
      "nacionalidad": "PRY",
      "fecha_nacimiento": "11/09/2025",
      "whatsapp": "+595981234567",
      "email": "[email protected]",
      "direccion": "Av. ejemplo",
      "numero_casa": "789",
      "barrio": "Barrio Ejemplo",
      "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
    },
    "motivo_codigo": 1,
    "factura_fecha_futura_emision": "02/02/2026",
    "responsable_emision": 1,
    "kilometros_estimados": 12,
    "transportista": {
      "tipo_persona": 1,
      "tipo_documento": 0,
      "documento": "1234567-8",
      "nombre": "Transportista Ejemplo",
      "nombre_fantasia": "",
      "nacionalidad": "PRY",
      "fecha_nacimiento": "11/09/2025",
      "whatsapp": "+595981234567",
      "email": "[email protected]",
      "direccion": "Av. ejemplo",
      "numero_casa": "789",
      "barrio": "Barrio Ejemplo",
      "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
    },
    "chofer": {
      "numero_documento": "1234567",
      "nombre": "Chofer Ejemplo",
      "domicilio_fiscal": "Domicilio fiscal del chofer"
    },
    "transporte": {
      "tipo": 1,
      "modalidad": 1,
      "responsable_costo_flete": 1,
      "codigo_condicion_negocio": "FOB",
      "fecha_inicio_traslado": "02/02/2026",
      "fecha_fin_traslado": "02/02/2026"
    },
    "vehiculo": {
      "tipo_vehiculo": 1,
      "marca": "TOYOTA",
      "tipo_identificacion": 2,
      "numero_matricula": "ABC123"
    },
    "salida": {
      "direccion": "Dirección de salida Ejemplo",
      "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
      "whatsapp": "+595981234567"
    },
    "destino": {
      "direccion": "Dirección de destino Ejemplo",
      "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
      "whatsapp": "+595981234567"
    },
    "items": {
      "mercaderias": [
        {
          "codigo_interno": "01-1234567",
          "codigo_original": "01-1234567",
          "codigo_barra": "7891234567890",
          "codigo_fabricante": "FAB123",
          "descripcion": "Mercadería Ejemplo",
          "descripcion_larga": "Mercadería Ejemplo con descripción larga",
          "observacion": "Observación Ejemplo",
          "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
          "marca": "Marca Ejemplo",
          "clasificacion": {
            "codigo": "01",
            "nombre": "Clasificación Ejemplo"
          },
          "cantidad": 1,
          "precio_unitario_original": 100000,
          "precio_unitario": {
            "0": 0,
            "5": 0,
            "10": 100000
          }
        }
      ],
      "servicios": []
    }
  }'

Reemplazá <access_token> por tu token JWT válido.

Ejemplo completo: con documento electrónico asociado

Mismo body que el ejemplo sin documentos, pero agregando el objeto documento_electronico en el objeto principal (entre destino e items):

{
  "jsonDE": false,
  "datos_emision": {
    "numero_timbrado": "12345678",
    "punto_expedicion": "001",
    "numero_establecimiento": "001"
  },
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "1234567-8",
    "nombre": "Cliente Ejemplo",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Barrio Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "motivo_codigo": 1,
  "factura_fecha_futura_emision": "02/02/2026",
  "responsable_emision": 1,
  "kilometros_estimados": 12,
  "transportista": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "1234567-8",
    "nombre": "Transportista Ejemplo",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Barrio Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "chofer": {
    "numero_documento": "1234567",
    "nombre": "Chofer Ejemplo",
    "domicilio_fiscal": "Domicilio fiscal del chofer"
  },
  "transporte": {
    "tipo": 1,
    "modalidad": 1,
    "responsable_costo_flete": 1,
    "codigo_condicion_negocio": "FOB",
    "fecha_inicio_traslado": "02/02/2026",
    "fecha_fin_traslado": "02/02/2026"
  },
  "vehiculo": {
    "tipo_vehiculo": 1,
    "marca": "TOYOTA",
    "tipo_identificacion": 2,
    "numero_matricula": "ABC123"
  },
  "salida": {
    "direccion": "Dirección de salida Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
    "whatsapp": "+595981234567"
  },
  "destino": {
    "direccion": "Dirección de destino Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
    "whatsapp": "+595981234567"
  },
  "documento_electronico": {
    "cdc": "01801580404001002000092212026020516358891390"
  },
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "01-1234567",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Mercadería Ejemplo",
        "descripcion_larga": "Mercadería Ejemplo con descripción larga",
        "observacion": "Observación Ejemplo",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "Marca Ejemplo",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Clasificación Ejemplo"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ],
    "servicios": []
  }
}

El cdc debe ser el código de control (44 caracteres) del documento electrónico al que se asocia la remisión.

Ejemplo completo: con documento manual (físico) asociado

Mismo body que el ejemplo sin documentos, pero agregando el objeto documento_manual en el objeto principal (entre destino e items):

{
  "jsonDE": false,
  "datos_emision": {
    "numero_timbrado": "12345678",
    "punto_expedicion": "001",
    "numero_establecimiento": "001"
  },
  "cliente": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "1234567-8",
    "nombre": "Cliente Ejemplo",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Barrio Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "motivo_codigo": 1,
  "factura_fecha_futura_emision": "02/02/2026",
  "responsable_emision": 1,
  "kilometros_estimados": 12,
  "transportista": {
    "tipo_persona": 1,
    "tipo_documento": 0,
    "documento": "1234567-8",
    "nombre": "Transportista Ejemplo",
    "nombre_fantasia": "",
    "nacionalidad": "PRY",
    "fecha_nacimiento": "11/09/2025",
    "whatsapp": "+595981234567",
    "email": "[email protected]",
    "direccion": "Av. ejemplo",
    "numero_casa": "789",
    "barrio": "Barrio Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341"
  },
  "chofer": {
    "numero_documento": "1234567",
    "nombre": "Chofer Ejemplo",
    "domicilio_fiscal": "Domicilio fiscal del chofer"
  },
  "transporte": {
    "tipo": 1,
    "modalidad": 1,
    "responsable_costo_flete": 1,
    "codigo_condicion_negocio": "FOB",
    "fecha_inicio_traslado": "02/02/2026",
    "fecha_fin_traslado": "02/02/2026"
  },
  "vehiculo": {
    "tipo_vehiculo": 1,
    "marca": "TOYOTA",
    "tipo_identificacion": 2,
    "numero_matricula": "ABC123"
  },
  "salida": {
    "direccion": "Dirección de salida Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
    "whatsapp": "+595981234567"
  },
  "destino": {
    "direccion": "Dirección de destino Ejemplo",
    "ciudad_id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
    "whatsapp": "+595981234567"
  },
  "documento_manual": {
    "numero_timbrado": "12345678",
    "numero_establecimiento": "001",
    "punto_expedicion": "001",
    "numero_documento": "0000007",
    "fecha_emision": "17/03/2025",
    "tipo_documento_impreso": 1
  },
  "items": {
    "mercaderias": [
      {
        "codigo_interno": "01-1234567",
        "codigo_original": "01-1234567",
        "codigo_barra": "7891234567890",
        "codigo_fabricante": "FAB123",
        "descripcion": "Mercadería Ejemplo",
        "descripcion_larga": "Mercadería Ejemplo con descripción larga",
        "observacion": "Observación Ejemplo",
        "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "marca": "Marca Ejemplo",
        "clasificacion": {
          "codigo": "01",
          "nombre": "Clasificación Ejemplo"
        },
        "cantidad": 1,
        "precio_unitario_original": 100000,
        "precio_unitario": {
          "0": 0,
          "5": 0,
          "10": 100000
        }
      }
    ],
    "servicios": []
  }
}

tipo_documento_impreso: 1 = Factura, 2 = Nota de crédito, 3 = Nota de débito, 4 = Nota de remisión (ver tablas).

Incluir documento electrónico en el body

Si la remisión se asocia a una factura (u otro DE) ya emitida, agregá en el body el objeto documento_electronico (mismo nivel que datos_emision, cliente, etc.). El resto del body es igual al ejemplo anterior. Ejemplo del bloque a agregar:

"documento_electronico": {
  "cdc": "01801580404001002000092212026020516358891390"
}

Reemplazá el valor de cdc por el código de control del documento al que querés asociar la remisión (44 caracteres). No enviés documento_manual si enviás documento_electronico.

Incluir documento manual en el body

Si la remisión se asocia a una factura impresa, agregá en el body el objeto documento_manual (mismo nivel que datos_emision, cliente, etc.). El resto del body es igual. Ejemplo del bloque a agregar:

"documento_manual": {
  "numero_timbrado": "12345678",
  "numero_establecimiento": "001",
  "punto_expedicion": "001",
  "numero_documento": "0000007",
  "fecha_emision": "17/03/2025",
  "tipo_documento_impreso": 1
}

El campo tipo_documento_impreso usa los códigos de Tipos de documentos impresos asociados (1: Factura, 2: Nota de crédito, 3: Nota de débito, 4: Nota de remisión). No enviés documento_electronico si enviás documento_manual.

Ejemplo de respuesta

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "numero_timbrado": "12345678",
    "numero_documento": "002-001-0000001",
    "serie": "AA",
    "cdc": "018015804040010020000182120251028149230824767",
    "estado_sifen": {
      "estado": "Aprobado",
      "mensaje": "Autorización del DE satisfactoria"
    },
    "xml": "https://api.guarani.app/sifen/xml/018015804040010020000182120251028149230824767",
    "qr": "https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&Id=..."
  }
}

Después de emitir, podés consultar el estado del documento con GET /sifen/consultas/estado/cdc/{cdc} (ver ejemplos de estado Aprobado/Rechazado/Pendiente en el tutorial desde carrito).

Resumen

Consultás el timbrado para obtener numero_timbrado, numero_establecimiento y punto_expedicion.
Construís el body completo con datos_emision, cliente, transportista, chofer, transporte, vehículo, salida, destino e items.
Enviás todo a POST /simplificado/notas/remision/manual.

Notas adicionales:

Documento asociado (opcional): sin documento, con documento_electronico (CDC) o con documento_manual (datos de factura impresa). Solo uno de los dos cuando se asocia.
jsonDE (opcional): si es true, la respuesta incluye el XML del DE en JSON.

¿Dónde encontrar más información?

Si algo sale mal: (ver Tabla de errores)
Tablas de referencia (códigos usados en este tutorial):
- Tipos de documentos — tipo_documento en cliente y transportista
- Tipos de personas — tipo_persona en cliente y transportista
- Motivo código de la nota de remisión — motivo_codigo
- Responsable de emisión de la nota de remisión — responsable_emision
- Tipo de transporte — transporte.tipo
- Modalidad de transporte — transporte.modalidad
- Responsable costo flete — transporte.responsable_costo_flete
- Códigos de las condiciones de negocio — transporte.codigo_condicion_negocio
- Tipos de vehiculos — vehiculo.tipo_vehiculo
- Tipo de identificación del vehiculo — vehiculo.tipo_identificacion
- Código interno — prefijo 01 (mercadería) y 02 (servicio) en items.mercaderias / items.servicios
- Tipos de documentos impresos asociados — documento_manual.tipo_documento_impreso
- Tablas de referencia (índice completo)

Antes de enviar: checklist

Revisá estos puntos antes de llamar a POST /simplificado/notas/remision/manual:

Header — Enviás Content-Type: application/json y x-api-key: Bearer <tu_token>.
Objeto único — Todo va en un solo JSON; documento_electronico o documento_manual (si los usás) están al mismo nivel que datos_emision, cliente, items, etc., no dentro de otro objeto.
Documento asociado — Si asociás documento: solo uno de los dos (documento_electronico o documento_manual), nunca los dos juntos.
Items — items es un objeto con mercaderias y servicios (arrays). Al menos uno de los dos con al menos un elemento. Cada mercadería tiene codigo_interno tipo 01-XXXXXXX, cada servicio 02-XXXXXXX.
Fechas — Formato DD/MM/YYYY (ej. 02/02/2026).
Teléfonos — Con código país, ej. +595981234567.
CDC (si usás documento electrónico) — Exactamente 44 caracteres, sin espacios.
IDs — ciudad_id y unidad_medida_venta_id son UUIDs válidos (podés obtenerlos con GET /ciudades y catálogos correspondientes).

Consejos que te van a ayudar

Usá el formato de fechas DD/MM/YYYY y teléfonos con código país (ej. +595981234567).
Obtené ciudad_id con GET /ciudades si no lo tenés (ver obtener ciudad ID).
El codigo_interno de mercaderías debe ser 01- + 7 caracteres; el de servicios 02- + 7 caracteres (ver Código interno).
En items podés enviar solo mercaderias, solo servicios, o ambos; al menos uno debe tener al menos un elemento.
Si la API devuelve error, revisá el mensaje y la tabla de errores; si tenés dudas sobre códigos, revisá las tablas de referencia.