Credit Notes API: Issue Financial Adjustments for Sales

Credit notes in MultiSas are issued to correct or adjust previously generated invoices. A credit note references a specific sale, production order, and client, and records the adjustment amount and reason. When created, the document embeds a snapshot of the company, client, production order, and original sale — giving the note full audit context without depending on the referenced documents remaining unchanged.

This endpoint requires three levels of authorization beyond a valid JWT:

Token middleware — the JWT must be a Company token (obtained via POST /api/user/login-company). TokenAny is not used here.
TokenAuthorize('Admin', 'Super Admin') — the caller’s role must be Admin or Super Admin.
TokenValidationPlan('Plan Basico') — the middleware calls plan.features['Plan Basico'] to determine allowed plans. If this check fails, the server responds immediately with {"msj": "Tu plan no permite usar esta funcion", "status": false}.

POST /api/notes/credit/:company_id/:sale_id/:production_id/:client_id

Issues a credit note that adjusts a specific sale for a given client and production order. A sequential bill number is auto-generated using the generate_bill_credit helper, and today’s date is stamped automatically onto the date_credit_note field. Auth: Token + TokenAuthorize('Admin', 'Super Admin') + TokenValidationPlan('Plan Basico')

Path Parameters

company_id

string

required

MongoDB ObjectId of the company issuing the credit note. The company must exist or the request is rejected with 404 Empresa no encontrada.

sale_id

string

required

MongoDB ObjectId of the sale being adjusted. Must reference an existing sale document.

production_id

string

required

MongoDB ObjectId of the production order associated with the sale. Must reference an existing production document.

client_id

string

required

MongoDB ObjectId of the client who was originally invoiced. Must reference an existing client document.

Body Parameters

reason

string

required

A plain-text explanation for the credit note (e.g. "Producto defectuoso devuelto", "Error en precio facturado"). Cannot be empty.

total

string

required

The adjustment amount as a string (e.g. "150000"). Stored as a string to preserve formatting consistency with other financial fields in the schema. Cannot be empty.

Example Request

curl -X POST \
  https://your-domain.com/api/notes/credit/64abc1230000000000000001/64abc1230000000000000010/64abc1230000000000000020/64abc1230000000000000030 \
  -H "token-access: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Producto defectuoso devuelto por el cliente",
    "total": "75000"
  }'

Response

Returns the persisted credit note document with all embedded snapshots.

{
  "msj": "Nota credito creada exitosamente",
  "status": true,
  "save_note_credit": {
    "_id": "64fff9990000000000000055",
    "bill_number": "NC-0001",
    "date_credit_note": "6/1/2024",
    "reason": "Producto defectuoso devuelto por el cliente",
    "total": "75000",
    "company": {
      "_id": "64abc1230000000000000001",
      "name_company": "Acme S.A.S",
      "name_founder": "Juan Pérez",
      "nit_company": "900123456-1"
    },
    "client": {
      "_id": "64abc1230000000000000030",
      "document_type_client": "CC",
      "number_document_client": "1020304050",
      "name_client": "María López",
      "emial_client": "maria@example.com",
      "phone_client": "3001234567"
    },
    "production": {
      "_id": "64abc1230000000000000020",
      "bill_number": "PR-0042",
      "price_production": "150000",
      "type_production": "Camisa",
      "quantity_production": "10"
    },
    "sale": {
      "_id": "64abc1230000000000000010",
      "bill_number": "FA-0087",
      "date_sale": "5/28/2024",
      "quantity": 10,
      "state": "Pagado",
      "price": 15000,
      "sub_total": 150000,
      "total": 150000
    },
    "createdAt": "2024-06-01T10:00:00.000Z",
    "updatedAt": "2024-06-01T10:00:00.000Z",
    "__v": 0
  }
}

Response Fields

msj

string

Confirmation message: "Nota credito creada exitosamente".

status

boolean

true on success.

save_note_credit

object

The full persisted CreditNote document.

Show save_note_credit fields

_id

string

MongoDB ObjectId of the new credit note.

bill_number

string

Auto-generated sequential bill number for the credit note (e.g. "NC-0001"), produced by the generate_bill_credit helper.

date_credit_note

string

Date the credit note was issued. Set automatically from new Date().toLocaleDateString() at creation time (e.g. "6/1/2024").

reason

string

The adjustment reason supplied in the request body.

total

string

The adjustment amount supplied in the request body.

company

object

Snapshot of the issuing company.

Show company fields

_id

string

Company’s MongoDB ObjectId.

name_company

string

Registered company name.

name_founder

string

Name of the company founder.

nit_company

string

Company tax identification number (NIT).

client

object

Snapshot of the client at the time of credit note issuance.

Show client fields

_id

string

Client’s MongoDB ObjectId.

document_type_client

string

Type of identity document (e.g. "CC" for Cédula de Ciudadanía).

number_document_client

string

Client’s identity document number.

name_client

string

Client’s full name.

emial_client

string

Client’s email address. Note: the field name is emial_client — this matches the model schema verbatim.

phone_client

string

Client’s phone number.

production

object

Snapshot of the production order referenced by this credit note.

Show production fields

_id

string

Production document’s MongoDB ObjectId.

bill_number

string

Production’s bill counter string (sourced from production.bill_counter), e.g. "PR-0042".

price_production

string

Unit price of the production order.

type_production

string

Type of item produced (e.g. "Camisa", "Uniforme", "Sudadera").

quantity_production

string

Number of units in the production order.

sale

object

Snapshot of the original sale being adjusted.

Show sale fields

_id

string

Sale document’s MongoDB ObjectId.

bill_number

string

Original invoice number (e.g. "FA-0087").

date_sale

string

Date the original sale was created.

quantity

number

Number of units sold in the original transaction.

state

string

Payment state of the original sale (e.g. "Pagado", "Pendiente").

price

number

Unit price of the product at the time of sale.

sub_total

number

Subtotal before any adjustments.

total

number

Final total of the original sale.

createdAt

string

ISO 8601 timestamp set automatically by Mongoose (timestamps: true).

updatedAt

string

ISO 8601 timestamp set automatically by Mongoose (timestamps: true).

Plan Validation

The route calls TokenValidationPlan('Plan Basico'). Inside that middleware, plan.features['Plan Basico'] is looked up in the platform’s plan.json configuration. The plan.json file defines feature keys (facturacion, inventario_basico, etc.) but does not define a key named 'Plan Basico'. As a result allowedPlans is undefined and the middleware always rejects the request before the controller runs:

{ "msj": "Tu plan no permite usar esta funcion", "status": false }

This is a known discrepancy in the current codebase. The route file (notesRoutes.js) passes 'Plan Basico' as the feature key to TokenValidationPlan, but the plan configuration (plan.json) uses 'facturacion' as the correct key for billing features. Until the route is updated to TokenValidationPlan('facturacion'), this endpoint will always return 403 for all callers regardless of their plan.

Debit Notes

The DebitNote model (debit_note collection) exists in the codebase as the structural counterpart to CreditNote. It is imported in notesController.js and shares an identical schema layout:

Field	Type	Description
`bill_number`	`String`	Auto-generated sequential debit note number
`date_debit_note`	`String`	Date the debit note was issued (set automatically)
`reason`	`String`	Plain-text reason for the debit adjustment (manual input)
`total`	`String`	Adjustment amount as a string (manual input)
`company`	`Object`	Snapshot: `_id`, `name_company`, `name_founder`, `nit_company`
`client`	`Object`	Snapshot: `_id`, `document_type_client`, `number_document_client`, `name_client`, `emial_client`, `phone_client`
`production`	`Object`	Snapshot: `_id`, `bill_number`, `price_production`, `type_production`, `quantity_production`
`sale`	`Object`	Snapshot: `_id`, `bill_number`, `date_sale`, `quantity`, `state`, `price`, `sub_total`, `total`

As of the current codebase, no HTTP route for debit note creation is registered in notesRoutes.js. The DebitNote model is imported in the controller but its creation handler has not yet been wired to an endpoint. Do not attempt to call a debit note endpoint — no such route exists. The data model is in place for future use.

Error Responses

Status	Body	Cause
`401`	`{"msj": "Sin autorizacion", "status": false}`	No token provided in the request
`403`	`{"msj": "Sesion finalizada", "status": false}`	The JWT has expired
`403`	`{"msj": "No tienes permisos", "status": false}`	Caller role is not `Admin` or `Super Admin`
`403`	`{"msj": "Tu plan no permite usar esta funcion", "status": false}`	`TokenValidationPlan('Plan Basico')` check failed (see Plan Validation above)
`403`	`{"msj": "Completa todos los campos", "status": false}`	`reason` or `total` is missing from the request body
`404`	`{"msj": "Empresa no encontrada", "status": false}`	No company matches the given `company_id`
`404`	`{"msj": "Venta no encontrada", "status": false}`	No sale matches the given `sale_id`
`404`	`{"msj": "Produccion no encontrada", "status": false}`	No production order matches the given `production_id`
`404`	`{"msj": "Cliente no encontrado", "status": false}`	No client matches the given `client_id`
`500`	Mongoose/Node error object	Unexpected server-side error

Authentication & Companies

Sublimation

Restaurant

Pharmacy

Accounting & Notes

Credit Notes API: Issue Financial Adjustments for Sales

POST /api/notes/credit/:company_id/:sale_id/:production_id/:client_id

Path Parameters

Body Parameters

Example Request

Response

Response Fields

Plan Validation

Debit Notes

Error Responses

Build docs developers (and LLMs) love

Authentication & Companies

Sublimation

Restaurant

Pharmacy

Accounting & Notes

Documentation Index

​POST /api/notes/credit/:company_id/:sale_id/:production_id/:client_id

​Path Parameters

​Body Parameters

​Example Request

​Response

​Response Fields

​Plan Validation

​Debit Notes

​Error Responses

Build docs developers (and LLMs) love

POST /api/notes/credit/:company_id/:sale_id/:production_id/:client_id

Path Parameters

Body Parameters

Example Request

Response

Response Fields

Plan Validation

Debit Notes

Error Responses