Gestión de documentos de compra y venta en A3ERP API

Los endpoints de documento te permiten gestionar toda la cadena documental de compras y ventas de A3ERP: desde una oferta inicial hasta la factura final, pasando por pedidos, albaranes y depósitos. Cada documento se identifica por su tipo ({tipo}) y su identificador interno ({id}). La estructura de respuesta incluye siempre la cabecera del documento (Documentos), sus líneas (Lineas) y el detalle de cada línea (Detalle), permitiendo una visión completa del documento en una sola llamada.

Tipos de documento

El parámetro {tipo} de la ruta debe ser la abreviatura del tipo de documento. Los valores disponibles son:

Abreviatura	Tipo de documento
`OV`	Oferta de venta
`PV`	Pedido de venta
`AV`	Albarán de venta
`DV`	Depósito de venta
`FVS`	Factura de venta (stock)
`FVC`	Factura de venta (contable)
`EX`	Expedientes
`TR`	Traspasos
`RE`	Regularizaciones
`OC`	Oferta de compra
`PC`	Pedido de compra
`AC`	Albarán de compra
`DC`	Depósito de compra
`FCS`	Factura de compra (stock)
`FCC`	Factura de compra (contable)

Configuración de facturación de venta

La pestaña Facturación venta del Configurador API permite configurar la creación y eliminación de facturas de venta.

Eliminación de facturas

Opción	Descripción
Permitir eliminar facturas	Habilita la eliminación de facturas de venta.
Generar rectificativa si borrado de factura de venta	Configura la generación de una factura rectificativa al borrar una factura de venta.

Antes de utilizar DELETE /api/documento/{tipo}/{id} para eliminar una factura de venta, revisa estas opciones en el Configurador API.

Creación de facturas

Opción	Descripción
Permitir insertar número de documento en la creación de facturas	Permite indicar el número de documento al crear una factura.
No permitir fecha de factura superior a la actual	Impide crear facturas con una fecha posterior a la fecha actual.
No permitir fecha de factura inferior a la última creada por serie	Impide crear una factura con una fecha anterior a la de la última factura creada en la misma serie.
Comprobar creación de factura de venta en RepLog	Activa la comprobación de la creación de la factura de venta en RepLog.

Al crear facturas de venta mediante POST /api/documento/{tipo}, ten en cuenta la configuración del número de documento y las restricciones de fecha.

GET
POST
PUT
DELETE

Obtener todos los documentos de un tipo

Devuelve todos los documentos del tipo indicado, incluyendo cabecera, líneas y detalle de cada línea.

string

required

Tipo de documento (p. ej. PV, FVS, AV).

string

required

Token JWT con prefijo Bearer.

GET https://servidor:<puerto>/api/documento/{tipo}
Authorization: Bearer {token}

Respuesta 200:

{
  "Documentos": [
    {
      "idpedv": "text",
      "tipocont": "text",
      "serie": "text",
      "numdoc": "text",
      "codcli": "text",
      "nomcli": "text",
      "nifcli": "text",
      "fecha": "text",
      "basemoneda": "text",
      "totivamoneda": "text",
      "totdoc": "text",
      "situacion": "text",
      "centrocoste": "text",
      "centrocoste2": "text",
      "centrocoste3": "text",
      "codrep": "text",
      "codalm": "text",
      "regiva": "text",
      "situaciondetalle": "text",
      "docpag": "text",
      "forpag": "text",
      "ivaincluido": "text",
      "numdir": "text",
      "Lineas": [
        {
          "unidades": "text",
          "idpedv": "text",
          "idlin": "text",
          "ordlin": "text",
          "fecha": "text",
          "codart": "text",
          "codalm": "text",
          "desclin": "text",
          "prcmoneda": "text",
          "desc1": "text",
          "desc2": "text",
          "desc3": "text",
          "desc4": "text",
          "basemoneda": "text",
          "tipiva": "text",
          "situacion": "text",
          "eskit": "text",
          "escomponente": "text",
          "Detalle": [
            {
              "idpedv": "text",
              "idlin": "text",
              "unidades": "text",
              "feccaduc": "text",
              "grupo": "text"
            }
          ]
        }
      ]
    }
  ]
}

Código	Descripción
`200`	Lista de documentos
`401`	Unauthorized
`404`	Endpoint no encontrado

Obtener la cabecera de un documento

Devuelve únicamente los datos de cabecera del documento, sin líneas ni detalle. Útil cuando solo necesitas los datos generales del documento (importes totales, cliente, fechas, situación…).

string

required

Tipo de documento (p. ej. PV, FVS, AV).

integer

required

Identificador interno del documento.

string

required

Token JWT con prefijo Bearer.

GET https://servidor:<puerto>/api/cabeceradocumento/{tipo}/{id}
Authorization: Bearer {token}

Respuesta 200:

{
  "idpedv": 1,
  "tipocont": "text",
  "serie": "text",
  "numdoc": 1,
  "codcli": "text",
  "nomcli": "text",
  "nifcli": "text",
  "fecha": "2026-01-01",
  "referencia": "text",
  "basemoneda": 1,
  "totivamoneda": 1,
  "totdoc": 1,
  "situacion": "text",
  "centrocoste": "text",
  "centrocoste2": "text",
  "centrocoste3": "text",
  "codrep": "text",
  "codrep2": "text",
  "codrep3": "text",
  "codalm": "text",
  "regiva": "text",
  "situaciondetalle": "text",
  "docpag": "text",
  "forpag": "text",
  "ivaincluido": "text",
  "numdir": 1
}

Código	Descripción
`200`	Cabecera del documento
`401`	Unauthorized
`404`	Endpoint no encontrado

Imprimir un documento en PDF

Genera el PDF de un documento y lo devuelve codificado en base64. Si no se especifica el modelo de impresión, se toma por defecto el configurado para el cliente o proveedor del documento.

string

required

Tipo de documento.

integer

required

Identificador del documento.

string

Modelo de impresión. Opcional — si se omite, se usa el modelo por defecto del cliente/proveedor.

string

required

Token JWT con prefijo Bearer.

GET https://servidor:<puerto>/api/documento/{tipo}/impresion/{id}/modelo/{modelo}
Authorization: Bearer {token}

Respuesta 200:

{
  "documento": "<base64 del PDF>"
}

Código	Descripción
`200`	PDF generado en base64
`401`	Unauthorized
`404`	Endpoint no encontrado

Servir un documento a otro

Sirve el documento indicado convirtiéndolo en un documento de nivel superior de la cadena documental (por ejemplo, sirve un pedido a albarán, o un albarán a factura).

string

required

Tipo del documento origen (p. ej. PV, AV).

string

required

Acción de servicio. Valores posibles: servirapedido, serviraalbaran, servirafactura, serviradeposito.

integer

required

Identificador del documento a servir.

string

required

Token JWT con prefijo Bearer.

GET https://servidor:<puerto>/api/documento/{tipo}/{servir}/{id}
Authorization: Bearer {token}

Ejemplo — Servir albarán a factura:

GET https://servidor:5555/api/documento/AV/servirafactura/55
Authorization: Bearer {token}

Respuesta 200:

{
  "Identificador": "text"
}

Código	Descripción
`200`	Documento servido — devuelve el ID del nuevo documento
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al servir el documento

Imprimir un documento por GUID (sin autenticación)

Permite obtener el PDF de un documento público usando el GUID almacenado en el campo API_GUIDDESCARGA de la cabecera del documento. Este endpoint no requiere token de autenticación, lo que lo hace ideal para incluir en enlaces de descarga pública.Si necesitas un modelo de impresión concreto, añade /modelo/{modelo} al final de la URL.

string

required

Tipo de documento.

string

required

GUID del documento. Se obtiene del campo API_GUIDDESCARGA de la cabecera.

GET https://servidor:<puerto>/api/documento/{tipo}/impresionguid/{guid}

Respuesta 200:

{
  "Documento": "<base64 del PDF>"
}

Código	Descripción
`200`	PDF generado en base64
`302`	El documento no existe
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al servir el documento
`500`	Error interno del servidor

Crear un nuevo documento

Crea un documento de compra o venta con su cabecera y líneas en una sola llamada.

Para documentos de venta, incluye codcli (código de cliente).
Para documentos de compra, incluye codpro (código de proveedor).
En pedidos de compra, incluye también fecentrega (fecha de entrega).

string

required

Tipo de documento a crear (p. ej. PV, FVS, AC).

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/documento/{tipo}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

{
  "json": {
    "fecha": "15/07/2022",
    "codcli": "12",
    "lineas": [
      {
        "codart": "8403",
        "unidades": "2"
      }
    ]
  }
}

Ejemplo — Alta de traspaso con detalle de lote y número de serie:

[
  {
    "codalment": "       2",
    "codalmsal": "       1",
    "fecha": "15/07/2022",
    "motivo": "Alta de traspaso 1",
    "lineas": [
      {
        "codalment": "       2",
        "codalmsal": "       1",
        "codart": "RF",
        "unidades": 2,
        "detalle": [
          {
            "unidades": "1",
            "feccaduc": "30/12/1899",
            "ubicacionsal": "P1E1A2",
            "ubicacionent": "T4",
            "numserie": "RMNU73HKNV"
          },
          {
            "unidades": "1",
            "feccaduc": "30/12/1899",
            "ubicacionsal": "P1E1A2",
            "ubicacionent": "T4",
            "numserie": "3332KBG5GH"
          }
        ]
      }
    ]
  }
]

Respuesta 200:

{
  "id": "text"
}

El campo id contiene el identificador del nuevo documento creado.

Código	Descripción
`200`	Documento creado — devuelve el `id`
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al crear el documento

Servir líneas a otro documento

Sirve líneas específicas de uno o varios documentos a un nuevo documento de nivel superior. El tipo de destino se indica en la ruta {servir}.

string

required

Destino del servicio. Valores posibles: servirlineasapedido, servirlineasaalbaran, servirlineasadeposito.

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/{servir}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

{
  "fecha": "13/06/2025",
  "codigo": "1",
  "tipo": "C",
  "Lineas": [
    {
      "tipo": "P",
      "idlin": "texto",
      "unidades": "5",
      "iddocumento": "166"
    }
  ]
}

Campos del cuerpo:

string

required

Fecha del documento destino en formato DD/MM/AAAA.

string

required

Código del cliente o proveedor.

string

required

Indica si es compra (C) o venta (V).

array

required

Array de líneas a servir. Cada objeto debe incluir tipo, idlin, unidades e iddocumento. Opcionalmente puede incluir lote, numserie, feccaduc o ubicacion.

Ejemplo — Servir albarán a factura con lote, número de serie y ubicación:

{
  "fecha": "21/04/2022",
  "codigo": " 1",
  "tipo": "C",
  "lineas": [
    {
      "tipo": "O",
      "iddocumento": "166",
      "numlin": "3",
      "unidades": "3",
      "lote": "L145"
    },
    {
      "tipo": "O",
      "iddocumento": "164",
      "numlin": "4",
      "unidades": "10",
      "feccaduc": "22/04/2022",
      "numserie": "14528798"
    },
    {
      "tipo": "O",
      "iddocumento": "165",
      "numlin": "4",
      "unidades": "2",
      "ubicacion": "A2P3L8"
    }
  ]
}

Respuesta 200:

{
  "Identificador": "text"
}

Código	Descripción
`200`	Líneas servidas — devuelve el identificador del nuevo documento
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al servir el documento

Enviar documento por email en formato PDF

Genera el PDF del documento con el modelo de impresión indicado y lo envía por correo electrónico.

string

required

Tipo de documento.

integer

required

Identificador del documento.

string

required

Modelo de impresión para el PDF.

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/documento/{tipo}/email/{id}/modelo/{modelo}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

string

Dirección de correo del destinatario principal.

string

Dirección de correo en copia.

string

Dirección de correo en copia oculta.

string

Título o asunto del correo.

string

Asunto del correo.

string

Texto plano del cuerpo del correo.

string

Cuerpo del correo en formato HTML.

Ejemplo — Enviar una factura de venta:

POST https://servidor:5555/api/documento/FVS/email/5767/modelo/1
Authorization: Bearer {token}
Content-Type: application/json

{
  "para": "rperez@jnc.es",
  "cc": "charyperez1@gmail.com",
  "cco": "fsaez@jnc.es",
  "titulo": "Envío con documento adjunto",
  "asunto": "Envío documento",
  "texto": "Adjunto envío su documento en pdf",
  "cuerpo": "<HTML><HEAD></HEAD><BODY lang=ES>Estimado cliente,<p>Adjunto archivo con documento en formato pdf.<p>Un saludo,<p><b>Rosario Pérez</b></BODY></HTML>"
}

Código	Descripción
`200`	Documento enviado por email correctamente
`401`	Unauthorized
`404`	Endpoint no encontrado

Vincular adjunto a un documento

Adjunta un archivo a un documento de compra o venta. El archivo se guarda en la carpeta de vínculos configurada en config.ini con el nombre y extensión indicados.

string

required

Tipo de documento.

integer

required

Identificador del documento.

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/documento/{tipo}/vincular/{id}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

string

Nombre del archivo con extensión (p. ej. contrato.pdf). La extensión determina el tipo de archivo.

string

Contenido del archivo codificado en base64.

{
  "nombre": "contrato.pdf",
  "Documento": "<base64 del archivo>"
}

Código	Descripción
`200`	Adjunto vinculado correctamente
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al vincular el adjunto

Vincular adjunto a una línea de documento

Adjunta un archivo a una línea concreta de un documento.

string

required

Tipo de documento.

integer

required

Identificador de la línea a la que adjuntar el archivo.

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/documento/{tipo}/vincularlinea/{linea}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

string

Nombre del archivo con extensión.

string

Descripción del adjunto.

string

Contenido del archivo codificado en base64.

{
  "nombre": "especificaciones.pdf",
  "descripcion": "Especificaciones técnicas del artículo",
  "Documento": "<base64 del archivo>"
}

Código	Descripción
`200`	Adjunto vinculado a la línea correctamente
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al vincular el adjunto

Anular un documento completo

Anula el documento indicado en su totalidad.

string

required

Tipo de documento.

integer

required

Identificador del documento a anular.

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/documento/{tipo}/anular/{id}
Authorization: Bearer {token}

Respuesta 200:

{
  "Documento": "text"
}

Código	Descripción
`200`	Documento anulado correctamente
`302`	El documento no existe
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al anular

Anular una línea de un documento

Anula una única línea del documento, identificada por su número de línea.

string

required

Tipo de documento.

integer

required

Identificador del documento.

integer

required

Número de la línea a anular.

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/documento/{tipo}/anular/{id}/linea/{numlin}
Authorization: Bearer {token}

Código	Descripción
`200`	Línea anulada correctamente
`302`	El documento no existe
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	No existe la línea

Anular unidades específicas de una línea

Anula un número concreto de unidades de una línea, sin afectar al resto.

string

required

Tipo de documento.

integer

required

Identificador del documento.

integer

required

Número de la línea.

integer

required

Número de unidades a anular de la línea.

string

required

Token JWT con prefijo Bearer.

POST https://servidor:<puerto>/api/documento/{tipo}/anular/{id}/linea/{numlin}/unidades/{unidades}
Authorization: Bearer {token}

Código	Descripción
`200`	Unidades anuladas correctamente
`302`	El documento no existe
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	No existe la línea

Actualizar un documento existente

Actualiza los datos de cabecera y/o las líneas de un documento ya existente.

string

required

Tipo de documento a actualizar.

integer

required

Identificador del documento.

string

required

Token JWT con prefijo Bearer.

PUT https://servidor:<puerto>/api/documento/{tipo}/{id}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

{
  "json": {
    "fecha": "01/09/2021",
    "codcli": "12",
    "serie": "2022",
    "codalm": " 1",
    "fecentrega": "02/09/2021",
    "lineas": [
      {
        "numlinped": "1",
        "codart": "3",
        "unidades": "4",
        "prcmoneda": "33",
        "desc1": "10"
      },
      {
        "numlinped": "2",
        "codart": "4C",
        "unidades": "5",
        "prcmoneda": "24",
        "desc1": "15"
      }
    ]
  }
}

Para modificar líneas existentes, incluye el campo numlinped con el número de línea correspondiente. Las líneas que no aparezcan en el array no se modifican.

Respuesta 200:

{
  "id": "text"
}

Código	Descripción
`200`	Documento actualizado — devuelve el `id`
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al actualizar el documento

Añadir nuevas líneas a un documento existente

Agrega nuevas líneas a un documento ya creado sin modificar las existentes.

string

required

Tipo de documento.

integer

required

Identificador del documento.

string

required

Token JWT con prefijo Bearer.

PUT https://servidor:<puerto>/api/documento/{tipo}/nuevaslineas/{id}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

{
  "lineas": [
    {
      "codart": "8403",
      "desclin": "PORTATIL LENOVO THINKPAD T480",
      "unidades": 2
    }
  ]
}

Respuesta 200:

{
  "id": "text"
}

Código	Descripción
`200`	Líneas añadidas — devuelve el `id` del documento
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al añadir líneas

Añadir detalle (lote / número de serie) a una línea

Añade detalle de trazabilidad —lotes, números de serie, fechas de caducidad, ubicaciones— a una línea existente de un documento.

string

required

Tipo de documento.

integer

required

Identificador del documento.

integer

required

Número de línea (campo numlin, no el identificador idlin).

string

required

Token JWT con prefijo Bearer.

PUT https://servidor:<puerto>/api/documento/{tipo}/nuevosdetalleslinea/iddocumento/{id}/numlin/{numlin}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

{
  "Unidades": "3",
  "Detalle": [
    {
      "unidades": "1",
      "lote": "L10",
      "feccaduc": "12/12/2027"
    }
  ]
}

Es importante que el campo Unidades (en la raíz del body) coincida con la suma de unidades de todos los objetos del array Detalle.

Respuesta 200:

{
  "Documento": "text"
}

Código	Descripción
`200`	Detalle actualizado correctamente
`302`	El documento no existe
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	No existe la línea o el JSON no es correcto

Añadir componentes a una línea KIT

Agrega los componentes de un artículo KIT a una línea de documento. El artículo de la línea debe estar configurado como KIT en A3ERP.

string

required

Tipo de documento.

integer

required

Identificador del documento.

integer

required

Número de línea (campo numlin, no el identificador idlin).

string

required

Token JWT con prefijo Bearer.

PUT https://servidor:<puerto>/api/documento/{tipo}/nuevoscomponenteslinea/iddocumento/{id}/numlin/{numlin}
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la petición:

{
  "componentes": [
    {
      "Codart": "L10",
      "Unidades": "10"
    }
  ]
}

Respuesta 200:

{
  "Documento": "text"
}

Código	Descripción
`200`	Componentes actualizados correctamente
`302`	El documento no existe
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	No existe la línea o el JSON no es correcto

Eliminar un documento

Elimina de forma permanente el documento indicado junto con todas sus líneas y detalle.

string

required

Tipo de documento.

integer

required

Identificador del documento a eliminar.

string

required

Token JWT con prefijo Bearer.

DELETE https://servidor:<puerto>/api/documento/{tipo}/{id}
Authorization: Bearer {token}

La eliminación de documentos es irreversible. Asegúrate de que el documento no esté vinculado a otros documentos de la cadena (p. ej. albaranes ya servidos a factura) antes de eliminarlo.

Código	Descripción
`200`	Documento eliminado correctamente
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	Error al eliminar el documento

Eliminar una línea de un documento

Elimina una línea concreta del documento, identificada por el id del documento y el número de línea.

string

required

Tipo de documento.

integer

required

Identificador del documento.

integer

required

Número de la línea a eliminar (campo idlin).

string

required

Token JWT con prefijo Bearer.

DELETE https://servidor:<puerto>/api/documento/{tipo}/{id}/linea/{numlin}
Authorization: Bearer {token}

Código	Descripción
`200`	Línea eliminada correctamente
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	No existe la línea a borrar

Eliminar los componentes de una línea KIT

Elimina los componentes asociados a una línea de artículo KIT en un documento.

string

required

Tipo de documento.

integer

required

Identificador del documento.

integer

required

Número de la línea cuyos componentes se eliminarán (campo idlin).

string

required

Token JWT con prefijo Bearer.

DELETE https://servidor:<puerto>/api/documento/{tipo}/{id}/componentelinea/{numlin}
Authorization: Bearer {token}

Código	Descripción
`200`	Componentes de la línea eliminados correctamente
`401`	Unauthorized
`404`	Endpoint no encontrado
`406`	No existe la línea a borrar

Fundamentos

Maestros y Documentos

Stock e Inventario

Informes y Datos

Producción

Módulos Adicionales

Contabilidad

Gestión de documentos de compra y venta en A3ERP API

Tipos de documento

Configuración de facturación de venta

Eliminación de facturas

Creación de facturas

Obtener todos los documentos de un tipo

Obtener la cabecera de un documento

Imprimir un documento en PDF

Servir un documento a otro

Imprimir un documento por GUID (sin autenticación)

Crear un nuevo documento

Servir líneas a otro documento

Enviar documento por email en formato PDF

Vincular adjunto a un documento

Vincular adjunto a una línea de documento

Anular un documento completo

Anular una línea de un documento

Anular unidades específicas de una línea

Actualizar un documento existente

Añadir nuevas líneas a un documento existente

Añadir detalle (lote / número de serie) a una línea

Añadir componentes a una línea KIT

Eliminar un documento

Eliminar una línea de un documento

Eliminar los componentes de una línea KIT