Crear nota de crédito

Crea una nueva nota de crédito en el sistema. Existen dos endpoints diferentes según el origen de la nota de crédito:

1. POST /notas/credito: Para crear notas de crédito asociadas a un cliente, con documento asociado electrónico o físico (manual).
2. POST /notas/credito/carrito: Para crear notas de crédito asociadas a un carrito (factura) existente en el sistema.

---

Entorno

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

Endpoints

Endpoint 1: Crear nota de crédito con documento manual o electrónico asociado

POST /notas/credito

Endpoint 2: Crear nota de crédito asociada a un carrito (factura) existente

POST /notas/credito/carrito

---

Ejemplo de solicitud con cliente (documento físico)

# Nota de crédito con documento físico asociado
curl -X POST "https://api.guarani.app/notas/credito" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "cliente_id": "0906cbce-874c-4931-a5b1-c95a66a0ed99",
    "moneda": "PYG",
    "cotizacion": 1,
    "motivo_codigo": 2,
    "motivo_descripcion": "DEVOLUCION",
    "documento_asociado_tipo": 2,
    "documento_asociado_manual": {
        "numero_timbrado_documento_asociado": "12345678",
        "numero_establecimiento_documento_asociado": "001",
        "punto_expedicion_documento_asociado": "001",
        "fecha_emision_documento_asociado": "22/03/2025",
        "numero_documento_asociado": "0000001",
        "tipo_documento_impreso": 1
    }
  }' | jq

Ejemplo de solicitud con documento electrónico asociado

# Nota de crédito con documento electrónico asociado
curl -X POST "https://api.guarani.app/notas/credito" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "cliente_id": "0906cbce-874c-4931-a5b1-c95a66a0ed99",
    "moneda": "PYG",
    "cotizacion": 1,
    "motivo_codigo": 2,
    "motivo_descripcion": "DEVOLUCION",
    "documento_asociado_tipo": 1,
    "documento_asociado_electronico": {
      "cdc": "01234567890123456789012345678901234567890123"
    }
  }' | jq

Ejemplo de solicitud con carrito

# Nota de crédito asociada a un carrito (factura) existente
curl -X POST "https://api.guarani.app/notas/credito/carrito" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "carrito_id": "uuid-del-carrito-existente",
    "motivo_codigo": 2,
    "motivo_descripcion": "Error de emision"
  }' | jq

Nota: Asegúrate de reemplazar <access_token> con un token JWT válido proporcionado por el equipo Guarani. Importante:
Es imprescindible incluir un token de acceso válido en el encabezado x-api-key para autenticar y autorizar el uso de este endpoint. Sin este token, la solicitud será rechazada.

---

Encabezados de la solicitud

Encabezado	Valor	Descripción
Content-Type	application/json	Indica que los datos se envían en formato JSON.
x-api-key	Bearer <access_token>	Token de autenticación necesario para acceder al recurso.

Descripción de Campos

Campos para nota de crédito con documento físico asociado

Campo	Tipo	Requerido	Tamaño	Descripción
cliente_id	uuid	Sí	36	Identificador único del cliente asociado a la nota de crédito. ver (clientes)
motivo_codigo	number	Sí	1	Código del motivo de la nota de crédito. (ver tablas-referencias)
motivo_descripcion	string	Sí	6-30	Descripción del motivo de la nota de crédito. Describe el por qué se emitió la nota de crédito.
documento_asociado_tipo	number	Sí	1	Tipo de documento asociado. Debe ser 2 para documento físico. (ver tablas-referencias)
moneda	string	Sí	3	Código de moneda en formato ISO 4217. (ver tablas-referencias)
cotizacion	number	Sí	10	Cotización de la moneda respecto a Guaraníes. Debe ser mayor a 0. Si es Guaraníes, enviar 1.
documento_asociado_manual	object	Sí	-	Objeto con información del documento físico asociado. Requerido cuando documento_asociado_tipo es 2.

Campos del objeto documento_asociado_manual

Campo	Tipo	Requerido	Tamaño	Descripción
numero_timbrado_documento_asociado	string	Sí	8	Número de timbrado del documento asociado.
numero_establecimiento_documento_asociado	string	Sí	3	Número de establecimiento del documento asociado.
punto_expedicion_documento_asociado	string	Sí	3	Punto de expedición del documento asociado.
fecha_emision_documento_asociado	string	Sí	10	Fecha de emisión del documento asociado en formato DD/MM/YYYY.
numero_documento_asociado	string	Sí	7	Número del documento asociado.
tipo_documento_impreso	number	Sí	1	Tipo de documento impreso. (ver tablas-referencias)

---

Campos para nota de crédito con documento electrónico asociado

Campo	Tipo	Requerido	Tamaño	Descripción
cliente_id	uuid	Sí	36	Identificador único del cliente asociado a la nota de crédito. ver (clientes)
motivo_codigo	number	Sí	1	Código del motivo de la nota de crédito. (ver tablas-referencias)
motivo_descripcion	string	Sí	6-30	Descripción del motivo de la nota de crédito. Describe el por qué se emitió la nota de crédito.
documento_asociado_tipo	number	Sí	1	Tipo de documento asociado. Debe ser 1 para documento electrónico. (ver tablas-referencias)
moneda	string	Sí	3	Código de moneda en formato ISO 4217. (ver tablas-referencias)
cotizacion	number	Sí	10	Cotización de la moneda respecto a Guaraníes. Debe ser mayor a 0. Si es Guaraníes, enviar 1.
documento_asociado_electronico	object	Sí	-	Objeto con información del documento electrónico asociado. Requerido cuando documento_asociado_tipo es 1.

Campos del objeto documento_asociado_electronico

Campo	Tipo	Requerido	Tamaño	Descripción
cdc	string	Sí	44	Código de Control (CDC) del documento electrónico.

---

Campos para nota de crédito asociada a un carrito

Campos requeridos para el endpoint POST /notas/credito/carrito cuando se crea una nota de crédito a partir de un carrito (factura) existente.

Campo	Tipo	Requerido	Tamaño	Descripción
carrito_id	uuid	Sí	36	Identificador único del carrito (factura) asociado a la nota de crédito. El carrito debe estar aprobado en SIFEN. ver (carritos)
motivo_codigo	number	Sí	1	Código del motivo de la nota de crédito. (ver tablas-referencias)
motivo_descripcion	string	Sí	6-30	Descripción del motivo de la nota de crédito. Describe el por qué se emitió la nota de crédito.

Nota: Cuando se crea una nota de crédito con carrito_id, el sistema automáticamente asocia el documento electrónico del carrito y hereda la información del cliente, moneda y cotización del carrito original.

Ejemplos de respuesta

Ejemplo de Respuesta de Nota de Crédito con Documento Físico Asociado

{
  "success": true,
  "codigo": "201",
  "message": "Recurso creado con éxito.",
  "data": {
    "id": "ejemplo-uuid-nota-credito-123",
    "motivo_codigo": 2,
    "motivo_descripcion": "DEVOLUCION",
    "total": 0,
    "moneda": "PYG",
    "cotizacion": 1,
    "carrito_id": null,
    "fecha_emision": null,
    "estado_nota_credito": 1,
    "numero_documento": null,
    "tipo_origen": 1,
    "cliente": {
      "id": "ejemplo-uuid-cliente-123",
      "tipo_persona": 1,
      "tipo_documento": 1,
      "documento": "1234567",
      "nombre": "Cliente de ejemplo",
      "nombre_fantasia": "Cliente de ejemplo",
      "nacionalidad": "PRY",
      "fecha_nacimiento": "01/01/1990",
      "whatsapp": "+595981234567",
      "email": "[email protected]",
      "numero_casa": "0",
      "direccion": "Direccion ejemplo",
      "barrio": "Barrio ejemplo",
      "ciudad": {
        "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
        "codigo_sifen": "3556",
        "nombre": "SANTA RITA",
        "distrito": {
          "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
          "codigo_sifen": "209",
          "nombre": "SANTA RITA",
          "departamento": {
            "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
            "codigo_sifen": "11",
            "nombre": "ALTO PARANA"
          }
        }
      }
    },
    "documentos_asociados_electronicos": null,
    "documentos_asociados_manuales": {
      "numero_timbrado_documento_asociado": "12345678",
      "numero_establecimiento_documento_asociado": "001",
      "punto_expedicion_documento_asociado": "001",
      "fecha_emision_documento_asociado": "22/03/2025",
      "tipo_documento_asociado": 2,
      "numero_documento_asociado": "0000001",
      "tipo_documento_impreso": 1
    },
    "items": []
  }
}

Ejemplo de Respuesta de Nota de Crédito con Documento Electrónico Asociado

{
  "success": true,
  "codigo": "201",
  "message": "Recurso creado con éxito.",
  "data": {
    "id": "ejemplo-uuid-nota-credito-123",
    "motivo_codigo": 2,
    "motivo_descripcion": "DEVOLUCION",
    "total": 0,
    "moneda": "PYG",
    "cotizacion": 1,
    "carrito_id": null,
    "fecha_emision": null,
    "estado_nota_credito": 1,
    "numero_documento": null,
    "tipo_origen": 1,
    "cliente": {
      "id": "ejemplo-uuid-cliente-123",
      "tipo_persona": 1,
      "tipo_documento": 1,
      "documento": "1234567",
      "nombre": "Cliente de ejemplo",
      "nombre_fantasia": "Cliente de ejemplo",
      "nacionalidad": "PRY",
      "fecha_nacimiento": "01/01/1990",
      "whatsapp": "+595981234567",
      "email": "[email protected]",
      "numero_casa": "0",
      "direccion": "Direccion ejemplo",
      "barrio": "Barrio ejemplo",
      "ciudad": {
        "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
        "codigo_sifen": "3556",
        "nombre": "SANTA RITA",
        "distrito": {
          "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
          "codigo_sifen": "209",
          "nombre": "SANTA RITA",
          "departamento": {
            "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
            "codigo_sifen": "11",
            "nombre": "ALTO PARANA"
          }
        }
      }
    },
    "documentos_asociados_electronicos": {
      "cdc": "01234567890123456789012345678901234567890123"
    },
    "documentos_asociados_manuales": null,
    "items": []
  }
}

Ejemplo de Respuesta de Nota de Crédito con Carrito ID

{
  "success": true,
  "codigo": "201",
  "message": "Recurso creado con éxito.",
  "data": {
    "id": "4c782a0f-5d6f-4ab6-b6b3-b85110cd71ea",
    "motivo_codigo": 2,
    "motivo_descripcion": "Error de emision",
    "total": 0,
    "moneda": "PYG",
    "cotizacion": 1,
    "carrito_id": "a793b850-a28a-45db-98d4-a4c2b138466b",
    "fecha_emision": null,
    "estado_nota_credito": 1,
    "numero_documento": null,
    "tipo_origen": 2,
    "cliente": {
      "id": "ejemplo-uuid-cliente-123",
      "tipo_persona": 1,
      "tipo_documento": 1,
      "documento": "1234567",
      "nombre": "Cliente de ejemplo",
      "nombre_fantasia": "Cliente de ejemplo",
      "nacionalidad": "PRY",
      "fecha_nacimiento": "01/01/1990",
      "whatsapp": "+595981234567",
      "email": "[email protected]",
      "numero_casa": "0",
      "direccion": "Dirección de ejemplo",
      "barrio": "Barrio de ejemplo",
      "ciudad": {
        "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
        "codigo_sifen": "3556",
        "nombre": "SANTA RITA",
        "distrito": {
          "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
          "codigo_sifen": "209",
          "nombre": "SANTA RITA",
          "departamento": {
            "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
            "codigo_sifen": "11",
            "nombre": "ALTO PARANA"
          }
        }
      }
    },
    "documentos_asociados_electronicos": {
      "cdc": "08238131283812838123812838118238128318231283"
    },
    "documentos_asociados_manuales": null,
    "items": []
  }
}

Descripción de Campos de Respuesta

Campos Principales

Campo	Tipo	Descripción
id	uuid	Identificador único de la nota de crédito creada.
motivo_descripcion	string	Descripción literal del motivo asignado al código anterior.
total	number	Monto total de la nota de crédito en la moneda especificada. Inicialmente es 0.
moneda	string	Código de moneda en formato ISO 4217 (ej: PYG, USD).
cotizacion	number	Cotización de la moneda respecto a Guaraníes.
fecha_emision	string	Fecha de emisión de la nota de crédito. Es null hasta que la nota de crédito se finalice.
estado_nota_credito	number	Estado actual de la nota de crédito. (ver tablas-referencias)
numero_documento	string	Número del documento de la nota de crédito. Es null hasta que la nota de crédito se finalice.
tipo_origen	number	Tipo de origen de la nota de crédito.
cliente	object	Objeto con la información completa del cliente asociado a la nota de crédito.
documentos_asociados_electronicos	object	Documento electrónico asociado (si aplica). Es null si no hay documento electrónico asociado.
documentos_asociados_manuales	object	Documento manual asociado (si aplica). Es null si no hay documento manual asociado.
items	array	Lista de los ítems (mercaderías o servicios) asociados a la nota de crédito. Inicialmente es un array vacío [].

Campos del Cliente

Campo	Tipo	Descripción
id	uuid	Identificador único del cliente.
tipo_persona	number	Tipo de persona. 1 = Persona Física, 2 = Persona Jurídica.
tipo_documento	number	Tipo de documento de identidad. 1 = Cédula, 2 = Pasaporte, 3 = RUC, etc.
documento	string	Número del documento de identidad del cliente.
nombre	string	Nombre completo del cliente (razón social para personas jurídicas).
nombre_fantasia	string	Nombre comercial o fantasía del cliente.
nacionalidad	string	Código de nacionalidad en formato ISO 3166-1 alpha-3 (ej: PRY, ARG, BRA).
fecha_nacimiento	string	Fecha de nacimiento del cliente en formato DD/MM/YYYY.
whatsapp	string	Número de WhatsApp del cliente en formato internacional.
email	string	Dirección de correo electrónico del cliente.
numero_casa	string	Número de casa o edificio de la dirección del cliente.
direccion	string	Dirección completa del cliente.
barrio	string	Nombre del barrio donde reside el cliente.
ciudad	object	Objeto con información de la ciudad del cliente.

Campos de Ciudad

Campo	Tipo	Descripción
id	uuid	Identificador único de la ciudad.
codigo_sifen	string	Código de la ciudad según el catálogo SIFEN.
nombre	string	Nombre de la ciudad.
distrito	object	Objeto con información del distrito al que pertenece la ciudad.
departamento	object	Objeto con información del departamento al que pertenece la ciudad.

Campos de Distrito

Campo	Tipo	Descripción
id	uuid	Identificador único del distrito.
nombre	string	Nombre del distrito.
codigo_sifen	string	Código del distrito según el catálogo SIFEN.

Campos de Departamento

Campo	Tipo	Descripción
id	uuid	Identificador único del departamento.
nombre	string	Nombre del departamento.
codigo_sifen	string	Código del departamento según el catálogo SIFEN.

Recursos adicionales

Para más información sobre posibles errores y cómo manejarlos, consulta errores.