Facturación

Ciclos de facturación, próximas facturas, métodos de pago.

Base path: /organizations/:orgId/billing·12 endpoints·Source: mosend-wb-backend/src/modules/billing/billing.controller.ts
GET/organizations/:orgId/billing/periods
bearer

Lista los periodos de facturación de la organización.

Path params

  • orgIdstringrequerido

Respuestas

  • 200
curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/periods' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
GET/organizations/:orgId/billing/usage
bearer

Devuelve el consumo del periodo de facturación en curso.

Path params

  • orgIdstringrequerido

Respuestas

  • 200
curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/usage' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
GET/organizations/:orgId/billing/estimated-next-charge
bearer

Estima cuánto pagaría la organización si se cerrara hoy el periodo abierto. NO persiste.

Path params

  • orgIdstringrequerido

Respuestas

  • 200
curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/estimated-next-charge' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
POST/organizations/:orgId/billing/coupons/validate
bearer

Valida un cupón sin consumirlo (previsualización del descuento).

Path params

  • orgIdstringrequerido

Body (JSON)

  • codestringrequerido
  • planSlugstring

Respuestas

  • 201
curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/coupons/validate' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"code": "<code>","planSlug": "<planSlug>"}'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
POST/organizations/:orgId/billing/coupons/redeem
bearer

Valida y redime un cupón a nombre de la organización.

Path params

  • orgIdstringrequerido

Body (JSON)

  • codestringrequerido
  • planSlugstring

Respuestas

  • 201
curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/coupons/redeem' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"code": "<code>","planSlug": "<planSlug>"}'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
PATCH/organizations/:orgId/billing/interval
bearer

Cambia el intervalo de facturación (mensual/anual). Aplica al próximo cierre; anual cobra el año desde esta fecha.

Path params

  • orgIdstringrequerido

Body (JSON)

  • intervalstringrequerido
    MONTHLYYEARLY

Respuestas

  • 200
curl -X PATCH 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/interval' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"interval": "MONTHLY"}'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
POST/organizations/:orgId/billing/invoices/:invoiceId/enviar
bearer

Envía la factura por correo con su PDF adjunto (correo de facturación, o el del usuario con aMiCorreo).

Path params

  • orgIdstringrequerido
  • invoiceIdstringrequerido

Body (JSON)

  • aMiCorreoboolean

    true = al correo de quien lo pide; si no, al de facturación de la organización.

Respuestas

  • 201
curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/invoices/00000000-0000-0000-0000-000000000000/enviar' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"aMiCorreo": true}'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
GET/organizations/:orgId/billing/datos-fiscales
bearer

Datos de la organización para su factura electrónica.

Path params

  • orgIdstringrequerido

Respuestas

  • 200
curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/datos-fiscales' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
POST/organizations/:orgId/billing/datos-fiscales/consultar-dian
bearer

Busca el NIT en la DIAN: calcula el DV y trae la razón social y el correo registrado (oculto). Máximo 10 por hora.

Path params

  • orgIdstringrequerido

Body (JSON)

  • nitstring

    NIT, con o sin dígito de verificación.

Respuestas

  • 201
curl -X POST 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/datos-fiscales/consultar-dian' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"nit": "<nit>"}'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
PUT/organizations/:orgId/billing/datos-fiscales
bearer

Guarda los datos para la factura electrónica (NIT con DV validado, razón social, dirección, municipio, correo).

Path params

  • orgIdstringrequerido

Body (JSON)

  • necesitaFacturaElectronicaboolean

    ¿Necesita factura electrónica a su nombre?

  • tipoPersonastring
    NATURALJURIDICA
  • tipoDocumentostring
    NITCCCEPASAPORTE
  • numeroDocumentostring

    Número de documento (el NIT sin dígito de verificación).

  • dvnumber

    Dígito de verificación del NIT; si falta, se calcula.

  • razonSocialstring
  • direccionstring
  • municipioIdnumber

    Id del municipio en el catálogo del proveedor de facturación.

  • telefonostring
  • correoFacturastring

    Correo para la factura electrónica. Vacío = el de facturación de la organización.

  • usarCorreoDianboolean

    Usar como correo de la factura el registrado en la DIAN (de la última consulta de este NIT).

Respuestas

  • 200
curl -X PUT 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/datos-fiscales' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"necesitaFacturaElectronica": true,"tipoPersona": "NATURAL","tipoDocumento": "NIT","numeroDocumento": "<numeroDocumento>","dv": 0,"razonSocial": "<razonSocial>","direccion": "<direccion>","municipioId": 0,"telefono": "<telefono>","correoFactura": "<correoFactura>","usarCorreoDian": true}'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
GET/organizations/:orgId/billing/invoices/:invoiceId/facturas-electronicas
bearer

Facturas electrónicas emitidas por una factura de Mosend.

Path params

  • orgIdstringrequerido
  • invoiceIdstringrequerido

Respuestas

  • 200
curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/invoices/00000000-0000-0000-0000-000000000000/facturas-electronicas' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}
GET/organizations/:orgId/billing/facturas-electronicas/:feId/pdf
bearer

PDF (base64) de una factura electrónica de Mosend.

Path params

  • orgIdstringrequerido
  • feIdstringrequerido

Respuestas

  • 200
curl -X GET 'https://api.mosend.dev/organizations/a1b2c3d4-1234-5678-9abc-def012345678/billing/facturas-electronicas/00000000-0000-0000-0000-000000000000/pdf' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>'
Response · 200
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2026-05-01T03:42:18.123Z"
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}