# Crear notas de crédito en lote

`POST /v1/companies/{companyRut}/createCreditNote`

> 🧪 **Beta.** Endpoint nuevo y en desarrollo: se publica a propósito, pero la forma de la request o de la respuesta puede cambiar antes de estabilizarse.

**Notas de crédito en lote a partir de CFEs referenciados. Sin consumidor real; normalmente las notas van por sendCfes.**

**Acceso:** restringida. Requiere sesión, y sólo opera sobre el RUT de tu propia empresa: pedir otro RUT responde `403 FORBIDDEN`.

Crea notas de crédito (NC) a partir de CFEs referenciados. El establecimiento (branchOffice) se infiere del CFE referenciado.
Body: referencedDocuments (CFEs a referenciar), clientEmissionId requerido por documento, opcional items, mntToAffect/pctToAffect, emailsToNotify, phonesToNotify.

## OpenAPI

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "pymo Gateway API",
    "version": "1.0.0",
    "description": "API del gateway de facturación electrónica (CFE) de pymo. Los métodos y las rutas salen del código del servicio, así que la referencia refleja lo que la API hace hoy."
  },
  "servers": [
    {
      "url": "https://gatewaytest.pymo.uy",
      "description": "Homologación: emite contra la ePrueba de DGI. Es donde se integra."
    },
    {
      "url": "https://gateway.pymo.uy",
      "description": "Producción: los comprobantes son fiscales y no se pueden borrar."
    }
  ],
  "security": [
    {
      "sessionCookie": []
    }
  ],
  "paths": {
    "/v1/companies/{companyRut}/createCreditNote": {
      "post": {
        "operationId": "post_v1_companies_companyRut_createCreditNote",
        "summary": "Crear notas de crédito en lote",
        "description": "> 🧪 **Beta.** Endpoint nuevo y en desarrollo: se publica a propósito, pero la forma de la request o de la respuesta puede cambiar antes de estabilizarse.\n\n**Notas de crédito en lote a partir de CFEs referenciados. Sin consumidor real; normalmente las notas van por sendCfes.**\n\n**Acceso:** restringida. Requiere sesión, y sólo opera sobre el RUT de tu propia empresa: pedir otro RUT responde `403 FORBIDDEN`.\n\nCrea notas de crédito (NC) a partir de CFEs referenciados. El establecimiento (branchOffice) se infiere del CFE referenciado.\nBody: referencedDocuments (CFEs a referenciar), clientEmissionId requerido por documento, opcional items, mntToAffect/pctToAffect, emailsToNotify, phonesToNotify.",
        "tags": [
          "3 Emisión"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyRut"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SolicitudNota"
              },
              "example": {
                "referencedDocuments": [
                  {
                    "clientEmissionId": "nc-2026-000045",
                    "cfeId": "6a7121a37698d7c0ab3f1b51",
                    "pctToAffect": 100
                  }
                ],
                "emailsToNotify": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Respuesta"
                }
              }
            }
          },
          "401": {
            "description": "Sesión no iniciada o vencida (`UNAUTHORIZED`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaError"
                },
                "examples": {
                  "No_autorizado": {
                    "value": {
                      "payload": {},
                      "message": {
                        "code": "UNAUTHORIZED",
                        "value": "Debe iniciar sesión."
                      },
                      "status": "FAIL"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "La sesión existe pero no alcanza este recurso (`FORBIDDEN`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaError"
                },
                "examples": {
                  "Prohibido": {
                    "value": {
                      "payload": {},
                      "message": {
                        "code": "FORBIDDEN",
                        "value": "No tiene permisos para realizar esta acción."
                      },
                      "status": "FAIL"
                    }
                  }
                }
              }
            }
          }
        },
        "x-acceso": "restringida-por-rut",
        "x-status-superficie": "beta"
      }
    }
  },
  "components": {
    "schemas": {
      "CfeItem": {
        "type": "object",
        "description": "Una línea del comprobante.",
        "properties": {
          "NroLinDet": {
            "type": "string",
            "description": "Número de línea, empezando en 1."
          },
          "IndFact": {
            "type": "string",
            "enum": [
              "1",
              "2",
              "3",
              "4",
              "5",
              "6",
              "7",
              "8",
              "10",
              "11",
              "12",
              "13",
              "14",
              "15",
              "16"
            ],
            "description": "Indicador de facturación DGI, define el tratamiento de IVA de la línea. `1` exento, `2` tasa mínima (10%), `3` tasa básica (22%), `4` otra tasa, `5` entrega gratuita, `6`/`7` no facturable, `8`/`10` exportación y asimiladas, `11` impuesto percibido, `12` IVA en suspenso, `13` vendido por no contribuyente, `14` IVA mínimo / Monotributo, `15` IMEBA, `16` obligación IVA mínimo. Para una venta gravada común es `3`. La misma tabla que devuelve `GET /v1/taxes`, así que se puede consultar en vivo.",
            "example": "3"
          },
          "NomItem": {
            "type": "string",
            "description": "Descripción del ítem."
          },
          "Cantidad": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "UniMed": {
            "type": "string",
            "description": "Unidad de medida. `N/A` cuando no aplica."
          },
          "PrecioUnitario": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Redondeá a 2 decimales antes de enviar: el gateway no re-redondea las líneas, sólo formatea los totales en UYU a 2 decimales al enviarlos a DGI."
          },
          "MontoItem": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Monto de la línea. Si falta, DGI lo deriva de cantidad y precio. Redondeá a 2 decimales antes de enviar: el gateway no re-redondea las líneas, sólo formatea los totales en UYU a 2 decimales al enviarlos a DGI."
          },
          "SubDescuento": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "SubRecargo": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "RetencPercep": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Retenciones de la línea (`Tasa`, `CodRet`, `MntSujetoaRet`, `ValRetPerc`)."
          }
        },
        "minProperties": 1,
        "required": [
          "NroLinDet",
          "IndFact",
          "NomItem"
        ]
      },
      "DocumentoReferenciado": {
        "type": "object",
        "required": [
          "clientEmissionId"
        ],
        "description": "Un CFE original al que la nota hace referencia. Se identifica **o** por `cfeId` **o** por la terna (`cfeType`, `serie`, `nro`): mandar las dos formas es un error explícito.",
        "properties": {
          "clientEmissionId": {
            "type": "string",
            "description": "**Obligatorio por documento.** Es la clave de idempotencia de la nota que se va a crear, no la del original."
          },
          "cfeId": {
            "type": "string"
          },
          "cfeType": {
            "type": "string"
          },
          "serie": {
            "type": "string"
          },
          "nro": {
            "type": "integer"
          },
          "pctToAffect": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Porcentaje del original a afectar."
          },
          "mntToAffect": {
            "type": "number",
            "description": "Monto a afectar. Tiene que ser mayor a 0.",
            "minimum": 0,
            "exclusiveMinimum": true
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CfeItem"
            },
            "description": "Líneas explícitas. **Si se mandan, `pctToAffect` y `mntToAffect` se ignoran.** Si no se mandan, el gateway arma la línea desde la primera del original."
          }
        }
      },
      "SolicitudNota": {
        "type": "object",
        "required": [
          "referencedDocuments"
        ],
        "description": "Crea notas de crédito o débito a partir de CFEs ya emitidos. La sucursal y el tipo de la nota se infieren del comprobante referenciado.",
        "properties": {
          "referencedDocuments": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/DocumentoReferenciado"
            }
          },
          "emailsToNotify": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "phonesToNotify": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "extendNotifications": {
            "type": "boolean"
          }
        }
      },
      "Respuesta": {
        "type": "object",
        "required": [
          "payload",
          "status"
        ],
        "description": "Envoltorio común a todas las respuestas. **`status` no se deduce del código HTTP**: hay al menos nueve lugares en el gateway que responden `HTTP 200` con `status: \"FAIL\"` (por ejemplo `CFE_NOT_FOUND` y `DGI_COMPANY_NOT_READY_YET`). Un cliente tiene que leer `status`, no el código.",
        "properties": {
          "payload": {
            "description": "Los datos de la respuesta. `{}` cuando el endpoint no devuelve nada.",
            "oneOf": [
              {
                "type": "object"
              },
              {
                "type": "array",
                "items": {}
              }
            ]
          },
          "message": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Mensaje"
              }
            ],
            "description": "Presente cuando la operación tiene algo que decir. Las lecturas simples responden sólo `payload` y `status`."
          },
          "status": {
            "$ref": "#/components/schemas/Estado"
          }
        }
      },
      "RespuestaError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Respuesta"
          }
        ],
        "description": "El mismo envoltorio, con `status: \"FAIL\"` y `payload` normalmente vacío."
      },
      "Mensaje": {
        "type": "object",
        "required": [
          "code",
          "value"
        ],
        "description": "Código estable y su texto en español. **El código es el contrato, el texto no**: `value` sale de una tabla de traducciones y puede reescribirse sin aviso, así que un cliente ramifica por `code`.",
        "properties": {
          "code": {
            "type": "string",
            "example": "DGI_CFES_RECEIVE_SUCCESS"
          },
          "value": {
            "type": "string",
            "example": "Cfes recibidos correctamente."
          }
        }
      },
      "Estado": {
        "type": "string",
        "enum": [
          "SUCCESS",
          "FAIL"
        ],
        "description": "De las 82 claves de mensaje del gateway, 29 son `SUCCESS` y 53 `FAIL`. Es lo que hay que mirar para saber si la llamada funcionó."
      }
    },
    "securitySchemes": {
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "connect.sid",
        "description": "Sesión por cookie de `POST /v1/login`, válida 1 hora. Ver [Autenticación](/autenticacion)."
      }
    },
    "parameters": {
      "CompanyRut": {
        "name": "companyRut",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "219999990008",
          "default": "219999990008"
        },
        "example": "219999990008"
      }
    }
  }
}
```